oniagent/SKILL.md

Oxygen Not Included (ONI) Agent

职责

协助玩家操作和管理游戏"缺氧"(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= 查询）：

{
  "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)

端点	说明	用途
/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}	建造建筑
/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 如何进行推理和操作

第一步：获取全局上下文

python3 tools/oni_api.py status
python3 tools/oni_api.py buildings
python3 tools/oni_analyzer.py

第二步：理解地图

# 探索基地中心区域（假设基地在 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

第三步：参考知识库

# 查找某个建筑的 ID
python3 tools/oni_api.py registry buildings Electrolyzer

# 查看元素属性
python3 tools/oni_api.py registry elements Water

# 查看科技树
python3 tools/oni_api.py registry techs

第四步：执行操作

# 建造电解器
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 + 导热液体管道

---

暂停与速度参考

游戏状态中的 isPaused 和 gameSpeed 字段：

isPaused: true   ← 是否暂停
gameSpeed: 0     ← 0=暂停, 1=1x, 2=2x, 3=3x

暂停规则已集成在"统一操作协议"的标准 SOP 中，详见下节。核心原则：

• 所有写操作前必须暂停（dig/build/deconstruct/batch/pipe/wire）
• 只读查询不需要暂停（status/resources/events）
• 操作完成后必须恢复

---

---

AI 统一操作协议

这是 AI 操作缺氧的标准协议。所有决策和操作必须遵循此协议。

铁律（必须遵守）

铁律 1: 任何时候 AI 开始推理/决策前 → 必须先暂停游戏。
        工具在获取游戏状态数据时会自动触发暂停，
        保证 AI 获取的信息是当前时刻的准确快照。
        → 工具自动执行 pause（无需手动调用）
        → AI 完成所有操作后主动 unpause

铁律 2: 任何时候 AI 需要向用户提问，必须先暂停游戏。
        → 工具自动暂停，用户回答后 AI 恢复时 unpause

铁律 3: 任何时候 AI 结束回答/退出操作状态，必须确保游戏处于暂停态，
        除非用户明确要求不暂停。
        → 防止游戏在 AI 不监控时状态恶化（窒息/过载/高温/CO₂）

铁律 4: 任何时候 AI 执行写操作（dig/build/deconstruct/batch/pipe/wire），
        工具自动确保暂停态。

铁律 5: 重大操作前必须先 save 存档，失败后允许 load 回滚。

核心操作循环

每次 AI 与游戏交互都必须遵循这个五步循环：

┌─────────────────────────────────────────────────────────┐
│                   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 执行操作，必须按以下流程：

步骤 0: 暂停
  python3 tools/oni_api.py pause "操作说明"
  → 确认 success=true，否则重试

步骤 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 面对任何问题按此框架思考：

【数据收集】
  status → diagnose → power → co2 → temp_zones → resources → buildings

【定位分析】
  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

标准方案手册

方案 A：初期基地（Cycle 1-20）

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

方案 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 确认下降

方案 C：电力过载

症状：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

方案 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 不应等待指令——事件本身就是指令。

---

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 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	环境初始化与检查
scripts/event_daemon.py	事件守护进程 — 持续轮询事件 → AI 输入流
docs/AI_KNOWLEDGE_BASE.md	建筑/元素/科技 ID 注册表和游戏机制参考
docs/batch_example.json	批量任务示例文件

---

核心游戏知识

生存优先级

1. 氧气 — 电解器 > 藻类制氧（前期过渡）
2. 食物 — 浆果 > 烤肉 > 营养膏
3. 温度控制 — 液冷 + 蒸汽机
4. 电力 — 氢气发电 > 煤炭 > 手动
5. 水资源管理 — 净水器、污水过滤

常用布局

• SPOM: 电解制氧 + 氢气发电闭环
• 卫生间水循环: 卫生间 → 净水器 → 卫生间
• 冷却系统: 液冷 + 蒸汽机 + 导热管
• Ranch 模块: 养殖哈奇/滑鳞/飞鱼

关键事件预警

• 氧气不足 (< 500g/tile) → 增加制氧
• 温度超标 (> 40°C 或 < -10°C) → 增加温控
• 食物短缺 (< 5 周期余量) → 扩大种植/养殖
• 电力不足 → 增加发电或减少负载
• 污水满溢 → 增加净水/扩大存储