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 在描述操作时应使用以下格式：

在坐标 (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	预置蓝图建造（SPOM/农场/养殖等）
scripts/auto_repair.sh	诊断 Mod 连接问题
scripts/auto_analyze.sh	一键健康检查+状态+分析
scripts/watch.sh [秒]	循环监控模式
scripts/setup.sh	环境初始化与检查
docs/AI_KNOWLEDGE_BASE.md	建筑/元素/科技 ID 注册表和游戏机制参考

---

核心游戏知识

生存优先级

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

常用布局

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

关键事件预警

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