# ONI Agent Skill

AI 操作《缺氧》(Oxygen Not Included) 的完整技能定义。

## 触发条件
- 用户提到《缺氧》/ Oxygen Not Included / ONI
- 用户询问游戏策略、建造方案、资源管理
- 用户希望 Mod 工具链执行操作
- 用户需要实时游戏操作协助

## 游戏核心玩法

缺氧是一款太空殖民模拟游戏。核心目标是在恶劣环境中维持复制人的生存并建设可持续基地。

### 生存要素优先级

| 优先级 | 要素 | 危险条件 | 后果 | 解决方案路线 |
|--------|------|---------|------|-------------|
| ★★★ | 氧气 | O₂ < 500 kg 或无制氧设备 | 复制人 110s 内窒息死亡 | 藻类制氧(前期) → 电解器+氢气发电(SPOM) |
| ★★★ | 食物 | Calories < 1000 kcal/人 | 复制人饿死 | 浆果种植 → 烤肉 → 营养膏棒 |
| ★★☆ | 温度 | > 40°C 或 < 10°C | 作物枯萎/复制人受伤 | 隔热/液冷+蒸汽机/加热 |
| ★★☆ | 电力 | 电量不足/电路过载 | 设备停摆/电线起火 | 手动→煤→氢→天然气→太阳能 |
| ★☆☆ | 士气 | Stress > 80% | 精神崩溃/破坏设备 | 房间奖励/装饰/按摩/高品质食物 |
| ★☆☆ | 病菌 | Slimelung/Food Poisoning | 生病死亡 | 洗手/净化/消毒/氧气服 |

### 游戏世界规则

- 二维网格地图，原点 (0,0) 在左下角，x 向右 y 向上
- 气体按密度分层：CO₂(沉底) < PollutedO₂ < O₂ < NaturalGas < H₂(上升)
- 建筑占用 w×h 格子，坐标指左下角锚点
- 科技通过研究站→超级计算机逐步解锁新建筑
- 每 3 周期传送舱提供一次新复制人或补给选择

---

## API 总览（92 个端点）

工具链让 AI 能像人类玩家一样理解游戏并执行操作。所有 API 通过 `tools/oni_api.py` 命令行调用。

### 一、状态查询 — 理解"当前发生了什么"

每次 AI 推理前工具自动暂停游戏，保证数据时效性。AI 操作完成后主动 unpause。

```bash
# 全局总览 — 最常用的命令
python3 tools/oni_api.py status
# 输出：周期、窒息人数、饥饿人数、压力人数、是否暂停、游戏速度

# 全面诊断
python3 tools/oni_commander.py diagnose
# 输出：电力+CO₂+温度+疾病+管道的完整报告
```

**各状态查询命令的用途：**

| 命令 | 等价于玩家做什么 | AI 用它做什么 |
|------|-----------------|-------------|
| `status` | 看一眼基地总览面板 | 快速评估危机：有人在窒息吗？在挨饿吗？ |
| `resources` | 打开资源面板 | 检查氧气储量够多久、煤还剩多少 |
| `duplicants` | 逐一查看每个复制人 | 谁在窒息？谁压力爆了？谁没事干？ |
| `buildings` | 按分类查看建筑 | 数一数有多少发电机、电解器、种植箱 |
| `power` | 打开电力覆盖层 | 哪个电路过载了？负载多少？ |
| `co2` | 看 CO₂ 在哪聚集 | CO₂ 是前中期最大杀手，找到它并挖排气道 |
| `temp_zones` | 看温度覆盖层 | 找到过热区域（>50°C）和过冷区域（<5°C） |
| `pipes gas/liquid` | 点开管道看看 | 管道堵塞了吗？内容物在流动吗？ |
| `rooms` | 打开房间覆盖层 | 确认宿舍/卫生间/餐厅生效了吗 |
| `morale` | 查看士气面板 | 士气够不够支撑当前技能数 |
| `diseases` | 打开病菌覆盖层 | 谁被感染了？环境病菌多吗？ |
| `storage` | 查看储物建筑 | 储备粮在哪、存了多少 |
| `storages` | 同上 | 同 storage |
| `resources` | 资源面板 | 所有物资的精确余量 |
| `skills` | 技能面板 | 每个复制人的属性值和已学技能 |
| `research` | 科技树 | 哪些科技已完成、哪些可研究 |
| `research_detail` | 点开研究站 | 研究站在工作吗？现在在研究什么？ |
| `buildable` | 建造菜单 | 当前科技解锁了哪些建筑 |
| `geysers` | 查看喷泉 | 找到水源/天然气/火山位置 |
| `critters` | 查看生物 | 哈奇/飞鱼/滑鳞的数量和位置 |
| `plants` | 查看植物 | 作物生长进度、是否枯萎 |

