tako 文档 GitHub

19v6-01 · 契约:四个 API

本篇是 doc/19-v6 文档集的契约篇:四个端点的请求/响应/错误字节是真源。 目录、概念表、跨切面注意事项见 index(19-运行引擎架构-v6.md);客户端总流程见 19v6-02;验收见 19v6-04;存储形态见 19v6-03。

0. 第一步的范围

客户端要跑通的最小循环只有一件事:投一条消息,轮询看着回复一点点生成、定稿。 支撑它需要且仅需要四个 API:

# API 干什么 游标
1 POST /api/runs 创建一场 run(= 投递消息启动执行;含首条消息懒创建会话) —
2 GET /api/sessions/{sessionId} 状态查询:有没有活 run + runlog 高水位 —
3 GET /api/runs/{runId}/frames 拉某场 run 的生成中帧 eventOffset(run 内)
4 GET /api/sessions/{sessionId}/log 拉 定稿历史记录 runlogOffset(全局)

URL 形状约定:run 是顶层资源(创建它 = 投递消息);session 是归属资源,它的两个端点挂在 /api/sessions/{sessionId} 下。未知 session → 404 112001(找不到这场会话);未知 run 在 frames 上不是 404, 而是 200 gone——「从未存在」与「已过期删除」故意不区分(客户端两者都转拉 log,行为相同)。

纯拉模型:无 SSE、无长连接、无推送、无 heartbeat。实时性 = 客户端轮询节奏(dev 建议 300–500 ms,服务端不管频率)。没有 inbox / 合并 / 跨 client 同步 / Stop / Delete / approval / 会话级帧——需要时后续 loop 照此扩,不预留。

【2026-10-18 翻案,doc/31】「无 SSE」句不再成立:GET /api/runs/{runId}/stream(§5)已落地,同一帧面的第二种运输方式。翻案边界钉死——本篇四 API 一字未动,拉仍是正确性:断线恢复、新 tab、补历史、收口对账全走拉;流是优化、不承诺可靠送达。

