oniagent/SKILL.md

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（用泥土）是最简单的初期食物来源

我该怎么做：

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