feat: comprehensive AI-oriented data model with cell-level map API and knowledge base

- Add cell/tile map APIs: /api/state/cell, /api/state/cells, /api/state/cells/slice, /api/state/gas - Add entity registry APIs: /api/registry/buildings, /api/registry/elements, /api/registry/techs - Add plants, rooms, mop, harvest endpoints - Rich semantic metadata: element state/category, building category/power, duplicant chore/cell - AI-friendly coordinate system with (x,y) + cell index in all responses - Build AI_KNOWLEDGE_BASE.md with building IDs, element IDs, tech trees, game mechanics - Rewrite SKILL.md with data model explanation, coordinate guide, operation patterns - Update Python tools: explore, cell, cells, slice, gas, registry subcommands - Update MOD_DEV_GUIDE.md with AI data design principles
2026-05-22 08:54:03 +08:00
parent 0e17e8a6ac
commit 6a7ac87c1b
6 changed files with 1775 additions and 341 deletions
--- a/SKILL.md
+++ b/SKILL.md
@ -3,75 +3,283 @@
 ## 职责
 协助玩家操作和管理游戏"缺氧"(Oxygen Not Included)，提供游戏知识、策略建议，并通过 Mod API 直接操控游戏。

+## 工程结构
+
+```
+oni-agent/
+├── config.json              # Mod 连接配置
+├── mod/
+│   ├── mod_info.yaml        # Mod 元信息
+│   └── ONIAgentBridge.cs    # Mod HTTP API 服务 (端口 23876)
+├── tools/
+│   ├── oni_api.py           # Mod API 客户端
+│   ├── oni_analyzer.py      # 游戏状态分析
+│   └── oni_builder.py       # 蓝图建造规划
+├── scripts/
+│   ├── auto_repair.sh       # 连接诊断
+│   ├── auto_analyze.sh      # 一键分析
+│   ├── watch.sh             # 持续监控
+│   └── setup.sh             # 环境初始化
+├── docs/
+│   ├── MOD_DEV_GUIDE.md     # Mod 开发指南
+│   └── AI_KNOWLEDGE_BASE.md # AI 知识库 (ID注册表/语义标签)
+├── skills/
+│   └── oni_agent.md         # Agent skill 定义
+└── SKILL.md                 # 本文件
+```
+
+---
+
+## 重要概念：理解 ONI 的数据模型
+
+### 1. 坐标系
+
+ONI 使用二维方格（tile）系统。AI 必须理解坐标系才能正确操作：
+
+```
+  y ▲
+    │  ┌────┬────┬────┐
+    │  │(5,5)│(6,5)│(7,5)│
+    │  ├────┼────┼────┤
+    │  │(5,4)│(6,4)│(7,4)│   ← 这个格子 (6,4) 包含一个电解器
+    │  ├────┼────┼────┤
+    │  │(5,3)│(6,3)│(7,3)│
+    │  └────┴────┴────┘
+    └──────────────────────────► x
+   (0,0)
+```
+
+- **原点 (0,0)** 在地图**左下角**
+- **x 轴**向右增加，**y 轴**向上增加
+- 每个格子 (cell) 有唯一的 (x, y) 坐标
+- 建筑占用 w×h 个格子，其坐标是**左下角锚点**
+- 世界大小通过 `/api/state/game` 查询（`gridWidth` x `gridHeight`）
+- 典型地图: ~256 x 384 格
+
+### 2. 理解格子状态
+
+每格的数据结构如下（通过 `/api/state/cell?x=&y=` 查询）：
+
+```json
+{
+  "x": 10, "y": 5,
+  "element": "Oxygen",           // 该格包含的元素名称
+  "elementState": "gas",         // solid/liquid/gas/vacuum
+  "massKg": 1.8,                 // 该格中元素的质量
+  "temperatureC": 23.5,          // 温度(摄氏度)
+  "hasBuilding": true,           // 是否有建筑
+  "buildingName": "Electrolyzer",// 建筑名称(如有)
+  "hasDuplicant": false,         // 是否有复制人
+  "isVacuum": false,             // 是否为真空
+  "isSolid": false,              // 是否为固体
+  "isLiquid": false,
+  "isGas": true,
+  "isVisible": true              // 是否已探索
+}
+```
+
+### 3. 理解地图区域
+
+通过 `/api/state/cells?x=&y=&width=&height=` 获取矩形区域的格子数组。
+
+通过 `explore <x> <y> <w> <h>` 命令获取 AI 友好的结构化摘要：
+- 该区域的建筑列表（带是否可运行）
+- 该区域的复制人列表（带压力/当前任务）
+- 元素分布统计
+- 感兴趣的关键格子
+
+---
+
 ## 通信方式