### 二、格子地图 — 理解"每个格子有什么"

所有建造操作前必须先用格子查询确认位置。

```bash
# 查看单个格子（最常用）
python3 tools/oni_api.py cell 45 48
# 输出：元素、温度、有无建筑、有无复制人、是否可挖掘、是否安全

# 查看 10x10 区域
python3 tools/oni_api.py cells 40 40 10 10
# 输出：区域内所有格子的地图 + AI 友好摘要

# 扫描某一行/列
python3 tools/oni_api.py slice y 20 0 50
# 输出：第 20 行从 0 到 50 的每个格子

# 气体分析
python3 tools/oni_api.py gas 50 50 30
# 输出：以 50,50 为中心半径 30 内的气体分布

# AI 友好区域探索
python3 tools/oni_api.py explore 40 40 20 20
# 输出：区域内建筑列表+复制人+元素摘要+感兴趣格子
```

**AI 坐标定位方法：**

```
方法 1: buildings → 查已有建筑坐标 → 在附近偏移找空地
方法 2: explore <x> <y> <w> <h> → 找 buildings_in_region 为空的区域
方法 3: cell <x> <y> → 确认 isSolid=false + hasBuilding=false + isVisible=true
方法 4: co2 → 在 CO₂ 聚集点下方挖排气通道
方法 5: gas → 在气体聚集区放气体泵
```

### 三、实体注册表 — "这个建筑是什么"

AI 在运行时查询任何不懂的 ID：

```bash
# 查建筑
python3 tools/oni_api.py registry buildings Electrolyzer
# 输出：名称、分类、尺寸(2x2)、功耗(120W)、所需材料

# 查元素
python3 tools/oni_api.py registry elements Water
# 输出：比热容、导热系数、沸点(99°C)、物态

# 查科技
python3 tools/oni_api.py registry techs ImprovedOxygen
# 输出：前置科技、解锁建筑(Electrolyzer)

# 查优先级含义
python3 tools/oni_api.py registry priorities
# 输出：1=最低 5=默认 9=紧急
```

### 四、建造操作 — "建造世界"

建造 = 挖掘(dig) → 放置(build)。坐标是建筑左下角。

```bash
# 挖掘区域
python3 tools/oni_api.py dig 40 40 10 10
# 在 (40,40) 处挖一个 10x10 的空间

# 放置建筑
python3 tools/oni_api.py build Electrolyzer 45 42
# 在 (45,42) 放电解器（左下角定位，占 2x2 格）

# 铺设管路
python3 tools/oni_api.py build_pipe_line liquid 42 40 48 40 line
# 从 (42,40) 到 (48,40) 铺液体管道
# mode=line: 与已有管线合并
# mode=cross: 交叉处自动用跨接器跳过
# mode=single: 单段

# 铺设电线
python3 tools/oni_api.py build_wire_line heavy 30 20 45 20 cross
# 从 (30,20) 到 (45,20) 铺重载电线
# 交叉处用跨接器不连通

# 拆除
python3 tools/oni_api.py deconstruct Tile 42 45
# 拆除 (42,45) 处的 Tile

# 旋转
python3 tools/oni_api.py rotate 45 48
# 旋转 (45,48) 处的建筑

# 清碎片
python3 tools/oni_api.py clear 40 40 5
# 清除 (40,40) 半径 5 内的碎片

# 复制设置
python3 tools/oni_api.py copy_settings 45 48 50 48
# 把 (45,48) 建筑的设置复制到 (50,48)
```

