jianf/oniagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update all docs: README, AI_KNOWLEDGE_BASE, MOD_DEV_GUIDE, batch_example, SKILL

Browse Source
This commit is contained in:
JianFeeeee
2026-05-30 12:51:05 +08:00
parent 3d70338087
commit 21423a6bb4
4 changed files with 367 additions and 824 deletions
Download Patch File Download Diff File Expand all files Collapse all files

376
README.md
View File

@ -1,325 +1,173 @@
# ONI Agent — 缺氧 AI 助手工具集 # ONI Agent — 缺氧 AI 助手工具集
[Oxygen Not Included](https://www.kleientertainment.com/games/oxygen-not-included)（《缺氧》）是一款高难度的太空殖民模拟游戏。**ONI Agent** 为 AI 提供了一套完整的"眼手"系统：92 个 RESTful API 端点覆盖了玩家能做的全部操作（建造/挖掘/研究/管线/自动化/生物管理/覆盖层切换等），截图和视角控制让 AI 看到游戏画面，事件守护进程让 AI 实时感知游戏动态。Mod + Python 工具链 + AI 三层架构，让任何支持 Tool Use 的模型都能像人类一样操作游戏。 [Oxygen Not Included](https://www.kleientertainment.com/games/oxygen-not-included)（《缺氧》）高难度太空殖民模拟游戏。
**ONI Agent** 为 AI 提供"眼手"系统：RESTful API + Mod（C# Harmony）+ Python 工具链，让任何支持 Tool Use 的模型都能像人类一样操作游戏。
## 整体架构 ## 架构
``` ```
┌─────────────────────────────────────────────────┐ AI Agent (Claude/GPT/任何支持 Tool Use 的模型)
│ AI Agent │ ↕ HTTP API (RESTful JSON, 端口 23876) + CLI 工具链
│ (Claude / GPT / 任何支持 Tool Use 的模型) │ ONI Mod (C# Harmony) ←→ Python Tools
└──────┬──────────────────────────┬───────────────┘ ↕
│ HTTP API (RESTful JSON) │ CLI 工具链 Oxygen Not Included (游戏)
▼ ▼
┌──────────────┐ ┌────────────────────────────┐
│ ONI Mod │ │ Python Tools │
│ (C# / │ │ ├── oni_api.py (客户端) │
│ Harmony) │ │ ├── oni_analyzer.py (分析) │
│ 端口 23876 │ │ └── oni_builder.py (蓝图) │
└──────┬───────┘ └──────────┬─────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────┐
│ Oxygen Not Included (游戏) │
└─────────────────────────────────────────────────┘
``` ```
## 快速开始 ## 快速开始
### 前置条件
- [Oxygen Not Included](https://store.steampowered.com/app/457140) 游戏
- Python 3.8+
- Mod 文件部署到游戏 Mod 目录
### 1. 安装 Mod ### 1. 安装 Mod
将 `mod/` 目录下的内容（`mod_info.yaml` + `ONIAgentBridge.dll`）放入游戏的 Mod 文件夹： 将 `mod/` 下的 3 个文件放入游戏的 Mod 目录：
``` ```
Windows: %USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\local\ONIAgentBridge\ Windows: %USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\local\ONIAgentBridge\
macOS: ~/Library/Application Support/Klei/OxygenNotIncluded/mods/local/ONIAgentBridge/ ```
Linux: ~/.config/unity3d/Klei/OxygenNot Included/mods/local/ONIAgentBridge/
部署后目录结构：
```
ONIAgentBridge/
├── mod.yaml # Mod 元信息
├── mod_info.yaml # DLC/版本配置
└── ONIAgentBridge.dll # Mod DLL
``` ```
### 2. 启动游戏 ### 2. 启动游戏
启动 ONI，在 Mod 菜单中启用 **ONI Agent Bridge**，加载存档。 启动 ONI → Mod 菜单 → 启用 **ONI Agent Bridge** → 加载存档。
### 3. 验证连接 ### 3. 验证连接
```bash ```bash
python3 tools/oni_api.py health python tools/oni_api.py health
# 输出: Status: ok Version: 2.0.0
``` ```
预期输出: `{ "status": "ok", "service": "oni-agent-bridge" }` ## 工具链
### 4. 查看游戏状态 ### `tools/oni_api.py` — 主 CLI 客户端
```bash
python3 tools/oni_api.py status
python3 tools/oni_analyzer.py
```
## 工具链详解
### `tools/oni_api.py` — Mod API 客户端
与游戏 Mod 通信的核心 CLI 工具，支持所有查询和操作。
```bash ```bash
# 状态查询 # 状态查询
python3 tools/oni_api.py status # 游戏总览 python tools/oni_api.py status # 游戏总览
python3 tools/oni_api.py resources # 全部资源 python tools/oni_api.py resources # 资源清单
python3 tools/oni_api.py buildings # 全部建筑 python tools/oni_api.py buildings # 全部建筑
python3 tools/oni_api.py duplicants # 复制人详情 python tools/oni_api.py duplicants # 复制人
python3 tools/oni_api.py research # 科技进度 python tools/oni_api.py research # 科研
python3 tools/oni_api.py geysers # 喷泉列表 python tools/oni_api.py rooms # 房间
python3 tools/oni_api.py critters # 小动物 python tools/oni_api.py events # 事件日志
python3 tools/oni_api.py plants # 植物
python3 tools/oni_api.py rooms # 房间
# 地图/格子数据 # 地图数据
python3 tools/oni_api.py cell 10 5 # 查看单个格子 python tools/oni_api.py cell <x> <y> # 单格
python3 tools/oni_api.py cells 0 0 20 20 # 查看 20x20 区域 python tools/oni_api.py cells <x> <y> <w> <h> # 矩形区域
python3 tools/oni_api.py slice y 20 0 50 # 扫描第 20 行 python tools/oni_api.py slice <axis> <i> <s> <e> # 行列扫描
python3 tools/oni_api.py gas 50 50 30 # 气体分析 python tools/oni_api.py gas <x> <y> <r> # 气体分布
python3 tools/oni_api.py explore 40 40 30 20 # AI 友好摘要 python tools/oni_api.py explore <x> <y> <w> <h> # AI摘要
# 实体注册表（查询 ID） # 注册表查询
python3 tools/oni_api.py registry buildings Electrolyzer python tools/oni_api.py registry buildings [filter]
python3 tools/oni_api.py registry elements Water python tools/oni_api.py registry elements [filter]
python3 tools/oni_api.py registry techs python tools/oni_api.py registry techs
# 执行操作 # 操作（自动拉视角）
python3 tools/oni_api.py dig 10 10 8 6 # 挖掘区域 python tools/oni_api.py dig <x> <y> <w> <h> # 挖掘
python3 tools/oni_api.py build Electrolyzer 15 12 # 建造建筑 python tools/oni_api.py build <id> <x> <y> # 建造
python3 tools/oni_api.py deconstruct Tile 10 10 # 拆除 python tools/oni_api.py deconstruct <x> <y> # 拆除
python3 tools/oni_api.py prioritize 15 12 9 # 优先 python tools/oni_api.py prioritize <x> <y> <1-9> # 优先级
python3 tools/oni_api.py research_select ImprovedOxygen # 科研 python tools/oni_api.py research_select <techId> # 科研
python3 tools/oni_api.py mop 10 10 # 清理液体 python tools/oni_api.py mop <x> <y> # 清理
python3 tools/oni_api.py harvest 20 15 # 收获植物 python tools/oni_api.py harvest <x> <y> # 收获
python tools/oni_api.py pause [reason] # 暂停
# 游戏速度控制（AI 操作前必须先暂停） python tools/oni_api.py unpause [speed] # 恢复
python3 tools/oni_api.py pause "Reason here" # 暂停游戏 python tools/oni_api.py speed <1-3> # 速度
python3 tools/oni_api.py unpause 1 # 恢复（1x 速度） python tools/oni_api.py camera <x> <y> [zoom] # 视角
python3 tools/oni_api.py speed 3 # 直接设速度（不暂停） python tools/oni_api.py batch <file> # 批量
python tools/oni_api.py save [name] # 存档
# 批量任务 python tools/oni_api.py load <name> # 读档
python3 tools/oni_api.py batch docs/batch_example.json # 执行批量建造计划 python tools/oni_api.py priority_global <t> <p> # 全局优先级
python tools/oni_api.py priority_type <t> <p> # 类型优先级
# 优先级管理
python3 tools/oni_api.py priority_global dig 7 # 全局挖掘优先级设为 7
python3 tools/oni_api.py priority_type Electrolyzer 9 # 电解器建造优先级设为 9
# 管道/电线路径
python3 tools/oni_api.py build_pipe_line liquid 42 40 48 40 # 铺设液体管道
python3 tools/oni_api.py build_wire_line regular 42 40 48 40 # 铺设电线
# 高级指令（多个 API 组合）
python3 tools/oni_commander.py diagnose # 全面诊断
python3 tools/oni_commander.py fix_co2 # 自动处理 CO2
python3 tools/oni_commander.py fix_overload # 处理过载电路
python3 tools/oni_commander.py emergency_o2 # 紧急制氧
python3 tools/oni_commander.py expand_base 40 40 10 8 # 一键拓展房间
``` ```
### `tools/oni_analyzer.py` — 智能分析器 ### `tools/oni_analyzer.py` — 智能分析器
自动拉取全方位游戏状态，分析六大维度并生成可操作建议。
```bash ```bash
python3 tools/oni_analyzer.py python tools/oni_analyzer.py
# 分析：氧气/食物/电力/温度/水/科研 六维度 + 建议
``` ```
分析内容： ### `tools/oni_builder.py` — 蓝图
- 氧气供应状态 → 建议 SPOM 建造时机
- 食物储备 → 建议扩建农场/养殖
- 电力状况 → 建议新增发电类型
- 温度异常 → 建议冷却方案
- 水资源 → 建议过滤/收集策略
- 科研进度 → 建议下一个研究方向
### `tools/oni_builder.py` — 蓝图建造器
预置常用建筑模块，一键部署。
```bash ```bash
python3 tools/oni_builder.py list # 列出所有蓝图 python tools/oni_builder.py list # 列出蓝图
python3 tools/oni_builder.py build spom 42 42 # 建造 SPOM python tools/oni_builder.py build spom x y # 部署SPOM
```
蓝图：spom, spom_mini, toilet_loop, farm_mealwood, bedroom, cooling, ranch_hatch
### `tools/oni_commander.py` — 高级指令
```bash
python tools/oni_commander.py diagnose # 全面诊断
python tools/oni_commander.py emergency_o2 # 紧急制氧
python tools/oni_commander.py fix_co2 # 处理CO₂
python tools/oni_commander.py fix_overload # 过载电路
python tools/oni_commander.py expand_base x y w h # 拓展
``` ```
内置蓝图（7个）： ### `scripts/event_daemon.py` — 事件守护进程
| 蓝图 | 说明 | 尺寸 | ```bash
python scripts/event_daemon.py
# 持续轮询事件，分类显示到控制台
```
## API 端点
| 类别 | 端点 | 方法 |
|------|------|------| |------|------|------|
| `spom` | 标准 SPOM（电解制氧+氢气发电闭环） | 8×6 | | 健康 | `/health` | GET |
| `spom_mini` | 紧凑型 SPOM（前期过渡用） | 5×4 | | 状态 | `/api/state/game`, `resources`, `buildings`, `duplicants`, `research`, `rooms`, `alert`, `camera`, `storage`, `saves`, `events` | GET |
| `toilet_loop` | 卫生间水循环（厕所→净水器→厕所） | 8×4 | | 地图 | `/api/state/cell`, `cells`, `cells/slice`, `gas` | GET |
| `ranch_hatch` | 哈奇养殖模块 | 10×6 | | 注册表 | `/api/registry/buildings`, `elements`, `techs` | GET |
| `farm_mealwood` | 浆果农场（6个种植箱+储物箱） | 6×4 | | 截图 | `/api/screenshot/latest` | GET |
| `cooling` | 蒸汽涡轮冷却模块 | 8×6 | | 操作 | `/api/action/pause`, `unpause`, `speed`, `dig`, `build`, `deconstruct`, `prioritize`, `research`, `mop`, `harvest`, `batch`, `save`, `load`, `camera`, `priority_global`, `priority_type` | POST |
| `bedroom` | 标准卧室（床+梯子床+装饰） | 8×4 | | | **所有操作自动拉视角到坐标** | |
### `scripts/event_daemon.py` — 事件守护进程（AI 输入源） 错误格式：`{success: false, error: "...", errorMessage: "..."}`
持续轮询游戏事件并将其注入 AI 输入流。这是 AI 感知游戏状态变化的实时通道。
```bash
python3 scripts/event_daemon.py
```
工作原理：
1. 每 5 秒轮询 `GET /api/state/events?since=<seq>` 获取新事件
2. 对事件分类（critical / warning / info）
3. critical 事件 → 红色告警 + **自动触发全量游戏快照**（周期/窒息/饥饿/压力）
4. warning 事件 → 结构化输出给 AI
5. 维护滚动事件历史（最多 200 条），AI 可随时查询摘要
事件类型：
- `critical` — 复制人窒息、建筑损坏、电力中断 → 立即触发分析
- `warning` — 低氧、食物短缺、高温 → 主动通知给 AI
- `action_feedback` — 建造/挖掘等操作的结果反馈
- `info` — 常规游戏状态变化
### 辅助脚本
```bash
bash scripts/auto_repair.sh # 诊断 Mod 连接
bash scripts/auto_analyze.sh # 一键健康检查+状态+分析
bash scripts/watch.sh 60 # 每 60 秒持续监控
bash scripts/setup.sh # 环境初始化
python3 scripts/event_daemon.py # 事件守护进程（AI 输入源）
```
## Mod API 完整端点
### 状态查询 (GET)
| 端点 | 说明 |
|------|------|
| `/health` | Mod 存活检测 |
| `/api/state/game` | 全局状态（周期/人数/世界尺寸） |
| `/api/state/resources` | 资源列表（含物态/分类） |
| `/api/state/duplicants` | 复制人（位置/压力/食物/当前任务） |
| `/api/state/buildings` | 建筑（位置/是否运行/功耗/分类） |
| `/api/state/research` | 科技树（进度/解锁建筑） |
| `/api/state/geysers` | 喷泉（位置/状态/排放率） |
| `/api/state/alert` | 警报 |
| `/api/state/critters` | 小动物（位置/种类/幸福度） |
| `/api/state/plants` | 植物（位置/生长进度/是否枯萎） |
| `/api/state/rooms` | 房间（类型/格数/建筑数） |
| `/api/state/queue` | 任务队列（查看待处理任务） |
| `/api/state/events?since=&limit=` | 事件流（AI 轮询增量事件） |
| `/api/state/priorities` | 优先级配置（全局/建筑/复制人） |
### 地图/格子数据 (GET)
| 端点 | 说明 |
|------|------|
| `/api/state/cell?x=10&y=5` | 单格详情 |
| `/api/state/cells?x=&y=&width=&height=` | 矩形区域批量查询 |
| `/api/state/cells/slice?axis=&index=&start=&end=` | 行/列扫描 |
| `/api/state/gas?x=&y=&radius=` | 区域气体分布 |
### 实体注册表 (GET，AI 参考)
| 端点 | 说明 |
|------|------|
| `/api/registry/buildings` | 全部建筑定义（尺寸/功耗/材料） |
| `/api/registry/elements` | 全部元素定义（比热容/熔沸点/导热） |
| `/api/registry/techs` | 全部科技定义（前置/解锁） |
| `/api/registry/priorities` | 优先级级别含义对照表 |
### 操作 (POST)
| 端点 | 请求体 |
|------|--------|
| `/api/action/dig` | `{x, y, width, height}` |
| `/api/action/build` | `{buildingId, x, y}` |
| `/api/action/deconstruct` | `{buildingId, x, y}` |
| `/api/action/prioritize` | `{x, y, priority}` |
| `/api/action/research` | `{techId}` |
| `/api/action/mop` | `{x, y}` |
| `/api/action/harvest` | `{x, y}` |
| `/api/action/schedule` | `{duplicantId, schedule}` |
| `/api/action/wardrobe` | `{duplicantId, equipment}` |
| `/api/action/batch` | `{actions: [{type, ...}]}` — 批量执行 |
| `/api/action/priority_global` | `{target, priority}` — 全局默认优先级 |
| `/api/action/priority_type` | `{buildingType, priority}` — 按建筑类型设优先级 |
| `/api/action/pause` | `{reason?}` — 暂停游戏（AI 操作前必须调用） |
| `/api/action/unpause` | `{speed?}` — 恢复游戏 |
| `/api/action/speed` | `{speed}` — 设置速度 1x/2x/3x |
## 项目结构 ## 项目结构
``` ```
oni-agent/ oni-agent/
├── README.md # ← 本文件 ├── README.md
├── config.json # Mod 连接配置（host/port/timeout） ├── SKILL.md # AI Agent 完整缺氧教程
├── SKILL.md # AI Agent skill 定义与操作手册 ├── config.json # Mod 连接配置
│ ├── mod/
├── mod/ # 游戏 Mod（C# / Harmony） │ ├── ONIAgentBridge.cs # Mod 源码 (C# Harmony)
│ ├── mod_info.yaml # Mod 元信息（标题/版本/兼容性） │ ├── ONIAgentBridge.csproj
│ └── ONIAgentBridge.cs # HTTP API 服务实现 │ ├── mod.yaml / mod_info.yaml
│ ├── tools/
├── tools/ # Python 工具链 │ ├── oni_api.py # CLI 客户端 (20+ 子命令)
│ ├── oni_api.py # API 客户端（20+ 子命令） │ ├── oni_analyzer.py # 六维度分析
│ ├── oni_analyzer.py # 状态分析（6维度预警+建议） │ ├── oni_builder.py # 蓝图建造
│ └── oni_builder.py # 蓝图建造（7个预置模块） │ └── oni_commander.py # 高级指令
│ ├── scripts/
├── scripts/ # 辅助脚本 │ ├── event_daemon.py # 事件守护进程
│ ├── setup.sh # 环境初始化 │ ├── build_mod.sh # 编译脚本
│ ├── auto_repair.sh # 连接诊断 │ └── setup.sh # 环境初始化
│ ├── auto_analyze.sh # 一键分析
│ ├── watch.sh # 持续监控模式
│ └── event_daemon.py # 事件守护进程（AI 实时输入源）
│
├── docs/ ├── docs/
│ ├── MOD_DEV_GUIDE.md # Mod 开发规范与约束 │ ├── AI_KNOWLEDGE_BASE.md # AI 知识库
│ ├── AI_KNOWLEDGE_BASE.md # 200+ 建筑/元素/科技 ID 知识库 │ └── MOD_DEV_GUIDE.md # Mod 开发指南
│ └── batch_example.json # 批量任务示例文件
│
└── skills/ └── skills/
└── oni_agent.md # Agent skill 定义 └── oni_agent.md # Agent skill 定义
``` ```
## 文档索引 ## 文档索引
| 文档 | 目标读者 | 内容 | | 文档 | 目标 | 内容 |
|------|---------|------| |------|------|------|
| `SKILL.md` | AI Agent | 坐标系理解、API 用途、场景推理示例、操作表述规范 | | `SKILL.md` | AI Agent | 完整游玩教程：分阶段目标/材料/可达性/方块/操作协议 |
| `docs/AI_KNOWLEDGE_BASE.md` | AI Agent | 建筑 ID 对照表、元素属性、科技树、游戏机制参考 | | `docs/AI_KNOWLEDGE_BASE.md` | AI Agent | 建筑ID/元素属性/科技树/游戏机制参考 |
| `docs/MOD_DEV_GUIDE.md` | Mod 开发者 | 通信协议、端点规范、安全约束、检查清单 |
| `README.md` | 人类用户 | ← 你在看这个 | | `README.md` | 人类用户 | ← 你在看这个 |
## 常见问题
**Q: Mod 连接不上？**
运行 `bash scripts/auto_repair.sh` 诊断。确认：
1. 游戏已启动并加载存档
2. Mod 已在游戏中启用
3. 端口 23876 未被占用
**Q: `buildingId` 从哪查？**
```bash
python3 tools/oni_api.py registry buildings | grep -i electrolyzer
```
或者查看 `docs/AI_KNOWLEDGE_BASE.md`。
**Q: 怎么知道在哪个坐标建造？**
使用 `explore` 命令探索区域：
```bash
python3 tools/oni_api.py explore 40 40 30 20
```
它会告诉你该区域有哪些建筑、复制人、元素分布，帮你决策。
## 许可证 ## 许可证
MIT MIT

407
docs/AI_KNOWLEDGE_BASE.md
View File

@ -1,268 +1,189 @@
# ONI Knowledge Base — AI Reference # ONI AI Knowledge Base — 建筑/元素/科技/机制参考
This file aggregates all building IDs, element IDs, tech IDs, and their semantic metadata AI Agent 查询用参考手册。所有 buildingId 可通过 `/api/registry/buildings` 动态查询。
in one structured document. The AI uses this to understand what each entity means and
how to reason about the game.
## Coordinate System ## 坐标系
ONI uses a 2D grid. The origin (0,0) is at the **bottom-left** of the map. - 原点 (0,0) = 地图**左下角**，x→右，y→上
- x increases to the right - 建筑坐标 = 左下角锚点 (width × height)
- y increases upward - 默认地图大小：256×384
- Each cell is 1x1 tile
- Buildings may occupy multiple cells (width x height); the (x,y) is the **bottom-left anchor**
- World size varies by asteroid (default ~256x384 cells)
When the AI wants to reference a location: ## 建筑数据库
- Use absolute (x,y) coordinates
- For regions: (x, y, width, height)
- For buildings: reference the bottom-left cell of the building
- For movement: "at (x,y)" or "from (x1,y1) to (x2,y2)"
## Building Categories ### 氧气
| ID | 尺寸 | 材料 | 耗电(W) | 功能 |
|----|------|------|---------|------|
| Electrolyzer | 2×2 | Metal | 120 | 水→O₂+H₂ (1kg/s水) |
| OxygenDiffuser | 2×2 | Metal | 120 | 藻类→O₂ (早期) |
| Deodorizer | 1×2 | Metal | 0 | 污染氧→氧气 (需过滤介质) |
| AlgaeDistillery | 3×4 | Metal | 120 | 藻泥→藻类 |
| AlgaeHabitat | 1×2 | Farmable | 0 | 藻类养殖 |
| Category | Purpose | Examples | ### 电力
|------------|----------------------------------------|---------------------------------------------------| | ID | 尺寸 | 材料 | 发电(W) | 燃料 |
| Base | Structure, storage, doors, ladders | Tile, Ladder, StorageBin, InsulatedTile, Door | |----|------|------|---------|------|
| Oxygen | Oxygen production, gas cleaning | Electrolyzer, OxygenDiffuser, Deodorizer | | ManualGenerator | 2×2 | Metal | 400 | 人力 |
| Power | Power generation, storage, wiring | CoalGenerator, HydrogenGenerator, Battery | | CoalGenerator | 2×2 | Metal | 600 | 煤 |
| Food | Food production, cooking, ranching | PlanterBox, ElectricGrill, MicrobeMusher, Ranch | | HydrogenGenerator | 2×2 | Metal | 800 | 氢 |
| Plumbing | Liquid handling, hygiene | LiquidPump, Lavatory, WaterSiever, Shower | | NaturalGasGenerator | 2×2 | Metal | 800 | 天然气 |
| Ventilation| Gas handling | GasPump, GasFilter, GasVent | | PetroleumGenerator | 3×2 | Metal | 2000 | 石油 |
| Refinement | Material processing | MetalRefinery, RockCrusher, Kiln, Compost | | SteamTurbine | 4×2 | Metal | 850 | 蒸汽(热删除) |
| Medicine | Health, disease treatment | Apothecary, MassageTable, SickBay | | SolarPanel | 2×1 | Metal | 380 | 光照 |
| Furniture | Decor, morale, stress relief | Cot, MessTable, ArcadeCabinet, FlowerPot | | Battery | 1×1 | Metal | 0 | 储电 10kJ |
| Stations | Research, suit docks, crafting | ResearchStation, SuperComputer, AtmoSuitDock | | JumboBattery | 2×1 | Metal | 0 | 储电 40kJ |
| Utilities | Temperature management | ThermoAquatuner, SpaceHeater, TempshiftPlate | | Transformer | 2×1 | Metal | 0 | 电路分离 |
| Automation | Logic circuits, sensors | AND Gate, AtmoSensor, AutomationWire |
| Shipping | Conveyor systems | ConveyorLoader, ConveyorRail, SolidFilter |
## Key Building IDs (frequently used by AI) ### 管道/通风
| ID | 尺寸 | 材料 | 耗电 | 功能 |
|----|------|------|------|------|
| GasPump | 1×2 | Metal | 240W | 抽气 |
| GasFilter | 1×2 | Metal | 120W | 气体分离 |
| GasVent | 1×1 | Metal | 0 | 排气口 |
| LiquidPump | 1×2 | Metal | 240W | 抽液 |
| LiquidFilter | 1×2 | Metal | 120W | 液体分离 |
| LiquidVent | 1×1 | Metal | 0 | 排水口 |
| WaterPurifier | 2×2 | Metal | 120W | 污水→清水 |
``` ### 食物/农业
# Oxygen production | ID | 尺寸 | 材料 | 功能 |
Electrolyzer -> Produces O2 + H2 from water (needs 1kg/s water) |----|------|------|------|
OxygenDiffuser -> Produces O2 from algae (early game) | PlanterBox | 1×1 | BuildableRaw | 种植(需泥土) |
Deodorizer -> Converts PollutedOxygen to Oxygen (needs filtration medium) | FarmTile | 1×1 | BuildableRaw | 种植(需灌溉) |
| HydroponicFarmTile | 1×2 | Metal | 液培(需液体管道) |
| StorageLocker | 1×1 | BuildableRaw | 储物 |
| RationBox | 2×2 | BuildableRaw | 储食(CO₂防腐) |
| Refrigerator | 1×2 | Metal | 冷藏(耗电) |
| ElectricGrill | 2×2 | Metal | 烹饪 |
| MicrobeMusher | 2×2 | BuildableRaw | 初期制食 |
# Power ### 卫生
ManualGenerator -> 400W, duplicant powered | ID | 尺寸 | 材料 | 功能 |
CoalGenerator -> 600W, consumes Coal |----|------|------|------|
HydrogenGenerator -> 800W, consumes H2 | Outhouse | 1×2 | BuildableRaw | 初期厕所(需清理) |
NaturalGasGenerator-> 800W, consumes NaturalGas | WashBasin | 1×1 | BuildableRaw | 洗手(需水) |
PetroleumGenerator -> 2000W, consumes Petroleum | Lavatory | 1×2 | Metal | 抽水马桶(需水管) |
SteamTurbine -> Extracts heat from steam, produces power | WashSink | 1×1 | Metal | 自动洗手(需水管) |
SolarPanel -> 380W max, needs light | Shower | 2×1 | Metal | 淋浴(士气) |
WoodBurner -> 300W, consumes Lumber
# Power storage ### 基地
Battery -> 10kJ storage, small | ID | 尺寸 | 材料 | 功能 |
JumboBattery -> 40kJ storage |----|------|------|------|
SmartBattery -> 20kJ storage, automation output | Tile | 1×1 | BuildableRaw | 地板/墙 |
| InsulationTile | 1×1 | BuildableRaw | 隔热 |
| Ladder | 1×1 | BuildableRaw | 攀爬 |
| FirePole | 1×1 | Metal | 速降 |
| PneumaticDoor | 1×2 | Metal | 自动门 |
| ManualDoor | 1×2 | BuildableRaw | 手动门 |
| Cot | 1×1 | BuildableRaw | 床 |
| ResearchStation | 2×2 | BuildableRaw | 初级科研(60W) |
| SuperComputer | 2×2 | Plastic | 高级科研(120W) |
| TriageCot | 1×2 | BuildableRaw | 医疗床 |
# Food ### 精炼
PlanterBox -> Grows plants, needs dupe delivery | ID | 尺寸 | 材料 | 功能 |
FarmTile -> Grows plants with irrigation |----|------|------|------|
HydroponicFarm -> Grows plants with automatic irrigation | MetalRefinery | 3×2 | Metal | 精炼金属(1200W) |
ElectricGrill -> Cooks food (better quality) | RockCrusher | 2×2 | BuildableRaw | 碎矿 |
MicrobeMusher -> Makes basic mush bars from water + dirt | Kiln | 1×2 | BuildableRaw | 烧陶瓷/玻璃 |
GasRange -> Advanced cooking with gas | PolymerPress | 2×3 | Metal | 石油→塑料(240W) |
Refrigerator -> Stores food, slows decay | OilRefinery | 3×2 | Metal | 石油→天然气+石油 |
| Compost | 2×2 | BuildableRaw | 污染土→泥土 |
# Plumbing ### 温度控制
LiquidPump -> Pumps liquids (240kg/s) | ID | 尺寸 | 材料 | 功能 |
Lavatory -> Produces PollutedWater from dupe use |----|------|------|------|
WaterSiever -> Filters PollutedWater -> Water | Aquatuner | 1×2 | RefinedMetal | 液冷(1200W) |
Desalinator -> Removes salt from SaltWater/Brine | SpaceHeater | 1×1 | Metal | 加热(120W) |
LiquidVent -> Outputs liquid into world | IceFan | 2×1 | BuildableRaw | 降温(耗冰) |
| IceKettle | 1×2 | BuildableRaw | 冰→水 |
| TempshiftPlate | 1×1 | BuildableRaw | 导热板 |
# Ventilation ### 动物/养殖
GasPump -> Pumps gases (500g/s) | ID | 尺寸 | 材料 | 功能 |
GasFilter -> Filters specific gas from mixed pipes |----|------|------|------|
GasVent -> Outputs gas into world | RanchStation | 2×2 | BuildableRaw | 养殖站 |
HighPressureGasVent-> 20kg/tile max pressure | Incubator | 2×2 | BuildableRaw | 孵化器 |
| CritterFeeder | 1×2 | BuildableRaw | 投喂器 |
| CritterTrap | 1×1 | Metal | 陷阱 |
# Refinement ## 材料类别映射
MetalRefinery -> Refines metal ores into refined metals
RockCrusher -> Crushes rock into sand/power
Kiln -> Burns clay -> ceramic
GlassForge -> Makes glass from sand
Compost -> Converts polluted dirt into dirt
# Base | 类别 | 包含元素 | 来源 |
Tile -> Standard tile, 2 tiles high |------|---------|------|
Ladder -> Allows vertical movement | BuildableRaw | SandStone, Granite, IgneousRock, SedimentaryRock, Obsidian, MaficRock | 挖掘 |
InsulatedTile -> Reduces heat transfer (best insulation) | Metal | Cuprite, IronOre, GoldAmalgam, Wolframite, Cobaltite | 挖掘 |
ManualAirlock -> Manual door | RefinedMetal | Copper, Iron, Gold, Steel, Tungsten | 精炼 |
PneumaticDoor -> Auto door, lets gas pass | Plastic | Polypropylene | 聚合压机制造 |
MechanizedAirlock -> Auto door, seals gas/liquid | Glass | MoltenGlass→Glass | 窑炉 |
StorageBin -> Stores solid resources | BuildingFiber | ReedFiber | 耕种 |
LiquidReservoir -> Stores 5t of liquid | Transparent | Diamond, Glass | 挖掘/制造 |
GasReservoir -> Stores 150kg of gas | Farmable | Dirt | 挖掘/堆肥 |
# Temperature ## 元素属性参考
ThermoAquatuner -> Cools liquid piped through it (needs steam room)
ThermoRegulator -> Cools gas piped through it
SpaceHeater -> Heats area (inefficient)
LiquidTepidizer -> Heats liquid (up to 85C)
TempshiftPlate -> Distributes heat evenly
# Stations | 元素 | 比热容(J/g·K) | 导热(W/m·K) | 熔点(°C) |
ResearchStation -> Basic research (needs dirt) |------|--------------|-------------|---------|
SuperComputer -> Advanced research (needs plastic) | SandStone | 0.800 | 2.000 | - |
AtmoSuitDock -> Stores atmo suit | Granite | 0.790 | 3.390 | - |
GroomingStation -> Grooms critters for happiness/eggs | IgneousRock | 1.000 | 2.000 | - |
RanchStation -> Ranching skill station | SedimentaryRock | 0.200 | 2.000 | - |
FarmStation -> Improves farm yield (needs fertilizer) | Cuprite | 0.600 | 4.500 | - |
PowerControlStation-> Improves generator efficiency | IronOre | 0.440 | 4.000 | - |
| GoldAmalgam | 0.240 | 2.000 | - |
| Water | 4.179 | 0.609 | 0/100 |
| PollutedWater | 4.179 | 0.580 | -0.65/100 |
| Oxygen | 1.005 | 0.024 | -183/-183 |
| Hydrogen | 8.640 | 0.168 | -252/-252 |
| CarbonDioxide | 0.846 | 0.015 | 0/-78 |
| CrudeOil | 1.690 | 2.000 | -40/400 |
# Medicine ## 科技树 (常用)
MassageTable -> Reduces stress
SickBay -> Cures diseases
TriageCot -> Heals physical damage
Apothecary -> Produces medicine
# Automation (common items) | Tech ID | 名称 | 前置 | 解锁 |
AtmoSensor -> Senses gas pressure |---------|------|------|------|
ThermoSensor -> Senses temperature | FarmingTech | 农业技术 | - | PlanterBox, FarmTile |
HydroSensor -> Senses liquid pressure | PowerRegulation | 电力调节 | - | Transformer, HeavyWire |
GasElementSensor -> Senses specific gas type | Plumbing | 管道 | - | Lavatory, WaterPurifier |
AND Gate, NOT Gate, FILTER Gate, BUFFER Gate | Ventilation | 通风 | - | GasPump, GasFilter |
``` | Refinement | 精炼 | - | MetalRefinery, RockCrusher |
| TemperatureModulation | 调温 | - | Aquatuner, SteamTurbine |
| SmartStorage | 智能存储 | - | SmartStorageBin |
| AdvancedPowerRegulation | 高级电力 | PowerRegulation | PowerTransformer |
| LiquidPiping | 液体管道 | Plumbing | LiquidPump, LiquidFilter |
| GasPiping | 气体管道 | Ventilation | GasValve |
| FineDining | 精致餐饮 | FarmingTech | ElectricGrill |
| AnimalControl | 动物控制 | - | CritterTraps |
| Ranching | 畜牧 | AnimalControl | RanchStation |
## Key Element IDs (resources) ## 房间系统
``` | 房间 | 要求 | 加成 |
# Critical survival |------|------|------|
Oxygen -> Breathable gas (needed by dupes) | Bedroom(卧室) | 4×床, 封闭 | +1士气 |
Water -> Essential for farming, electrolysis, life support | Washroom(卫生间) | 洗手盆+马桶, 封闭 | +1士气 |
Dirt -> Used in research (early) and farming | MessHall(餐厅) | 餐桌+配给盒, 封闭 | +2士气 |
Algae -> Consumed by OxygenDiffuser | GreatHall(大堂) | 装饰+餐桌+配给盒 | +4士气 |
| Greenhouse(温室) | 种植+光照, 封闭 | 植物生长+50% |
| Hospital(医院) | 医疗床+医生, 封闭 | 治疗加速 |
| Ranch(畜舍) | 养殖站+喂食器 | 动物繁殖加速 |
| PowerPlant(电站) | 发电机×2+电池 | 发电效率+10% |
# Food chain ## 电路规则
Calories -> Aggregate food energy for colony
MealLice -> Basic food from mealwood plants
BristleBerry -> Mid-tier food from bristle blossom
Mushroom -> Food from dusk cap (needs CO2 + slime)
RawEgg -> Egg for cooking
Meat -> From ranching
# Power chain - 普通电线最大负载：1000W
Coal -> Burned in CoalGenerator - 重导线(Wire) 最大负载：2000W
Hydrogen -> Burned in HydrogenGenerator - 超过负载 → 过载损坏 → 复制人维修
NaturalGas -> Burned in NaturalGasGenerator - 使用变压器(Transformer)将重导线电路分成普通导线子电路
Petroleum -> Burned in PetroleumGenerator - 智能电池可连接自动化电路控制发电机启停
CrudeOil -> Can be refined to Petroleum
# Construction metals ## 紧急阈值
CopperOre -> Early building material
IronOre -> Mid building material
GoldAmalgam -> High corrosion resistance
Wolframite -> Very high melting point (tungsten source)
Steel -> Strong, high melting point (refined)
RefinedIron -> Mid refined metal
Plastic -> Advanced material (from polymer press or dreckos)
Ceramic -> Best insulation material
# Water / liquids | 指标 | 警告 | 危险 | 应对 |
SaltWater -> Can be desalinated to Water |------|------|------|------|
Brine -> Can be desalinated (more salt per water) | O₂质量 | <2000kg | <500kg | 增加制氧 |
PollutedWater -> Can be filtered to Water (also used by reed fiber) | 食物 | <500kkcal | <200kkcal | 增加农场 |
CrudeOil -> Pumped from oil biome | 水 | <20000kg | <5000kg | 找水源/净化 |
Petroleum -> Refined from oil (cooking or refinery) | 温度 | >35°C | >50°C | 隔热+冷却 |
Lumber -> From arbor trees, burned in wood burner | CO₂ | 可见积聚 | >2kg/tile | 挖排气管 |
Ethanol -> From lumber, burned in petroleum generator | 藻类 | <2000kg | <500kg | 转电解器 |
| 煤 | <5000kg | <1000kg | 找煤矿/换发电 |
# Gas handling
PollutedOxygen -> Can be deodorized to Oxygen
CarbonDioxide -> Sinks to bottom, used by mushrooms/soda fountain
ChlorineGas -> Disinfects, used by balm lily
SourGas -> Can be cooled to methane + sulfur
# Rare / advanced
Niobium -> End-game space material
Thermium -> Best heat conductor (space material)
Isoresin -> Used for insulation (space material)
ViscoGel -> Non-mixing liquid (space material)
Radium -> Radioactive, spaced out DLC
```
## Research Tech Tree (simplified path)
```
Tier 0 (start): FarmingTech, PowerRegulation, Plumbing, Ventilation
Tier 1: FoodPreparation (-> ElectricGrill, MicrobeMusher)
InteriorDecor (-> Cot, FlowerPot, various decor)
AdvancedPowerRegulation (-> SmartBattery, PowerTransformer)
LiquidPiping (-> LiquidPump, WaterSiever, Desalinator)
GasPiping (-> GasPump, GasFilter)
FineDining (-> GasRange, Refrigerator)
Tier 2: ImprovedOxygen (-> Electrolyzer)
RefinedObjects (-> MetalRefinery, RockCrusher)
TemperatureModulation (-> ThermoAquatuner, ThermoRegulator)
Ranching (-> GroomingStation, Incubator)
SmartStorage (-> LiquidReservoir, GasReservoir)
Automation (-> first automation buildings)
Tier 3: HighTemperatureForging (-> Steel)
SpaceProgram (-> telescope, rocket platform)
CryoFuelPropulsion (-> hydrogen rocket engine)
Tier 4: MaterialsScience (-> SuperCoolant, ViscoGel)
```
## Building Size Reference (width x height)
```
1x1: Wire, GasPipe, LiquidPipe, AutomationWire, Switch, Sensor
1x2: ManualGenerator, Battery, PlanterBox, FarmTile, RationBox
2x1: GasFilter, LiquidFilter, Incubator, Jukebot
2x2: CoalGenerator, HydrogenGenerator, OxygenDiffuser, Electrolyzer,
GasPump, LiquidPump, AlgaeTerrarium, Deodorizer, WaterSiever,
ElectricGrill, MicrobeMusher, RockCrusher, Kiln, Compost,
MassageTable, Apothecary, ResearchStation, TextileLoom
2x3: MetalRefinery, PolymerPress, OilRefinery, AtmoSuitDock
2x4: Telescope, MolecularForge
3x1: LadderBed, DisplayShelf
3x2: ManualAirlock, PneumaticDoor, MechanizedAirlock, ConveyorLoader,
SmartStorageBin, LiquidReservoir, GasReservoir
3x3: Shower, Sauna, HotTub
3x4: SteamTurbine
4x2: SuperComputer, JumboBattery, StorageBin
4x4: SolarPanel
```
## Common Game Mechanics (AI reference)
### Gas/Liquid Physics
- Gases **layer by density**: CO2 (sinks) < O2 < PollutedO2 < NaturalGas < H2 (rises)
- Liquids **layer by density**: Petroleum < Water/SaltWater/Brine < CrudeOil < Mercury
- Pressure limit for gas vents: GasVent = 2kg/tile, HighPressureGasVent = 20kg/tile
- Buildings overheat above their overheat temperature (default 75C, some higher)
- Insulated Tile reduces heat transfer by ~100x
### Duplicant Needs
- Oxygen: need ~100g/s per dupe
- Food: need ~1000kcal/cycle per dupe
- Stress: > 50% starts causing problems, > 80% mental breaks
- Temperature: comfortable at 18-35C, hypothermia below 10C, hyperthermia above 40C
- Morale: affected by decor, food quality, room bonuses
### Room Types
- Latrine: Outhouse + WashBasin = +1 morale
- Washroom: Lavatory + Sink = +2 morale
- Barracks: Cot/LadderBed + 1 decor = +1 morale
- Bedroom: ComfyBed + 1 decor = +2 morale
- Mess Hall: MessTable + 1 decor = +3 morale
- Great Hall: MessTable + 2+ decor and recreation = +6 morale
- Park: 4+ wild/planted plants = +1 morale
- Nature Reserve: 12+ wild plants = +6 morale
- Stable: GroomingStation + CritterDropOff = ranching room
- Ranch: Incubator + feeder (spaced out)
### SPOM (Self-Powered Oxygen Module)
The classic Rodriguez SPOM:
- 1 Electrolyzer (consumes 1kg/s water -> 888g/s O2 + 112g/s H2)
- 2 GasPumps for O2 extraction
- 1 HydrogenGenerator (burns 100g/s H2, produces 800W)
- 1 GasFilter to separate H2 from O2
- Net power positive (runs on its own hydrogen)
- Standard size: 8x6 tiles

399
docs/MOD_DEV_GUIDE.md
View File

@ -2,348 +2,121 @@
## 概述 ## 概述
本文档规定了一个与外部 Agent（AI 助手）对接的《缺氧》(Oxygen Not Included) Mod 应遵循的接口规范、约束条件和最佳实践。遵循此规范开发的 Mod 可与 `oni-agent` 工具链无缝协作。 本文档规定 ONI Agent Bridge Mod 的接口规范和开发约束。
---
## 1. 通信协议 ## 1. 通信协议
### 1.1 传输层 ### 1.1 传输层
- **协议**: HTTP 1.1 - **协议**: HTTP 1.1
- **地址**: `127.0.0.1`（仅本地回环，禁止暴露到外部网络） - **地址**: `127.0.0.1`（仅本地回环，禁止暴露外部网络）
- **端口**: 由配置文件指定（默认 `23876`） - **端口**: 默认 `23876`，可在 `config.json` 修改
- **编码**: 所有请求和响应均为 UTF-8 - **编码**: UTF-8
### 1.2 数据格式 ### 1.2 数据格式
- 所有请求和响应使用 `application/json` 所有请求和响应使用 `application/json`。
- 响应必须包含有效的 JSON
- 错误响应必须包含 `error` 字段 **统一响应格式：**
```json ```json
// 成功响应 // 成功
{ "result": "ok", ... } { "success": true, "data": { ... } }
// 错误响应 // 错误
{ "error": "error_message" } { "success": false, "error": "error_code", "errorMessage": "可读信息" }
``` ```
### 1.3 请求超时 **旧格式兼容**（/health 端点历史版本）：
- 服务端应在 5 秒内响应 ```json
- 长时间操作应排队后立即返回 `{ "result": "queued" }` { "status": "ok" }
```
--- ### 1.3 线程模型
- **读操作**可通过 `EnqueueRead(Func<object>)` 排队到主线程执行（`ManualResetEvent` 同步等待）
- **写操作**通过静态 `ConcurrentQueue<Action> cmdQueue` + `QueueProcessor` (MonoBehaviour.Update) 排队到主线程
- **格子数据**（Grid.Element/Mass/Temperature/Objects）可从后台线程直接读取（静态数组）
## 2. API 端点规范 ## 2. 端点规范
### 2.1 健康检查 ### 2.1 健康检查
``` ```
GET /health GET /health
``` ```
必须始终可达，不依赖游戏状态。
用于 Agent 探测 Mod 是否存活。必须始终可达，不依赖游戏状态。
**响应**:
```json ```json
{ "status": "ok", "service": "mod_name" } { "success": true, "data": { "status": "ok", "service": "oni-agent-bridge", "version": "2.0.0" } }
``` ```
### 2.2 状态查询端点 ### 2.2 状态查询 (GET /api/state/)
| 端点 | 说明 | 实现方式 |
|------|------|---------|
| game | 周期/复制人/世界尺寸/暂停/速度 | EnqueueRead |
| resources | 资源列表(含物态/存量) | EnqueueRead |
| buildings | 建筑列表(含位置/尺寸) | EnqueueRead |
| duplicants | 复制人(位置/血量) | EnqueueRead |
| research | 科技进度 | EnqueueRead |
| rooms | 房间类型 | EnqueueRead |
| events | 事件日志(支持since分页) | 直接读取(eventLock) |
| storage | 储物建筑内容 | EnqueueRead |
| saves | 存档列表 | EnqueueRead |
| alert | 游戏警报 | EnqueueRead |
| camera | 相机位置 | EnqueueRead |
所有状态查询为 `GET` 请求，路径前缀 `/api/state/`。 ### 2.3 格子数据 (GET, 可后台线程)
| 端点 | 参数 | 说明 |
| 端点 | 返回内容 | 必需 | 新增字段 |
|------|---------|------|---------|
| `/api/state/game` | 周期、复制人、世界尺寸 | **是** | `gridWidth`, `gridHeight` |
| `/api/state/resources` | 资源列表(含分类/物态) | **是** | `id`, `state`, `category` |
| `/api/state/duplicants` | 复制人详情 | **是** | `x`, `y`, `cell`, `currentChore` |
| `/api/state/buildings` | 建筑列表 | 推荐 | `cell`, `category`, `powerWatt` |
| `/api/state/research` | 科技树(含解锁列表) | 推荐 | `requiredTechs`, `unlockedBuildings` |
| `/api/state/geysers` | 喷泉详情 | 可选 | `cell`, `isActive`, `isDormant` |
| `/api/state/alert` | 当前警报 | 推荐 | `clickable` |
| `/api/state/critters` | 小动物详情 | 可选 | `cell`, `calories` |
| `/api/state/plants` | 植物列表 | 可选 | `isGrown`, `progress`, `isWilting` |
| `/api/state/rooms` | 房间列表 | 可选 | 类型/格数/建筑/生物/植物 |
### 2.3 地图/格子数据端点
这是 AI 理解游戏世界最重要的端点。格子级数据让 AI 知道每个具体位置的状态。
| 端点 | 说明 | 参数 |
|------|------|------| |------|------|------|
| `GET /api/state/cell` | 单格详情 | `?x=&y=` | | cell | x, y | 单格详情 |
| `GET /api/state/cells` | 矩形区域(批量) | `?x=&y=&width=&height=` | | cells | x, y, width, height | 矩形区域 |
| `GET /api/state/cells/slice` | 行或列扫描 | `?axis=x&index=&start=&end=` | | cells/slice | axis, index, start, end | 行列扫描 |
| `GET /api/state/gas` | 气体分布分析 | `?x=&y=&radius=` | | gas | x, y, radius | 气体分布 |
#### `GET /api/state/cell?x=10&y=5` ### 2.4 注册表 (GET /api/registry/)
| 端点 | 说明 |
|------|------|
| buildings | 所有建筑定义(含尺寸/材料类别) |
| elements | 所有元素定义 |
| techs | 科技树(含前置) |
```json ### 2.5 操作 (POST /api/action/)
{ 所有操作执行前**自动拉视角**到目标坐标。
"x": 10, "y": 5, "cell": 4523,
"element": "Oxygen", | 端点 | 请求体 | 说明 |
"elementId": "Oxygen", |------|--------|------|
"elementState": "gas", | pause | {reason?} | 暂停(通过SpeedControlScreen) |
"massKg": 1.8, | unpause | {speed?} | 恢复 |
"temperatureC": 23.5, | speed | {speed} | 设速度 |
"isSolid": false, "isLiquid": false, "isGas": true, | dig | {x,y,width,height} | 挖掘(使用DigTool.PlaceDig) |
"hasBuilding": true, "buildingName": "GasPump", | build | {buildingId,x,y} | 建造(使用BuildingDef.Instantiate) |
"hasDuplicant": false, "duplicantName": null, | deconstruct | {x,y} | 拆除(使用Deconstructable.QueueDeconstruction) |
"isVacuum": false, "isVisible": true | prioritize | {x,y,priority} | 设优先级(1-9) |
} | research | {techId} | 研究(SetActiveResearch) |
| mop | {x,y} | 清理液体 |
| harvest | {x,y} | 收获植物 |
| batch | {actions} | 批量操作 |
| save | {name?} | 存档 |
| load | {name} | 读档 |
| camera | {x,y,zoom?} | 移动视角 |
| priority_global | {target,priority} | 全局默认优先级 |
| priority_type | {buildingType,priority} | 按类型优先级 |
### 2.6 截图
``` ```
GET /api/screenshot/latest
#### `GET /api/state/cells?x=0&y=0&width=5&height=5`
```json
{
"region": { "x": 0, "y": 0, "width": 5, "height": 5 },
"cells": [ /* array of cell objects */ ]
}
``` ```
返回 PNG 图片。通过 `ScreenCapture.CaptureScreenshot` 异步生成。
### 2.4 实体注册表端点 (AI 参考) ## 3. 事件系统
用于 AI 在运行时查询游戏实体的元数据。所有为 `GET` 请求。 Mod 内部维护事件列表 (`List<AgentEvent> + lock`)。
事件可通过 `GET /api/state/events?since=N` 轮询。
事件自动记录操作日志。
| 端点 | 返回内容 | ## 4. Mod 开发检查清单
|------|---------|
| `/api/registry/buildings` | 全部建筑定义(尺寸/功耗/发热/材料) |
| `/api/registry/elements` | 全部元素定义(比热容/导热/熔沸点) |
| `/api/registry/techs` | 全部科技定义(前置/解锁建筑) |
#### `GET /api/registry/buildings` - [ ] Mod 类继承 `UserMod2`，重写 `OnLoad(Harmony)`
- [ ] 用 `GameObject + MonoBehaviour` 处理队列，`DontDestroyOnLoad`
```json - [ ] 用 `HttpListener` 暴露 HTTP 服务，`BeginGetContext` 异步处理
[ - [ ] 格子数据安全读取：`Grid.Element[]`、`Grid.Mass[]`、`Grid.Solid[]`、`Grid.Objects[,]`
{ - [ ] 读操作用 `EnqueueRead` 同步到主线程
"id": "Electrolyzer", - [ ] 写操作用 `cmdQueue` 排队到主线程的 `Update()` 中执行
"name": "Electrolyzer", - [ ] 响应统一 `{success, data}` 或 `{success, error, errorMessage}`
"category": "Oxygen", - [ ] 所有操作自动 `QWithCamera(x,y,action)` 拉视角
"width": 2, "height": 2,
"powerCost": 120,
"heatGeneration": 1.25,
"constructionMass": ["IronOre", "IronOre"]
}
]
```
### 2.5 操作端点
所有操作为 `POST` 请求，路径前缀 `/api/action/`。
| 端点 | 作用 | 必需 |
|------|------|------|
| `/api/action/dig` | 挖掘指定区域 | **是** |
| `/api/action/build` | 建造建筑 | **是** |
| `/api/action/deconstruct` | 拆除建筑 | 推荐 |
| `/api/action/prioritize` | 设置优先级 | 可选 |
| `/api/action/research` | 选择研究方向 | 推荐 |
| `/api/action/schedule` | 修改复制人日程 | 可选 |
| `/api/action/wardrobe` | 修改复制人装备 | 可选 |
| `/api/action/mop` | 清理液体 | 推荐 |
| `/api/action/harvest` | 收获植物 | 推荐 |
| `/api/action/cancel` | 取消操作 | 可选 |
#### `GET /api/state/game`
```json
{
"cycle": 42,
"duplicantCount": 6,
"worldName": "Terra",
"worldSize": 256
}
```
#### `GET /api/state/duplicants`
```json
[
{
"name": "Dup1",
"stress": 12.5,
"calories": 850000,
"stamina": 98.2,
"oxygen": 85.0,
"diseases": 0,
"skillLevels": 3
}
]
```
#### `GET /api/state/resources`
```json
[
{ "name": "Oxygen", "tag": "Oxygen", "amount": 12345.6, "unit": "kg" }
]
```
#### `GET /api/state/buildings`
```json
[
{
"name": "Manual Generator",
"id": "ManualGenerator",
"x": 10,
"y": 5,
"isOperational": true
}
]
```
### 2.3 操作端点
所有操作为 `POST` 请求，路径前缀 `/api/action/`。
| 端点 | 作用 | 必需 |
|------|------|------|
| `/api/action/dig` | 挖掘指定区域 | **是** |
| `/api/action/build` | 建造建筑 | **是** |
| `/api/action/deconstruct` | 拆除建筑 | 推荐 |
| `/api/action/prioritize` | 设置优先级 | 可选 |
| `/api/action/research` | 选择研究方向 | 推荐 |
| `/api/action/schedule` | 修改复制人日程 | 可选 |
| `/api/action/wardrobe` | 修改复制人装备 | 可选 |
#### `POST /api/action/dig`
**请求体**:
```json
{ "x": 10, "y": 5, "width": 8, "height": 6 }
```
**响应**:
```json
{ "result": "dig_queued", "x": 10, "y": 5, "width": 8, "height": 6 }
```
#### `POST /api/action/build`
**请求体**:
```json
{ "buildingId": "Electrolyzer", "x": 10, "y": 5, "rotation": null }
```
**响应**:
```json
{ "result": "build_queued", "buildingId": "Electrolyzer", "x": 10, "y": 5 }
```
---
## 3. Mod 约束
### 3.1 安全性
1. **仅绑定本地回环地址** `127.0.0.1`，不得监听 `0.0.0.0`
2. **不得实现认证/授权**——回环地址默认安全
3. **不得执行文件 I/O**（读取 Mod 自带配置除外）
4. **输入校验**——所有用户输入必须校验类型和范围
### 3.2 性能
1. 状态查询必须是**只读操作**，不得持有锁
2. 资源列表等大数据量接口应考虑分页（未来扩展）
3. 建造/挖掘等操作应返回 `queued` 后异步执行
4. HTTP 服务器应在**单独线程**运行，不得阻塞游戏主线程
### 3.3 兼容性
1. 使用 `KMod.UserMod2` 基类
2. 使用 `Harmony` 进行补丁（如果使用）
3. 引用 `UnityEngine` 和 `Assembly-CSharp` 程序集
4. 最小支持游戏版本应在 `mod_info.yaml` 中声明（当前推荐 `612000`）
### 3.4 错误处理
```json
// Mod 内部错误的通用格式
{ "error": "error_type", "details": "human readable message" }
// 常见错误类型
{ "error": "not_found" } // 404 端点不存在
{ "error": "invalid_request" } // 请求体解析失败
{ "error": "not_implemented" } // 功能尚未实现
{ "error": "unknown_building", "buildingId": "..." } // 建筑 ID 不识别
{ "error": "unknown_tech", "techId": "..." } // 科技 ID 不识别
```
---
## 4. 配置文件规范
Agent 侧通过 `config.json` 定位 Mod：
```json
{
"modHost": "127.0.0.1",
"modPort": 23876,
"timeout": 10
}
```
- `modHost`: 始终为 `127.0.0.1`
- `modPort`: 应与 Mod 中监听的端口一致
- `timeout`: HTTP 请求超时秒数
---
## 5. AI-Friendly 数据设计原则
### 5.1 数据可读性
所有暴露的数据应满足 AI 可直接理解的三个条件：
1. **命名语义化** — 使用自然语言字段名（如 `temperatureC` 而非 `tempK`)
2. **数据类型合理** — 使用数字而非枚举字符串（温度用 `float` 而非 `string`)
3. **上下文完整** — 每个实体包含足够的位置和状态信息（坐标、类别、是否可运行）
### 5.2 坐标系统
- 统一使用 `(x, y)` 整数坐标，对应游戏网格
- 原点在左下角：`(0, 0)`
- 建筑使用其左下角锚点坐标
- 返回数据中同时提供 `cell` 索引（Grid 内部使用）和 `(x, y)` 坐标
### 5.3 实体分类
每个实体（建筑、元素、科技）必须包含分类标签：
- 建筑: `category`（Base/Oxygen/Power/Food/...）
- 元素: `state`（solid/liquid/gas）+ `category`（metal/water/fuel/...）
- 资源: 带 `state` 和 `category` 帮助 AI 推理用途
### 5.4 AI 推理辅助
- `/api/registry/*` 端点提供完整的实体元数据查询
- `GET /api/state/gas` 提供区域气体分布统计（AI 无法逐格遍历）
- `/api/state/rooms` 提供房间判定结果（AI 无法自行判断房间类型）
### 5.5 操作设计
操作设计遵循以下原则：
- **幂等性** — 同个操作重复执行不产生副作用
- **非阻塞** — 操作立即返回 `queued`，异步执行
- **确定性** — 使用绝对坐标 `(x, y)`，不支持"在某个建筑旁边"这类模糊表述
- **输入校验** — 拒绝未知的 `buildingId` 或越界坐标
## 6. 扩展建议
### 5.1 添加新端点
1. 在 `ProcessRequest` 中添加路由匹配
2. 实现对应的处理方法
3. 更新本指南和 `SKILL.md`
### 5.2 蓝图系统
预置的建造方案（蓝图）应满足：
- 坐标相对于原点，便于偏移
- 包含预先挖掘区域
- 建筑顺序隐含依赖关系
### 5.3 事件推送（未来）
考虑支持 WebSocket 或 SSE，用于游戏事件实时推送（如警报触发）。
---
## 6. 开发检查清单
- [ ] Mod 继承 `UserMod2`，在 `OnLoad` 中启动 HTTP 服务
- [ ] 在 `OnUnload` 中停止 HTTP 服务
- [ ] 实现全部必需端点（health, game, resources, duplicants, dig, build）
- [ ] 错误响应包含 `error` 字段
- [ ] 端口号与 `config.json` 一致
- [ ] 仅绑定 `127.0.0.1`
- [ ] 使用 `Newtonsoft.Json`（游戏自带，无需额外依赖）
- [ ] `mod_info.yaml` 声明了正确的游戏版本

9
docs/batch_example.json
View File

@ -1,5 +1,4 @@
{ {
"name": "Build SPOM - Step 1: Dig and Electrolyzer",
"actions": [ "actions": [
{ {
"type": "dig", "type": "dig",
@ -27,11 +26,13 @@
"y": 40 "y": 40
}, },
{ {
"type": "wait", "type": "build",
"delayMs": 100 "buildingId": "GasFilter",
"x": 44,
"y": 40
}, },
{ {
"type": "priority", "type": "prioritize",
"x": 45, "x": 45,
"y": 42, "y": 42,
"priority": 9 "priority": 9