oniagent/docs/MOD_DEV_GUIDE.md

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。

统一响应格式：

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

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

旧格式兼容（/health 端点历史版本）：

{ "status": "ok" }

1.3 线程模型

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

2. 端点规范

2.1 健康检查

GET /health

必须始终可达，不依赖游戏状态。

{ "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) 拉视角