# 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)

| 端点 | 说明 | 用途 |
|------|------|------|
| `/api/state/buildable` | 当前科技解锁的建筑 | 查看 AI 现在能造什么 |
| `/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/toggle` | `{x, y}` | 开关建筑（省电/控制流程） |
| `/api/action/set_recipe` | `{x, y, recipeId}` | 设置建筑配方 |
| `/api/action/empty` | `{x, y}` | 清空建筑储物 |
| `/api/action/cancel_errand` | `{x, y}` | 取消建筑处的任务 |
| `/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 + 导热液体管道

---

## 暂停与速度参考

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