oniagent/README.md

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

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

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

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/
│   ├── oni_api.py                # CLI 客户端 (20+ 子命令)
│   ├── oni_analyzer.py           # 六维度分析
│   ├── oni_builder.py            # 蓝图建造
│   └── oni_commander.py          # 高级指令
├── scripts/
│   ├── event_daemon.py           # 事件守护进程
│   ├── build_mod.sh              # 编译脚本
│   └── setup.sh                  # 环境初始化
├── docs/
│   ├── AI_KNOWLEDGE_BASE.md      # AI 知识库
│   └── MOD_DEV_GUIDE.md          # Mod 开发指南
└── skills/
    └── oni_agent.md              # Agent skill 定义

文档索引

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

许可证

MIT