docs: unified AI operating protocol with complete playbook

Complete rewrite of SKILL.md with a comprehensive AI operating protocol: - Core Operating Loop: 5-step cycle (context → plan → protect → execute → verify) - Standard Operating Procedure (SOP): 0-6 step-by-step for every operation - Decision Framework: how to analyze, locate, choose, and execute - 7 Standard Playbooks: A: Initial base setup (Cycle 1-20) B: CO2 crisis handling C: Power overload recovery D: Oxygen crisis emergency E: SPOM construction F: Pipe/wire crossing (with bridge detection) G: Electrical wiring (connect building to grid) - Error Recovery Table: every error code with specific recovery steps - Coordinate Location Methods: 4 strategies for finding build positions - Event Auto-Response Rules: what to do for each event type - Consolidated pause/speed reference
2026-05-22 09:22:59 +08:00
parent f91ac2eb95
commit e07280db4e
1 changed files with 248 additions and 123 deletions
--- a/SKILL.md
+++ b/SKILL.md
@ -234,162 +234,287 @@ python3 tools/oni_builder.py build spom 42 42

 ---

-## AI 暂停协议（关键规则）
+## 暂停与速度参考

-AI **必须**在每次操作序列前暂停游戏，操作完成后恢复。这防止推理延迟期间游戏状态变化导致操作失效。
-
-### 规则
-```
-1. 收到事件 / 决定操作 → 立即 PAUSE
-2. 查询状态、分析、决策（可耗时，游戏已暂停）
-3. 执行操作（dig / build / batch）
-4. 检查操作反馈
-5. 所有操作完成后 → UNPAUSE
-```
-
-### 示例
-
-```bash
-# 1. 暂停
-python3 tools/oni_api.py pause "Building SPOM"
-
-# 2. 查询状态（游戏已冻结，不会变化）
-python3 tools/oni_api.py explore 40 40 30 20
-python3 tools/oni_api.py cell 45 42
-
-# 3. 执行操作
-python3 tools/oni_api.py dig 40 40 8 6
-python3 tools/oni_api.py build Electrolyzer 45 42
-
-# 4. 恢复
-python3 tools/oni_api.py unpause 1
-```
-
-### 当前游戏速度
-
-通过 `status` 命令查看：
+游戏状态中的 `isPaused` 和 `gameSpeed` 字段：

 ```
-isPaused: true   ← 游戏是否暂停
+isPaused: true   ← 是否暂停
 gameSpeed: 0     ← 0=暂停, 1=1x, 2=2x, 3=3x
 ```

-### 总是暂停的场景
+暂停规则已集成在"统一操作协议"的标准 SOP 中，详见下节。核心原则：
+- **所有写操作前必须暂停**（dig/build/deconstruct/batch/pipe/wire）
+- **只读查询不需要暂停**（status/resources/events）
+- **操作完成后必须恢复**

-| 场景 | 原因 |
-|------|------|
-| 收到 critical 事件 | 可能需要紧急操作 |
-| 执行 dig / build / deconstruct | 坐标必须精确，不能偏移 |
-| 执行 batch | 多个相关操作需原子性 |
-| 查询状态后做决策 | 避免推理时状态变化 |
+---

-### 不需要暂停的场景
+---
+## AI 统一操作协议

-| 场景 | 原因 |
-|------|------|
-| 仅查看 status / resources | 只读操作，无副作用 |
-| 轮询 events | 事件本身是增量变化的 |
+这是 AI 操作缺氧的标准协议。所有决策和操作必须遵循此协议。

-## AI 事件驱动工作流
+### 核心操作循环

-AI 应持续运行事件守护进程，形成"事件 → 分析 → 操作 → 反馈"的闭环：
+每次 AI 与游戏交互都必须遵循这个五步循环：

 ```
-                    ┌───────────────────────────────────┐
-                    │        Event Daemon               │
-                    │  (scripts/event_daemon.py)         │
-                    │  polls every 5 seconds             │
-                    └──────────┬────────────────────────┘
-                               │ 新事件
-                               ▼
-                    ┌───────────────────────────────────┐
-                    │        AI Decision Loop            │
-                    │                                   │
-                    │  1. 收到事件 → 分类严重程度        │
-                    │  2. 严重 → 立即用 tools 调查状态   │
-                    │  3. 分析根本原因                   │
-                    │  4. 执行操作（dig/build/batch）    │
-                    │  5. 检查操作反馈（success/fail）   │
-                    │  6. 失败 → 读取错误原因 + 建议     │
-                    │  7. 调整方案后重试                 │
-                    └───────────────────────────────────┘
+┌─────────────────────────────────────────────────────────┐
+│                   1. 上下文感知                           │
+│   snapshot + diagnose + events                          │
+│   "我现在看到什么？当前状态是什么？发生了什么？"          │
+└──────────────────────┬──────────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────────┐
+│                   2. 决策与规划                           │
+│   pause → 分析数据 → 确定目标 → 选择工具                │
+│   "基于现状，我需要做什么？用什么工具？在哪个坐标？"      │
+└──────────────────────┬──────────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────────┐
+│                   3. 执行前保护                           │
+│   save → camera → cell → snapshot                       │
+│   "先存档，然后把视野移过去，确认坐标正确"               │
+└──────────────────────┬──────────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────────┐
+│                   4. 执行操作                             │
+│   dig/build/build_pipe_line/batch                       │
+│   每一步检查反馈（success/fail + suggestion）             │
+└──────────────────────┬──────────────────────────────────┘
+                       ▼
+┌─────────────────────────────────────────────────────────┐
+│                   5. 验证与恢复                           │
+│   unpause → snapshot → 检查状态                         │
+│   恶化 → load 回滚 → 换方案                              │
+└─────────────────────────────────────────────────────────┘
 ```

