# Oxygen Not Included (ONI) AI Agent — 完整游玩指南

你通过 REST API + Python CLI 工具链完全控制《缺氧》。你的目标是**让复制人存活并建立自持基地**。

---

## 一、核心概念

### 1.1 坐标系
- (0,0) = 地图**左下角**，x→右，y→上
- 每个格子 (cell) 1×1，通过 (x,y) 唯一定位
- 建筑坐标 = 其**左下角锚点**
- 地图大小：`/api/state/game` → gridWidth × gridHeight（通常 256×384）
- **自动拉视角**：dig/build/deconstruct/prioritize 会自动将镜头移到坐标

### 1.2 格子数据
通过 `cell <x> <y>` 查看：
```
element: "Oxygen" | "Water" | "SandStone" | "Vacuum"
massKg: 质量 | temperatureC: 温度
isSolid / isLiquid / isGas / isVacuum: 物态
isDiggable: 可挖掘（固体且非Unobtanium）
hasBuilding: 有建筑 | hasDuplicant: 有复制人
```

### 1.3 可达性 (AI 必须理解)
复制人只能通过**开放空间**移动。障碍物和规则：
- **固体方块**（isSolid=true）阻挡移动——需要挖掘
- **液体/气体** 不阻挡移动
- **梯子 (Ladder)** 提供垂直移动
- **火棒 (FirePole)** 提供快速下落
- **门 (Door/PneumaticDoor)** 控制通行
- **砖块 (Tile)** 提供稳固地面
- **区域必须互相连通**：被固体完全包围的空间不可达
- **水位**：超过复制人高度的液体(约800kg/tile)会减慢甚至阻止移动

### 1.4 方块类型
| 方块 | 功能 | 材料 |
|------|------|------|
| Tile (砖块) | 地板/天花板，提供站立面 | RawMineral |
| Ladder (梯子) | 垂直攀爬 | RawMineral |
| FirePole (火棒) | 快速下落（比梯子快） | Metal |
| PneumaticDoor (气动门) | 控制进出 | Metal |
| ManualDoor (手动门) | 初期手动门 | RawMineral |
| InsulationTile (隔热砖) | 阻止热传递 | RawMineral + Ceramic |
| WindowTile (透光砖) | 透光地板 | Glass |
| MeshTile (网格砖) | 透水透气的砖块 | Metal |
| PlasticTile (塑料砖) | 高装饰地板 | Plastic |
| CarpetTile (地毯砖) | 高装饰 | Reed Fiber + Plastic |

### 1.5 材料系统
建筑需要**特定类别的材料**。游戏把材料分为以下类别：

| 材料类别 | 包含元素 | 如何获得 |
|----------|---------|---------|
| **BuildableRaw** | SandStone, Granite, IgneousRock, SedimentaryRock, Obsidian, MaficRock | 挖掘 | 
| **RawMineral** | 同上（BuildableRaw的子集） | 挖掘 |
| **Metal** | Cuprite(铜矿), IronOre(铁矿), GoldAmalgam(金汞齐), Wolframite(钨矿), Cobaltite(钴矿) | 挖掘 → 精炼 |
| **RefinedMetal** | Copper(铜), Iron(铁), Gold(金), Steel(钢), Tungsten(钨) | 在精炼炉/金属精炼器中生产 |
| **Plastic** | Polypropylene(塑料) | 聚合压机制造 |
| **Glass** | Glass(玻璃) | 窑炉烧制砂→熔融玻璃→冷却 |
| **BuildingFiber** | Reed Fiber(芦苇纤维) | 种植芦苇→收获 |
| **Transparent** | Diamond(钻石), Glass(玻璃) | 挖掘或制造 |
| **Farmable** | Dirt(泥土) | 挖掘或堆肥 |

**AI 必须理解**：造建筑时，需要查看世界库存中**有哪些元素满足该类别**。
例如 `ManualGenerator` 需要 Material=`['Metal']`，世界库存中有 Cuprite(铜矿) 和 IronOre(铁矿)，AI 应选择存量最多的。

