WebSocket API v1

端点：

ws://127.0.0.1:25548/api/v1/ws
wss://<远程入口>/api/v1/ws

协议版本 v=1。所有消息都是 JSON 文本帧。

信封

请求

{
  "v": 1,
  "type": "request",
  "id": "req-001",
  "method": "instances.list",
  "params": {}
}

字段	约束
v	必须为 1
type	request
id	1–100 字符，同一会话内不能重复
method	已注册方法名
params	严格模型，禁止额外字段

成功响应

{ "v": 1, "type": "response", "id": "req-001", "ok": true, "result": [] }

失败响应

{
  "v": 1,
  "type": "response",
  "id": "req-001",
  "ok": false,
  "error": { "code": "INVALID_PARAMS", "message": "请求格式或参数不正确", "details": [] }
}

事件

{ "v": 1, "type": "event", "topic": "overview", "data": {} }

会话

连接后服务器主动推送：

{
  "v": 1,
  "type": "event",
  "topic": "session",
  "data": { "authRequired": true, "protocolVersion": 1 }
}

• authRequired: false 表示本机回环且未设密码，直接可调用。
• 未鉴权时读超时 30 秒，已鉴权 60 秒。

登录

{
  "v": 1, "type": "request", "id": "a1", "method": "auth.login",
  "params": { "password": "<WebUI 密码>" }
}

远程配对客户端提交的是配对凭据，不是主密码。撤销配对后，下一次请求（含 15 秒心跳）会返回 UNAUTHORIZED。

订阅

{
  "v": 1, "type": "request", "id": "s1", "method": "events.subscribe",
  "params": { "instance": "ap", "topics": ["overview", "logs", "statistics"] }
}

主题	数据	采样
instances	实例列表与运行状态	2 秒
overview	当前任务、资源	1 秒
logs	增量日志	变更即推
preview	截图预览	变更即推
statistics	统计报表	1 秒
notifications	通知流	事件
stock	交易所	事件

订阅是整体替换

再次订阅会清空旧主题。Android 宿主因此只允许一个全局订阅者；外部工具不要和前端同时订阅同一实例后互相覆盖。

限制与错误码

项	值
单条消息	≤ 8 MiB
普通请求	≤ 1 MiB
大请求例外	mind.import、mind.recognize、mind.save、mind.calculate
频率	30 请求 / 秒

错误码	含义
INVALID_REQUEST	信封/大小不合法
INVALID_PARAMS	参数校验失败
UNAUTHORIZED	未登录或配对撤销
TLS_REQUIRED	远程账号操作未走 WSS
RATE_LIMITED	请求过频
DUPLICATE_REQUEST	请求 ID 复用
INTERNAL_ERROR	服务端异常，详情不返回

参数错误只回字段路径与类型，不回显输入值。

常用流程

列出实例并读取总览

{"v":1,"type":"request","id":"1","method":"instances.list","params":{}}
{"v":1,"type":"request","id":"2","method":"overview.get","params":{"instance":"ap"}}

启动与停止调度器

{"v":1,"type":"request","id":"3","method":"scheduler.start","params":{"instance":"ap"}}
{"v":1,"type":"request","id":"4","method":"scheduler.stop","params":{"instance":"ap"}}

修改配置

{
  "v": 1, "type": "request", "id": "5", "method": "config.patch",
  "params": {
    "instance": "ap",
    "revision": "<上次读取的 revision>",
    "changes": [{ "path": "Research.Scheduler.Enable", "value": true }]
  }
}

revision 是乐观并发控制：与当前不一致会返回冲突，需要重新 config.get 后再提交。

立即运行任务

{"v":1,"type":"request","id":"6","method":"tasks.run","params":{"instance":"ap","task":"Research"}}

这是「跳过调度直接执行」，不会修改 NextRun。

读取日志

{"v":1,"type":"request","id":"7","method":"logs.get","params":{"instance":"ap","after":128}}

after 是游标，返回此后的增量条目。

方法清单

下表由 frontend/src/api/contract.json 生成。展开任一行可看参数类型与约束。

72 / 72 个方法 · 契约版本 1 · 7de6bb9

客户端实现建议

1. 连接后先等 session 事件，再决定是否登录。
2. id 用单调递增或 UUID，不要复用。
3. 断线后用指数退避重连，并重新订阅。
4. 订阅前先 overview.get 拿一次全量，再靠事件增量。
5. 写操作后不要假设成功，读回状态确认。
6. 不要把密码写进 URL（MCP 的 ?key= 是例外，且仅限无法设 Header 的客户端）。

安全

• 远程访问必须走 WSS；账号操作在非本机连接下强制 TLS。
• 不要把 WebSocket 地址与密码一起截图分享。
• 自建看板应使用只读方法，避免误触 scheduler.stop 之类的写操作。