177 lines
6.4 KiB
Markdown
177 lines
6.4 KiB
Markdown
# ONI Agent — 缺氧 AI 助手工具集
|
||
|
||
[Oxygen Not Included](https://www.kleientertainment.com/games/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. 验证连接
|
||
|
||
```bash
|
||
python tools/oni_api.py health
|
||
# 输出: Status: ok Version: 2.0.0
|
||
```
|
||
|
||
## 工具链
|
||
|
||
### `tools/oni_api.py` — 主 CLI 客户端
|
||
|
||
```bash
|
||
# 状态查询
|
||
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` — 智能分析器
|
||
|
||
```bash
|
||
python tools/oni_analyzer.py
|
||
# 分析：氧气/食物/电力/温度/水/科研 六维度 + 建议
|
||
```
|
||
|
||
### `tools/oni_builder.py` — 蓝图
|
||
|
||
```bash
|
||
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` — 高级指令
|
||
|
||
```bash
|
||
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` — 事件守护进程
|
||
|
||
```bash
|
||
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
|