# 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` 与游戏通信
- 端口�?`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 周期余量) �?扩大种植/养殖
- 电力不足 �?增加发电或减少负�?- 污水满溢 �?增加净�?扩大存储