docs: add AI skill guide with comprehensive API purpose documentation

- README.md: add summary paragraph covering 92 endpoints, screenshot/camera, event daemon, Mod+Python+AI architecture - skills/oni_agent.md: complete rewrite from 42 to 480 lines: - Gameplay overview (survival priorities, world rules) - All 92 API endpoints organized in 12 categories - Each command annotated with: what player action it maps to, what AI uses it for, example output - Coordinate positioning methods (4 strategies) - Common scenario query paths (suffocating, power, research, pipes) - Quick reference for emergency operations
2026-05-22 10:02:25 +08:00
parent 48dd1075ed
commit 6a71d42f78
2 changed files with 453 additions and 29 deletions
--- a/README.md
+++ b/README.md
@ -1,6 +1,6 @@
 # ONI Agent — 缺氧 AI 助手工具集

-[Oxygen Not Included](https://www.kleientertainment.com/games/oxygen-not-included)（《缺氧》）的 AI Agent 工具集。包含一个游戏内 Mod 作为 HTTP API 服务，以及配套的 Python 工具链，让 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 的模型都能像人类一样操作游戏。

 ## 整体架构

--- a/skills/oni_agent.md
+++ b/skills/oni_agent.md
@ -1,42 +1,466 @@
 # ONI Agent Skill

+AI 操作《缺氧》(Oxygen Not Included) 的完整技能定义。
+
 ## 触发条件
 - 用户提到《缺氧》/ Oxygen Not Included / ONI
 - 用户询问游戏策略、建造方案、资源管理
 - 用户希望 Mod 工具链执行操作
+- 用户需要实时游戏操作协助

-## 能力
-1. 通过 `tools/oni_api.py` 查询游戏状态
-2. 通过 `tools/oni_analyzer.py` 分析并生成建议
-3. 通过 `tools/oni_builder.py` 执行蓝图建造
-4. 通过 `scripts/auto_repair.sh` 诊断连接问题
-5. 通过 `scripts/watch.sh` 持续监控
+## 游戏核心玩法

-## 常用操作
+缺氧是一款太空殖民模拟游戏。核心目标是在恶劣环境中维持复制人的生存并建设可持续基地。
+
+### 生存要素优先级
+
+| 优先级 | 要素 | 危险条件 | 后果 | 解决方案路线 |
+|--------|------|---------|------|-------------|
+| ★★★ | 氧气 | O₂ < 500 kg 或无制氧设备 | 复制人 110s 内窒息死亡 | 藻类制氧(前期) → 电解器+氢气发电(SPOM) |
+| ★★★ | 食物 | Calories < 1000 kcal/人 | 复制人饿死 | 浆果种植 → 烤肉 → 营养膏棒 |
+| ★★☆ | 温度 | > 40°C 或 < 10°C | 作物枯萎/复制人受伤 | 隔热/液冷+蒸汽机/加热 |
+| ★★☆ | 电力 | 电量不足/电路过载 | 设备停摆/电线起火 | 手动→煤→氢→天然气→太阳能 |
+| ★☆☆ | 士气 | Stress > 80% | 精神崩溃/破坏设备 | 房间奖励/装饰/按摩/高品质食物 |
+| ★☆☆ | 病菌 | Slimelung/Food Poisoning | 生病死亡 | 洗手/净化/消毒/氧气服 |
+
+### 游戏世界规则
+
+- 二维网格地图，原点 (0,0) 在左下角，x 向右 y 向上
+- 气体按密度分层：CO₂(沉底) < PollutedO₂ < O₂ < NaturalGas < H₂(上升)
+- 建筑占用 w×h 格子，坐标指左下角锚点
+- 科技通过研究站→超级计算机逐步解锁新建筑
+- 每 3 周期传送舱提供一次新复制人或补给选择
+
+---
+
+## API 总览（92 个端点）
+
+工具链让 AI 能像人类玩家一样理解游戏并执行操作。所有 API 通过 `tools/oni_api.py` 命令行调用。
+
+### 一、状态查询 — 理解"当前发生了什么"
+
+每次 AI 推理前工具自动暂停游戏，保证数据时效性。AI 操作完成后主动 unpause。

 ```bash
-# 检查连接
-python3 tools/oni_api.py health
-
-# 游戏总览
+# 全局总览 — 最常用的命令
 python3 tools/oni_api.py status
+# 输出：周期、窒息人数、饥饿人数、压力人数、是否暂停、游戏速度

-# 分析报告
-python3 tools/oni_analyzer.py
-
-# 查看蓝图
-python3 tools/oni_builder.py list
-
-# 建造 SPOM （SPOM = Self-Powered Oxygen Module）
-# 偏移坐标 (origin_x, origin_y) 为模块左下角
-python3 tools/oni_builder.py build spom 15 10
-
-# 持续监控（每 60 秒刷新）
-bash scripts/watch.sh 60
+# 全面诊断
+python3 tools/oni_commander.py diagnose
+# 输出：电力+CO₂+温度+疾病+管道的完整报告
 ```

-## 核心知识
- SPOM：电解制氧 + 氢气发电闭环
- 卫生间水循环：卫生间 → 净水器 → 卫生间
- 冷却系统：液冷机 + 蒸汽机 + 导热管
- 养殖模块：哈奇/滑鳞/飞鱼
+**各状态查询命令的用途：**
+
+| 命令 | 等价于玩家做什么 | AI 用它做什么 |
+|------|-----------------|-------------|
+| `status` | 看一眼基地总览面板 | 快速评估危机：有人在窒息吗？在挨饿吗？ |
+| `resources` | 打开资源面板 | 检查氧气储量够多久、煤还剩多少 |
+| `duplicants` | 逐一查看每个复制人 | 谁在窒息？谁压力爆了？谁没事干？ |
+| `buildings` | 按分类查看建筑 | 数一数有多少发电机、电解器、种植箱 |
+| `power` | 打开电力覆盖层 | 哪个电路过载了？负载多少？ |
+| `co2` | 看 CO₂ 在哪聚集 | CO₂ 是前中期最大杀手，找到它并挖排气道 |
+| `temp_zones` | 看温度覆盖层 | 找到过热区域（>50°C）和过冷区域（<5°C） |
+| `pipes gas/liquid` | 点开管道看看 | 管道堵塞了吗？内容物在流动吗？ |
+| `rooms` | 打开房间覆盖层 | 确认宿舍/卫生间/餐厅生效了吗 |
+| `morale` | 查看士气面板 | 士气够不够支撑当前技能数 |
+| `diseases` | 打开病菌覆盖层 | 谁被感染了？环境病菌多吗？ |
+| `storage` | 查看储物建筑 | 储备粮在哪、存了多少 |
+| `storages` | 同上 | 同 storage |
+| `resources` | 资源面板 | 所有物资的精确余量 |
+| `skills` | 技能面板 | 每个复制人的属性值和已学技能 |
+| `research` | 科技树 | 哪些科技已完成、哪些可研究 |
+| `research_detail` | 点开研究站 | 研究站在工作吗？现在在研究什么？ |
+| `buildable` | 建造菜单 | 当前科技解锁了哪些建筑 |
+| `geysers` | 查看喷泉 | 找到水源/天然气/火山位置 |
+| `critters` | 查看生物 | 哈奇/飞鱼/滑鳞的数量和位置 |
+| `plants` | 查看植物 | 作物生长进度、是否枯萎 |
+
+### 二、格子地图 — 理解"每个格子有什么"
+
+所有建造操作前必须先用格子查询确认位置。
+
+```bash
+# 查看单个格子（最常用）
+python3 tools/oni_api.py cell 45 48
+# 输出：元素、温度、有无建筑、有无复制人、是否可挖掘、是否安全
+
+# 查看 10x10 区域
+python3 tools/oni_api.py cells 40 40 10 10
+# 输出：区域内所有格子的地图 + AI 友好摘要
+
+# 扫描某一行/列
+python3 tools/oni_api.py slice y 20 0 50
+# 输出：第 20 行从 0 到 50 的每个格子
+
+# 气体分析
+python3 tools/oni_api.py gas 50 50 30
+# 输出：以 50,50 为中心半径 30 内的气体分布
+
+# AI 友好区域探索
+python3 tools/oni_api.py explore 40 40 20 20
+# 输出：区域内建筑列表+复制人+元素摘要+感兴趣格子
+```
+
+**AI 坐标定位方法：**
+
+```
+方法 1: buildings → 查已有建筑坐标 → 在附近偏移找空地
+方法 2: explore <x> <y> <w> <h> → 找 buildings_in_region 为空的区域
+方法 3: cell <x> <y> → 确认 isSolid=false + hasBuilding=false + isVisible=true
+方法 4: co2 → 在 CO₂ 聚集点下方挖排气通道
+方法 5: gas → 在气体聚集区放气体泵
+```
+
+### 三、实体注册表 — "这个建筑是什么"
+
+AI 在运行时查询任何不懂的 ID：
+
+```bash
+# 查建筑
+python3 tools/oni_api.py registry buildings Electrolyzer
+# 输出：名称、分类、尺寸(2x2)、功耗(120W)、所需材料
+
+# 查元素
+python3 tools/oni_api.py registry elements Water
+# 输出：比热容、导热系数、沸点(99°C)、物态
+
+# 查科技
+python3 tools/oni_api.py registry techs ImprovedOxygen
+# 输出：前置科技、解锁建筑(Electrolyzer)
+
+# 查优先级含义
+python3 tools/oni_api.py registry priorities
+# 输出：1=最低 5=默认 9=紧急
+```
+
+### 四、建造操作 — "建造世界"
+
+建造 = 挖掘(dig) → 放置(build)。坐标是建筑左下角。
+
+```bash
+# 挖掘区域
+python3 tools/oni_api.py dig 40 40 10 10
+# 在 (40,40) 处挖一个 10x10 的空间
+
+# 放置建筑
+python3 tools/oni_api.py build Electrolyzer 45 42
+# 在 (45,42) 放电解器（左下角定位，占 2x2 格）
+
+# 铺设管路
+python3 tools/oni_api.py build_pipe_line liquid 42 40 48 40 line
+# 从 (42,40) 到 (48,40) 铺液体管道
+# mode=line: 与已有管线合并
+# mode=cross: 交叉处自动用跨接器跳过
+# mode=single: 单段
+
+# 铺设电线
+python3 tools/oni_api.py build_wire_line heavy 30 20 45 20 cross
+# 从 (30,20) 到 (45,20) 铺重载电线
+# 交叉处用跨接器不连通
+
+# 拆除
+python3 tools/oni_api.py deconstruct Tile 42 45
+# 拆除 (42,45) 处的 Tile
+
+# 旋转
+python3 tools/oni_api.py rotate 45 48
+# 旋转 (45,48) 处的建筑
+
+# 清碎片
+python3 tools/oni_api.py clear 40 40 5
+# 清除 (40,40) 半径 5 内的碎片
+
+# 复制设置
+python3 tools/oni_api.py copy_settings 45 48 50 48
+# 把 (45,48) 建筑的设置复制到 (50,48)
+```
+
+### 五、建筑操作 — "使用已建成的建筑"
+
+相当于玩家点击建筑后选择功能。
+
+```bash
+# 开关
+python3 tools/oni_api.py toggle 45 42
+# 关闭/打开电解器（省电或恢复运行）
+
+# 设优先级
+python3 tools/oni_api.py set_building_priority 45 42 9
+# 电解器优先级设为 9（紧急）
+
+# 设配方
+python3 tools/oni_api.py set_recipe 30 25 Crush
+# 碎岩机设为粉碎模式
+
+# 开关自动化
+python3 tools/oni_api.py set_automation 45 42 on
+# 电解器开启自动化控制
+
+# 清空储物
+python3 tools/oni_api.py empty 50 50
+# 清空 (50,50) 储物箱全部内容
+
+# 设储物过滤
+python3 tools/oni_api.py storage_filter 50 50 Coal
+# 储物箱只收煤炭
+
+# 设冰箱温度
+python3 tools/oni_api.py fridge_temp 60 30 2
+# 冰箱设为 2°C
+
+# 设电池充放电阈值
+python3 tools/oni_api.py battery_charge 35 25 90 20
+# 智能电池 90% 停充、20% 启动
+
+# 设阀门流量
+python3 tools/oni_api.py valve_flow 42 42 1000
+# 阀门限流 1000g/s
+
+# 设排气口压力
+python3 tools/oni_api.py vent_pressure 45 50 2000
+# 高压排气口设为 2000g
+
+# 设孵化器
+python3 tools/oni_api.py incubator_setting 50 40 HatchEgg
+# 孵化器优先孵哈奇蛋
+
+# 设传感器阈值
+python3 tools/oni_api.py sensor_threshold 70 30 500
+# 气压传感器阈值 500g
+
+# 消毒
+python3 tools/oni_api.py disinfect 42 42
+# 对 (42,42) 消毒
+
+# 清扫
+python3 tools/oni_api.py sweep 40 40 10
+# 标记 (40,40) 半径 10 内的物品为待清扫
+
+# 取消任务
+python3 tools/oni_api.py cancel_errand 45 42
+# 取消电解器处的排队任务
+```
+
+### 六、门控制
+
+```bash
+# 锁门
+python3 tools/oni_api.py door_lock 42 45 on
+# 锁上 (42,45) 的门，复制人不能通过
+
+# 单向通行
+python3 tools/oni_api.py door_one_way 42 45 left
+# 门只允许向左通过
+
+# 手动开门/关门
+python3 tools/oni_api.py door_open 42 45 off
+# 手动关闭 (42,45) 的门
+```
+
+### 七、复制人管理
+
+```bash
+# 移动复制人
+python3 tools/oni_api.py dupe_move Dup1 30 25
+# 命令 Dup1 移动到 (30,25)
+
+# 取消任务
+python3 tools/oni_api.py dupe_cancel_task Dup1
+# 命令 Dup1 取消当前正在做的事
+
+# 分配工作
+python3 tools/oni_api.py assign_job Dup1 Dig
+# 让 Dup1 专注挖掘工作
+
+# 个人优先级
+python3 tools/oni_api.py dupe_personal_priority Dup1 Dig 9
+# Dup1 的挖掘优先级设为 9（最高）
+```
+
+### 八、科研管理
+
+```bash
+# 查看研究状态
+python3 tools/oni_api.py research_detail
+# 输出：研究站是否工作、当前研究什么、超级计算机是否造好
+
+# 选择研究
+python3 tools/oni_api.py research_select ImprovedOxygen
+# 开始研究 ImprovedOxygen
+
+# 取消研究
+python3 tools/oni_api.py research_cancel
+# 取消全部当前研究
+```
+
+### 九、生物/植物管理
+
+```bash
+# 攻击生物
+python3 tools/oni_api.py critter_attack 120 80
+# 标记 (120,80) 的生物为攻击目标
+
+# 抓捕生物
+python3 tools/oni_api.py critter_wrangle 120 80
+# 抓捕 (120,80) 的生物运到存放点
+
+# 收获植物
+python3 tools/oni_api.py harvest 50 45
+# 收获 (50,45) 的成熟作物
+
+# 拔除植物
+python3 tools/oni_api.py plant_uproot 50 45
+# 拔掉 (50,45) 的植物
+```
+
+### 十、游戏控制
+
+```bash
+# 暂停/恢复
+python3 tools/oni_api.py pause "Building SPOM"
+python3 tools/oni_api.py unpause 1
+
+# 速度
+python3 tools/oni_api.py speed 3
+
+# 存档回滚
+python3 tools/oni_api.py save "before_experiment"
+python3 tools/oni_api.py saves
+python3 tools/oni_api.py load "before_experiment"
+
+# 截图视角
+python3 tools/oni_api.py snapshot /tmp/now.png
+python3 tools/oni_api.py camera 120 80 20
+
+# 覆盖层切换
+python3 tools/oni_api.py overlay power
+python3 tools/oni_api.py overlay temp
+python3 tools/oni_api.py overlay gas
+python3 tools/oni_api.py overlay rooms
+
+# 传送舱
+python3 tools/oni_api.py printing_pod
+python3 tools/oni_api.py printing_pod_select 0
+```
+
+### 十一、批量操作
+
+```bash
+python3 tools/oni_api.py batch docs/batch_example.json
+# 一次执行多个动作，逐个报告结果
+```
+
+### 十二、高级指令
+
+```bash
+# 全面诊断
+python3 tools/oni_commander.py diagnose
+
+# 自动处理 CO₂
+python3 tools/oni_commander.py fix_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
+```
+
+---
+
+## 常见场景查询路线
+
+### "复制人要窒息了"
+```
+status → 看 suffocating 计数
+duplicants → 找 oxygen < 20 的复制人
+cell <窒息复制人坐标> → 所在格子的元素
+co2 → 如果是 CO₂ 窒息，fix_co2 挖排气道
+resources → O₂ 存量和 Algae 存量
+buildings → 过滤 Oxygen 分类看有无制氧设备
+无设备 → emergency_o2 或 build OxygenDiffuser
+```
+
+### "基地没电了"
+```
+power → 看各电路负载和过载
+resources → Coal/Hydrogen/NaturalGas 存量
+buildings → Power 分类有哪些发电机
+过载 → fix_overload
+缺电 → 根据资源选发电机类型
+```
+
+### "研究卡住了"
+```
+research_detail → 研究站通不通电、有没有复制人在研究
+building_detail <研究站坐标> → 供上电了吗
+resources → Dirt 够吗（研究站消耗）
+需超级计算机 → build SuperComputer <坐标>
+```
+
+### "管道不走了"
+```
+pipes liquid → 看管道内容
+building_detail <水泵> → 泵有没有电
+building_detail <目的地建筑> → 输入是否已满
+build_pipe_line liquid <起点> <终点> cross → 重建
+```
+
+### "传送舱来了"
+```
+event_daemon 显示 [EVENT] Printing Pod ready
+printing_pod → 看选项
+printing_pod_select 0|1|2 → 选择
+```
+
+---
+
+## AI 操作铁律
+
+```
+铁律 1: AI 开始推理/决策前 → 工具自动暂停游戏
+铁律 2: AI 需要问用户时 → 工具自动暂停
+铁律 3: AI 退出回答时 → 确保游戏已暂停（无人监控时不能运行）
+铁律 4: 写操作前 → 工具自动确保暂停态
+铁律 5: 重大操作前 → save 存档，失败可 load 回滚
+铁律 6: 每次操作后检查反馈 → 读 error + errorMessage + suggestion
+```
+
+## 工具列表
+
+| 工具 | 用途 |
+|------|------|
+| `tools/oni_api.py` | 92 个 API 端点的 CLI 客户端（所有查询/操作） |
+| `tools/oni_commander.py` | 高级指令（diagnose/fix_co2/expand_base 等） |
+| `tools/oni_analyzer.py` | 自动分析+6 维度预警建议 |
+| `tools/oni_builder.py` | 预置 SPOM/农场/养殖等蓝图 |
+| `scripts/event_daemon.py` | 事件守护进程，持续轮询推送游戏事件到 AI |
+
+## 常用操作速查
+
+```bash
+# 每分钟检查
+python3 scripts/event_daemon.py
+
+# 紧急三步
+python3 tools/oni_api.py pause "Emergency"
+python3 tools/oni_commander.py diagnose
+python3 tools/oni_api.py status
+# ...操作...
+python3 tools/oni_api.py unpause 1
+
+# 存档保护
+python3 tools/oni_api.py save "before_操作"
+# ...操作...
+# 如果搞砸了：
+python3 tools/oni_api.py load "before_操作"
+
+# 截图确认
+python3 tools/oni_api.py camera 50 50 20
+python3 tools/oni_api.py snapshot
+```