### 1.6 挖掘系统
- 挖掘命令：`dig <x> <y> <width> <height>` → 在矩形区域内标记所有可挖掘格子
- 可挖掘条件：`isSolid === true && element !== Unobtanium && element !== Vacuum`
- 挖掘需要**任务排队**：复制人把挖掘任务加入队列后才会执行
- 挖掘完成后：该格变为真空或气体（取决于背后的元素）
- 挖掘产物：掉落物 → 复制人会捡起→放入附近储存箱
- **必须在要建造的区域先挖掘**，因为建筑不能放置在固体方块上

### 1.7 任务队列与优先级
- 游戏内所有操作（挖掘/建造/运输/研究）都由复制人执行
- 优先级 1-9（9最高）影响复制人选择顺序
- 全局优先级默认5。紧急任务设为9，非紧急设为1

---

## 二、分阶段游戏目标

### 第一阶段：初期基地 (Cycle 1-20) — 生存基础

**目标：建立基本生存设施**

**检查清单：**
```
□ 手动发电机(ManualGenerator) ×1 — 提供电力
□ 电池(Battery) ×1 — 储电
□ 氧气扩散器(OxygenDiffuser) ×1 — 用藻类产氧（如有）
□ 或电解器(Electrolyzer) + 水泵 — 用水产氧
□ 厕所(Outhouse/Lavatory) ×1-2 — 控制污染
□ 洗手盆(WashBasin) ×1 — 防止食物中毒
□ 床(Cot) ×3 — 每复制人1张
□ 配给盒(RationBox) ×1 — 储食（放在CO₂中防腐）
□ 种植箱(PlanterBox) ×3-5 — 种Mealwood产食物
□ 研究站(ResearchStation) ×1 — 开始科研
□ 储存箱(StorageLocker) ×N — 分类储料
```

**关键决策点：**
- **氧气路径选择**：藻类 >200kg 可以用OxygenDiffuser；否则必须尽快建造 Electrolyzer
- **电力规划**：先手工(ManualGenerator)，尽快过渡到燃煤(CoalGenerator)
- **食物规划**：Mealwood（用泥土）是最简单的初期食物来源

**我该怎么做：**
```bash
# 1. 暂停游戏
python tools/oni_api.py pause "Phase 1 - Initial base"
# 2. 查看状态
python tools/oni_api.py status
# 3. 探索起始区域（通常在120-140, 180-200附近）
python tools/oni_api.py explore 120 180 40 30
# 4. 检查资源
python tools/oni_api.py resources
# 5. 挖掘基地空间
python tools/oni_api.py dig 120 180 20 15
# 6. 建造初期设施（检查材料是否足够）
python tools/oni_api.py build ManualGenerator 125 192
python tools/oni_api.py build Battery 123 192
python tools/oni_api.py build ResearchStation 125 189
python tools/oni_api.py build Cot 120 192
# 7. 开始研究（农牧技术 → 电力调节）
python tools/oni_api.py research_select FarmingTech
# 8. 恢复游戏
python tools/oni_api.py unpause 1
```

### 第二阶段：中期扩张 (Cycle 20-100) — 自持系统

**目标：建立闭环系统，摆脱对初始资源的依赖**

**检查清单：**
```
□ SPOM（电解器+氢气发电机）— 无限氧气+部分电力
□ 卫生间水循环（马桶→净水器→马桶）— 无限水循环
□ 燃煤发电机 ×1-2 — 主电力来源
□ 变压器(Transformer) — 电路分离，防止过载
□ 食物农场扩张 — ≥6个种植箱或4个农场砖
□ 医疗床(TriageCot) — 治疗受伤复制人
□ 装饰物 — 缓解压力（参考房间系统）
□ 隔热砖包围基地 — 阻止外部高温进入
□ 气压服存放柜(OxygenMaskLocker) — 探索外部
```

**关键系统详解：**
- **SPOM**：水→电解器→O₂+H₂→H₂发电机(发电)+O₂排入基地
  - 需要：水源（初始水池或喷泉）+ 电解器 + 气泵 + 氢气发电机 + 气体过滤器
  - 使用蓝图：`python tools/oni_builder.py build spom <x> <y>`
- **卫生间水循环**：抽水马桶→水泵→净水器→抽水马桶
  - 净水器消耗过滤介质（沙/砂石），排出清水+污染物（污染土）
  - 使用蓝图：`python tools/oni_builder.py build toilet_loop <x> <y>`
