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

Update all docs: README, AI_KNOWLEDGE_BASE, MOD_DEV_GUIDE, batch_example, SKILL

Browse Source
This commit is contained in:
JianFeeeee
2026-05-30 12:51:05 +08:00
parent 3d70338087
commit 21423a6bb4
4 changed files with 367 additions and 824 deletions
Download Patch File Download Diff File Expand all files Collapse all files

407
docs/AI_KNOWLEDGE_BASE.md
View File

@ -1,268 +1,189 @@
# ONI Knowledge Base — AI Reference
# ONI AI Knowledge Base — 建筑/元素/科技/机制参考
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.
AI Agent 查询用参考手册。所有 buildingId 可通过 `/api/registry/buildings` 动态查询。
## 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)
- 原点 (0,0) = 地图**左下角**，x→右，y→上
- 建筑坐标 = 左下角锚点 (width × height)
- 默认地图大小：256×384
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
### 氧气
| ID | 尺寸 | 材料 | 耗电(W) | 功能 |
|----|------|------|---------|------|
| Electrolyzer | 2×2 | Metal | 120 | 水→O₂+H₂ (1kg/s水) |
| OxygenDiffuser | 2×2 | Metal | 120 | 藻类→O₂ (早期) |
| Deodorizer | 1×2 | Metal | 0 | 污染氧→氧气 (需过滤介质) |
| AlgaeDistillery | 3×4 | Metal | 120 | 藻泥→藻类 |
| AlgaeHabitat | 1×2 | Farmable | 0 | 藻类养殖 |
| 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 |
### 电力
| ID | 尺寸 | 材料 | 发电(W) | 燃料 |
|----|------|------|---------|------|
| ManualGenerator | 2×2 | Metal | 400 | 人力 |
| CoalGenerator | 2×2 | Metal | 600 | 煤 |
| HydrogenGenerator | 2×2 | Metal | 800 | 氢 |
| NaturalGasGenerator | 2×2 | Metal | 800 | 天然气 |
| PetroleumGenerator | 3×2 | Metal | 2000 | 石油 |
| SteamTurbine | 4×2 | Metal | 850 | 蒸汽(热删除) |
| SolarPanel | 2×1 | Metal | 380 | 光照 |
| Battery | 1×1 | Metal | 0 | 储电 10kJ |
| JumboBattery | 2×1 | Metal | 0 | 储电 40kJ |
| Transformer | 2×1 | Metal | 0 | 电路分离 |
## Key Building IDs (frequently used by AI)
### 管道/通风
| ID | 尺寸 | 材料 | 耗电 | 功能 |
|----|------|------|------|------|
| GasPump | 1×2 | Metal | 240W | 抽气 |
| GasFilter | 1×2 | Metal | 120W | 气体分离 |
| GasVent | 1×1 | Metal | 0 | 排气口 |
| LiquidPump | 1×2 | Metal | 240W | 抽液 |
| LiquidFilter | 1×2 | Metal | 120W | 液体分离 |
| LiquidVent | 1×1 | Metal | 0 | 排水口 |
| WaterPurifier | 2×2 | Metal | 120W | 污水→清水 |
```
# 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)
### 食物/农业
| ID | 尺寸 | 材料 | 功能 |
|----|------|------|------|
| PlanterBox | 1×1 | BuildableRaw | 种植(需泥土) |
| FarmTile | 1×1 | BuildableRaw | 种植(需灌溉) |
| HydroponicFarmTile | 1×2 | Metal | 液培(需液体管道) |
| StorageLocker | 1×1 | BuildableRaw | 储物 |
| RationBox | 2×2 | BuildableRaw | 储食(CO₂防腐) |
| Refrigerator | 1×2 | Metal | 冷藏(耗电) |
| ElectricGrill | 2×2 | Metal | 烹饪 |
| MicrobeMusher | 2×2 | BuildableRaw | 初期制食 |
# 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
### 卫生
| ID | 尺寸 | 材料 | 功能 |
|----|------|------|------|
| Outhouse | 1×2 | BuildableRaw | 初期厕所(需清理) |
| WashBasin | 1×1 | BuildableRaw | 洗手(需水) |
| Lavatory | 1×2 | Metal | 抽水马桶(需水管) |
| WashSink | 1×1 | Metal | 自动洗手(需水管) |
| Shower | 2×1 | Metal | 淋浴(士气) |
# Power storage
Battery -> 10kJ storage, small
JumboBattery -> 40kJ storage
SmartBattery -> 20kJ storage, automation output
### 基地
| ID | 尺寸 | 材料 | 功能 |
|----|------|------|------|
| Tile | 1×1 | BuildableRaw | 地板/墙 |
| InsulationTile | 1×1 | BuildableRaw | 隔热 |
| Ladder | 1×1 | BuildableRaw | 攀爬 |
| FirePole | 1×1 | Metal | 速降 |
| PneumaticDoor | 1×2 | Metal | 自动门 |
| ManualDoor | 1×2 | BuildableRaw | 手动门 |
| Cot | 1×1 | BuildableRaw | 床 |
| ResearchStation | 2×2 | BuildableRaw | 初级科研(60W) |
| SuperComputer | 2×2 | Plastic | 高级科研(120W) |
| TriageCot | 1×2 | BuildableRaw | 医疗床 |
# 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
### 精炼
| ID | 尺寸 | 材料 | 功能 |
|----|------|------|------|
| MetalRefinery | 3×2 | Metal | 精炼金属(1200W) |
| RockCrusher | 2×2 | BuildableRaw | 碎矿 |
| Kiln | 1×2 | BuildableRaw | 烧陶瓷/玻璃 |
| PolymerPress | 2×3 | Metal | 石油→塑料(240W) |
| OilRefinery | 3×2 | Metal | 石油→天然气+石油 |
| Compost | 2×2 | BuildableRaw | 污染土→泥土 |
# 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
### 温度控制
| ID | 尺寸 | 材料 | 功能 |
|----|------|------|------|
| Aquatuner | 1×2 | RefinedMetal | 液冷(1200W) |
| SpaceHeater | 1×1 | Metal | 加热(120W) |
| IceFan | 2×1 | BuildableRaw | 降温(耗冰) |
| IceKettle | 1×2 | BuildableRaw | 冰→水 |
| TempshiftPlate | 1×1 | BuildableRaw | 导热板 |
# Ventilation
GasPump -> Pumps gases (500g/s)
GasFilter -> Filters specific gas from mixed pipes
GasVent -> Outputs gas into world
HighPressureGasVent-> 20kg/tile max pressure
### 动物/养殖
| ID | 尺寸 | 材料 | 功能 |
|----|------|------|------|
| RanchStation | 2×2 | BuildableRaw | 养殖站 |
| Incubator | 2×2 | BuildableRaw | 孵化器 |
| CritterFeeder | 1×2 | BuildableRaw | 投喂器 |
| CritterTrap | 1×1 | Metal | 陷阱 |
# 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
| 类别 | 包含元素 | 来源 |
|------|---------|------|
| BuildableRaw | SandStone, Granite, IgneousRock, SedimentaryRock, Obsidian, MaficRock | 挖掘 |
| Metal | Cuprite, IronOre, GoldAmalgam, Wolframite, Cobaltite | 挖掘 |
| RefinedMetal | Copper, Iron, Gold, Steel, Tungsten | 精炼 |
| Plastic | Polypropylene | 聚合压机制造 |
| Glass | MoltenGlass→Glass | 窑炉 |
| BuildingFiber | ReedFiber | 耕种 |
| Transparent | Diamond, Glass | 挖掘/制造 |
| Farmable | Dirt | 挖掘/堆肥 |
# 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
| 元素 | 比热容(J/g·K) | 导热(W/m·K) | 熔点(°C) |
|------|--------------|-------------|---------|
| SandStone | 0.800 | 2.000 | - |
| Granite | 0.790 | 3.390 | - |
| IgneousRock | 1.000 | 2.000 | - |
| SedimentaryRock | 0.200 | 2.000 | - |
| Cuprite | 0.600 | 4.500 | - |
| IronOre | 0.440 | 4.000 | - |
| GoldAmalgam | 0.240 | 2.000 | - |
| Water | 4.179 | 0.609 | 0/100 |
| PollutedWater | 4.179 | 0.580 | -0.65/100 |
| Oxygen | 1.005 | 0.024 | -183/-183 |
| Hydrogen | 8.640 | 0.168 | -252/-252 |
| CarbonDioxide | 0.846 | 0.015 | 0/-78 |
| CrudeOil | 1.690 | 2.000 | -40/400 |
# 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
```
| Tech ID | 名称 | 前置 | 解锁 |
|---------|------|------|------|
| FarmingTech | 农业技术 | - | PlanterBox, FarmTile |
| PowerRegulation | 电力调节 | - | Transformer, HeavyWire |
| Plumbing | 管道 | - | Lavatory, WaterPurifier |
| Ventilation | 通风 | - | GasPump, GasFilter |
| Refinement | 精炼 | - | MetalRefinery, RockCrusher |
| TemperatureModulation | 调温 | - | Aquatuner, SteamTurbine |
| SmartStorage | 智能存储 | - | SmartStorageBin |
| AdvancedPowerRegulation | 高级电力 | PowerRegulation | PowerTransformer |
| LiquidPiping | 液体管道 | Plumbing | LiquidPump, LiquidFilter |
| GasPiping | 气体管道 | Ventilation | GasValve |
| FineDining | 精致餐饮 | FarmingTech | ElectricGrill |
| AnimalControl | 动物控制 | - | CritterTraps |
| Ranching | 畜牧 | AnimalControl | RanchStation |
## 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
| 房间 | 要求 | 加成 |
|------|------|------|
| Bedroom(卧室) | 4×床, 封闭 | +1士气 |
| Washroom(卫生间) | 洗手盆+马桶, 封闭 | +1士气 |
| MessHall(餐厅) | 餐桌+配给盒, 封闭 | +2士气 |
| GreatHall(大堂) | 装饰+餐桌+配给盒 | +4士气 |
| Greenhouse(温室) | 种植+光照, 封闭 | 植物生长+50% |
| Hospital(医院) | 医疗床+医生, 封闭 | 治疗加速 |
| Ranch(畜舍) | 养殖站+喂食器 | 动物繁殖加速 |
| PowerPlant(电站) | 发电机×2+电池 | 发电效率+10% |
# 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
- 普通电线最大负载：1000W
- 重导线(Wire) 最大负载：2000W
- 超过负载 → 过载损坏 → 复制人维修
- 使用变压器(Transformer)将重导线电路分成普通导线子电路
- 智能电池可连接自动化电路控制发电机启停
# 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
| 指标 | 警告 | 危险 | 应对 |
|------|------|------|------|
| O₂质量 | <2000kg | <500kg | 增加制氧 |
| 食物 | <500kkcal | <200kkcal | 增加农场 |
| 水 | <20000kg | <5000kg | 找水源/净化 |
| 温度 | >35°C | >50°C | 隔热+冷却 |
| CO₂ | 可见积聚 | >2kg/tile | 挖排气管 |
| 藻类 | <2000kg | <500kg | 转电解器 |
| 煤 | <5000kg | <1000kg | 找煤矿/换发电 |