-### 事件驱动示例：复制人窒息
+### 标准操作 SOP
+
+任何时候 AI 执行操作，必须按以下流程：

 ```
-[EVENT CRITICAL] Cycle 42 @ 14:32:15
-  Title:   suffocating
-  Entity:  Dup1
+步骤 0: 暂停
+  python3 tools/oni_api.py pause "操作说明"
+  → 确认 success=true，否则重试

-→ AI 收到此事件后自动执行：
-  1. python3 tools/oni_api.py duplicants        # 查看所有复制人氧气值
-  2. python3 tools/oni_api.py cell 23 45         # 查看 Dup1 所在格子
-  3. python3 tools/oni_api.py resources          # 检查 O2 + Algae 存量
-  4. python3 tools/oni_api.py buildings          # 是否有电解器/扩散器
-  5. 根据分析结果：
-     - 如果无电解器且 Algae < 1t → 紧急建造 SPOM
-     - 如果有扩散器但无 Algae → 改用电解器
-     - 如果 Dup1 在 CO2 里 → 挖掘排气通道
-  6. python3 tools/oni_api.py build Electrolyzer 42 42
-  7. 读取反馈：成功？材料不足？格子被占？
+步骤 1: 视觉确认
+  python3 tools/oni_api.py camera <x> <y> <zoom>
+  python3 tools/oni_api.py snapshot
+  → 下载截图，确认目标位置正确
+
+步骤 2: 数据确认
+  python3 tools/oni_api.py cell <x> <y>
+  → hasBuilding=true → 先 deconstruct 或换位置
+  → isSolid=true → 先 dig
+  → isVacuum=true → 确认原因
+
+步骤 3: 安全存档
+  python3 tools/oni_api.py save "before_任务名"
+  → 确认 success=true
+
+步骤 4: 执行
+  dig / build / build_pipe_line / build_wire_line / batch
+  → 每次检查反馈：
+    success=true → 继续
+    success=false → 读 suggestion → 调整重试 → 3次失败则 load 回滚
+
+步骤 5: 验证
+  snapshot → 截图对比
+  resources → 资源变化
+  未改善 → load 回滚
+
+步骤 6: 恢复
+  unpause 1
 ```

-### 操作反馈处理
+### 决策框架

-每次操作后 AI **必须**检查反馈中的 `success` 字段：
+AI 面对任何问题按此框架思考：

-```json
-// 成功
-{ "success": true, "result": "build_queued", "buildingId": "Electrolyzer" }
+```
+【数据收集】
+  status → diagnose → power → co2 → temp_zones → resources → buildings

-// 失败 — AI 必须读取 error, errorMessage, suggestion
-{
-  "success": false,
-  "result": "failed",
-  "error": "cell_occupied",
-  "errorMessage": "Cell (42,42) already has building 'GasPump'",
-  "suggestion": "Choose a different location, or deconstruct the existing building first"
-}
+【定位分析】
+  cells <x> <y> <w> <h> → cell <x> <y> → camera + snapshot
+
+【方案选择】
+  紧急 → emergency_o2 / fix_co2 / fix_overload
+  建造 → 定坐标 → build / build_pipe_line / build_wire_line
+  批量 → batch JSON
+  扩展 → expand_base
+  检查 → diagnose
+  回滚 → load
 ```

-常见错误码：
-| 错误 | 含义 | AI 应如何处理 |
-|------|------|-------------|
-| `cell_occupied` | 格子已被建筑占据 | 换位置或先拆除 |
-| `cell_solid` | 格子是固体方块（未挖掘） | 先 dig 再 build |
-| `cell_occupied_by_dupe` | 复制人站在那 | 等待或取消其任务 |
-| `material_shortage` | 建造材料不足 | 检查资源并安排生产 |
-| `cell_out_of_bounds` | 超出地图范围 | 调整坐标 |
-| `unknown_building` | buildingId 错误 | 查询 registry buildings |
-| `missing_prerequisites` | 科技未研究 | 先研究前置科技 |
-| `no_liquid_at_cell` | 没有液体可清理 | 用 cell 命令检查 |
-| `invalid_priority` | 优先级必须是 1-9 | 调整数字 |
+### 标准方案手册

-### 批量任务示例
+#### 方案 A：初期基地（Cycle 1-20）

-AI 可以通过批处理一次性执行一个复杂的建造计划：
-
-```bash
-# 1. 查看批量计划内容
-cat docs/batch_example.json
-
-# 2. 执行批量计划
-python3 tools/oni_api.py batch docs/batch_example.json
+```
+1. pause "Initial base"
+2. diagnose
+3. expand_base <中心> <宽> <高>
+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
 ```