- **电力管理**：单路电线最大1000W，超过=过载损坏
  - 使用变压器分成小电路：发电线路(重导线) → 变压器 → 用电线路(普通导线)
  - 检查电力：`/api/state/power` 查看各电路负载（需要Mod实现）

**科研优先级：**
1. FarmingTech → 食物生产
2. PowerRegulation → 变压器+重导线
3. Plumbing → 厕所水循环
4. Ventilation → 气泵+管道
5. Refinement → 精炼金属+玻璃
6. TemperatureModulation → 温度控制

### 第三阶段：后期自动化 (Cycle 100-300) — 全面自持

**目标：全自动化，应对长期挑战**

**检查清单：**
```
□ 石油发电 / 天然气发电 — 稳定大容量电力
□ 液冷模块（蒸汽机+导热管）— 主动降温
□ 自动化控制（自动化线+传感器）— 智能管理
□ 喷泉开发（冷水泉/蒸汽泉/天然气泉）— 无限资源
□ 畜牧模块（哈奇/滑鳞/飞鱼）— 稳定食物+材料
□ 太空探索（望远镜+火箭）— 终极资源
□ 精炼系统（金属精炼器/聚合压机/窑炉）
```

**温度控制：**
- 生物生存温度：-10°C ~ 40°C
- 高温来源：发电机/精炼器/电池 → 需隔热+冷却
- 冷却方案：Aquatuner(导热管)+ SteamTurbine(蒸汽机) → 主动热删除
- 隔热方案：InsulationTile + Vacuum气密层

**房间系统：**
房间提供重要加成。房间判定条件：
- **卧室(Bedroom)**：4×床 + 封闭空间 + 门 → +1士气
- **卫生间(Washroom)**：洗手盆+马桶+封闭 → +1士气
- **餐厅(MessHall)**：餐桌+食物盒 → +2士气
- **温室(Greenhouse)**：种植箱+光照+封闭 → 植物生长+50%

---

## 三、建筑数据库（AI 常用）

| buildingId | 尺寸 | 材料 | 耗电 | 用途 |
|-----------|------|------|------|------|
| ManualGenerator | 2×2 | Metal | -400W | 人力发电 |
| CoalGenerator | 2×2 | Metal | -600W | 燃煤发电 |
| HydrogenGenerator | 2×2 | Metal | -800W | 燃氢发电 |
| Electrolyzer | 2×2 | Metal | +120W | 水→O₂+H₂ |
| OxygenDiffuser | 2×2 | Metal | +120W | 藻类→O₂ |
| GasPump | 1×2 | Metal | +240W | 抽气 |
| GasFilter | 1×2 | Metal | +120W | 过滤气体 |
| WaterPump | 1×2 | Metal | +240W | 抽水 |
| LiquidPump | 1×2 | Metal | +240W | 抽任意液体 |
| LiquidFilter | 1×2 | Metal | +120W | 过滤液体 |
| WaterPurifier | 2×2 | Metal | +120W | 污水→清水 |
| PlanterBox | 1×1 | BuildableRaw | 0 | 种植食物 |
| FarmTile | 1×1 | BuildableRaw | 0 | 灌溉种植 |
| StorageLocker | 1×1 | BuildableRaw | 0 | 储存 |
| RationBox | 2×2 | BuildableRaw | 0 | 储食 |
| Cot | 1×1 | BuildableRaw | 0 | 床 |
| Lavatory | 1×2 | Metal | 0 | 抽水马桶 |
| WashBasin | 1×1 | BuildableRaw | 0 | 洗手 |
| Outhouse | 1×2 | BuildableRaw | 0 | 初期厕所 |
| Tile | 1×1 | BuildableRaw | 0 | 地板 |
| InsulationTile | 1×1 | BuildableRaw | 0 | 隔热墙 |
| Ladder | 1×1 | BuildableRaw | 0 | 梯子 |
| FirePole | 1×1 | Metal | 0 | 火棒 |
| PneumaticDoor | 1×2 | Metal | 0 | 气压门 |
| Battery | 1×1 | Metal | 0 | 电池(1000J) |
| Transformer | 2×1 | Metal | 0 | 变压器 |
| ResearchStation | 2×2 | BuildableRaw | +60W | 初级研究 |
| SuperComputer | 2×2 | Plastic | +120W | 高级研究 |
| SteamTurbine | 4×2 | Metal | -850W | 发电+热删除 |
| Aquatuner | 1×2 | RefinedMetal | +1200W | 液体冷却 |
| Kiln | 1×2 | BuildableRaw | 0 | 烧陶瓷/玻璃 |
| MetalRefinery | 3×2 | Metal | +1200W | 精炼金属 |
| PolymerPress | 2×3 | Metal | +240W | 石油→塑料 |
| Incubator | 2×2 | BuildableRaw | 0 | 孵化蛋 |