+
 - Mod 在游戏内启动 HTTP 服务，暴露 RESTful API
 - 通过 `http://127.0.0.1:PORT` 与游戏通信
 - 端口在 `oni-agent/config.json` 中配置（默认 23876）

+---
+
 ## 可用 API 端点

 ### 状态查询 (GET)
-| 端点 | 返回内容 |
-|------|---------|
-| `/api/state/game` | 周期、复制人数量、全局资源 |
-| `/api/state/resources` | 所有主要资源存量 |
-| `/api/state/duplicants` | 所有复制人状态 |
-| `/api/state/buildings` | 所有建筑列表 |
-| `/api/state/research` | 科技树进度 |
-| `/api/state/geysers` | 喷泉状态 |
-| `/api/state/alert` | 当前警报 |
-| `/api/state/critters` | 小动物状态 |
+
+| 端点 | 说明 | 用途 |
+|------|------|------|
+| `/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` | 房间（类型/格数/建筑数） | 房间判定 |
+
+### 地图/格子数据 (GET)
+
+| 端点 | 说明 | 示例 |
+|------|------|------|
+| `/api/state/cell?x=10&y=5` | 单格详情 | 查看某个格子是气体/液体/建筑 |
+| `/api/state/cells?x=0&y=0&width=10&height=10` | 矩形区域 | 查看 10x10 区域 |
+| `/api/state/cells/slice?axis=y&index=20&start=0&end=50` | 行/列扫描 | 查看第 20 行 |
+| `/api/state/gas?x=10&y=10&radius=20` | 区域气体分析 | 查看周围气体成分 |
+
+### 实体注册表 (GET，AI 参考用)
+
+| 端点 | 说明 |
+|------|------|
+| `/api/registry/buildings` | 所有建筑 ID 及尺寸/功耗/发热 |
+| `/api/registry/elements` | 所有元素 ID 及比热容/导热/熔沸点 |
+| `/api/registry/techs` | 所有科技 ID 及前置/解锁内容 |

 ### 操作 (POST)
-| 端点 | 请求体 |
-|------|--------|
-| `/api/action/dig` | `{x, y, width, height}` |
-| `/api/action/build` | `{buildingId, x, y, rotation?}` |
-| `/api/action/deconstruct` | `{buildingId, x, y}` |
-| `/api/action/prioritize` | `{x, y, priority}` |
-| `/api/action/research` | `{techId}` |
-| `/api/action/schedule` | `{duplicantId, schedule}` |
-| `/api/action/wardrobe` | `{duplicantId, equipment}` |
+
+| 端点 | 请求体 | 用途 |
+|------|--------|------|
+| `/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}` | 收获植物 |
+
+---
+
+## AI 如何进行推理和操作
+
+### 第一步：获取全局上下文
+
+```bash
+python3 tools/oni_api.py status
+python3 tools/oni_api.py buildings
+python3 tools/oni_analyzer.py
+```
+
+### 第二步：理解地图
+
+```bash
+# 探索基地中心区域（假设基地在 50,50）
+python3 tools/oni_api.py explore 40 40 40 30
+
+# 检查某个格子的详细信息
+python3 tools/oni_api.py cell 45 48
+
+# 查看气体分布
+python3 tools/oni_api.py gas 50 50 30
+```
+
+### 第三步：参考知识库
+
+```bash
+# 查找某个建筑的 ID
+python3 tools/oni_api.py registry buildings Electrolyzer
+
+# 查看元素属性
+python3 tools/oni_api.py registry elements Water
+
+# 查看科技树
+python3 tools/oni_api.py registry techs
+```
+
+### 第四步：执行操作
+
+```bash
+# 建造电解器
+python3 tools/oni_api.py build Electrolyzer 45 48
+
+# 挖掘空间
+python3 tools/oni_api.py dig 40 45 8 6
+
+# 选择科研方向
+python3 tools/oni_api.py research_select ImprovedOxygen
+
+# 使用蓝图
+python3 tools/oni_builder.py build spom 42 42
+```
+
+---
+
+## AI 如何理解常见游戏场景
+
+### 场景 1：氧气不足
+
+**AI 推理过程：**
+1. 检查 `/api/state/resources` 中的 O2 和 Algae 存量
+2. 检查 `/api/state/buildings` 是否有电解器或氧气扩散器
+3. 检查 `/api/state/cell?x=&y=` 查询基地气体分布
+4. 如果 Algae < 1t 且无电解器 → 建议建造 SPOM
+5. SPOM 需要：水源 + 电解器 + 气体泵 + 氢气发电机 + 气体过滤器
+6. 通过 `explore` 找到一个 8x6 的空地
+7. 执行 `build Electrolyzer x y` + `build GasPump ...` + `build HydrogenGenerator ...`
+
+### 场景 2：食物短缺
+
+**AI 推理过程：**
+1. 检查 Calories < 500,000 kcal → 食物预警
+2. 检查是否有 PlanterBox/FarmTile 和 ElectricGrill
+3. 如果没有农场 → 建议建造 5 个 PlanterBox 种 Mealwood
+4. Mealwood 不需要灌溉或施肥，只需 Dirt
+5. 检查 Dirt 存量，如果足够 → 执行建造
+6. 如果有污水 → 建议建造 Water Sieve + 厕所水循环
+
+### 场景 3：温度过高
+
+**AI 推理过程：**
+1. 检查温度数据（通过资源中的 Temperature 或格子数据）
+2. 查看热源（煤发电机、精炼厂等靠近基地的位置）
+3. 建议：用隔热门包围热源 + 建造液冷模块
+4. 液冷模块需要：Aquatuner + SteamTurbine + 导热液体管道
+
+---
+
+## AI 如何表达"在哪个格子做什么"
+
+### 定位语法
+
+AI 在描述操作时应使用以下格式：
+
+```
+在坐标 (x, y) 建造 <buildingId>
+在区域 (x, y, width, height) 进行挖掘
+从 (x1,y1) 到 (x2,y2) 铺设管道/电线
+在格子 (x, y) 设置优先级为 <priority>
+```
+
+### 坐标查找策略
+
+当 AI 不确定在哪里建造时：
+1. 先用 `explore` 找一个空闲区域（没有建筑和固体阻挡）
+2. 检查空闲区域的元素和温度是否适合
+3. 用 `cell` 命令确认目标格子状态
+4. 然后用 `dig` 清理空间
+5. 最后用 `build` 建造
+
+### 建筑放置规则
+
+- 建筑坐标是其**左下角**的位置
+- 建筑占用的 w×h 区域必须全部是空地
+- 需要确认目标区域无建筑、无固体自然方块
+- 气体/液体不会阻挡建筑
+- 如果建筑需要特定环境（如电解器需要水），AI 需要先检查环境
+
+---

 ## 工具列表

 | 工具 | 用途 |
 |------|------|
