326 lines
13 KiB
Markdown
326 lines
13 KiB
Markdown
# ONI Agent — 缺氧 AI 助手工具集
|
||
|
||
[Oxygen Not Included](https://www.kleientertainment.com/games/oxygen-not-included)（《缺氧》）是一款高难度的太空殖民模拟游戏。**ONI Agent** 为 AI 提供了一套完整的"眼手"系统：92 个 RESTful API 端点覆盖了玩家能做的全部操作（建造/挖掘/研究/管线/自动化/生物管理/覆盖层切换等），截图和视角控制让 AI 看到游戏画面，事件守护进程让 AI 实时感知游戏动态。Mod + Python 工具链 + AI 三层架构，让任何支持 Tool Use 的模型都能像人类一样操作游戏。
|
||
|
||
## 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ AI Agent │
|
||
│ (Claude / GPT / 任何支持 Tool Use 的模型) │
|
||
└──────┬──────────────────────────┬───────────────┘
|
||
│ HTTP API (RESTful JSON) │ CLI 工具链
|
||
▼ ▼
|
||
┌──────────────┐ ┌────────────────────────────┐
|
||
│ ONI Mod │ │ Python Tools │
|
||
│ (C# / │ │ ├── oni_api.py (客户端) │
|
||
│ Harmony) │ │ ├── oni_analyzer.py (分析) │
|
||
│ 端口 23876 │ │ └── oni_builder.py (蓝图) │
|
||
└──────┬───────┘ └──────────┬─────────────────┘
|
||
│ │
|
||
▼ ▼
|
||
┌─────────────────────────────────────────────────┐
|
||
│ Oxygen Not Included (游戏) │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 前置条件
|
||
|
||
- [Oxygen Not Included](https://store.steampowered.com/app/457140) 游戏
|
||
- Python 3.8+
|
||
- Mod 文件部署到游戏 Mod 目录
|
||
|
||
### 1. 安装 Mod
|
||
|
||
将 `mod/` 目录下的内容（`mod_info.yaml` + `ONIAgentBridge.dll`）放入游戏的 Mod 文件夹：
|
||
|
||
```
|
||
Windows: %USERPROFILE%\Documents\Klei\OxygenNotIncluded\mods\local\ONIAgentBridge\
|
||
macOS: ~/Library/Application Support/Klei/OxygenNotIncluded/mods/local/ONIAgentBridge/
|
||
Linux: ~/.config/unity3d/Klei/OxygenNot Included/mods/local/ONIAgentBridge/
|
||
```
|
||
|
||
### 2. 启动游戏
|
||
|
||
启动 ONI，在 Mod 菜单中启用 **ONI Agent Bridge**，加载存档。
|
||
|
||
### 3. 验证连接
|
||
|
||
```bash
|
||
python3 tools/oni_api.py health
|
||
```
|
||
|
||
预期输出: `{ "status": "ok", "service": "oni-agent-bridge" }`
|
||
|
||
### 4. 查看游戏状态
|
||
|
||
```bash
|
||
python3 tools/oni_api.py status
|
||
python3 tools/oni_analyzer.py
|
||
```
|
||
|
||
## 工具链详解
|
||
|
||
### `tools/oni_api.py` — Mod API 客户端
|
||
|
||
与游戏 Mod 通信的核心 CLI 工具，支持所有查询和操作。
|
||
|
||
```bash
|
||
# 状态查询
|
||
python3 tools/oni_api.py status # 游戏总览
|
||
python3 tools/oni_api.py resources # 全部资源
|
||
python3 tools/oni_api.py buildings # 全部建筑
|
||
python3 tools/oni_api.py duplicants # 复制人详情
|
||
python3 tools/oni_api.py research # 科技进度
|
||
python3 tools/oni_api.py geysers # 喷泉列表
|
||
python3 tools/oni_api.py critters # 小动物
|
||
python3 tools/oni_api.py plants # 植物
|
||
python3 tools/oni_api.py rooms # 房间
|
||
|
||
# 地图/格子数据
|
||
python3 tools/oni_api.py cell 10 5 # 查看单个格子
|
||
python3 tools/oni_api.py cells 0 0 20 20 # 查看 20x20 区域
|
||
python3 tools/oni_api.py slice y 20 0 50 # 扫描第 20 行
|
||
python3 tools/oni_api.py gas 50 50 30 # 气体分析
|
||
python3 tools/oni_api.py explore 40 40 30 20 # AI 友好摘要
|
||
|
||
# 实体注册表（查询 ID）
|
||
python3 tools/oni_api.py registry buildings Electrolyzer
|
||
python3 tools/oni_api.py registry elements Water
|
||
python3 tools/oni_api.py registry techs
|
||
|
||
# 执行操作
|
||
python3 tools/oni_api.py dig 10 10 8 6 # 挖掘区域
|
||
python3 tools/oni_api.py build Electrolyzer 15 12 # 建造建筑
|
||
python3 tools/oni_api.py deconstruct Tile 10 10 # 拆除
|
||
python3 tools/oni_api.py prioritize 15 12 9 # 优先
|
||
python3 tools/oni_api.py research_select ImprovedOxygen # 科研
|
||
python3 tools/oni_api.py mop 10 10 # 清理液体
|
||
python3 tools/oni_api.py harvest 20 15 # 收获植物
|
||
|
||
# 游戏速度控制（AI 操作前必须先暂停）
|
||
python3 tools/oni_api.py pause "Reason here" # 暂停游戏
|
||
python3 tools/oni_api.py unpause 1 # 恢复（1x 速度）
|
||
python3 tools/oni_api.py speed 3 # 直接设速度（不暂停）
|
||
|
||
# 批量任务
|
||
python3 tools/oni_api.py batch docs/batch_example.json # 执行批量建造计划
|
||
|
||
# 优先级管理
|
||
python3 tools/oni_api.py priority_global dig 7 # 全局挖掘优先级设为 7
|
||
python3 tools/oni_api.py priority_type Electrolyzer 9 # 电解器建造优先级设为 9
|
||
|
||
# 管道/电线路径
|
||
python3 tools/oni_api.py build_pipe_line liquid 42 40 48 40 # 铺设液体管道
|
||
python3 tools/oni_api.py build_wire_line regular 42 40 48 40 # 铺设电线
|
||
|
||
# 高级指令（多个 API 组合）
|
||
python3 tools/oni_commander.py diagnose # 全面诊断
|
||
python3 tools/oni_commander.py fix_co2 # 自动处理 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 # 一键拓展房间
|
||
```
|
||
|
||
### `tools/oni_analyzer.py` — 智能分析器
|
||
|
||
自动拉取全方位游戏状态，分析六大维度并生成可操作建议。
|
||
|
||
```bash
|
||
python3 tools/oni_analyzer.py
|
||
```
|
||
|
||
分析内容：
|
||
- 氧气供应状态 → 建议 SPOM 建造时机
|
||
- 食物储备 → 建议扩建农场/养殖
|
||
- 电力状况 → 建议新增发电类型
|
||
- 温度异常 → 建议冷却方案
|
||
- 水资源 → 建议过滤/收集策略
|
||
- 科研进度 → 建议下一个研究方向
|
||
|
||
### `tools/oni_builder.py` — 蓝图建造器
|
||
|
||
预置常用建筑模块，一键部署。
|
||
|
||
```bash
|
||
python3 tools/oni_builder.py list # 列出所有蓝图
|
||
python3 tools/oni_builder.py build spom 42 42 # 建造 SPOM
|
||
```
|
||
|
||
内置蓝图（7个）：
|
||
|
||
| 蓝图 | 说明 | 尺寸 |
|
||
|------|------|------|
|
||
| `spom` | 标准 SPOM（电解制氧+氢气发电闭环） | 8×6 |
|
||
| `spom_mini` | 紧凑型 SPOM（前期过渡用） | 5×4 |
|
||
| `toilet_loop` | 卫生间水循环（厕所→净水器→厕所） | 8×4 |
|
||
| `ranch_hatch` | 哈奇养殖模块 | 10×6 |
|
||
| `farm_mealwood` | 浆果农场（6个种植箱+储物箱） | 6×4 |
|
||
| `cooling` | 蒸汽涡轮冷却模块 | 8×6 |
|
||
| `bedroom` | 标准卧室（床+梯子床+装饰） | 8×4 |
|
||
|
||
### `scripts/event_daemon.py` — 事件守护进程（AI 输入源）
|
||
|
||
持续轮询游戏事件并将其注入 AI 输入流。这是 AI 感知游戏状态变化的实时通道。
|
||
|
||
```bash
|
||
python3 scripts/event_daemon.py
|
||
```
|
||
|
||
工作原理：
|
||
1. 每 5 秒轮询 `GET /api/state/events?since=<seq>` 获取新事件
|
||
2. 对事件分类（critical / warning / info）
|
||
3. critical 事件 → 红色告警 + **自动触发全量游戏快照**（周期/窒息/饥饿/压力）
|
||
4. warning 事件 → 结构化输出给 AI
|
||
5. 维护滚动事件历史（最多 200 条），AI 可随时查询摘要
|
||
|
||
事件类型：
|
||
- `critical` — 复制人窒息、建筑损坏、电力中断 → 立即触发分析
|
||
- `warning` — 低氧、食物短缺、高温 → 主动通知给 AI
|
||
- `action_feedback` — 建造/挖掘等操作的结果反馈
|
||
- `info` — 常规游戏状态变化
|
||
|
||
### 辅助脚本
|
||
|
||
```bash
|
||
bash scripts/auto_repair.sh # 诊断 Mod 连接
|
||
bash scripts/auto_analyze.sh # 一键健康检查+状态+分析
|
||
bash scripts/watch.sh 60 # 每 60 秒持续监控
|
||
bash scripts/setup.sh # 环境初始化
|
||
python3 scripts/event_daemon.py # 事件守护进程（AI 输入源）
|
||
```
|
||
|
||
## Mod API 完整端点
|
||
|
||
### 状态查询 (GET)
|
||
|
||
| 端点 | 说明 |
|
||
|------|------|
|
||
| `/health` | Mod 存活检测 |
|
||
| `/api/state/game` | 全局状态（周期/人数/世界尺寸） |
|
||
| `/api/state/resources` | 资源列表（含物态/分类） |
|
||
| `/api/state/duplicants` | 复制人（位置/压力/食物/当前任务） |
|
||
| `/api/state/buildings` | 建筑（位置/是否运行/功耗/分类） |
|
||
| `/api/state/research` | 科技树（进度/解锁建筑） |
|
||
| `/api/state/geysers` | 喷泉（位置/状态/排放率） |
|
||
| `/api/state/alert` | 警报 |
|
||
| `/api/state/critters` | 小动物（位置/种类/幸福度） |
|
||
| `/api/state/plants` | 植物（位置/生长进度/是否枯萎） |
|
||
| `/api/state/rooms` | 房间（类型/格数/建筑数） |
|
||
| `/api/state/queue` | 任务队列（查看待处理任务） |
|
||
| `/api/state/events?since=&limit=` | 事件流（AI 轮询增量事件） |
|
||
| `/api/state/priorities` | 优先级配置（全局/建筑/复制人） |
|
||
|
||
### 地图/格子数据 (GET)
|
||
|
||
| 端点 | 说明 |
|
||
|------|------|
|
||
| `/api/state/cell?x=10&y=5` | 单格详情 |
|
||
| `/api/state/cells?x=&y=&width=&height=` | 矩形区域批量查询 |
|
||
| `/api/state/cells/slice?axis=&index=&start=&end=` | 行/列扫描 |
|
||
| `/api/state/gas?x=&y=&radius=` | 区域气体分布 |
|
||
|
||
### 实体注册表 (GET，AI 参考)
|
||
|
||
| 端点 | 说明 |
|
||
|------|------|
|
||
| `/api/registry/buildings` | 全部建筑定义（尺寸/功耗/材料） |
|
||
| `/api/registry/elements` | 全部元素定义（比热容/熔沸点/导热） |
|
||
| `/api/registry/techs` | 全部科技定义（前置/解锁） |
|
||
| `/api/registry/priorities` | 优先级级别含义对照表 |
|
||
|
||
### 操作 (POST)
|
||
|
||
| 端点 | 请求体 |
|
||
|------|--------|
|
||
| `/api/action/dig` | `{x, y, width, height}` |
|
||
| `/api/action/build` | `{buildingId, x, y}` |
|
||
| `/api/action/deconstruct` | `{buildingId, x, y}` |
|
||
| `/api/action/prioritize` | `{x, y, priority}` |
|
||
| `/api/action/research` | `{techId}` |
|
||
| `/api/action/mop` | `{x, y}` |
|
||
| `/api/action/harvest` | `{x, y}` |
|
||
| `/api/action/schedule` | `{duplicantId, schedule}` |
|
||
| `/api/action/wardrobe` | `{duplicantId, equipment}` |
|
||
| `/api/action/batch` | `{actions: [{type, ...}]}` — 批量执行 |
|
||
| `/api/action/priority_global` | `{target, priority}` — 全局默认优先级 |
|
||
| `/api/action/priority_type` | `{buildingType, priority}` — 按建筑类型设优先级 |
|
||
| `/api/action/pause` | `{reason?}` — 暂停游戏（AI 操作前必须调用） |
|
||
| `/api/action/unpause` | `{speed?}` — 恢复游戏 |
|
||
| `/api/action/speed` | `{speed}` — 设置速度 1x/2x/3x |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
oni-agent/
|
||
├── README.md # ← 本文件
|
||
├── config.json # Mod 连接配置（host/port/timeout）
|
||
├── SKILL.md # AI Agent skill 定义与操作手册
|
||
│
|
||
├── mod/ # 游戏 Mod（C# / Harmony）
|
||
│ ├── mod_info.yaml # Mod 元信息（标题/版本/兼容性）
|
||
│ └── ONIAgentBridge.cs # HTTP API 服务实现
|
||
│
|
||
├── tools/ # Python 工具链
|
||
│ ├── oni_api.py # API 客户端（20+ 子命令）
|
||
│ ├── oni_analyzer.py # 状态分析（6维度预警+建议）
|
||
│ └── oni_builder.py # 蓝图建造（7个预置模块）
|
||
│
|
||
├── scripts/ # 辅助脚本
|
||
│ ├── setup.sh # 环境初始化
|
||
│ ├── auto_repair.sh # 连接诊断
|
||
│ ├── auto_analyze.sh # 一键分析
|
||
│ ├── watch.sh # 持续监控模式
|
||
│ └── event_daemon.py # 事件守护进程（AI 实时输入源）
|
||
│
|
||
├── docs/
|
||
│ ├── MOD_DEV_GUIDE.md # Mod 开发规范与约束
|
||
│ ├── AI_KNOWLEDGE_BASE.md # 200+ 建筑/元素/科技 ID 知识库
|
||
│ └── batch_example.json # 批量任务示例文件
|
||
│
|
||
└── skills/
|
||
└── oni_agent.md # Agent skill 定义
|
||
```
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 目标读者 | 内容 |
|
||
|------|---------|------|
|
||
| `SKILL.md` | AI Agent | 坐标系理解、API 用途、场景推理示例、操作表述规范 |
|
||
| `docs/AI_KNOWLEDGE_BASE.md` | AI Agent | 建筑 ID 对照表、元素属性、科技树、游戏机制参考 |
|
||
| `docs/MOD_DEV_GUIDE.md` | Mod 开发者 | 通信协议、端点规范、安全约束、检查清单 |
|
||
| `README.md` | 人类用户 | ← 你在看这个 |
|
||
|
||
## 常见问题
|
||
|
||
**Q: Mod 连接不上？**
|
||
|
||
运行 `bash scripts/auto_repair.sh` 诊断。确认：
|
||
1. 游戏已启动并加载存档
|
||
2. Mod 已在游戏中启用
|
||
3. 端口 23876 未被占用
|
||
|
||
**Q: `buildingId` 从哪查？**
|
||
|
||
```bash
|
||
python3 tools/oni_api.py registry buildings | grep -i electrolyzer
|
||
```
|
||
|
||
或者查看 `docs/AI_KNOWLEDGE_BASE.md`。
|
||
|
||
**Q: 怎么知道在哪个坐标建造？**
|
||
|
||
使用 `explore` 命令探索区域：
|
||
|
||
```bash
|
||
python3 tools/oni_api.py explore 40 40 30 20
|
||
```
|
||
|
||
它会告诉你该区域有哪些建筑、复制人、元素分布，帮你决策。
|
||
|
||
## 许可证
|
||
|
||
MIT
|