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 + 导热液体管道

---

AI 暂停协议（关键规则）

AI 必须在每次操作序列前暂停游戏，操作完成后恢复。这防止推理延迟期间游戏状态变化导致操作失效。

规则

1. 收到事件 / 决定操作 → 立即 PAUSE
2. 查询状态、分析、决策（可耗时，游戏已暂停）
3. 执行操作（dig / build / batch）
4. 检查操作反馈
5. 所有操作完成后 → UNPAUSE

示例

# 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: true   ← 游戏是否暂停
gameSpeed: 0     ← 0=暂停, 1=1x, 2=2x, 3=3x

总是暂停的场景

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

不需要暂停的场景

场景	原因
仅查看 status / resources	只读操作，无副作用
轮询 events	事件本身是增量变化的

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. 调整方案后重试                 │
                    └───────────────────────────────────┘

事件驱动示例：复制人窒息

[EVENT CRITICAL] Cycle 42 @ 14:32:15
  Title:   suffocating
  Entity:  Dup1

→ 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. 读取反馈：成功？材料不足？格子被占？

操作反馈处理

每次操作后 AI 必须检查反馈中的 success 字段：

// 成功
{ "success": true, "result": "build_queued", "buildingId": "Electrolyzer" }

// 失败 — 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"
}

常见错误码：

错误	含义	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	调整数字

批量任务示例

AI 可以通过批处理一次性执行一个复杂的建造计划：

# 1. 查看批量计划内容
cat docs/batch_example.json

# 2. 执行批量计划
python3 tools/oni_api.py batch docs/batch_example.json

批量反馈会逐个报告每个动作的结果，AI 应遍历并处理失败项。

优先级系统

ONI 优先级范围 1（最低）~ 9（紧急/黄 alert）：

# 设置全局默认
python3 tools/oni_api.py priority_global dig 9

# 查看优先级含义
python3 tools/oni_api.py registry priorities

---

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 周期余量) → 扩大种植/养殖
• 电力不足 → 增加发电或减少负载
• 污水满溢 → 增加净水/扩大存储