-| `tools/oni_api.py` | 与 Mod HTTP API 通信 |
-| `tools/oni_analyzer.py` | 分析游戏状态、生成建议 |
-| `tools/oni_builder.py` | 蓝图/建造规划 |
-| `scripts/auto_repair.sh` | 诊断连接问题 |
-| `scripts/auto_analyze.sh` | 一键拉取状态+分析 |
-| `scripts/watch.sh` | 持续监控模式 |
-| `scripts/setup.sh` | 环境初始化 |
+| `tools/oni_api.py` | 与 Mod HTTP API 通信（所有查询/操作） |
+| `tools/oni_analyzer.py` | 自动分析游戏状态、生成预警和建议 |
+| `tools/oni_builder.py` | 预置蓝图建造（SPOM/农场/养殖等） |
+| `scripts/auto_repair.sh` | 诊断 Mod 连接问题 |
+| `scripts/auto_analyze.sh` | 一键健康检查+状态+分析 |
+| `scripts/watch.sh [秒]` | 循环监控模式 |
+| `scripts/setup.sh` | 环境初始化与检查 |
+| `docs/AI_KNOWLEDGE_BASE.md` | 建筑/元素/科技 ID 注册表和游戏机制参考 |

-## 使用方式
-
-```bash
-# 检查游戏连接
-python3 tools/oni_api.py health
-
-# 获取游戏状态概览
-python3 tools/oni_api.py status
-
-# 列出所有资源
-python3 tools/oni_api.py resources
-
-# 分析并生成建议
-python3 tools/oni_analyzer.py
-
-# 查看可用蓝图
-python3 tools/oni_builder.py list
-
-# 执行建造计划
-python3 tools/oni_builder.py build spom 15 10
-
-# 持续监控（每 60 秒）
-bash scripts/watch.sh 60
-
-# 诊断连接
-bash scripts/auto_repair.sh
-```
+---

 ## 核心游戏知识

@ -83,7 +291,7 @@ bash scripts/auto_repair.sh
 5. **水资源管理** — 净水器、污水过滤

 ### 常用布局
- SPOM (Self-Powered Oxygen Module): 电解制氧 + 氢气发电闭环
+- SPOM: 电解制氧 + 氢气发电闭环
 - 卫生间水循环: 卫生间 → 净水器 → 卫生间
 - 冷却系统: 液冷 + 蒸汽机 + 导热管
 - Ranch 模块: 养殖哈奇/滑鳞/飞鱼