---

## 四、AI 操作铁律

### 4.1 标准操作流程（每一步自动拉视角）

```
STEP 1: 暂停
  pause "我要做什么"          ← 必须！任何决策前暂停

STEP 2: 感知
  status                    ← 游戏总览
  resources                 ← 资源清单
  events                    ← 最近事件
  explore x y w h           ← 探索目标区域

STEP 3: 验证坐标
  cell x y                  ← 检查目标格子是否可建造/可挖掘
  registry buildings ID     ← 确认buildingId正确

STEP 4: 执行
  dig x y w h               ← 先挖（自动拉视角）
  build ID x y              ← 再建（自动拉视角）
  deconstruct x y            ← 拆除（自动拉视角）

STEP 5: 验证与恢复
  events                    ← 检查执行结果
  unpause 1                 ← 恢复运行
```

### 4.2 错误处理

| 错误 | 原因 | 对策 |
|------|------|------|
| `nothing_to_dig` | 区域已经挖空 | 跳过挖掘，直接建造 |
| `cell_occupied` | 该格已有建筑 | `deconstruct` 或选相邻位置 |
| `unknown_building` | buildingId 不存在 | 查 `registry buildings <关键词>` |
| `material_shortage` | 材料不够 | `resources` 查看缺什么，先挖材料 |
| `bounds` | 坐标越界 | 确认坐标在 gridWidth×gridHeight 内 |
| `missing_prerequisites` | 科技未解锁 | 先 `research_select` 研发前置科技 |

### 4.3 紧急处理

当事件流中出现以下情况：

```
⚠️ 氧气<500kg → pause → emergency_o2 → build Electrolyzer
⚠️ 食物<200kkcal → pause → build PlanterBox ×5
⚠️ CO₂积聚 → pause → fix_co2 → 挖排气管路
⚠️ 温度>40°C → pause → 隔热+冷却模块
⚠️ 污水满溢 → pause → build WaterPurifier
```

### 4.4 工具调用速查

```
# 基本监控
python tools/oni_api.py status
python tools/oni_api.py resources
python tools/oni_api.py events
python tools/oni_api.py registry buildings <关键词>

# 坐标操作
python tools/oni_api.py cell <x> <y>          # 看格子
python tools/oni_api.py cells <x> <y> <w> <h>  # 看区域
python tools/oni_api.py explore <x> <y> <w> <h> # AI摘要
python tools/oni_api.py gas <x> <y> <r>        # 气体

# 执行
python tools/oni_api.py pause "原因"
python tools/oni_api.py dig <x> <y> <w> <h>
python tools/oni_api.py build <id> <x> <y>
python tools/oni_api.py deconstruct <x> <y>
python tools/oni_api.py prioritize <x> <y> <1-9>
python tools/oni_api.py research_select <id>
python tools/oni_api.py batch <file.json>
python tools/oni_api.py save <name>
python tools/oni_api.py camera <x> <y> <zoom>
python tools/oni_api.py unpause <1-3>

# 高级
python tools/oni_analyzer.py
python tools/oni_commander.py diagnose
python tools/oni_commander.py emergency_o2
python tools/oni_commander.py fix_co2
python tools/oni_commander.py fix_overload
python tools/oni_builder.py build spom <x> <y>
python tools/oni_builder.py build toilet_loop <x> <y>
python tools/oni_builder.py build bedroom <x> <y>
python tools/oni_builder.py build cooling <x> <y>
```