# 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