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

2026-05-30 12:51:05 +08:00
parent 3d70338087
commit 21423a6bb4
4 changed files with 367 additions and 824 deletions
--- a/README.md
+++ b/README.md
@ -1,325 +1,173 @@
 # 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 的模型)       │
-└──────┬──────────────────────────┬───────────────┘
-       │ HTTP API (RESTful JSON)  │ CLI 工具链
-       ▼                          ▼
-┌──────────────┐    ┌────────────────────────────┐
-│  ONI Mod     │    │  Python Tools               │
-│  (C# /       │    │  ├── oni_api.py (客户端)    │
-│   Harmony)   │    │  ├── oni_analyzer.py (分析)  │
-│  端口 23876  │    │  └── oni_builder.py (蓝图)   │
-└──────┬───────┘    └──────────┬─────────────────┘
-       │                        │
-       ▼                        ▼
-┌─────────────────────────────────────────────────┐
-│           Oxygen Not Included (游戏)             │
-└─────────────────────────────────────────────────┘
+AI Agent (Claude/GPT/任何支持 Tool Use 的模型)
+    ↕ HTTP API (RESTful JSON, 端口 23876)  +  CLI 工具链
+ONI Mod (C# Harmony)  ←→  Python Tools
+    ↕
+Oxygen Not Included (游戏)
 ```

 ## 快速开始

-### 前置条件
-
- [Oxygen Not Included](https://store.steampowered.com/app/457140) 游戏
- Python 3.8+
- Mod 文件部署到游戏 Mod 目录
-
 ### 1. 安装 Mod

-将 `mod/` 目录下的内容（`mod_info.yaml` + `ONIAgentBridge.dll`）放入游戏的 Mod 文件夹：
+将 `mod/` 下的 3 个文件放入游戏的 Mod 目录：

 ```
 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. 启动游戏

-启动 ONI，在 Mod 菜单中启用 **ONI Agent Bridge**，加载存档。
+启动 ONI → Mod 菜单 → 启用 **ONI Agent Bridge** → 加载存档。

 ### 3. 验证连接

 ```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. 查看游戏状态
-
-```bash
-python3 tools/oni_api.py status
-python3 tools/oni_analyzer.py
-```
-
-## 工具链详解
-
-### `tools/oni_api.py` — Mod API 客户端
-
-与游戏 Mod 通信的核心 CLI 工具，支持所有查询和操作。
+### `tools/oni_api.py` — 主 CLI 客户端

 ```bash
 # 状态查询
-python3 tools/oni_api.py status           # 游戏总览
-python3 tools/oni_api.py resources         # 全部资源
-python3 tools/oni_api.py buildings         # 全部建筑
-python3 tools/oni_api.py duplicants        # 复制人详情
-python3 tools/oni_api.py research          # 科技进度
-python3 tools/oni_api.py geysers           # 喷泉列表
-python3 tools/oni_api.py critters          # 小动物
-python3 tools/oni_api.py plants            # 植物
-python3 tools/oni_api.py rooms             # 房间
+python tools/oni_api.py status           # 游戏总览
+python tools/oni_api.py resources        # 资源清单
+python tools/oni_api.py buildings        # 全部建筑
+python tools/oni_api.py duplicants       # 复制人
+python tools/oni_api.py research         # 科研
+python tools/oni_api.py rooms            # 房间
+python tools/oni_api.py events           # 事件日志

-# 地图/格子数据
-python3 tools/oni_api.py cell 10 5         # 查看单个格子
-python3 tools/oni_api.py cells 0 0 20 20   # 查看 20x20 区域
-python3 tools/oni_api.py slice y 20 0 50   # 扫描第 20 行
-python3 tools/oni_api.py gas 50 50 30      # 气体分析
-python3 tools/oni_api.py explore 40 40 30 20  # AI 友好摘要
+# 地图数据
+python tools/oni_api.py cell <x> <y>              # 单格
+python tools/oni_api.py cells <x> <y> <w> <h>     # 矩形区域
+python tools/oni_api.py slice <axis> <i> <s> <e>  # 行列扫描
+python tools/oni_api.py gas <x> <y> <r>           # 气体分布
+python tools/oni_api.py explore <x> <y> <w> <h>   # AI摘要

-# 实体注册表（查询 ID）
-python3 tools/oni_api.py registry buildings Electrolyzer
-python3 tools/oni_api.py registry elements Water
-python3 tools/oni_api.py registry techs
+# 注册表查询
+python tools/oni_api.py registry buildings [filter]
+python tools/oni_api.py registry elements [filter]
+python tools/oni_api.py registry techs

-# 执行操作
-python3 tools/oni_api.py dig 10 10 8 6     # 挖掘区域
-python3 tools/oni_api.py build Electrolyzer 15 12  # 建造建筑
-python3 tools/oni_api.py deconstruct Tile 10 10   # 拆除
-python3 tools/oni_api.py prioritize 15 12 9      # 优先
-python3 tools/oni_api.py research_select ImprovedOxygen  # 科研
-python3 tools/oni_api.py mop 10 10               # 清理液体
-python3 tools/oni_api.py harvest 20 15           # 收获植物
-
-# 游戏速度控制（AI 操作前必须先暂停）
-python3 tools/oni_api.py pause "Reason here"    # 暂停游戏
-python3 tools/oni_api.py unpause 1              # 恢复（1x 速度）
-python3 tools/oni_api.py speed 3                # 直接设速度（不暂停）
-
-# 批量任务
-python3 tools/oni_api.py batch docs/batch_example.json  # 执行批量建造计划
-
-# 优先级管理
-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 # 一键拓展房间
+# 操作（自动拉视角）
+python tools/oni_api.py dig <x> <y> <w> <h>         # 挖掘
+python tools/oni_api.py build <id> <x> <y>          # 建造
+python tools/oni_api.py deconstruct <x> <y>         # 拆除
+python tools/oni_api.py prioritize <x> <y> <1-9>    # 优先级
+python tools/oni_api.py research_select <techId>    # 科研
+python tools/oni_api.py mop <x> <y>                 # 清理
+python tools/oni_api.py harvest <x> <y>             # 收获
+python tools/oni_api.py pause [reason]              # 暂停
+python tools/oni_api.py unpause [speed]             # 恢复
+python tools/oni_api.py speed <1-3>                 # 速度
+python tools/oni_api.py camera <x> <y> [zoom]       # 视角
+python tools/oni_api.py batch <file>                # 批量
+python tools/oni_api.py save [name]                 # 存档
+python tools/oni_api.py load <name>                 # 读档
+python tools/oni_api.py priority_global <t> <p>     # 全局优先级
+python tools/oni_api.py priority_type <t> <p>       # 类型优先级
 ```

 ### `tools/oni_analyzer.py` — 智能分析器

-自动拉取全方位游戏状态，分析六大维度并生成可操作建议。
-
 ```bash
-python3 tools/oni_analyzer.py
+python tools/oni_analyzer.py
+# 分析：氧气/食物/电力/温度/水/科研 六维度 + 建议
 ```

-分析内容：
- 氧气供应状态 → 建议 SPOM 建造时机
- 食物储备 → 建议扩建农场/养殖
- 电力状况 → 建议新增发电类型
- 温度异常 → 建议冷却方案
- 水资源 → 建议过滤/收集策略
- 科研进度 → 建议下一个研究方向
-
-### `tools/oni_builder.py` — 蓝图建造器
-
-预置常用建筑模块，一键部署。
+### `tools/oni_builder.py` — 蓝图

 ```bash
-python3 tools/oni_builder.py list          # 列出所有蓝图
-python3 tools/oni_builder.py build spom 42 42  # 建造 SPOM
+python tools/oni_builder.py list           # 列出蓝图
+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 |
-| `spom_mini` | 紧凑型 SPOM（前期过渡用） | 5×4 |
-| `toilet_loop` | 卫生间水循环（厕所→净水器→厕所） | 8×4 |
-| `ranch_hatch` | 哈奇养殖模块 | 10×6 |
-| `farm_mealwood` | 浆果农场（6个种植箱+储物箱） | 6×4 |
-| `cooling` | 蒸汽涡轮冷却模块 | 8×6 |
-| `bedroom` | 标准卧室（床+梯子床+装饰） | 8×4 |
+| 健康 | `/health` | GET |
+| 状态 | `/api/state/game`, `resources`, `buildings`, `duplicants`, `research`, `rooms`, `alert`, `camera`, `storage`, `saves`, `events` | GET |
+| 地图 | `/api/state/cell`, `cells`, `cells/slice`, `gas` | GET |
+| 注册表 | `/api/registry/buildings`, `elements`, `techs` | GET |
+| 截图 | `/api/screenshot/latest` | GET |
+| 操作 | `/api/action/pause`, `unpause`, `speed`, `dig`, `build`, `deconstruct`, `prioritize`, `research`, `mop`, `harvest`, `batch`, `save`, `load`, `camera`, `priority_global`, `priority_type` | POST |
+| | **所有操作自动拉视角到坐标** | |

-### `scripts/event_daemon.py` — 事件守护进程（AI 输入源）
-
-持续轮询游戏事件并将其注入 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 |
+错误格式：`{success: false, error: "...", errorMessage: "..."}`

 ## 项目结构

 ```
 oni-agent/
-├── README.md                  # ← 本文件
-├── config.json                # Mod 连接配置（host/port/timeout）
-├── SKILL.md                   # AI Agent skill 定义与操作手册
-│
-├── mod/                       # 游戏 Mod（C# / Harmony）
-│   ├── mod_info.yaml          # Mod 元信息（标题/版本/兼容性）
-│   └── ONIAgentBridge.cs      # HTTP API 服务实现
-│
-├── tools/                     # Python 工具链
-│   ├── oni_api.py             # API 客户端（20+ 子命令）
-│   ├── oni_analyzer.py        # 状态分析（6维度预警+建议）
-│   └── oni_builder.py         # 蓝图建造（7个预置模块）
-│
-├── scripts/                   # 辅助脚本
-│   ├── setup.sh               # 环境初始化
-│   ├── auto_repair.sh         # 连接诊断
-│   ├── auto_analyze.sh        # 一键分析
-│   ├── watch.sh               # 持续监控模式
-│   └── event_daemon.py        # 事件守护进程（AI 实时输入源）
-│
+├── README.md
+├── SKILL.md                      # AI Agent 完整缺氧教程
+├── config.json                   # Mod 连接配置
+├── mod/
+│   ├── ONIAgentBridge.cs         # Mod 源码 (C# Harmony)
+│   ├── ONIAgentBridge.csproj
+│   ├── mod.yaml / mod_info.yaml
+├── tools/
+│   ├── oni_api.py                # CLI 客户端 (20+ 子命令)
+│   ├── oni_analyzer.py           # 六维度分析
+│   ├── oni_builder.py            # 蓝图建造
+│   └── oni_commander.py          # 高级指令
+├── scripts/
+│   ├── event_daemon.py           # 事件守护进程
+│   ├── build_mod.sh              # 编译脚本
+│   └── setup.sh                  # 环境初始化
 ├── docs/
-│   ├── MOD_DEV_GUIDE.md       # Mod 开发规范与约束
-│   ├── AI_KNOWLEDGE_BASE.md   # 200+ 建筑/元素/科技 ID 知识库
-│   └── batch_example.json     # 批量任务示例文件
-│
+│   ├── AI_KNOWLEDGE_BASE.md      # AI 知识库
+│   └── MOD_DEV_GUIDE.md          # Mod 开发指南
 └── skills/
-    └── oni_agent.md           # Agent skill 定义
+    └── oni_agent.md              # Agent skill 定义
 ```

 ## 文档索引

-| 文档 | 目标读者 | 内容 |
-|------|---------|------|
-| `SKILL.md` | AI Agent | 坐标系理解、API 用途、场景推理示例、操作表述规范 |
-| `docs/AI_KNOWLEDGE_BASE.md` | AI Agent | 建筑 ID 对照表、元素属性、科技树、游戏机制参考 |
-| `docs/MOD_DEV_GUIDE.md` | Mod 开发者 | 通信协议、端点规范、安全约束、检查清单 |
+| 文档 | 目标 | 内容 |
+|------|------|------|
+| `SKILL.md` | AI Agent | 完整游玩教程：分阶段目标/材料/可达性/方块/操作协议 |
+| `docs/AI_KNOWLEDGE_BASE.md` | AI Agent | 建筑ID/元素属性/科技树/游戏机制参考 |
 | `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