diff --git a/README.md b/README.md new file mode 100644 index 0000000..0d9e28b --- /dev/null +++ b/README.md @@ -0,0 +1,268 @@ +# ONI Agent — 缺氧 AI 助手工具集 + +[Oxygen Not Included](https://www.kleientertainment.com/games/oxygen-not-included)（《缺氧》）的 AI Agent 工具集。包含一个游戏内 Mod 作为 HTTP API 服务，以及配套的 Python 工具链，让 AI 能读取游戏状态、分析局势、并执行建造/挖掘等操作。 + +## 整体架构 + +``` +┌─────────────────────────────────────────────────┐ +│ 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 # 收获植物 +``` + +### `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 | + +### 辅助脚本 + +```bash +bash scripts/auto_repair.sh # 诊断 Mod 连接 +bash scripts/auto_analyze.sh # 一键健康检查+状态+分析 +bash scripts/watch.sh 60 # 每 60 秒持续监控 +bash scripts/setup.sh # 环境初始化 +``` + +## 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` | 房间（类型/格数/建筑数） | + +### 地图/格子数据 (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` | 全部科技定义（前置/解锁） | + +### 操作 (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}` | + +## 项目结构 + +``` +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 # 持续监控模式 +│ +├── docs/ +│ ├── MOD_DEV_GUIDE.md # Mod 开发规范与约束 +│ └── AI_KNOWLEDGE_BASE.md # 200+ 建筑/元素/科技 ID 知识库 +│ +└── 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