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
This commit is contained in:
root
@ -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` 中添加路由匹配
|
||||
|
||||
Reference in New Issue
Block a user