### 五、建筑操作 — "使用已建成的建筑"

相当于玩家点击建筑后选择功能。

```bash
# 开关
python3 tools/oni_api.py toggle 45 42
# 关闭/打开电解器（省电或恢复运行）

# 设优先级
python3 tools/oni_api.py set_building_priority 45 42 9
# 电解器优先级设为 9（紧急）

# 设配方
python3 tools/oni_api.py set_recipe 30 25 Crush
# 碎岩机设为粉碎模式

# 开关自动化
python3 tools/oni_api.py set_automation 45 42 on
# 电解器开启自动化控制

# 清空储物
python3 tools/oni_api.py empty 50 50
# 清空 (50,50) 储物箱全部内容

# 设储物过滤
python3 tools/oni_api.py storage_filter 50 50 Coal
# 储物箱只收煤炭

# 设冰箱温度
python3 tools/oni_api.py fridge_temp 60 30 2
# 冰箱设为 2°C

# 设电池充放电阈值
python3 tools/oni_api.py battery_charge 35 25 90 20
# 智能电池 90% 停充、20% 启动

# 设阀门流量
python3 tools/oni_api.py valve_flow 42 42 1000
# 阀门限流 1000g/s

# 设排气口压力
python3 tools/oni_api.py vent_pressure 45 50 2000
# 高压排气口设为 2000g

# 设孵化器
python3 tools/oni_api.py incubator_setting 50 40 HatchEgg
# 孵化器优先孵哈奇蛋

# 设传感器阈值
python3 tools/oni_api.py sensor_threshold 70 30 500
# 气压传感器阈值 500g

# 消毒
python3 tools/oni_api.py disinfect 42 42
# 对 (42,42) 消毒

# 清扫
python3 tools/oni_api.py sweep 40 40 10
# 标记 (40,40) 半径 10 内的物品为待清扫

# 取消任务
python3 tools/oni_api.py cancel_errand 45 42
# 取消电解器处的排队任务
```

### 六、门控制

```bash
# 锁门
python3 tools/oni_api.py door_lock 42 45 on
# 锁上 (42,45) 的门，复制人不能通过

# 单向通行
python3 tools/oni_api.py door_one_way 42 45 left
# 门只允许向左通过

# 手动开门/关门
python3 tools/oni_api.py door_open 42 45 off
# 手动关闭 (42,45) 的门
```

### 七、复制人管理

```bash
# 移动复制人
python3 tools/oni_api.py dupe_move Dup1 30 25
# 命令 Dup1 移动到 (30,25)

# 取消任务
python3 tools/oni_api.py dupe_cancel_task Dup1
# 命令 Dup1 取消当前正在做的事

# 分配工作
python3 tools/oni_api.py assign_job Dup1 Dig
# 让 Dup1 专注挖掘工作

# 个人优先级
python3 tools/oni_api.py dupe_personal_priority Dup1 Dig 9
# Dup1 的挖掘优先级设为 9（最高）
```

### 八、科研管理

```bash
# 查看研究状态
python3 tools/oni_api.py research_detail
# 输出：研究站是否工作、当前研究什么、超级计算机是否造好

# 选择研究
python3 tools/oni_api.py research_select ImprovedOxygen
# 开始研究 ImprovedOxygen

# 取消研究
python3 tools/oni_api.py research_cancel
# 取消全部当前研究
```

### 九、生物/植物管理

```bash
# 攻击生物
python3 tools/oni_api.py critter_attack 120 80
# 标记 (120,80) 的生物为攻击目标

# 抓捕生物
python3 tools/oni_api.py critter_wrangle 120 80
# 抓捕 (120,80) 的生物运到存放点

# 收获植物
python3 tools/oni_api.py harvest 50 45
# 收获 (50,45) 的成熟作物

# 拔除植物
python3 tools/oni_api.py plant_uproot 50 45
# 拔掉 (50,45) 的植物
```

### 十、游戏控制

