feat: comprehensive AI-oriented data model with cell-level map API and knowledge base

- Add cell/tile map APIs: /api/state/cell, /api/state/cells, /api/state/cells/slice, /api/state/gas - Add entity registry APIs: /api/registry/buildings, /api/registry/elements, /api/registry/techs - Add plants, rooms, mop, harvest endpoints - Rich semantic metadata: element state/category, building category/power, duplicant chore/cell - AI-friendly coordinate system with (x,y) + cell index in all responses - Build AI_KNOWLEDGE_BASE.md with building IDs, element IDs, tech trees, game mechanics - Rewrite SKILL.md with data model explanation, coordinate guide, operation patterns - Update Python tools: explore, cell, cells, slice, gas, registry subcommands - Update MOD_DEV_GUIDE.md with AI data design principles
2026-05-22 08:54:03 +08:00
parent 0e17e8a6ac
commit 6a7ac87c1b
6 changed files with 1775 additions and 341 deletions
--- a/docs/AI_KNOWLEDGE_BASE.md
+++ b/docs/AI_KNOWLEDGE_BASE.md
@ -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
--- a/docs/MOD_DEV_GUIDE.md
+++ b/docs/MOD_DEV_GUIDE.md
@ -52,16 +52,98 @@ GET /health

 所有状态查询为 `GET` 请求，路径前缀 `/api/state/`。

-| 端点 | 返回内容 | 必需 |
-|------|---------|------|
-| `/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/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`

@ -205,7 +287,39 @@ Agent 侧通过 `config.json` 定位 Mod：

 ---

-## 5. 扩展建议
+## 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` 中添加路由匹配