399
docs/MOD_DEV_GUIDE.md
View File

@ -2,348 +2,121 @@
## 概述
本文档规定了一个与外部 Agent（AI 助手）对接的《缺氧》(Oxygen Not Included) Mod 应遵循的接口规范、约束条件和最佳实践。遵循此规范开发的 Mod 可与 `oni-agent` 工具链无缝协作。
---
本文档规定 ONI Agent Bridge Mod 的接口规范和开发约束。
## 1. 通信协议
### 1.1 传输层
- **协议**: HTTP 1.1
- **地址**: `127.0.0.1`（仅本地回环，禁止暴露到外部网络）
- **端口**: 由配置文件指定（默认 `23876`）
- **编码**: 所有请求和响应均为 UTF-8
- **地址**: `127.0.0.1`（仅本地回环，禁止暴露外部网络）
- **端口**: 默认 `23876`，可在 `config.json` 修改
- **编码**: UTF-8
### 1.2 数据格式
- 所有请求和响应使用 `application/json`
- 响应必须包含有效的 JSON
- 错误响应必须包含 `error` 字段
所有请求和响应使用 `application/json`。
**统一响应格式：**
```json
// 成功响应
{ "result": "ok", ... }
// 成功
{ "success": true, "data": { ... } }
// 错误响应
{ "error": "error_message" }
// 错误
{ "success": false, "error": "error_code", "errorMessage": "可读信息" }
```
### 1.3 请求超时
- 服务端应在 5 秒内响应
- 长时间操作应排队后立即返回 `{ "result": "queued" }`
**旧格式兼容**（/health 端点历史版本）：
```json
{ "status": "ok" }
```
---
### 1.3 线程模型
- **读操作**可通过 `EnqueueRead(Func<object>)` 排队到主线程执行（`ManualResetEvent` 同步等待）
- **写操作**通过静态 `ConcurrentQueue<Action> cmdQueue` + `QueueProcessor` (MonoBehaviour.Update) 排队到主线程
- **格子数据**（Grid.Element/Mass/Temperature/Objects）可从后台线程直接读取（静态数组）
## 2. API 端点规范
## 2. 端点规范
### 2.1 健康检查
```
GET /health
```
用于 Agent 探测 Mod 是否存活。必须始终可达，不依赖游戏状态。
**响应**:
必须始终可达，不依赖游戏状态。
```json
{ "status": "ok", "service": "mod_name" }
{ "success": true, "data": { "status": "ok", "service": "oni-agent-bridge", "version": "2.0.0" } }
```
### 2.2 状态查询端点
### 2.2 状态查询 (GET /api/state/)
| 端点 | 说明 | 实现方式 |
|------|------|---------|
| game | 周期/复制人/世界尺寸/暂停/速度 | EnqueueRead |
| resources | 资源列表(含物态/存量) | EnqueueRead |
| buildings | 建筑列表(含位置/尺寸) | EnqueueRead |
| duplicants | 复制人(位置/血量) | EnqueueRead |
| research | 科技进度 | EnqueueRead |
| rooms | 房间类型 | EnqueueRead |
| events | 事件日志(支持since分页) | 直接读取(eventLock) |
| storage | 储物建筑内容 | EnqueueRead |
| saves | 存档列表 | EnqueueRead |
| alert | 游戏警报 | EnqueueRead |
| camera | 相机位置 | EnqueueRead |
所有状态查询为 `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 知道每个具体位置的状态。
| 端点 | 说明 | 参数 |
### 2.3 格子数据 (GET, 可后台线程)
| 端点 | 参数 | 说明 |
|------|------|------|
| `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=` |
| cell | x, y | 单格详情 |
| cells | x, y, width, height | 矩形区域 |
| cells/slice | axis, index, start, end | 行列扫描 |
| gas | x, y, radius | 气体分布 |
#### `GET /api/state/cell?x=10&y=5`
### 2.4 注册表 (GET /api/registry/)
| 端点 | 说明 |
|------|------|
| buildings | 所有建筑定义(含尺寸/材料类别) |
| elements | 所有元素定义 |
| techs | 科技树(含前置) |
```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
}
### 2.5 操作 (POST /api/action/)
所有操作执行前**自动拉视角**到目标坐标。
| 端点 | 请求体 | 说明 |
|------|--------|------|
| pause | {reason?} | 暂停(通过SpeedControlScreen) |
| unpause | {speed?} | 恢复 |
| speed | {speed} | 设速度 |
| dig | {x,y,width,height} | 挖掘(使用DigTool.PlaceDig) |
| build | {buildingId,x,y} | 建造(使用BuildingDef.Instantiate) |
| deconstruct | {x,y} | 拆除(使用Deconstructable.QueueDeconstruction) |
| prioritize | {x,y,priority} | 设优先级(1-9) |
| research | {techId} | 研究(SetActiveResearch) |
| mop | {x,y} | 清理液体 |
| harvest | {x,y} | 收获植物 |
| batch | {actions} | 批量操作 |
| save | {name?} | 存档 |
| load | {name} | 读档 |
| camera | {x,y,zoom?} | 移动视角 |
| priority_global | {target,priority} | 全局默认优先级 |
| priority_type | {buildingType,priority} | 按类型优先级 |
### 2.6 截图
```
#### `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 */ ]
}
GET /api/screenshot/latest
```
返回 PNG 图片。通过 `ScreenCapture.CaptureScreenshot` 异步生成。
### 2.4 实体注册表端点 (AI 参考)
## 3. 事件系统
用于 AI 在运行时查询游戏实体的元数据。所有为 `GET` 请求。
Mod 内部维护事件列表 (`List<AgentEvent> + lock`)。
事件可通过 `GET /api/state/events?since=N` 轮询。
事件自动记录操作日志。
| 端点 | 返回内容 |
|------|---------|
| `/api/registry/buildings` | 全部建筑定义(尺寸/功耗/发热/材料) |
| `/api/registry/elements` | 全部元素定义(比热容/导热/熔沸点) |
| `/api/registry/techs` | 全部科技定义(前置/解锁建筑) |
## 4. Mod 开发检查清单
#### `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` 声明了正确的游戏版本
- [ ] Mod 类继承 `UserMod2`，重写 `OnLoad(Harmony)`
- [ ] 用 `GameObject + MonoBehaviour` 处理队列，`DontDestroyOnLoad`
- [ ] 用 `HttpListener` 暴露 HTTP 服务，`BeginGetContext` 异步处理
- [ ] 格子数据安全读取：`Grid.Element[]`、`Grid.Mass[]`、`Grid.Solid[]`、`Grid.Objects[,]`
- [ ] 读操作用 `EnqueueRead` 同步到主线程
- [ ] 写操作用 `cmdQueue` 排队到主线程的 `Update()` 中执行
- [ ] 响应统一 `{success, data}` 或 `{success, error, errorMessage}`
- [ ] 所有操作自动 `QWithCamera(x,y,action)` 拉视角

9
docs/batch_example.json
View File

@ -1,5 +1,4 @@
{
"name": "Build SPOM - Step 1: Dig and Electrolyzer",
"actions": [
{
"type": "dig",
@ -27,11 +26,13 @@
"y": 40
},
{
"type": "wait",
"delayMs": 100
"type": "build",
"buildingId": "GasFilter",
"x": 44,
"y": 40
},
{
"type": "priority",
"type": "prioritize",
"x": 45,
"y": 42,
"priority": 9