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"}}
eventOffset=N返回该 run 中 offset > N 的帧,升序,单批最多 W 条;缺省或=0即从start起(新客户端从零看到整段生成,超长回复分几批拉完)。nextOffset= 本批最大 offset;空则 = N(客户端直接拿它当下次的eventOffset)。被 W 截断时它就是本批末帧的 offset,续拉即补齐。- W 与 log 共用同一条规则,不做特例:frames 本身有界于单条回复长度,上限对它只是防「超长回复把一次响应撑爆」。
- 帧有七种
kind,顺序即真实事件序(tool_call/tool_result夹在delta之间):start:run 开头,带messageId(这条回复绑哪个客户端气泡)。delta:text是增量片段(非累计全文)。tool_call:模型决定调一次工具。name= 工具名;args= 模型给出的原始 JSON 字符串——原样透传、不重编码(形状由模型/工具 schema 定,服务端不裁剪)。tool_result:工具执行完回来,非流式——一次调用一条帧。name= 工具名;output= 工具输出文本。usage:账单帧(2026-10-18 落地,doc/27 §4a)。每枪一帧,数值列 =promptTokens/completionTokens/reasoningTokens/totalTokens/window(同UsageBill逐字段拷贝);agent/model= 产出该枪的 agent 与生效 ref。多枪时取最后一帧(= 下一枪的基线)。resume:续跑种子帧(2026-10-21 落地,doc/30 §8.3)。崩溃后接管那场 run 时, runlive 被seedResume删掉重建,第一条就是它。它的text是账本里已产出的整段正文, 不是增量片段——语义与delta相反:客户端必须替换(=)而不是追加(+=), 否则会把崩溃前的正文重复拼一遍。续跑后追加的正文走正常delta帧。terminal:见下条。- 客户端按
kind分派,未知 kind 必须忽略而非报错——七种之外将来还会长(这七种是截至 2026-10-21 的全集,不是不变集合)。
- 每帧带
agent:产出该帧的 agent 名,空 = root(主 agent)。任何帧都带它(含start/terminal)——委派的子代理帧带子代理名(T3 已落地,样例见下),客户端不解析也知道「这帧不属主线程」。 - 每帧带
model:产出该帧的模型身份——厂商/模型形态的生效 ref(与TAKO_MODEL同一词表)。主 agent 帧 = 主模型 ref;子代理帧 = 该规格的生效模型 ref(规格model:写default/inherit/继承时,生效的就是主模型,帧上写主模型的 ref——规格语义见19v6-05§4)。空 = 非模型产物(start/terminal)。与agent同为恒在字段:客户端不解析也知道「这帧由哪个模型生成」。 - 委派场景样例(T3;字节规则不变,
kind取值同上面七种):root 的tool_call/tool_result帧name= 子代理名(args= 委派任务描述原文),两帧之间夹子代理自己的帧流(delta/tool_call/tool_result逐条带子代理名与它的生效 ref):{"eventOffset":4,"kind":"delta","agent":"researcher","model":"deepseek/deepseek-flash","text":"…"}, {"eventOffset":5,"kind":"tool_result","agent":"","model":"deepseek/deepseek-flash","name":"researcher","output":"…(回传终稿;超上限已裁剪、尾带 omitted 提示——19v6-05 §4)"} status∈generating(还没 terminal)/done(本批或已含 terminal)/gone(runlive键已过期删除):generating→ 客户端按轮询间隔继续拉nextOffset之后;done→ 见 terminal,收口(19v6-02 第 4 步);gone→ 该 run 早已定稿清走,转拉 log。
terminal是这一场 run 的最后一个事件:终态status本步取complete/error两支(stopped是后续 loop)。error时照常压帧、放闸,但不写runlog——runlog 永远只有定稿记录(§3)。- 客户端把
delta帧按eventOffset顺序追加进气泡;地址↔︎内容一对一,去重 = 「见过的 eventOffset 跳过」。
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}
- 每行带
agent:空 = root(与帧同义);委派场景的行带子代理名(T3 已落地,样例见下)。 - 每行带
model:与帧同义(同一厂商/模型ref)——user行为空(不是模型产物);tool_call/tool_result行 = 发起/承接该调用的 agent 循环所用模型;子代理行 = 该规格的生效 ref。 - 委派场景样例(T3):行序 = 事件到达序(消息粒度,不做树形重排)——user → tool_call(委派,root) → [agent:"researcher" 的工具活动行 + 终稿 assistant 行] → tool_result(回传,root) → assistant(root 终稿);回传文本 = 子代理终稿的字节前缀(先裁后落;尾缀语义见
19v6-05§4):{"runlogOffset":3,"runId":"r_1","role":"assistant","agent":"researcher","model":"deepseek/deepseek-flash","text":"…(子代理终稿全量)"} - 行有两种粒度:
user/assistant= 消息本身;tool_call/tool_result= 工具活动扩展行(消息粒度,不是帧——生成中的 delta 只进 runlive,不落 runlog)。 - 扩展行的
text是可直接展示的一行:tool_call=name(args);tool_result= 输出原文。payload是结构化 JSON({"name","args"}/{"name","output"},字段与同名帧一一对应),只有扩展行有;其内args仍是字符串(模型原始 JSON 原文,不重编码——坏 JSON 也不会破 payload)。 user/assistant行的形状不变;assistant 定稿行 text = 本 run 全部 delta 累计(含工具轮前导语),仍是收口替换的锚。runlogOffset=N返回 offset > N 的记录,升序,单批最多 W 条;缺省或=0= 从头分批拉(要拉 ⌈总条数 / W⌉ 次),不是「一次拿全部」。- 初始游标不是 0:新客户端先
GET /api/sessions/{sessionId}拿高水位H,取runlogOffset = max(0, H - 窗口)只拉尾巴;要更早的历史就把游标往回拨再拉一次。理由:runlog永久增长(compact 压的是model_history,不动runlog),「从 0 全量」在长会话下是无界请求。窗口大小由客户端定,服务端的 W 兜底。 - 只有定稿记录:
runlog里永远只有已定稿的 message(§1 的 user 记录、概念表「定稿」的 assistant 记录——概念表在 index),没有半截——生成中的半截在 frames(§2)。(新 A6 已裁,2026-10-03)error 结局的残缺文本不进 runlog、不另留痕:frames 里的半截在 TTL 前可见,之后消失;model_history在 error 结局只进 user 那一半(assistant 不进)——模型上下文里保留这次失败的尝试,重投时模型看得到它。 nextOffset= 本批最大 offset;空则 = N。被 W 截断时它就是本批末条记录的 offset,客户端从它继续拉即补齐。- 记录带
runId:客户端按runId把定稿的assistant记录对上「正在生成」气泡替换(收口)。
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}
liveRunId:读runs表活行(WHERE session_id=$s AND status='running' AND lease_until > now()的一行),""= 会话闲着。决定客户端要不要拉 frames。runlogOffset:runlog:{sessionId}的高水位(LLEN)。客户端据此判断有没有新定稿要补。lastRunStatus(doc/17 §4,2026-10-17 落地):最新一场 run 的终态(running/complete/error/stopped),""= 这个会话还没有过 run。stopped收口靠它分辨「用户停的」与「失败」——两者的 log 长得一样(都没有 assistant 行)。lastRunId(doc/30 A1,2026-10-21 落地):最新一场 run 的 id,""= 无 run。它与lastRunStatus="interrupted"配对时, 就是「崩溃后可以被接管的那一场」——续跑入口POST /api/runs/{id}/resume靠这两个字段定位。 注意它说的是最新一场,未必是客户端正在看的那一场;要判单场,用GET /api/runs/{id}(doc/30 §10.1)。workspaceId(doc/35 A4,2026-10-20 落地):会话挂着的项目 id("ws_..."),游离会话是null(不是空串)。- 字段序 =
liveRunId→runlogOffset→lastRunStatus→lastRunId→workspaceId(Go 结构体声明序)。
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 游标的第二种读法,没有第二个游标抽象)。