认证前置(doc/28 起):本篇四个端点全部挂 RequireAuth,请求都要带 Authorization: Bearer <accessToken>; 不带一律 401 {"code":111102,"message":"请先登录","data":null"}。令牌来自 POST /api/auth/signup 或 POST /api/auth/login——全部 JSON 接口都用 {code,message,data} 信封(含本篇四个业务端点,doc/40)。 取令牌的 curl、租户模型前置与完整验收矩阵见 19v6-04 的「用例 0」。

响应信封细则(doc/40,2026-10-22 起):成功 code=0、message 空串、业务体在 data;失败 code 是数字业务码、message 是弹窗文案、data 为 null(有诊断细节时放 data,如 413 的 limit/tokens)。 业务码表与逐端点对照在 doc/40,本篇只给各端点的期望字节,不重复条款。 两样不进信封:GET /api/media 的成功体是图片字节(不是 JSON);GET /api/runs/{id}/stream 的 SSE 帧面(§5)——帧是长连接里的事件,不是某个响应的 body。

拉取一律有界:两个拉取端点都受单批上限 W 约束(dev 默认 200,-batch-window 可调);客户端初始游标取「高水位 − 窗口」而不是 0。理由:runlog 永久增长(compact 不动它),「从 0 全量重拉」在长会话下是无界请求。这不加端点、不加索引、不加请求参数——高水位本来就由 session 状态端点返回。

1. POST /api/runs —— 创建 run(= 投递消息)

请求体三个字段,按情形发:

情形 1 · 首条消息(本地还没有 sessionId)——不带 sessionId:

POST /api/runs
Content-Type: application/json

{"messageId":"m_1","text":"hi"}

→ 202 {"code":0,"message":"","data":{"sessionId":"s_01","runId":"r_01","messageId":"m_1"}}。服务端在投递事务内含铸会话(s_<ULID>);客户端要把 sessionId 存下来,之后所有请求都带着它。响应同时带回 runId,客户端可直接开始轮询 frames(§2)——查 session(§4)是 reconnect / 新 tab 的入口,不是发消息后的必经步。

情形 2 · 会话里的后续消息——带 sessionId:

POST /api/runs
Content-Type: application/json

{"sessionId":"s_01","messageId":"m_2","text":"读一下 doc/19"}

→ 带 = 准入检查:未登记一律 404,不隐式创建。

情形 3 · 超时重发——和情形 2 一模一样地重发(同 messageId、同 text):messageId 请求前就得生成好(绑本地气泡),重发不换 id;服务端不承诺按 messageId 去重,本步幂等语义仅限「闸」层面。

字段约定:sessionId 可省(不带=懒建会话,带=只认登记过的);messageId 客户端生成、不参与排序。

响应与错误:

202 {"code":0,"message":"","data":{"sessionId":"s_01","runId":"r_01","messageId":"m_1"}}
400 {"code":111001,"message":"请求格式不对","data":null}      ← 请求体不是合法 JSON
400 {"code":111004,"message":"图片不符合要求","data":{"reason":…}}
                                                              ← images 不合法(doc/32 A1);reason 进 data
404 {"code":112001,"message":"找不到这场会话","data":null}    ← 只带未知 sessionId 时
409 {"code":112101,"message":"这场会话正在跑,等它跑完再发","data":null}
                                                              ← 会话有活 run;什么都不写,客户端本地排队、本轮收口后补投
413 {"code":113003,"message":"这条消息太长,裁剪后再发","data":{"limit":M,"tokens":N}}
                                                              ← 单条消息超准入线(仅 compact 开启时,C5-A1):
                                                                limit = window − min(window/5, 16384)(三期起;
                                                                此前为 window×4/5),线 = limit/3;抢闸前拒收、
                                                                零痕迹,客户端裁剪后可原样重投
500 {"code":111901,"message":"服务暂时不可用,请再试一次","data":null}

服务端行为(一笔事务,同生同灭):闸检查(one_live_run_per_session 部分唯一索引)+ run 行 + 把用户消息追加为 runlog 一条 role:user 记录(占一个 runlogOffset)+ 建 runlive:{runId} 并压入 start 帧(eventOffset=1)。要么整笔成功(消息开跑),要么整笔回滚(409)。不存在「入队待调度」的中间态。

事务成功后,客户端并不知道 run 会回什么——它拿着 runId 靠 19v6-02 的 reconcile 轮询 frames / log 观测。POST 本身不返回任何生成内容。

2. GET /api/runs/{runId}/frames —— 拉生成中的帧

GET /api/runs/r_1/frames?eventOffset=N        ← LRANGE runlive:{runId} N N+W-1(**index+1** 即 eventOffset;W = 单批上限)

200 {"code":0,"message":"","data":{"frames":[
  {"eventOffset":1,"kind":"start","agent":"","model":"","messageId":"m_1"},
  {"eventOffset":2,"kind":"delta","agent":"","model":"deepseek/deepseek-flash","text":"我查一下"},
  {"eventOffset":3,"kind":"tool_call","agent":"","model":"deepseek/deepseek-flash","name":"get_time","args":"{\"timezone\":\"Asia/Shanghai\"}"},
  {"eventOffset":4,"kind":"tool_result","agent":"","model":"deepseek/deepseek-flash","name":"get_time","output":"2026-10-08 15:04:05 +0800 CST"},
  {"eventOffset":5,"kind":"delta","agent":"","model":"deepseek/deepseek-flash","text":",现在是 15:04"},
  {"eventOffset":6,"kind":"terminal","agent":"","model":"","status":"complete"}
],"nextOffset":6,"status":"done"}}

3. GET /api/sessions/{sessionId}/log —— 拉定稿历史

GET /api/sessions/s_01/log?runlogOffset=N        ← `seq > N ORDER BY seq LIMIT W`(**`seq` 即 runlogOffset**;W = 单批上限)

200 {"code":0,"message":"","data":{"rows":[
  {"runlogOffset":1,"runId":"r_1","role":"user","agent":"","model":"","messageId":"m_1","text":"现在几点"},
  {"runlogOffset":2,"runId":"r_1","role":"tool_call","agent":"","model":"deepseek/deepseek-flash","text":"get_time({\"timezone\":\"Asia/Shanghai\"})","payload":"{\"name\":\"get_time\",\"args\":\"{\\\"timezone\\\":\\\"Asia/Shanghai\\\"}\"}"},
  {"runlogOffset":3,"runId":"r_1","role":"tool_result","agent":"","model":"deepseek/deepseek-flash","text":"2026-10-08 15:04:05 +0800 CST","payload":"{\"name\":\"get_time\",\"output\":\"2026-10-08 15:04:05 +0800 CST\"}"},
  {"runlogOffset":4,"runId":"r_1","role":"assistant","agent":"","model":"deepseek/deepseek-flash","text":"现在是 15:04……"}
],"nextOffset":4}}
404 {"code":112001,"message":"找不到这场会话","data":null}

4. GET /api/sessions/{sessionId} —— 状态查询

GET /api/sessions/s_01

200 {"code":0,"message":"","data":{"liveRunId":"r_1","runlogOffset":1,"lastRunStatus":"running","lastRunId":"r_1","workspaceId":null}}
                                                ← run 正在跑,runlog 已有 1 条(用户消息)
200 {"code":0,"message":"","data":{"liveRunId":"","runlogOffset":2,"lastRunStatus":"complete","lastRunId":"r_1","workspaceId":"ws_01"}}
                                                ← run 结束,助手全文已进 runlog
404 {"code":112001,"message":"找不到这场会话","data":null}

5. GET /api/runs/{runId}/stream —— 帧面的 SSE 运输(doc/31,2026-10-18 落地)

第五个端点:同一帧面的第二种运输方式(text/event-stream),面向外部消费方(「一次 GET,读到 terminal 为止」)。真源与帧形状与 §2 完全同一份(runlive LIST、ReadFrames、七种 kind 原样透传、id: = eventOffset),契约字节、tail/心跳机制、gone 语义、边界情形表、验收实录的真源在 doc/31——本节只登记存在性与关系,不复制条款(同一机制一份真源)。

与四 API 的关系一句话:拉是正确性,流是优化。流不承诺可靠送达,续传把手 = Last-Event-ID(同一 eventOffset 游标的第二种读法,没有第二个游标抽象)。