jianf/oniagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ONI Agent Bridge - initial mod implementation

Browse Source
This commit is contained in:
JianFeeeee
2026-05-30 11:00:36 +08:00
commit 1f25d3d879
95 changed files with 50686 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
docs/AI_KNOWLEDGE_BASE.md Normal file
View File

@ -0,0 +1,268 @@
# ONI Knowledge Base — AI Reference
This file aggregates all building IDs, element IDs, tech IDs, and their semantic metadata
in one structured document. The AI uses this to understand what each entity means and
how to reason about the game.
## Coordinate System
ONI uses a 2D grid. The origin (0,0) is at the **bottom-left** of the map.
- x increases to the right
- y increases upward
- Each cell is 1x1 tile
- Buildings may occupy multiple cells (width x height); the (x,y) is the **bottom-left anchor**
- World size varies by asteroid (default ~256x384 cells)
When the AI wants to reference a location:
- Use absolute (x,y) coordinates
- For regions: (x, y, width, height)
- For buildings: reference the bottom-left cell of the building
- For movement: "at (x,y)" or "from (x1,y1) to (x2,y2)"
## Building Categories
| Category | Purpose | Examples |
|------------|----------------------------------------|---------------------------------------------------|
| Base | Structure, storage, doors, ladders | Tile, Ladder, StorageBin, InsulatedTile, Door |
| Oxygen | Oxygen production, gas cleaning | Electrolyzer, OxygenDiffuser, Deodorizer |
| Power | Power generation, storage, wiring | CoalGenerator, HydrogenGenerator, Battery |
| Food | Food production, cooking, ranching | PlanterBox, ElectricGrill, MicrobeMusher, Ranch |
| Plumbing | Liquid handling, hygiene | LiquidPump, Lavatory, WaterSiever, Shower |
| Ventilation| Gas handling | GasPump, GasFilter, GasVent |
| Refinement | Material processing | MetalRefinery, RockCrusher, Kiln, Compost |
| Medicine | Health, disease treatment | Apothecary, MassageTable, SickBay |
| Furniture | Decor, morale, stress relief | Cot, MessTable, ArcadeCabinet, FlowerPot |
| Stations | Research, suit docks, crafting | ResearchStation, SuperComputer, AtmoSuitDock |
| Utilities | Temperature management | ThermoAquatuner, SpaceHeater, TempshiftPlate |
| Automation | Logic circuits, sensors | AND Gate, AtmoSensor, AutomationWire |
| Shipping | Conveyor systems | ConveyorLoader, ConveyorRail, SolidFilter |
## Key Building IDs (frequently used by AI)
```
# Oxygen production
Electrolyzer -> Produces O2 + H2 from water (needs 1kg/s water)
OxygenDiffuser -> Produces O2 from algae (early game)
Deodorizer -> Converts PollutedOxygen to Oxygen (needs filtration medium)
# Power
ManualGenerator -> 400W, duplicant powered
CoalGenerator -> 600W, consumes Coal
HydrogenGenerator -> 800W, consumes H2
NaturalGasGenerator-> 800W, consumes NaturalGas
PetroleumGenerator -> 2000W, consumes Petroleum
SteamTurbine -> Extracts heat from steam, produces power
SolarPanel -> 380W max, needs light
WoodBurner -> 300W, consumes Lumber
# Power storage
Battery -> 10kJ storage, small
JumboBattery -> 40kJ storage
SmartBattery -> 20kJ storage, automation output
# Food
PlanterBox -> Grows plants, needs dupe delivery
FarmTile -> Grows plants with irrigation
HydroponicFarm -> Grows plants with automatic irrigation
ElectricGrill -> Cooks food (better quality)
MicrobeMusher -> Makes basic mush bars from water + dirt
GasRange -> Advanced cooking with gas
Refrigerator -> Stores food, slows decay
# Plumbing
LiquidPump -> Pumps liquids (240kg/s)
Lavatory -> Produces PollutedWater from dupe use
WaterSiever -> Filters PollutedWater -> Water
Desalinator -> Removes salt from SaltWater/Brine
LiquidVent -> Outputs liquid into world
# Ventilation
GasPump -> Pumps gases (500g/s)
GasFilter -> Filters specific gas from mixed pipes
GasVent -> Outputs gas into world
HighPressureGasVent-> 20kg/tile max pressure
# Refinement
MetalRefinery -> Refines metal ores into refined metals
RockCrusher -> Crushes rock into sand/power
Kiln -> Burns clay -> ceramic
GlassForge -> Makes glass from sand
Compost -> Converts polluted dirt into dirt
# Base
Tile -> Standard tile, 2 tiles high
Ladder -> Allows vertical movement
InsulatedTile -> Reduces heat transfer (best insulation)
ManualAirlock -> Manual door
PneumaticDoor -> Auto door, lets gas pass
MechanizedAirlock -> Auto door, seals gas/liquid
StorageBin -> Stores solid resources
LiquidReservoir -> Stores 5t of liquid
GasReservoir -> Stores 150kg of gas
# Temperature
ThermoAquatuner -> Cools liquid piped through it (needs steam room)
ThermoRegulator -> Cools gas piped through it
SpaceHeater -> Heats area (inefficient)
LiquidTepidizer -> Heats liquid (up to 85C)
TempshiftPlate -> Distributes heat evenly
# Stations
ResearchStation -> Basic research (needs dirt)
SuperComputer -> Advanced research (needs plastic)
AtmoSuitDock -> Stores atmo suit
GroomingStation -> Grooms critters for happiness/eggs
RanchStation -> Ranching skill station
FarmStation -> Improves farm yield (needs fertilizer)
PowerControlStation-> Improves generator efficiency
# Medicine
MassageTable -> Reduces stress
SickBay -> Cures diseases
TriageCot -> Heals physical damage
Apothecary -> Produces medicine
# Automation (common items)
AtmoSensor -> Senses gas pressure
ThermoSensor -> Senses temperature
HydroSensor -> Senses liquid pressure
GasElementSensor -> Senses specific gas type
AND Gate, NOT Gate, FILTER Gate, BUFFER Gate
```
## Key Element IDs (resources)
```
# Critical survival
Oxygen -> Breathable gas (needed by dupes)
Water -> Essential for farming, electrolysis, life support
Dirt -> Used in research (early) and farming
Algae -> Consumed by OxygenDiffuser
# Food chain
Calories -> Aggregate food energy for colony
MealLice -> Basic food from mealwood plants
BristleBerry -> Mid-tier food from bristle blossom
Mushroom -> Food from dusk cap (needs CO2 + slime)
RawEgg -> Egg for cooking
Meat -> From ranching
# Power chain
Coal -> Burned in CoalGenerator
Hydrogen -> Burned in HydrogenGenerator
NaturalGas -> Burned in NaturalGasGenerator
Petroleum -> Burned in PetroleumGenerator
CrudeOil -> Can be refined to Petroleum
# Construction metals
CopperOre -> Early building material
IronOre -> Mid building material
GoldAmalgam -> High corrosion resistance
Wolframite -> Very high melting point (tungsten source)
Steel -> Strong, high melting point (refined)
RefinedIron -> Mid refined metal
Plastic -> Advanced material (from polymer press or dreckos)
Ceramic -> Best insulation material
# Water / liquids
SaltWater -> Can be desalinated to Water
Brine -> Can be desalinated (more salt per water)
PollutedWater -> Can be filtered to Water (also used by reed fiber)
CrudeOil -> Pumped from oil biome
Petroleum -> Refined from oil (cooking or refinery)
Lumber -> From arbor trees, burned in wood burner
Ethanol -> From lumber, burned in petroleum generator
# Gas handling
PollutedOxygen -> Can be deodorized to Oxygen
CarbonDioxide -> Sinks to bottom, used by mushrooms/soda fountain
ChlorineGas -> Disinfects, used by balm lily
SourGas -> Can be cooled to methane + sulfur
# Rare / advanced
Niobium -> End-game space material
Thermium -> Best heat conductor (space material)
Isoresin -> Used for insulation (space material)
ViscoGel -> Non-mixing liquid (space material)
Radium -> Radioactive, spaced out DLC
```
## Research Tech Tree (simplified path)
```
Tier 0 (start): FarmingTech, PowerRegulation, Plumbing, Ventilation
Tier 1: FoodPreparation (-> ElectricGrill, MicrobeMusher)
InteriorDecor (-> Cot, FlowerPot, various decor)
AdvancedPowerRegulation (-> SmartBattery, PowerTransformer)
LiquidPiping (-> LiquidPump, WaterSiever, Desalinator)
GasPiping (-> GasPump, GasFilter)
FineDining (-> GasRange, Refrigerator)
Tier 2: ImprovedOxygen (-> Electrolyzer)
RefinedObjects (-> MetalRefinery, RockCrusher)
TemperatureModulation (-> ThermoAquatuner, ThermoRegulator)
Ranching (-> GroomingStation, Incubator)
SmartStorage (-> LiquidReservoir, GasReservoir)
Automation (-> first automation buildings)
Tier 3: HighTemperatureForging (-> Steel)
SpaceProgram (-> telescope, rocket platform)
CryoFuelPropulsion (-> hydrogen rocket engine)
Tier 4: MaterialsScience (-> SuperCoolant, ViscoGel)
```
## Building Size Reference (width x height)
```
1x1: Wire, GasPipe, LiquidPipe, AutomationWire, Switch, Sensor
1x2: ManualGenerator, Battery, PlanterBox, FarmTile, RationBox
2x1: GasFilter, LiquidFilter, Incubator, Jukebot
2x2: CoalGenerator, HydrogenGenerator, OxygenDiffuser, Electrolyzer,
GasPump, LiquidPump, AlgaeTerrarium, Deodorizer, WaterSiever,
ElectricGrill, MicrobeMusher, RockCrusher, Kiln, Compost,
MassageTable, Apothecary, ResearchStation, TextileLoom
2x3: MetalRefinery, PolymerPress, OilRefinery, AtmoSuitDock
2x4: Telescope, MolecularForge
3x1: LadderBed, DisplayShelf
3x2: ManualAirlock, PneumaticDoor, MechanizedAirlock, ConveyorLoader,
SmartStorageBin, LiquidReservoir, GasReservoir
3x3: Shower, Sauna, HotTub
3x4: SteamTurbine
4x2: SuperComputer, JumboBattery, StorageBin
4x4: SolarPanel
```
## Common Game Mechanics (AI reference)
### Gas/Liquid Physics
- Gases **layer by density**: CO2 (sinks) < O2 < PollutedO2 < NaturalGas < H2 (rises)
- Liquids **layer by density**: Petroleum < Water/SaltWater/Brine < CrudeOil < Mercury
- Pressure limit for gas vents: GasVent = 2kg/tile, HighPressureGasVent = 20kg/tile
- Buildings overheat above their overheat temperature (default 75C, some higher)
- Insulated Tile reduces heat transfer by ~100x
### Duplicant Needs
- Oxygen: need ~100g/s per dupe
- Food: need ~1000kcal/cycle per dupe
- Stress: > 50% starts causing problems, > 80% mental breaks
- Temperature: comfortable at 18-35C, hypothermia below 10C, hyperthermia above 40C
- Morale: affected by decor, food quality, room bonuses
### Room Types
- Latrine: Outhouse + WashBasin = +1 morale
- Washroom: Lavatory + Sink = +2 morale
- Barracks: Cot/LadderBed + 1 decor = +1 morale
- Bedroom: ComfyBed + 1 decor = +2 morale
- Mess Hall: MessTable + 1 decor = +3 morale
- Great Hall: MessTable + 2+ decor and recreation = +6 morale
- Park: 4+ wild/planted plants = +1 morale
- Nature Reserve: 12+ wild plants = +6 morale
- Stable: GroomingStation + CritterDropOff = ranching room
- Ranch: Incubator + feeder (spaced out)
### SPOM (Self-Powered Oxygen Module)
The classic Rodriguez SPOM:
- 1 Electrolyzer (consumes 1kg/s water -> 888g/s O2 + 112g/s H2)
- 2 GasPumps for O2 extraction
- 1 HydrogenGenerator (burns 100g/s H2, produces 800W)
- 1 GasFilter to separate H2 from O2
- Net power positive (runs on its own hydrogen)
- Standard size: 8x6 tiles