```bash
# 暂停/恢复
python3 tools/oni_api.py pause "Building SPOM"
python3 tools/oni_api.py unpause 1

# 速度
python3 tools/oni_api.py speed 3

# 存档回滚
python3 tools/oni_api.py save "before_experiment"
python3 tools/oni_api.py saves
python3 tools/oni_api.py load "before_experiment"

# 截图视角
python3 tools/oni_api.py snapshot /tmp/now.png
python3 tools/oni_api.py camera 120 80 20

# 覆盖层切换
python3 tools/oni_api.py overlay power
python3 tools/oni_api.py overlay temp
python3 tools/oni_api.py overlay gas
python3 tools/oni_api.py overlay rooms

# 传送舱
python3 tools/oni_api.py printing_pod
python3 tools/oni_api.py printing_pod_select 0
```

### 十一、批量操作

```bash
python3 tools/oni_api.py batch docs/batch_example.json
# 一次执行多个动作，逐个报告结果
```

### 十二、高级指令

```bash
# 全面诊断
python3 tools/oni_commander.py diagnose

# 自动处理 CO₂
python3 tools/oni_commander.py fix_co2

# 处理过载电路
python3 tools/oni_commander.py fix_overload

# 紧急制氧
python3 tools/oni_commander.py emergency_o2

# 一键拓展房间
python3 tools/oni_commander.py expand_base 40 40 10 8
```

---

## 常见场景查询路线

### "复制人要窒息了"
```
status → 看 suffocating 计数
duplicants → 找 oxygen < 20 的复制人
cell <窒息复制人坐标> → 所在格子的元素
co2 → 如果是 CO₂ 窒息，fix_co2 挖排气道
resources → O₂ 存量和 Algae 存量
buildings → 过滤 Oxygen 分类看有无制氧设备
无设备 → emergency_o2 或 build OxygenDiffuser
```

### "基地没电了"
```
power → 看各电路负载和过载
resources → Coal/Hydrogen/NaturalGas 存量
buildings → Power 分类有哪些发电机
过载 → fix_overload
缺电 → 根据资源选发电机类型
```

### "研究卡住了"
```
research_detail → 研究站通不通电、有没有复制人在研究
building_detail <研究站坐标> → 供上电了吗
resources → Dirt 够吗（研究站消耗）
需超级计算机 → build SuperComputer <坐标>
```

### "管道不走了"
```
pipes liquid → 看管道内容
building_detail <水泵> → 泵有没有电
building_detail <目的地建筑> → 输入是否已满
build_pipe_line liquid <起点> <终点> cross → 重建
```

### "传送舱来了"
```
event_daemon 显示 [EVENT] Printing Pod ready
printing_pod → 看选项
printing_pod_select 0|1|2 → 选择
```

---

## AI 操作铁律

```
铁律 1: AI 开始推理/决策前 → 工具自动暂停游戏
铁律 2: AI 需要问用户时 → 工具自动暂停
铁律 3: AI 退出回答时 → 确保游戏已暂停（无人监控时不能运行）
铁律 4: 写操作前 → 工具自动确保暂停态
铁律 5: 重大操作前 → save 存档，失败可 load 回滚
铁律 6: 每次操作后检查反馈 → 读 error + errorMessage + suggestion
```

## 工具列表

| 工具 | 用途 |
|------|------|
| `tools/oni_api.py` | 92 个 API 端点的 CLI 客户端（所有查询/操作） |
| `tools/oni_commander.py` | 高级指令（diagnose/fix_co2/expand_base 等） |
| `tools/oni_analyzer.py` | 自动分析+6 维度预警建议 |
| `tools/oni_builder.py` | 预置 SPOM/农场/养殖等蓝图 |
| `scripts/event_daemon.py` | 事件守护进程，持续轮询推送游戏事件到 AI |

## 常用操作速查

```bash
# 每分钟检查
python3 scripts/event_daemon.py

# 紧急三步
python3 tools/oni_api.py pause "Emergency"
python3 tools/oni_commander.py diagnose
python3 tools/oni_api.py status
# ...操作...
python3 tools/oni_api.py unpause 1

# 存档保护
python3 tools/oni_api.py save "before_操作"
# ...操作...
# 如果搞砸了：
python3 tools/oni_api.py load "before_操作"

# 截图确认
python3 tools/oni_api.py camera 50 50 20
python3 tools/oni_api.py snapshot
```