-批量反馈会逐个报告每个动作的结果，AI 应遍历并处理失败项。
+#### 方案 B：CO2 危机

-### 优先级系统
+```
+症状：duplicants 窒息，co2 显示大量 CO2
+1. pause "CO2"
+2. co2 → 找到最大 CO2 聚集点
+3. camera <x> <最低 y> 20
+4. snapshot → 确认地形
+5. save "before_co2"
+6. fix_co2 → 自动挖排气管
+7. snapshot → 确认挖通
+8. unpause 1
+9. 30s 后 co2 确认下降
+```

-ONI 优先级范围 1（最低）~ 9（紧急/黄 alert）：
+#### 方案 C：电力过载

-```bash
-# 设置全局默认
-python3 tools/oni_api.py priority_global dig 9
+```
+症状：power 显示 *** OVERLOAD ***
+1. pause "Power overload"
+2. power → 哪个电路过载
+3. diagnose → 资源检查
+4. save "before_power"
+5. fix_overload → 修复建议
+6. 如电力不足 → build <发电机> → build_wire_line <连接>
+7. power → 确认过载消失
+8. unpause 1
+```

-# 查看优先级含义
-python3 tools/oni_api.py registry priorities
+#### 方案 D：氧气危机
+
+```
+症状：duplicants 显示 oxygen<20%
+1. pause "O2"
+2. snapshot → 视觉确认
+3. resources → O2/Algae 存量
+4. buildings → 电解器/扩散器
+5. save "before_o2"
+6. 分支：
+   无设备 → build OxygenDiffuser
+   无藻类 → build Electrolyzer + 接水管电线
+   设备不工作 → cell 检查供水和供电
+7. unpause 1
+8. 30s 后 resources → O2 回升？
+```
+
+#### 方案 E：建造 SPOM
+
+```
+1. pause "SPOM"
+2. explore 找 8x6 空地
+3. camera → snapshot 确认
+4. save "before_spom"
+5. oni_builder.py build spom <x> <y>
+6. build_pipe_line liquid <水源> <电解器>
+7. build_wire_line heavy <发电机> <电池> cross
+8. unpause 1
+```
+
+#### 方案 F：管道铺设（带交叉处理）
+
+```
+需求：液体管道横穿已有气体管道
+1. pause "Plumbing"
+2. camera <起点> <终点> 25
+3. save "before_pipe"
+4. 横穿段用 cross 模式：
+   build_pipe_line liquid <起点> <终点> cross
+   → Mod 自动在交叉处放跨接器
+5. pipes liquid → 确认流动
+6. unpause 1
+```
+
+#### 方案 G：电线布线
+
+```
+需求：为新建筑拉电线到电网
+1. pause "Wiring"
+2. camera <建筑> <电源> 25
+3. power → 查空余容量
+4. save "before_wire"
+5. 布线（横穿用 cross）：
+   build_wire_line regular <建筑> <变压器> cross
+6. unpause 1
+```
+
+### 错误恢复
+
+```
+操作失败 → AI 必须读取 error + errorMessage + suggestion
+
+错误处理表：
+cell_occupied        → 换坐标或 deconstruct
+cell_solid           → 先 dig
+cell_occupied_by_dupe→ 等待
+material_shortage    → 查资源 + 安排生产
+unknown_building     → registry buildings 查询
+unknown_tech         → registry techs 查询
+missing_prerequisites→ 先研究前置科技
+invalid_priority     → 用 1-9
+save_not_found       → saves 列出
+
+重试 3 次失败 → load 回滚
+```
+
+### 坐标定位方法
+
+```
+方法 1: 基于已有建筑偏移
+  buildings → 查已有建筑坐标 → 偏移放置
+
+方法 2: 基于区域探索
+  explore <x> <y> <w> <h> → 找空地
+
+方法 3: 基于资源位置
+  co2 → CO2 聚集点下方挖排气道
+
+方法 4: 基于 cell 验证
+  cell <x> <y> → 确认 isSolid=false + hasBuilding=false + isVisible=true
+
+AI 习惯：头脑规划坐标 → cell 验证 → 确认无误再建造
+```
+
+### 事件自动响应
+
+event_daemon 运行时 AI 自动响应规则：
+
+```
+[CRITICAL] 窒息
+  → diagnose → 执行方案 D 或方案 B
+
+[CRITICAL] 电力中断
+  → power → 执行方案 C
+
+[WARNING] 食物短缺
+  → Calories<200k → 建 PlanterBox x5
+
+[WARNING] 温度过高
+  → temp_zones → 隔热门 + 冷却
+
+[INFO] 新周期
+  → research → 继续科研
+  → resources → 安排生产
+
+AI 不应等待指令——事件本身就是指令。
 ```

 ---