349
docs/MOD_DEV_GUIDE.md Normal file
View File

@ -0,0 +1,349 @@
# ONI Agent Mod 开发指南
## 概述
本文档规定了一个与外部 Agent（AI 助手）对接的《缺氧》(Oxygen Not Included) Mod 应遵循的接口规范、约束条件和最佳实践。遵循此规范开发的 Mod 可与 `oni-agent` 工具链无缝协作。
---
## 1. 通信协议
### 1.1 传输层
- **协议**: HTTP 1.1
- **地址**: `127.0.0.1`（仅本地回环，禁止暴露到外部网络）
- **端口**: 由配置文件指定（默认 `23876`）
- **编码**: 所有请求和响应均为 UTF-8
### 1.2 数据格式
- 所有请求和响应使用 `application/json`
- 响应必须包含有效的 JSON
- 错误响应必须包含 `error` 字段
```json
// 成功响应
{ "result": "ok", ... }
// 错误响应
{ "error": "error_message" }
```
### 1.3 请求超时
- 服务端应在 5 秒内响应
- 长时间操作应排队后立即返回 `{ "result": "queued" }`
---
## 2. API 端点规范
### 2.1 健康检查
```
GET /health
```
用于 Agent 探测 Mod 是否存活。必须始终可达，不依赖游戏状态。
**响应**:
```json
{ "status": "ok", "service": "mod_name" }
```
### 2.2 状态查询端点
所有状态查询为 `GET` 请求，路径前缀 `/api/state/`。
| 端点 | 返回内容 | 必需 | 新增字段 |
|------|---------|------|---------|
| `/api/state/game` | 周期、复制人、世界尺寸 | **是** | `gridWidth`, `gridHeight` |
| `/api/state/resources` | 资源列表(含分类/物态) | **是** | `id`, `state`, `category` |
| `/api/state/duplicants` | 复制人详情 | **是** | `x`, `y`, `cell`, `currentChore` |
| `/api/state/buildings` | 建筑列表 | 推荐 | `cell`, `category`, `powerWatt` |
| `/api/state/research` | 科技树(含解锁列表) | 推荐 | `requiredTechs`, `unlockedBuildings` |
| `/api/state/geysers` | 喷泉详情 | 可选 | `cell`, `isActive`, `isDormant` |
| `/api/state/alert` | 当前警报 | 推荐 | `clickable` |
| `/api/state/critters` | 小动物详情 | 可选 | `cell`, `calories` |
| `/api/state/plants` | 植物列表 | 可选 | `isGrown`, `progress`, `isWilting` |
| `/api/state/rooms` | 房间列表 | 可选 | 类型/格数/建筑/生物/植物 |
### 2.3 地图/格子数据端点
这是 AI 理解游戏世界最重要的端点。格子级数据让 AI 知道每个具体位置的状态。
| 端点 | 说明 | 参数 |
|------|------|------|
| `GET /api/state/cell` | 单格详情 | `?x=&y=` |
| `GET /api/state/cells` | 矩形区域(批量) | `?x=&y=&width=&height=` |
| `GET /api/state/cells/slice` | 行或列扫描 | `?axis=x&index=&start=&end=` |
| `GET /api/state/gas` | 气体分布分析 | `?x=&y=&radius=` |
#### `GET /api/state/cell?x=10&y=5`
```json
{
"x": 10, "y": 5, "cell": 4523,
"element": "Oxygen",
"elementId": "Oxygen",
"elementState": "gas",
"massKg": 1.8,
"temperatureC": 23.5,
"isSolid": false, "isLiquid": false, "isGas": true,
"hasBuilding": true, "buildingName": "GasPump",
"hasDuplicant": false, "duplicantName": null,
"isVacuum": false, "isVisible": true
}
```
#### `GET /api/state/cells?x=0&y=0&width=5&height=5`
```json
{
"region": { "x": 0, "y": 0, "width": 5, "height": 5 },
"cells": [ /* array of cell objects */ ]
}
```
### 2.4 实体注册表端点 (AI 参考)
用于 AI 在运行时查询游戏实体的元数据。所有为 `GET` 请求。
| 端点 | 返回内容 |
|------|---------|
| `/api/registry/buildings` | 全部建筑定义(尺寸/功耗/发热/材料) |
| `/api/registry/elements` | 全部元素定义(比热容/导热/熔沸点) |
| `/api/registry/techs` | 全部科技定义(前置/解锁建筑) |
#### `GET /api/registry/buildings`
```json
[
{
"id": "Electrolyzer",
"name": "Electrolyzer",
"category": "Oxygen",
"width": 2, "height": 2,
"powerCost": 120,
"heatGeneration": 1.25,
"constructionMass": ["IronOre", "IronOre"]
}
]
```
### 2.5 操作端点
所有操作为 `POST` 请求，路径前缀 `/api/action/`。
| 端点 | 作用 | 必需 |
|------|------|------|
| `/api/action/dig` | 挖掘指定区域 | **是** |
| `/api/action/build` | 建造建筑 | **是** |
| `/api/action/deconstruct` | 拆除建筑 | 推荐 |
| `/api/action/prioritize` | 设置优先级 | 可选 |
| `/api/action/research` | 选择研究方向 | 推荐 |
| `/api/action/schedule` | 修改复制人日程 | 可选 |
| `/api/action/wardrobe` | 修改复制人装备 | 可选 |
| `/api/action/mop` | 清理液体 | 推荐 |
| `/api/action/harvest` | 收获植物 | 推荐 |
| `/api/action/cancel` | 取消操作 | 可选 |
#### `GET /api/state/game`
```json
{
"cycle": 42,
"duplicantCount": 6,
"worldName": "Terra",
"worldSize": 256
}
```
#### `GET /api/state/duplicants`
```json
[
{
"name": "Dup1",
"stress": 12.5,
"calories": 850000,
"stamina": 98.2,
"oxygen": 85.0,
"diseases": 0,
"skillLevels": 3
}
]
```
#### `GET /api/state/resources`
```json
[
{ "name": "Oxygen", "tag": "Oxygen", "amount": 12345.6, "unit": "kg" }
]
```
#### `GET /api/state/buildings`
```json
[
{
"name": "Manual Generator",
"id": "ManualGenerator",
"x": 10,
"y": 5,
"isOperational": true
}
]
```
### 2.3 操作端点
所有操作为 `POST` 请求，路径前缀 `/api/action/`。
| 端点 | 作用 | 必需 |
|------|------|------|
| `/api/action/dig` | 挖掘指定区域 | **是** |
| `/api/action/build` | 建造建筑 | **是** |
| `/api/action/deconstruct` | 拆除建筑 | 推荐 |
| `/api/action/prioritize` | 设置优先级 | 可选 |
| `/api/action/research` | 选择研究方向 | 推荐 |
| `/api/action/schedule` | 修改复制人日程 | 可选 |
| `/api/action/wardrobe` | 修改复制人装备 | 可选 |
#### `POST /api/action/dig`
**请求体**:
```json
{ "x": 10, "y": 5, "width": 8, "height": 6 }
```
**响应**:
```json
{ "result": "dig_queued", "x": 10, "y": 5, "width": 8, "height": 6 }
```
#### `POST /api/action/build`
**请求体**:
```json
{ "buildingId": "Electrolyzer", "x": 10, "y": 5, "rotation": null }
```
**响应**:
```json
{ "result": "build_queued", "buildingId": "Electrolyzer", "x": 10, "y": 5 }
```
---
## 3. Mod 约束
### 3.1 安全性
1. **仅绑定本地回环地址** `127.0.0.1`，不得监听 `0.0.0.0`
2. **不得实现认证/授权**——回环地址默认安全
3. **不得执行文件 I/O**（读取 Mod 自带配置除外）
4. **输入校验**——所有用户输入必须校验类型和范围
### 3.2 性能
1. 状态查询必须是**只读操作**，不得持有锁
2. 资源列表等大数据量接口应考虑分页（未来扩展）
3. 建造/挖掘等操作应返回 `queued` 后异步执行
4. HTTP 服务器应在**单独线程**运行，不得阻塞游戏主线程
### 3.3 兼容性
1. 使用 `KMod.UserMod2` 基类
2. 使用 `Harmony` 进行补丁（如果使用）
3. 引用 `UnityEngine` 和 `Assembly-CSharp` 程序集
4. 最小支持游戏版本应在 `mod_info.yaml` 中声明（当前推荐 `612000`）
### 3.4 错误处理
```json
// Mod 内部错误的通用格式
{ "error": "error_type", "details": "human readable message" }
// 常见错误类型
{ "error": "not_found" } // 404 端点不存在
{ "error": "invalid_request" } // 请求体解析失败
{ "error": "not_implemented" } // 功能尚未实现
{ "error": "unknown_building", "buildingId": "..." } // 建筑 ID 不识别
{ "error": "unknown_tech", "techId": "..." } // 科技 ID 不识别
```
---
## 4. 配置文件规范
Agent 侧通过 `config.json` 定位 Mod：
```json
{
"modHost": "127.0.0.1",
"modPort": 23876,
"timeout": 10
}
```
- `modHost`: 始终为 `127.0.0.1`
- `modPort`: 应与 Mod 中监听的端口一致
- `timeout`: HTTP 请求超时秒数
---
## 5. AI-Friendly 数据设计原则
### 5.1 数据可读性
所有暴露的数据应满足 AI 可直接理解的三个条件：
1. **命名语义化** — 使用自然语言字段名（如 `temperatureC` 而非 `tempK`)
2. **数据类型合理** — 使用数字而非枚举字符串（温度用 `float` 而非 `string`)
3. **上下文完整** — 每个实体包含足够的位置和状态信息（坐标、类别、是否可运行）
### 5.2 坐标系统
- 统一使用 `(x, y)` 整数坐标，对应游戏网格
- 原点在左下角：`(0, 0)`
- 建筑使用其左下角锚点坐标
- 返回数据中同时提供 `cell` 索引（Grid 内部使用）和 `(x, y)` 坐标
### 5.3 实体分类
每个实体（建筑、元素、科技）必须包含分类标签：
- 建筑: `category`（Base/Oxygen/Power/Food/...）
- 元素: `state`（solid/liquid/gas）+ `category`（metal/water/fuel/...）
- 资源: 带 `state` 和 `category` 帮助 AI 推理用途
### 5.4 AI 推理辅助
- `/api/registry/*` 端点提供完整的实体元数据查询
- `GET /api/state/gas` 提供区域气体分布统计（AI 无法逐格遍历）
- `/api/state/rooms` 提供房间判定结果（AI 无法自行判断房间类型）
### 5.5 操作设计
操作设计遵循以下原则：
- **幂等性** — 同个操作重复执行不产生副作用
- **非阻塞** — 操作立即返回 `queued`，异步执行
- **确定性** — 使用绝对坐标 `(x, y)`，不支持"在某个建筑旁边"这类模糊表述
- **输入校验** — 拒绝未知的 `buildingId` 或越界坐标
## 6. 扩展建议
### 5.1 添加新端点
1. 在 `ProcessRequest` 中添加路由匹配
2. 实现对应的处理方法
3. 更新本指南和 `SKILL.md`
### 5.2 蓝图系统
预置的建造方案（蓝图）应满足：
- 坐标相对于原点，便于偏移
- 包含预先挖掘区域
- 建筑顺序隐含依赖关系
### 5.3 事件推送（未来）
考虑支持 WebSocket 或 SSE，用于游戏事件实时推送（如警报触发）。
---
## 6. 开发检查清单
- [ ] Mod 继承 `UserMod2`，在 `OnLoad` 中启动 HTTP 服务
- [ ] 在 `OnUnload` 中停止 HTTP 服务
- [ ] 实现全部必需端点（health, game, resources, duplicants, dig, build）
- [ ] 错误响应包含 `error` 字段
- [ ] 端口号与 `config.json` 一致
- [ ] 仅绑定 `127.0.0.1`
- [ ] 使用 `Newtonsoft.Json`（游戏自带，无需额外依赖）
- [ ] `mod_info.yaml` 声明了正确的游戏版本

40
docs/batch_example.json Normal file
View File

@ -0,0 +1,40 @@
{
"name": "Build SPOM - Step 1: Dig and Electrolyzer",
"actions": [
{
"type": "dig",
"x": 42,
"y": 40,
"width": 8,
"height": 6
},
{
"type": "build",
"buildingId": "Electrolyzer",
"x": 45,
"y": 42
},
{
"type": "build",
"buildingId": "GasPump",
"x": 43,
"y": 42
},
{
"type": "build",
"buildingId": "HydrogenGenerator",
"x": 45,
"y": 40
},
{
"type": "wait",
"delayMs": 100
},
{
"type": "priority",
"x": 45,
"y": 42,
"priority": 9
}
]
}