# ONI Agent Mod 开发指南

## 概述

本文档规定 ONI Agent Bridge Mod 的接口规范和开发约束。

## 1. 通信协议

### 1.1 传输层
- **协议**: HTTP 1.1
- **地址**: `127.0.0.1`（仅本地回环，禁止暴露外部网络）
- **端口**: 默认 `23876`，可在 `config.json` 修改
- **编码**: UTF-8

### 1.2 数据格式
所有请求和响应使用 `application/json`。

**统一响应格式：**

```json
// 成功
{ "success": true, "data": { ... } }

// 错误
{ "success": false, "error": "error_code", "errorMessage": "可读信息" }
```

**旧格式兼容**（/health 端点历史版本）：
```json
{ "status": "ok" }
```

### 1.3 线程模型
- **读操作**可通过 `EnqueueRead(Func<object>)` 排队到主线程执行（`ManualResetEvent` 同步等待）
- **写操作**通过静态 `ConcurrentQueue<Action> cmdQueue` + `QueueProcessor` (MonoBehaviour.Update) 排队到主线程
- **格子数据**（Grid.Element/Mass/Temperature/Objects）可从后台线程直接读取（静态数组）

## 2. 端点规范

### 2.1 健康检查
```
GET /health
```
必须始终可达，不依赖游戏状态。
```json
{ "success": true, "data": { "status": "ok", "service": "oni-agent-bridge", "version": "2.0.0" } }
```

### 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 |

### 2.3 格子数据 (GET, 可后台线程)
| 端点 | 参数 | 说明 |
|------|------|------|
| cell | x, y | 单格详情 |
| cells | x, y, width, height | 矩形区域 |
| cells/slice | axis, index, start, end | 行列扫描 |
| gas | x, y, radius | 气体分布 |

### 2.4 注册表 (GET /api/registry/)
| 端点 | 说明 |
|------|------|
| buildings | 所有建筑定义(含尺寸/材料类别) |
| elements | 所有元素定义 |
| techs | 科技树(含前置) |

### 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/screenshot/latest
```
返回 PNG 图片。通过 `ScreenCapture.CaptureScreenshot` 异步生成。

## 3. 事件系统

Mod 内部维护事件列表 (`List<AgentEvent> + lock`)。
事件可通过 `GET /api/state/events?since=N` 轮询。
事件自动记录操作日志。

## 4. Mod 开发检查清单

- [ ] 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)` 拉视角