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=` 查询）：

```json
{
  "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 如何进行推理和操作

### 第一步：获取全局上下文

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

### 第二步：理解地图

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

### 第三步：参考知识库

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

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

# 查看科技树
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：氧气不足

**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
```

### 示例

```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: 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` 字段：

```json
// 成功
{ "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 可以通过批处理一次性执行一个复杂的建造计划：

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

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

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

### 优先级系统

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

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