ONI Agent — 缺氧 AI 助手工具集

Oxygen Not Included（《缺氧》）高难度太空殖民模拟游戏。
ONI Agent 为 AI 提供"眼手"系统：RESTful API + Mod（C# Harmony）+ Python 工具链，让任何支持 Tool Use 的模型都能像人类一样操作游戏。

架构

AI Agent (Claude/GPT/任何支持 Tool Use 的模型)
    ↕ Python CLI (tools/oni_api.py) + HTTP API (RESTful JSON, 端口 23876)
ONI Mod (C# Harmony)  ←→  Python Toolchain
    ↕
Oxygen Not Included (游戏进程)

快速开始

1. 安装 Mod

编译后将 mod/ 下的 mod.yaml + mod_info.yaml + 编译产出的 ONIAgentBridge.dll 放入游戏 Mod 目录：

Windows: %USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\local\ONIAgentBridge\

部署后目录结构：

ONIAgentBridge/
├── mod.yaml              # Mod 元信息
├── mod_info.yaml         # DLC/版本配置
└── ONIAgentBridge.dll    # Mod DLL

2. 启动游戏

启动 ONI → Mod 菜单 → 启用 ONI Agent Bridge → 加载存档。

3. 验证连接

python tools/oni_api.py health
# 输出: Status: ok  Version: 2.0.0

工具链

tools/oni_api.py — 主 CLI 客户端

# 状态查询
python tools/oni_api.py status           # 游戏总览
python tools/oni_api.py resources        # 资源清单
python tools/oni_api.py buildings        # 全部建筑
python tools/oni_api.py duplicants       # 复制人
python tools/oni_api.py research         # 科研
python tools/oni_api.py rooms            # 房间
python tools/oni_api.py events           # 事件日志

# 地图数据
python tools/oni_api.py cell <x> <y>              # 单格
python tools/oni_api.py cells <x> <y> <w> <h>     # 矩形区域
python tools/oni_api.py slice <axis> <i> <s> <e>  # 行列扫描
python tools/oni_api.py gas <x> <y> <r>           # 气体分布
python tools/oni_api.py explore <x> <y> <w> <h>   # AI摘要

# 注册表查询
python tools/oni_api.py registry buildings [filter]
python tools/oni_api.py registry elements [filter]
python tools/oni_api.py registry techs

# 操作（自动拉视角）
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 <techId>    # 科研
python tools/oni_api.py mop <x> <y>                 # 清理
python tools/oni_api.py harvest <x> <y>             # 收获
python tools/oni_api.py pause [reason]              # 暂停
python tools/oni_api.py unpause [speed]             # 恢复
python tools/oni_api.py speed <1-3>                 # 速度
python tools/oni_api.py camera <x> <y> [zoom]       # 视角
python tools/oni_api.py batch <file>                # 批量
python tools/oni_api.py save [name]                 # 存档
python tools/oni_api.py load <name>                 # 读档
python tools/oni_api.py priority_global <t> <p>     # 全局优先级
python tools/oni_api.py priority_type <t> <p>       # 类型优先级

tools/oni_analyzer.py — 智能分析器

python tools/oni_analyzer.py
# 分析：氧气/食物/电力/温度/水/科研 六维度 + 建议

tools/oni_builder.py — 蓝图

python tools/oni_builder.py list           # 列出蓝图
python tools/oni_builder.py build spom x y # 部署SPOM

蓝图：spom, spom_mini, toilet_loop, farm_mealwood, bedroom, cooling, ranch_hatch

tools/oni_commander.py — 高级指令

python tools/oni_commander.py diagnose        # 全面诊断
python tools/oni_commander.py emergency_o2    # 紧急制氧
python tools/oni_commander.py fix_co2         # 处理CO₂
python tools/oni_commander.py fix_overload    # 过载电路
python tools/oni_commander.py expand_base x y w h  # 拓展

tools/event_daemon.py — 事件守护进程

python tools/event_daemon.py [interval_seconds]
# 持续轮询事件，分类显示到控制台

API 端点

类别	端点	方法
健康	/health	GET
状态	/api/state/game, resources, buildings, duplicants, research, rooms, alert, camera, storage, saves, events	GET
地图	/api/state/cell, cells, cells/slice, gas	GET
注册表	/api/registry/buildings, elements, techs	GET
截图	/api/screenshot/latest	GET
操作	/api/action/pause, unpause, speed, dig, build, deconstruct, prioritize, research, mop, harvest, batch, save, load, camera, priority_global, priority_type	POST
	所有操作自动拉视角到坐标

错误格式：{success: false, error: "...", errorMessage: "..."}

项目结构

oni-agent/
├── README.md
├── SKILL.md                      # AI Agent 完整缺氧教程
├── config.json                   # Mod 连接配置
├── mod/
│   ├── ONIAgentBridge.cs         # Mod 源码 (C# Harmony)
│   ├── ONIAgentBridge.csproj
│   ├── mod.yaml / mod_info.yaml
├── tools/                        # AI 直接调用的运行时工具
│   ├── oni_api.py                # CLI 客户端 (20+ 子命令)
│   ├── oni_analyzer.py           # 六维度智能分析
│   ├── oni_builder.py            # 蓝图建造
│   ├── oni_commander.py          # 高级指令
│   └── event_daemon.py           # 事件守护进程
├── scripts/                      # 开发者/构建用脚本
│   ├── build_mod.sh              # 编译 Mod
│   ├── setup.sh                  # 环境初始化
│   ├── watch.sh                  # 热重载
│   ├── fix_csharp.py             # C# 修复
│   ├── annotate_apis.py          # API 标注
│   ├── auto_analyze.sh           # 自动分析
│   └── auto_repair.sh            # 自动修复
├── docs/
│   ├── AI_KNOWLEDGE_BASE.md      # AI 知识库 (建筑/元素/科技)
│   └── MOD_DEV_GUIDE.md          # Mod 开发指南

文档索引

文档	目标	内容
SKILL.md	AI Agent	完整游玩教程：分阶段目标/材料/可达性/方块/操作协议
docs/AI_KNOWLEDGE_BASE.md	AI Agent	建筑ID/元素属性/科技树/游戏机制参考
README.md	人类用户	← 你在看这个

许可证

MIT