ONI Agent Bridge - initial mod implementation

2026-05-30 11:00:36 +08:00
commit 1f25d3d879
95 changed files with 50686 additions and 0 deletions
--- a/SKILL.md
+++ b/SKILL.md
@ -0,0 +1,489 @@
+# Oxygen Not Included (ONI) Agent
+
+## 职责
+协助玩家操作和管理游<EFBFBD><EFBFBD>?缺氧"(Oxygen Not Included)，提供游戏知识、策略建议，并通过 Mod API 直接操控游戏<E6B8B8><E6888F>?
+## 工程结构
+
+```
+oni-agent/
+├── config.json              # Mod 连接配置
+├── mod/
+<EFBFBD><EFBFBD>?  ├── mod_info.yaml        # Mod 元信<E58583><E4BFA1>?<3F><>?  └── ONIAgentBridge.cs    # Mod HTTP API 服务 (端口 23876)
+├── tools/
+<EFBFBD><EFBFBD>?  ├── oni_api.py           # Mod API 客户<E5AEA2><E688B7>?<3F><>?  ├── oni_analyzer.py      # 游戏状态分<E68081><E58886>?<3F><>?  └── oni_builder.py       # 蓝图建造规<E980A0><E8A784>?├── scripts/
+<EFBFBD><EFBFBD>?  ├── auto_repair.sh       # 连接诊断
+<EFBFBD><EFBFBD>?  ├── auto_analyze.sh      # 一键分<E994AE><E58886>?<3F><>?  ├── watch.sh             # 持续监控
+<EFBFBD><EFBFBD>?  └── setup.sh             # 环境初始<E5889D><E5A78B>?├── docs/
+<EFBFBD><EFBFBD>?  ├── MOD_DEV_GUIDE.md     # Mod 开发指<E58F91><E68C87>?<3F><>?  └── AI_KNOWLEDGE_BASE.md # AI 知识<E79FA5><E8AF86>?(ID注册<E6B3A8><E5868C>?语义标签)
+├── skills/
+<EFBFBD><EFBFBD>?  └── oni_agent.md         # Agent skill 定义
+└── SKILL.md                 # 本文<E69CAC><E69687>?```
+
+---
+
+## 重要概念：理<EFBC9A><E79086>?ONI 的数据模<E68DAE><E6A8A1>?
+### 1. 坐标<E59D90><E6A087>?
+ONI 使用二维方格（tile）系统。AI 必须理解坐标系才能正确操作：
+
+```
+  y <20><>?    <20><>? ┌────┬────┬────<E29480><E29480>?    <20><>? <20><>?5,5)<29><>?6,5)<29><>?7,5)<29><>?    <20><>? ├────┼────┼────<E29480><E29480>?    <20><>? <20><>?5,4)<29><>?6,4)<29><>?7,4)<29><>?  <20><>?这个格子 (6,4) 包含一个电解器
+    <20><>? ├────┼────┼────<E29480><E29480>?    <20><>? <20><>?5,3)<29><>?6,3)<29><>?7,3)<29><>?    <20><>? └────┴────┴────<E29480><E29480>?    └──────────────────────────<E29480><E29480>?x
+   (0,0)
+```
+
+- **原点 (0,0)** 在地<E59CA8><E59CB0>?*左下<E5B7A6><E4B88B>?*
+- **x <20><>?*向右增加<E5A29E><E58AA0>?*y <20><>?*向上增加
+- 每个格子 (cell) 有唯一<E594AF><E4B880>?(x, y) 坐标
+- 建筑占用 w×h 个格子，其坐标是**左下角锚<E8A792><E9949A>?*
+- 世界大小通过 `/api/state/game` 查询（`gridWidth` x `gridHeight`<60><>?- 典型地图: ~256 x 384 <20><>?
+### 2. 理解格子状<E5AD90><E78AB6>?
+每格的数据结构如下（通过 `/api/state/cell?x=&y=` 查询）：
+
+```json
+{
+  "x": 10, "y": 5,
+  "element": "Oxygen",           // 该格包含的元素名<E7B4A0><E5908D>?  "elementState": "gas",         // solid/liquid/gas/vacuum
+  "massKg": 1.8,                 // 该格中元素的质量
+  "temperatureC": 23.5,          // 温度(摄氏<E69184><E6B08F>?
+  "hasBuilding": true,           // 是否有建<E69C89><E5BBBA>?  "buildingName": "Electrolyzer",// 建筑名称(如有)
+  "hasDuplicant": false,         // 是否有复制人
+  "isVacuum": false,             // 是否为真<E4B8BA><E79C9F>?  "isSolid": false,              // 是否为固<E4B8BA><E59BBA>?  "isLiquid": false,
+  "isGas": true,
+  "isVisible": true              // 是否已探<E5B7B2><E68EA2>?}
+```
+
+### 3. 理解地图区域
+
+通过 `/api/state/cells?x=&y=&width=&height=` 获取矩形区域的格子数组<E695B0><E7BB84>?
+通过 `explore <x> <y> <w> <h>` 命令获取 AI 友好的结构化摘要<E69198><E8A681>?- 该区域的建筑列表（带是否可运行）
+- 该区域的复制人列表（带压<E5B8A6><E58E8B>?当前任务<E4BBBB><E58AA1>?- 元素分布统计
+- 感兴趣的关键格子
+
+---
+
+## 通信方式
+
+- Mod 在游戏内启动 HTTP 服务，暴<EFBC8C><E69AB4>?RESTful API
+- 通过 `http://127.0.0.1:PORT` 与游戏通信
+- 端口<E7ABAF><E58FA3>?`config.json` 中配置（默认 23876<37><36>?
+---
+
+## 可用 API 端点
+
+### 状态查<E68081><E69FA5>?(GET)
+
+| 端点 | 说明 | 用<><E794A8>?|
+|------|------|------|
+| `/api/state/buildable` | 当前科技解锁的建<E79A84><E5BBBA>?| 查看 AI 现在能造什<E980A0><E4BB80>?|
+| `/api/state/research` | 科技树（进度/解锁的建筑） | 科研规划 |
+| `/api/state/geysers` | 喷泉（位<EFBC88><E4BD8D>?状<><E78AB6>?排放率） | 资源规划 |
+| `/api/state/alert` | 警报列表 | 紧急处<E680A5><E5A484>?|
+| `/api/state/critters` | 小动物（位置/种类/幸福<E5B9B8><E7A68F>?年龄<E5B9B4><E9BE84>?| 养殖管理 |
+| `/api/state/plants` | 植物（位<EFBC88><E4BD8D>?生长进度/是否枯萎<E69EAF><E8908E>?| 农业管理 |
+| `/api/state/rooms` | 房间（类<EFBC88><E7B1BB>?格数/建筑数） | 房间判定 |
+
+### 地图/格子数据 (GET)
+
+| 端点 | 说明 | 示例 |
+|------|------|------|
+| `/api/state/cell?x=10&y=5` | 单格详情 | 查看某个格子是气<E698AF><E6B094>?液体/建筑 |
+| `/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><>?列扫<E58897><E689AB>?| 查看<E69FA5><E79C8B>?20 <20><>?|
+| `/api/state/gas?x=10&y=10&radius=20` | 区域气体分析 | 查看周围气体成分 |
+
+### 实体注册<E6B3A8><E5868C>?(GET，AI 参考用)
+
+| 端点 | 说明 |
+|------|------|
+| `/api/registry/buildings` | 所有建<E69C89><E5BBBA>?ID 及尺<E58F8A><E5B0BA>?功<><E58A9F>?发热 |
+| `/api/registry/elements` | 所有元<E69C89><E58583>?ID 及比热容/导热/熔沸<E78694><E6B2B8>?|
+| `/api/registry/techs` | 所有科技 ID 及前<E58F8A><E5898D>?解锁内容 |
+
+### 操作 (POST)
+
+| 端点 | 请求<E8AFB7><E6B182>?| 用<><E794A8>?|
+|------|--------|------|
+| `/api/action/toggle` | `{x, y}` | 开关建筑（省电/控制流程<E6B581><E7A88B>?|
+| `/api/action/set_recipe` | `{x, y, recipeId}` | 设置建筑配方 |
+| `/api/action/empty` | `{x, y}` | 清空建筑储物 |
+| `/api/action/cancel_errand` | `{x, y}` | 取消建筑处的任务 |
+| `/api/action/dig` | `{x, y, width, height}` | 挖掘区域 |
+| `/api/action/build` | `{buildingId, x, y}` | 建造建<E980A0><E5BBBA>?|
+| `/api/action/deconstruct` | `{buildingId, x, y}` | 拆除建筑 |
+| `/api/action/prioritize` | `{x, y, priority}` | 设优先级 |
+| `/api/action/research` | `{techId}` | 选研究项<E7A9B6><E9A1B9>?|
+| `/api/action/mop` | `{x, y}` | 清理液体 |
+| `/api/action/harvest` | `{x, y}` | 收获植物 |
+
+---
+
+## AI 如何进行推理和操<E5928C><E6938D>?
+### 第一步：获取全局上下<E4B88A><E4B88B>?
+```bash
+python3 tools/oni_api.py status
+python3 tools/oni_api.py buildings
+python3 tools/oni_analyzer.py
+```
+
+### 第二步：理解地图
+
+```bash
+# 探索基地中心区域（假设基地在 50,50<35><30>?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
+# 查找某个建筑<E5BBBA><E7AD91>?ID
+python3 tools/oni_api.py registry buildings Electrolyzer
+
+# 查看元素属<E7B4A0><E5B19E>?python3 tools/oni_api.py registry elements Water
+
+# 查看科技<E7A791><E68A80>?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：氧气不<E6B094><E4B88D>?
+**AI 推理过程<E8BF87><E7A88B>?*
+1. 检<><E6A380>?`/api/state/resources` 中的 O2 <20><>?Algae 存量
+2. 检<><E6A380>?`/api/state/buildings` 是否有电解器或氧气扩散器
+3. 检<><E6A380>?`/api/state/cell?x=&y=` 查询基地气体分布
+4. 如果 Algae < 1t 且无电解<EFBFBD><EFBFBD>?<3F><>?建议建<EFBFBD><EFBFBD>?SPOM
+5. SPOM 需要：水源 + 电解<EFBFBD><EFBFBD>?+ 气体<EFBFBD><EFBFBD>?+ 氢气发电<EFBFBD><EFBFBD>?+ 气体过滤<EFBFBD><EFBFBD>?6. 通过 `explore` 找到一<EFBFBD><EFBFBD>?8x6 的空<EFBFBD><EFBFBD>?7. 执行 `build Electrolyzer x y` + `build GasPump ...` + `build HydrogenGenerator ...`
+
+### 场景 2：食物短<E789A9><E79FAD>?
+**AI 推理过程<EFBFBD><EFBFBD>?*
+1. 检<EFBFBD><EFBFBD>?Calories < 500,000 kcal <EFBFBD><EFBFBD>?食物预警
+2. 检查是否有 PlanterBox/FarmTile <EFBFBD><EFBFBD>?ElectricGrill
+3. 如果没有农场 <EFBFBD><EFBFBD>?建议建<EFBFBD><EFBFBD>?5 <EFBFBD><EFBFBD>?PlanterBox <EFBFBD><EFBFBD>?Mealwood
+4. Mealwood 不需要灌溉或施肥，只需 Dirt
+5. 检<EFBFBD><EFBFBD>?Dirt 存量，如果足<EFBFBD><EFBFBD>?<3F><>?执行建<EFBFBD><EFBFBD>?6. 如果有污<EFBFBD><EFBFBD>?<3F><>?建议建<EFBFBD><EFBFBD>?Water Sieve + 厕所水循<EFBFBD><EFBFBD>?
+### 场景 3：温度过<E5BAA6><E8BF87>?
+**AI 推理过程<EFBFBD><EFBFBD>?*
+1. 检查温度数据（通过资源中的 Temperature 或格子数据）
+2. 查看热源（煤发电机、精炼厂等靠近基地的位置<EFBFBD><EFBFBD>?3. 建议：用隔热门包围热<EFBFBD><EFBFBD>?+ 建造液冷模<EFBFBD><EFBFBD>?4. 液冷模块需要：Aquatuner + SteamTurbine + 导热液体管道
+
+---
+
+## 暂停与速度参<E5BAA6><E58F82>?
+游戏状态中<EFBFBD><EFBFBD>?`isPaused` <EFBFBD><EFBFBD>?`gameSpeed` 字段<EFBFBD><EFBFBD>?
+```
+isPaused: true   <20><>?是否暂停
+gameSpeed: 0     <20><>?0=暂停, 1=1x, 2=2x, 3=3x
+```
+
+暂停规则已集成在"统一操作协议"的标<EFBFBD><EFBFBD>?SOP 中，详见下节。核心原则：
+- **所有写操作前必须暂<EFBFBD><EFBFBD>?*（dig/build/deconstruct/batch/pipe/wire<EFBFBD><EFBFBD>?- **只读查询不需要暂<EFBFBD><EFBFBD>?*（status/resources/events<EFBFBD><EFBFBD>?- **操作完成后必须恢<EFBFBD><EFBFBD>?*
+
+---
+
+---
+## AI 统一操作协议
+
+这是 AI 操作缺氧的标准协议。所有决策和操作必须遵循此协议<EFBFBD><EFBFBD>?
+### 铁律（必须遵守）
+
+```
+铁律 1: 任何时<E4BD95><E697B6>?AI 开始推<E5A78B><E68EA8>?决策<E586B3><E7AD96>?<3F><>?必须先暂停游戏<E6B8B8><E6888F>?        工具在获取游戏状态数据时会自动触发暂停，
+        保证 AI 获取的信息是当前时刻的准确快照<E5BFAB><E785A7>?        <20><>?工具自动执行 pause（无需手动调用<E8B083><E794A8>?        <20><>?AI 完成所有操作后主动 unpause
+
+铁律 2: 任何时<E4BD95><E697B6>?AI 需要向用户提问，必须先暂停游戏<E6B8B8><E6888F>?        <20><>?工具自动暂停，用户回答后 AI 恢复<E681A2><E5A48D>?unpause
+
+铁律 3: 任何时<E4BD95><E697B6>?AI 结束回答/退出操作状态，必须确保游戏处于暂停态，
+        除非用户明确要求不暂停<E69A82><E5819C>?        <20><>?防止游戏<E6B8B8><E6888F>?AI 不监控时状态恶化（窒息/过载/高温/CO₂）
+
+铁律 4: 任何时<E4BD95><E697B6>?AI 执行写操作（dig/build/deconstruct/batch/pipe/wire），
+        工具自动确保暂停态<E5819C><E68081>?
+铁律 5: 重大操作前必须先 save 存档，失败后允许 load 回滚<E59B9E><E6BB9A>?```
+
+### 核心操作循环
+
+每次 AI 与游戏交互都必须遵循这个五步循环<E5BEAA><E78EAF>?
+```
+┌─────────────────────────────────────────────────────────<EFBFBD><EFBFBD>?<3F><>?                  1. 上下文感<EFBFBD><EFBFBD>?                          <EFBFBD><EFBFBD>?<3F><>?  snapshot + diagnose + events                          <EFBFBD><EFBFBD>?<3F><>?  "我现在看到什么？当前状态是什么？发生了什么？"          <EFBFBD><EFBFBD>?└──────────────────────┬──────────────────────────────────<E29480><E29480>?                       <EFBFBD><EFBFBD>?┌─────────────────────────────────────────────────────────<E29480><E29480>?<3F><>?                  2. 决策与规<EFBFBD><EFBFBD>?                          <EFBFBD><EFBFBD>?<3F><>?  pause <EFBFBD><EFBFBD>?分析数据 <EFBFBD><EFBFBD>?确定目标 <EFBFBD><EFBFBD>?选择工具                <EFBFBD><EFBFBD>?<3F><>?  "基于现状，我需要做什么？用什么工具？在哪个坐标？"      <EFBFBD><EFBFBD>?└──────────────────────┬──────────────────────────────────<E29480><E29480>?                       <EFBFBD><EFBFBD>?┌─────────────────────────────────────────────────────────<E29480><E29480>?<3F><>?                  3. 执行前保<EFBFBD><EFBFBD>?                          <EFBFBD><EFBFBD>?<3F><>?  save <EFBFBD><EFBFBD>?camera <EFBFBD><EFBFBD>?cell <EFBFBD><EFBFBD>?snapshot                       <EFBFBD><EFBFBD>?<3F><>?  "先存档，然后把视野移过去，确认坐标正<EFBFBD><EFBFBD>?               <EFBFBD><EFBFBD>?└──────────────────────┬──────────────────────────────────<E29480><E29480>?                       <EFBFBD><EFBFBD>?┌─────────────────────────────────────────────────────────<E29480><E29480>?<3F><>?                  4. 执行操作                             <EFBFBD><EFBFBD>?<3F><>?  dig/build/build_pipe_line/batch                       <EFBFBD><EFBFBD>?<3F><>?  每一步检查反馈（success/fail + suggestion<EFBFBD><EFBFBD>?            <EFBFBD><EFBFBD>?└──────────────────────┬──────────────────────────────────<E29480><E29480>?                       <EFBFBD><EFBFBD>?┌─────────────────────────────────────────────────────────<E29480><E29480>?<3F><>?                  5. 验证与恢<EFBFBD><EFBFBD>?                          <EFBFBD><EFBFBD>?<3F><>?  unpause <EFBFBD><EFBFBD>?snapshot <EFBFBD><EFBFBD>?检查状<EFBFBD><EFBFBD>?                        <EFBFBD><EFBFBD>?<3F><>?  恶化 <EFBFBD><EFBFBD>?load 回滚 <EFBFBD><EFBFBD>?换方<EFBFBD><EFBFBD>?                             <EFBFBD><EFBFBD>?└─────────────────────────────────────────────────────────<E29480><E29480>?```
+
+### 标准操作 SOP
+
+任何时<EFBFBD><EFBFBD>?AI 执行操作，必须按以下流程<E6B581><E7A88B>?
+```
+步骤 0: 暂停
+  python3 tools/oni_api.py pause "操作说明"
+  <20><>?确认 success=true，否则重<E58899><E9878D>?
+步骤 1: 视觉确认
+  python3 tools/oni_api.py camera <x> <y> <zoom>
+  python3 tools/oni_api.py snapshot
+  <20><>?下载截图，确认目标位置正<E7BDAE><E6ADA3>?
+步骤 2: 数据确认
+  python3 tools/oni_api.py cell <x> <y>
+  <20><>?hasBuilding=true <20><>?<3F><>?deconstruct 或换位置
+  <20><>?isSolid=true <20><>?<3F><>?dig
+  <20><>?isVacuum=true <20><>?确认原因
+
+步骤 3: 安全存档
+  python3 tools/oni_api.py save "before_任务<E4BBBB><E58AA1>?
+  <20><>?确认 success=true
+
+步骤 4: 执行
+  dig / build / build_pipe_line / build_wire_line / batch
+  <20><>?每次检查反馈：
+    success=true <20><>?继续
+    success=false <20><>?<3F><>?suggestion <20><>?调整重试 <20><>?3次失败则 load 回滚
+
+步骤 5: 验证
+  snapshot <20><>?截图对比
+  resources <20><>?资源变化
+  未改<E69CAA><E694B9>?<3F><>?load 回滚
+
+步骤 6: 恢复
+  unpause 1
+```
+
+### 决策框架
+
+AI 面对任何问题按此框架思考：
+
+```
+【数据收集<EFBFBD><EFBFBD>?  status <20><>?diagnose <20><>?power <20><>?co2 <20><>?temp_zones <20><>?resources <20><>?buildings
+
+【定位分析<EFBFBD><EFBFBD>?  cells <x> <y> <w> <h> <20><>?cell <x> <y> <20><>?camera + snapshot
+
+【方案选择<EFBFBD><EFBFBD>?  紧<><E7B4A7>?<3F><>?emergency_o2 / fix_co2 / fix_overload
+  建<><E5BBBA>?<3F><>?定坐<E5AE9A><E59D90>?<3F><>?build / build_pipe_line / build_wire_line
+  批量 <20><>?batch JSON
+  扩展 <20><>?expand_base
+  检<><E6A380>?<3F><>?diagnose
+  回滚 <20><>?load
+```
+
+### 标准方案手册
+
+#### 方案 A：初期基地（Cycle 1-20<32><30>?
+```
+1. pause "Initial base"
+2. diagnose
+3. expand_base <中心> <<3C><>? <<3C><>?
+4. build ResearchStation <坐标>
+5. build ManualGenerator <坐标>
+6. build Battery <坐标>
+7. build OxygenDiffuser <坐标>
+8. build PlanterBox x5
+9. build Cot x3 / LadderBed x3
+10. build Outhouse + WashBasin
+11. research_select FarmingTech
+12. research_select PowerRegulation
+13. unpause 1
+```
+
+#### 方案 B：CO2 危机
+
+```
+症状：duplicants 窒息，co2 显示大量 CO2
+1. pause "CO2"
+2. co2 <20><>?找到最<E588B0><E69C80>?CO2 聚集<E8819A><E99B86>?3. camera <x> <最<><E69C80>?y> 20
+4. snapshot <20><>?确认地形
+5. save "before_co2"
+6. fix_co2 <20><>?自动挖排气管
+7. snapshot <20><>?确认挖<E8AEA4><E68C96>?8. unpause 1
+9. 30s <20><>?co2 确认下降
+```
+
+#### 方案 C：电力过<E58A9B><E8BF87>?
+```
+症状：power 显示 *** OVERLOAD ***
+1. pause "Power overload"
+2. power <20><>?哪个电路过载
+3. diagnose <20><>?资源检<E6BA90><E6A380>?4. save "before_power"
+5. fix_overload <20><>?修复建议
+6. 如电力不<E58A9B><E4B88D>?<3F><>?build <发电<E58F91><E794B5>? <20><>?build_wire_line <连接>
+7. power <20><>?确认过载消失
+8. unpause 1
+```
+
+#### 方案 D：氧气危<E6B094><E58DB1>?
+```
+症状：duplicants 显示 oxygen<20%
+1. pause "O2"
+2. snapshot <20><>?视觉确认
+3. resources <20><>?O2/Algae 存量
+4. buildings <20><>?电解<E794B5><E8A7A3>?扩散<E689A9><E695A3>?5. save "before_o2"
+6. 分支<E58886><E694AF>?   无设<E697A0><E8AEBE>?<3F><>?build OxygenDiffuser
+   无藻<E697A0><E897BB>?<3F><>?build Electrolyzer + 接水管电<E7AEA1><E794B5>?   设备不工<E4B88D><E5B7A5>?<3F><>?cell 检查供水和供电
+7. unpause 1
+8. 30s <20><>?resources <20><>?O2 回升<E59B9E><E58D87>?```
+
+#### 方案 E：建<EFBC9A><E5BBBA>?SPOM
+
+```
+1. pause "SPOM"
+2. explore <20><>?8x6 空地
+3. camera <20><>?snapshot 确认
+4. save "before_spom"
+5. oni_builder.py build spom <x> <y>
+6. build_pipe_line liquid <水源> <电解<E794B5><E8A7A3>?
+7. build_wire_line heavy <发电<E58F91><E794B5>? <电池> cross
+8. unpause 1
+```
+
+#### 方案 F：管道铺设（带交叉处理）
+
+```
+需求：液体管道横穿已有气体管道
+1. pause "Plumbing"
+2. camera <起点> <终点> 25
+3. save "before_pipe"
+4. 横穿段用 cross 模式<E6A8A1><E5BC8F>?   build_pipe_line liquid <起点> <终点> cross
+   <20><>?Mod 自动在交叉处放跨接器
+5. pipes liquid <20><>?确认流动
+6. unpause 1
+```
+
+#### 方案 G：电线布<E7BABF><E5B883>?
+```
+需求：为新建筑拉电线到电网
+1. pause "Wiring"
+2. camera <建筑> <电源> 25
+3. power <20><>?查空余容<E4BD99><E5AEB9>?4. save "before_wire"
+5. 布线（横穿用 cross）：
+   build_wire_line regular <建筑> <变压<E58F98><E58E8B>? cross
+6. unpause 1
+```
+
+### 错误恢复
+
+```
+操作失败 <20><>?AI 必须读取 error + errorMessage + suggestion
+
+错误处理表：
+cell_occupied        <20><>?换坐标或 deconstruct
+cell_solid           <20><>?<3F><>?dig
+cell_occupied_by_dupe<EFBFBD><EFBFBD>?等待
+material_shortage    <20><>?查资<E69FA5><E8B584>?+ 安排生产
+unknown_building     <20><>?registry buildings 查询
+unknown_tech         <20><>?registry techs 查询
+missing_prerequisites<EFBFBD><EFBFBD>?先研究前置科技
+invalid_priority     <20><>?<3F><>?1-9
+save_not_found       <20><>?saves 列出
+
+重试 3 次失<E6ACA1><E5A4B1>?<3F><>?load 回滚
+```
+
+### 坐标定位方法
+
+```
+方法 1: 基于已有建筑偏移
+  buildings <20><>?查已有建筑坐<E7AD91><E59D90>?<3F><>?偏移放置
+
+方法 2: 基于区域探索
+  explore <x> <y> <w> <h> <20><>?找空<E689BE><E7A9BA>?
+方法 3: 基于资源位置
+  co2 <20><>?CO2 聚集点下方挖排气<E68E92><E6B094>?
+方法 4: 基于 cell 验证
+  cell <x> <y> <20><>?确认 isSolid=false + hasBuilding=false + isVisible=true
+
+AI 习惯：头脑规划坐<E58892><E59D90>?<3F><>?cell 验证 <20><>?确认无误再建<E5868D><E5BBBA>?```
+
+### 事件自动响应
+
+event_daemon 运行<E8BF90><E8A18C>?AI 自动响应规则<E8A784><E58899>?
+```
+[CRITICAL] 窒息
+  <20><>?diagnose <20><>?执行方案 D 或方<E68896><E696B9>?B
+
+[CRITICAL] 电力中断
+  <20><>?power <20><>?执行方案 C
+
+[WARNING] 食物短缺
+  <20><>?Calories<200k <20><>?<3F><>?PlanterBox x5
+
+[WARNING] 温度过高
+  <20><>?temp_zones <20><>?隔热<E99A94><E783AD>?+ 冷却
+
+[INFO] 新周<E696B0><E591A8>?  <20><>?research <20><>?继续科研
+  <20><>?resources <20><>?安排生产
+
+AI 不应等待指令——事件本身就是指令<E68C87><E4BBA4>?```
+
+---
+
+## AI 如何表达"在哪个格子做什<E5819A><E4BB80>?
+
+### 定位语法
+
+AI 在描述操作时应使用以下格式：
+
+```
+在坐<EFBFBD><EFBFBD>?(x, y) 建<><E5BBBA>?<buildingId>
+在区<EFBFBD><EFBFBD>?(x, y, width, height) 进行挖掘
+<EFBFBD><EFBFBD>?(x1,y1) <20><>?(x2,y2) 铺设管道/电线
+在格<EFBFBD><EFBFBD>?(x, y) 设置优先级为 <priority>
+```
+
+### 坐标查找策略
+
+<EFBFBD><EFBFBD>?AI 不确定在哪里建造时<E980A0><E697B6>?1. 先用 `explore` 找一个空闲区域（没有建筑和固体阻挡）
+2. 检查空闲区域的元素和温度是否适合
+3. <20><>?`cell` 命令确认目标格子状<E5AD90><E78AB6>?4. 然后<E784B6><E5908E>?`dig` 清理空间
+5. 最后用 `build` 建<><E5BBBA>?
+### 建筑放置规则
+
+- 建筑坐标是其**左下<E5B7A6><E4B88B>?*的位<E79A84><E4BD8D>?- 建筑占用<E58DA0><E794A8>?w×h 区域必须全部是空<E698AF><E7A9BA>?- 需要确认目标区域无建筑、无固体自然方块
+- 气体/液体不会阻挡建筑
+- 如果建筑需要特定环境（如电解器需要水），AI 需要先检查环<E69FA5><E78EAF>?
+---
+
+## 工具列表
+
+| 工具 | 用<><E794A8>?|
+|------|------|
+| `tools/oni_api.py` | Mod API 客户端（状<EFBC88><E78AB6>?格子/注册<E6B3A8><E5868C>?操作/批量/优先<E4BC98><E58588>?事件<E4BA8B><E4BBB6>?|
+| `tools/oni_analyzer.py` | 自动分析游戏状态、生成预警和建议 |
+| `tools/oni_builder.py` | 预置蓝图建造（SPOM/农场/养殖等） |
+| `scripts/auto_repair.sh` | 诊断 Mod 连接问题 |
+| `scripts/auto_analyze.sh` | 一键健康检<E5BAB7><E6A380>?状<><E78AB6>?分析 |
+| `scripts/watch.sh [秒]` | 循环监控模式 |
+| `scripts/setup.sh` | 环境初始化与检<E4B88E><E6A380>?|
+| `scripts/event_daemon.py` | **事件守护进程** <20><>?持续轮询事件 <20><>?AI 输入<E8BE93><E585A5>?|
+| `docs/AI_KNOWLEDGE_BASE.md` | 建筑/元素/科技 ID 注册表和游戏机制参<E588B6><E58F82>?|
+| `docs/batch_example.json` | 批量任务示例文件 |
+
+---
+
+## 核心游戏知识
+
+### 生存优先<E4BC98><E58588>?1. **氧气** <20><>?电解<E794B5><E8A7A3>?> 藻类制氧（前期过渡）
+2. **食物** <EFBFBD><EFBFBD>?浆果 > 烤肉 > 营养<E890A5><E585BB>?3. **温度控制** <20><>?液冷 + 蒸汽<E892B8><E6B1BD>?4. **电力** <20><>?氢气发电 > 煤炭 > 手动
+5. **水资源管<E6BA90><E7AEA1>?* <20><>?净水器、污水过<E6B0B4><E8BF87>?
+### 常用布局
+- SPOM: 电解制氧 + 氢气发电闭环
+- 卫生间水循环: 卫生<E58DAB><E7949F>?<3F><>?净水器 <20><>?卫生<E58DAB><E7949F>?- 冷却系统: 液冷 + 蒸汽<E892B8><E6B1BD>?+ 导热<E5AFBC><E783AD>?- Ranch 模块: 养殖哈奇/滑鳞/飞鱼
+
+### 关键事件预警
+- 氧气不足 (< 500g/tile) <EFBFBD><EFBFBD>?增加制氧
+- 温度超标 (> 40°C <20><>?< -10°C) <EFBFBD><EFBFBD>?增加温控
+- 食物短缺 (< 5 周期余量) <EFBFBD><EFBFBD>?扩大种植/养殖
+- 电力不足 <EFBFBD><EFBFBD>?增加发电或减少负<EFBFBD><EFBFBD>?- 污水满溢 <EFBFBD><EFBFBD>?增加净<EFBFBD><EFBFBD>?扩大存储