Go to file

root 205ff7668a feat: pipe/wire path building API + oni_commander.py high-level commands

New Mod endpoints:
- POST /api/action/build_pipe: build gas/liquid pipe path (x1,y1)->(x2,y2) with bridge option
- POST /api/action/build_wire: build wire path with types: regular, heavy, conductive, heavy_conductive

New Python tool: tools/oni_commander.py
High-level commands that combine multiple low-level API calls:
- diagnose: full diagnostic (power, CO2, temp, diseases, pipes)
- fix_co2: auto-detect CO2 pockets and dig vent shafts
- fix_overload: detect overloaded circuits with fix suggestions
- emergency_o2: auto-check O2 and build OxygenDiffuser/Electrolyzer
- expand_base: dig + build walls/floors in one command (one-click room expansion)
- build_pipe_line: simplified CLI for pipe path building
- build_wire_line: simplified CLI for wire path building
All high-level commands auto-pause/resume the game.

CLI: build_pipe_line, build_wire_line added to oni_api.py

2026-05-22 09:11:04 +08:00

docs

feat: priority system, batch tasks, action feedback, event daemon

2026-05-22 09:01:12 +08:00

mod

feat: pipe/wire path building API + oni_commander.py high-level commands

2026-05-22 09:11:04 +08:00

scripts

feat: priority system, batch tasks, action feedback, event daemon

2026-05-22 09:01:12 +08:00

skills

feat: complete ONI Agent project with full Mod API, Python toolchain, and development guide

2026-05-22 08:44:56 +08:00

tools

feat: pipe/wire path building API + oni_commander.py high-level commands

2026-05-22 09:11:04 +08:00

.gitignore

feat: complete ONI Agent project with full Mod API, Python toolchain, and development guide

2026-05-22 08:44:56 +08:00

config.json

feat: complete ONI Agent project with full Mod API, Python toolchain, and development guide

2026-05-22 08:44:56 +08:00

README.md

feat: pipe/wire path building API + oni_commander.py high-level commands

2026-05-22 09:11:04 +08:00

SKILL.md

feat: game pause/speed control API with AI pause protocol

2026-05-22 09:04:04 +08:00

README.md

ONI Agent — 缺氧 AI 助手工具集

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 游戏
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. 验证连接

python3 tools/oni_api.py health

预期输出: { "status": "ok", "service": "oni-agent-bridge" }

4. 查看游戏状态

python3 tools/oni_api.py status
python3 tools/oni_analyzer.py

工具链详解

`tools/oni_api.py` — Mod API 客户端

与游戏 Mod 通信的核心 CLI 工具，支持所有查询和操作。

# 状态查询
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` — 智能分析器

自动拉取全方位游戏状态，分析六大维度并生成可操作建议。

python3 tools/oni_analyzer.py

分析内容：

氧气供应状态 → 建议 SPOM 建造时机
食物储备 → 建议扩建农场/养殖
电力状况 → 建议新增发电类型
温度异常 → 建议冷却方案
水资源 → 建议过滤/收集策略
科研进度 → 建议下一个研究方向

`tools/oni_builder.py` — 蓝图建造器

预置常用建筑模块，一键部署。

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 感知游戏状态变化的实时通道。

python3 scripts/event_daemon.py

工作原理：

每 5 秒轮询 GET /api/state/events?since=<seq> 获取新事件
对事件分类（critical / warning / info）
critical 事件 → 红色告警 + 自动触发全量游戏快照（周期/窒息/饥饿/压力）
warning 事件 → 结构化输出给 AI
维护滚动事件历史（最多 200 条），AI 可随时查询摘要

事件类型：

critical — 复制人窒息、建筑损坏、电力中断 → 立即触发分析
warning — 低氧、食物短缺、高温 → 主动通知给 AI
action_feedback — 建造/挖掘等操作的结果反馈
info — 常规游戏状态变化

辅助脚本

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 诊断。确认：

游戏已启动并加载存档
Mod 已在游戏中启用
端口 23876 未被占用

Q: buildingId 从哪查？

python3 tools/oni_api.py registry buildings | grep -i electrolyzer

或者查看 docs/AI_KNOWLEDGE_BASE.md。

Q: 怎么知道在哪个坐标建造？

使用 explore 命令探索区域：

python3 tools/oni_api.py explore 40 40 30 20

它会告诉你该区域有哪些建筑、复制人、元素分布，帮你决策。

许可证

MIT

README.md Unescape Escape

ONI Agent — 缺氧 AI 助手工具集

整体架构

快速开始

前置条件

1. 安装 Mod

2. 启动游戏

3. 验证连接

4. 查看游戏状态

工具链详解

tools/oni_api.py — Mod API 客户端

tools/oni_analyzer.py — 智能分析器

tools/oni_builder.py — 蓝图建造器

scripts/event_daemon.py — 事件守护进程（AI 输入源）

辅助脚本

Mod API 完整端点

状态查询 (GET)

地图/格子数据 (GET)

实体注册表 (GET，AI 参考)

操作 (POST)

项目结构

文档索引

常见问题

许可证

README.md

`tools/oni_api.py` — Mod API 客户端

`tools/oni_analyzer.py` — 智能分析器

`tools/oni_builder.py` — 蓝图建造器

`scripts/event_daemon.py` — 事件守护进程（AI 输入源）