tako 文档 GitHub

40 · 响应信封统一(runs / sessions / mcp / media / memory)

性质:已落地(2026-10-22)。A7-1…A7-8 共 8 拍全部落地并验收:后端六拍(curl 逐字节)+ 前端一拍(Playwright 活体)+ 收口一拍(契约文档同步)。 验收结论(2026-10-22):runs/sessions/mcp/media/memory 五组旧接口整包换成 {code,message,data}——成功体进 data(字段名与顺序一个没动),失败是数字业务码 + 弹窗文案。 grep 'gin.H{"error"' internal/runengine/*.go | grep -v _test = 0 处(只剩刻意保留的 /api/dev/reset——它是全库 TRUNCATE)。两样不进信封:media 的图片成功体、SSE 帧面。 前端 api.ts 的 request 是唯一拆包入口,chat.ts 五处按 code 分支——Playwright 实测: 助手气泡正常出文、409 出「会话忙,这条还在排队」、中断出「继续这一轮」、401 回登录页。 500 出口的字节由 internal/runengine/envelope_test.go 钉住。 随 cd85050 入库(2026-10-22):A7-1…A7-8 八拍的代码与契约文档都在那一笔;本篇头注的收口由它之后的 docs 笔回填。 代码落点:yk-tako-eino/internal/runengine/{auth.go,server.go,mcp.go,product_api.go,archive_sweep.go,envelope_test.go}、 yk-tako-eino/web/src/{api.ts,chat.ts};契约文档 doc/19-v6/19v6-01-契约-四个API.md 与 doc/19-v6/19v6-04-验收-curl.md; 台账 tmp/A7-信封迁移/(本地,不入库)。 真源关系:信封规则本身写在根 AGENTS.md(2026-10-18 用户定)。业务码表在本篇 §4(doc/28 §5.4 是同一张表的历史出处, 两者已同步);逐端点对照在本篇 §5;19v6-01(四 API 契约字节)与 19v6-04(curl 验收矩阵)已同步。 不在本篇:A7 那一档里的团队计费、API key、SSO、组织/跨租户共享、审计导出(见 doc/28 §15); 存储与帧面设计(doc/19-v6/);前端交互改造(前端只做「拆包跟着改」,不重新设计)。


0. 一句话结论

同一个引擎里现在并存两套响应格式:新的产品接口回 {code,message,data},旧的业务接口回裸 JSON 加 {"error":"..."}。这一笔把旧的五组接口(runs / sessions / mcp / media / memory)整包换成 {code,message,data},不动数据库、不动帧格式、不动 HTTP 状态码,只改响应体的外壳,并把旧 error 字符串里混着的多种语义拆成互不重叠的数字业务码。

1. 背景与动机:这套格式是怎么长成两套的

2026-10-18 之前,引擎只有一套接口,它的响应体长这样:

202 {"sessionId":"s_01","runId":"r_01","messageId":"m_1"}
404 {"error":"session_not_found"}
409 {"error":"session_busy"}
500 {"error":"internal"}

成功的时候,业务字段直接摊在顶层;失败的时候,只有一个 error 字段,里面放一个机器能认的短字符串。

2026-10-18 做了多租户(doc/28)。新加的接口(登录、租户、成员、邀请、项目、助手)从一开始就统一成:

{"code":0,"message":"","data":{"accessToken":"…","tokenType":"Bearer","expiresIn":900}}
{"code":111101,"message":"账号或密码不正确","data":null}

这就是信封:成功时业务体塞进 data,失败时 code 给页面分支用、message 直接当弹窗文案、data 放「没有额外细节就 null、键仍然在」。

病灶——一个具体会发生的失败故事:

前端同学要写「发消息失败」的提示。他打开 web/src/api.ts,看到两种失败体同时存在:

export type ApiErrorBody = { error: string }     // 旧的

他写了个判断:if (body.error === 'session_busy')。跑起来发现,登录过期返回的是 {"code":111102,"message":"请先登录"}——没有 error 字段,他这个判断永远不成立,于是登录过期的用户看到的是一句空白的「操作失败」。反过来,会话 404 返回的是 {"error":"session_not_found"}——没有 code,他想按 code 统一弹窗的拦截器也接不住。

**同一个页面,同一个失败,两套拆包。**这不是审美问题,是「前端每个接口各写一个拆包」的必然结果:AGENTS.md 里那句「没这条规则时,登录弹一句、会话 404 再弹另一套,前端每个接口各写一个拆包」,说的就是现在这个局面。

动机的落点:message 已经是现成的弹窗文案,code 已经是现成的分支依据。前端只需要写一次拦截器——看 code 决定要不要跳登录页,把 message 弹出来。这个收益要等到旧接口全部换完才兑现,所以这是一笔整体替换,不能一半一半地留着。

2. 现在代码里的两套面(2026-10-21 实读)

2.1 已经是信封的

位置 端点
auth.go(39 处 writeEnvelope) /api/auth/signup、login、refresh、logout、me、switch-tenant
tenant_api.go(27 处) /api/tenants/:id/*:成员、邀请、notes、agents、runtime-config、usage、audit-log
product_api.go(112 处) /api/workspaces/*、/api/tenants、/api/me/invitations、项目与会话的删除
server.go(40 处) 新接口里加的 401/403 分支(例如 POST /api/runs 没登录回 111102)

2.2 还是旧体的(这次要换的)

位置 端点 旧成功体 旧失败体
server.go POST /api/runs 202 {"sessionId","runId","messageId"} 400 bad_request / 400 bad_media+reason / 404 session_not_found / 409 session_busy / 413 message_too_large+limit+tokens / 500 internal
server.go POST /api/runs/:id/stop 200 {"status"} 404 run_not_found
server.go POST /api/runs/:id/resume 202 {"runId","status","resumeCount"} 404 run_not_found / 409 not_resumable / run_alive / resume_exhausted
server.go GET /api/runs/:id 200 {"runId","sessionId","status","resumeCount","resumable"} 404 run_not_found
server.go GET /api/runs/:id/frames 200 {"frames":[],"nextOffset":N,"status":"generating|done|gone"} 无
server.go GET /api/sessions/:id 200 {"liveRunId","runlogOffset","lastRunStatus","lastRunId","workspaceId"} 404 session_not_found
server.go GET /api/sessions/:id/log 200 {"rows":[],"nextOffset":N} 404 session_not_found
server.go PATCH /api/sessions/:id/workspace 已是信封 404 session_not_found
server.go PATCH /api/sessions/:id/visibility 已是信封 404 session_not_found
product_api.go:253 DELETE /api/sessions/:id 已是信封 404 session_not_found
mcp.go GET /api/mcp/servers 200 {"servers":[],"count":N} 400 {"error":"<Go 原始错误串>"}
server.go GET /api/media 200 是图片字节,不是 JSON 404 not_found(四种语义混用)/ 400 bad_request+reason
server.go GET /api/memory/items 200 {"items":[]} 500 internal
server.go GET /api/memory/jobs 200 {"jobs":[]} 500 internal
server.go GET /api/memory/dialogue 200 {"chunks":[]} 500 internal
server.go GET /api/memory/recall 200 {"block","memoryHits","dialogueHits","injectedRunes"} 400 bad_request / 500 internal
archive_sweep.go POST /api/dev/clean-sweep(仅 -dev) 200 {"swept":N,"watermark":"…"} 500 sweep_failed

最麻烦的一处不是「旧」,是「同一个接口自己新旧混用」。以 POST /api/runs 为例:

同一个 curl 调用,成功和失败要用两种方式解包。这才是「必须一次换干净」的核心理由。

2.3 前端与测试的现状

3. 换完是什么样

同一组接口,换完之后:

POST /api/runs 成功   202 {"code":0,"message":"","data":{"sessionId":"s_01","runId":"r_01","messageId":"m_1"}}
POST /api/runs 失败   404 {"code":112001,"message":"找不到这场会话","data":null}
POST /api/runs 超长   413 {"code":113003,"message":"这条消息太长,裁剪后再发","data":{"limit":940,"tokens":1200}}

规则四条:

  1. HTTP 状态码一个字不改。还是 400/401/403/404/409/413/429/500。状态给网关分类,业务码给页面区分同一种状态里的不同原因。
  2. data 里就是原来那个业务体,字段名一个都不改。{"liveRunId":"r_1","runlogOffset":1} → data 里还是 {"liveRunId":"r_1","runlogOffset":1}。这次只换外壳,不顺手改字段名。
  3. 失败时 data 是 null,但键必须在。有额外诊断信息(图片为什么不合法、消息超了多少)就放 data 里,message 只放人话。
  4. 204 没有 body,SSE 帧面和二进制成功体不进信封(见 §6)。

4. 业务码表

前两位是模块,沿用 doc/28 §5.4 已定的口径:11 身份与参数,12 会话与运行,13 配额,14 项目与工作区,15 人审与问答(doc/47)。

4.1 复用已有码(一个都不新造)

旧 error 新 code HTTP message 出处
session_not_found 112001 404 找不到这场会话 doc/28 §5.4 已定,代码里已有常量 codeSessionMissing
run_not_found 112002 404 找不到这次运行 doc/28 §5.4 已定,代码里还没有常量,本轮补 codeRunMissing = 112002
bad_request(请求体不是合法 JSON) 111001 400 请求格式不对 已有 codeBadJSON
internal(存储/ID 生成故障) 111901 500 服务暂时不可用,请再试一次 已有 codeInternal
sweep_failed 111901 500 服务暂时不可用,请再试一次 同上
project_busy 114004 — — 已退役(2026-10-22):项目闸随跨成员共享项目一起取消(doc/42)——同项目并发不再被拒,改由文件级防护兜(flock 写锁 + 写前指纹比对)。常量与分支已从代码删除

4.2 本轮新增的码

旧 error 新 code HTTP message 为什么需要新的
bad_media(图片 mime 不合法/base64 解不开/超 5MB/超 4 张) 111004 400 图片不符合要求 旧的 bad_media 是「入口媒体」专有的,旧码表里没有对应项
mcp.json 解析失败 111005 400 MCP 配置读不出来 旧的 400 直接把 Go 原始错误串当 body 吐出来——那是机器细节,不该出现在响应体里;改成固定 message + data.reason
session_busy(这场会话已有活 run) 112101 409 这场会话正在跑,等它跑完再发 注意与 114007 区分:114007 是「删除会话时这场会话有活 run」(doc/37 D3),语义不同,码不能撞
not_resumable 112102 409 这场 run 已经定稿,没有可续的 前端要靠它决定「不显示续跑按钮」
run_alive 112103 409 这场 run 还活着,别抢 前端要靠它决定「不是失败,转去重建帧面」
resume_exhausted 112104 409 续跑次数用完了,重新发一轮 前端要靠它决定「提示重发」
message_too_large 113003 413 这条消息太长,裁剪后再发 旧的 413 带 limit+tokens 两个诊断字段,换信封后放 data
not_found(media:文件不存在) 114101 404 找不到这个文件 旧的 not_found 一个字符串混了四种语义,必须拆开
not_found(media:路径格式不对/越界) 114102 404 媒体路径不对 同上
question_not_found(问题行不存在) 115002 404 找不到这个提问 doc/47 的 answer 端点按行 id 定位;行不存在与「看不见」同形
question_answered(问题行已答过/已失效) 115101 409 这个问题已经答过了 CAS 影响 0 行 = 一答终答;前端据此不再重复提交
question_expired(doc/72 Task 提问过期,2026-11-11) 115102 409 这个问题已经过期 与 115101 分开:超时收口先赢时迟到的回答回这个码,前端提示「已超时」而不是「已答过」;回答端 CAS 只认 pending 且未过期

4.2a 技能面(doc/52,A1–B4 已用到的码)

技能读工具的失败体也是同一套 {code,message,data} 信封,但它是工具结果、没有 HTTP 状态: 模型按 code 改道,UI 用 toolCallId 找到调用行弹 message。同一批只登记代码里已在用的五个; 安装/删除/上传的其余 116xxx 还没进代码,真源仍是 doc/52 §6.2,施工时再搬进来。

旧 error 新 code HTTP message 出处
— 116001 404(端点);无(工具结果) 找不到这个技能 详情端点与本租户视界解析;工具内文案是「找不到这个技能,可能已被删除或改名」(doc/52 §8.2-2)
— 116107 —(工具结果) 这个技能已被禁用,请先在管理页恢复 read_skill/use_skill/read_skill_file 调用时
— 116114 —(工具结果) 这个路径在技能资源里读不到;入口正文请用 read_skill 或 use_skill read_skill_file:越界、缺失、入口文件、平铺形态没有资源目录
— 116115 —(工具结果) 资源文件超过单次读取上限(16,384 token 或 64KB),没有读取 read_skill_file:与正文同一条判据,不截断、不给部分内容
— 116116 —(工具结果) 技能正文超过上下文预算(16,384 token 或 64KB),没有读取 read_skill/use_skill:整篇进上下文前先判

4.2b 记忆模式面(doc/65,2026-11-10 随记忆两层方案新增)

旧 error 新 code HTTP message 出处
—(doc/65 新增,无旧体) 118001 409 当前记忆模式不提供这个观测口 GET /api/memory/items、/jobs、/recall 在 markdown 模式下统一 409——不返回空数组假装文件里没有记忆(doc/65 §6.5);/dialogue 不过这道守卫

4.2c 任务编排面(doc/70,2026-11-10 随多 Agent 编排 V1 新增)

17 = 持久 Task 与编排:1170xx 资源缺失,1171xx 计划与状态冲突。端点真源在 doc/70 §6(V1 前五码)、doc/72 §5–§6(修订/继续三码)、doc/73 §11(通知读取与人工重试三码)与 doc/74 §4.7(工作区配置/重新发布/发布占用三码 117111–117113);117103 的「不能恢复」文案在 doc/72 里包含超时收口后的同一族状态。

旧 error 新 code HTTP message 出处
—(doc/70 新增,无旧体) 117001 404 找不到这件任务 GET/PATCH /api/tasks/:id;不存在或不在本人项目视界
— 117002 404 找不到这个编排组 GET /api/orchestrations/:id
— 117101 400 任务计划不合法 图校验失败;具体原因进 data.reason(不含 SQL 与堆栈)
— 117102 409 这个创建键已经用于另一份计划 幂等键重打但 plan_hash 不同——同键不同计划,拒绝而不是覆盖
— 117103 409 这件任务现在不能恢复 POST /api/tasks/:id/resume:任务未终态中断(有活执行者/已 succeeded/failed)或次数耗尽;「还没有执行记录」是同一码的另一条文案
— 117104 409 这件任务已经结束,不能停止 POST /api/tasks/:id/stop:任务已 succeeded/failed/cancelled
— 117105 409 这个编排组已经结束,不能停止 POST /api/orchestrations/:id/stop:组已收口
—(doc/72 新增,2026-11-11) 117106 409 计划已有新修订,请重新读取后再试 POST /api/orchestrations/:id/revisions 与 /continue:请求里的 baseRevision 落后于当前计划版本;修订与继续共用这个码
— 117107 409 这个编排组现在不能修订 组已收口、或最终 Task 已开始执行、或当前状态不允许改图
— 117108 409 这个修订键已经用于另一次修订 修订幂等键重打但命令内容不同——同键不同命令,拒绝而不是覆盖(同键同命令返回原修订)
—(doc/73 新增,2026-11-11) 117003 404 找不到这条通知 GET /api/notifications/:id 与 POST /api/notifications/:id/retry:通知不存在、跨租户不可见、viewer 无读权、来源会话已删除,四种出口同码同文案,不借通知 id 探测
— 117109 409 这条通知现在不能重新处理 /retry:通知不是 failed、failed 但当前 run 仍在跑(矛盾状态)、旧 attempt 已过期、pending 或已 consumed;claimed 且当前 run 仍活时回 200 现状,不走这个码
— 117110 409 结果产物已不可读取 /retry:恢复前校验整组完成通知的产物——路径越界、不是普通文件或文件已删除;补回文件后可再重试。doc/74 起 GET /api/tasks/:id/artifact 读不到当前结果版本的产物时同码
—(doc/74 新增,2026-11-12) 117111 400 工作区配置不合法 创建 Task:workspaceMode 词表外、shared 携带 verifyCommand、验证命令超限或含 NUL;具体原因进 data.reason
— 117112 409 这件任务现在不能重新发布 POST /api/tasks/:id/retry-publication:非隔离组的最终 Task、发布状态非 blocked(或 blocked 但 errorCode 不是发布错误)、状态矛盾或执行会话缺失;blocked 但已有活 run 等矛盾态同码
— 117113 409 项目正在发布结果,请稍后再试 POST /api/runs:同项目有当前发布标记(publicationEpoch 进行中)时挡新 run,避免与发布竞争;发布收尾后放行

复用不新造:非法 JSON 111001;来源会话 112001、项目 114001、执行者 Agent 112003、租户没装模型 111408;内部错误 111901。创建端点在租户并发容量满时仍回 202(Task 停在 ready 等调度)——容量裁决在领取时做(doc/43),不在创建时假装开始执行。doc/74 的产物端点读 shared 模式结果回 400 111002(请从项目文件读取),未知 Task 回 404 117001,未登录回 401 111102,均复用既有码。

4.2d 目标重规划与项目目录面(doc/75/doc/76,2026-11-12 新增)

117114–117116 归目标重规划与项目容器;117004 是 handoff 读面。端点真源在 doc/75 §6(继任创建/交接读取)与 doc/76 §4(项目目录迁移)。

旧 error 新 code HTTP message 出处
—(doc/75 新增,无旧体) 117004 404 找不到这次重规划交接 GET /api/orchestrations/:id/handoff:组在但没有(或没有完整的)handoff.md;组不存在或不可见走 117002,两者不合并
— 117114 409 这个编排组现在不能创建继任组 POST /api/orchestrations/:id/successors:原组已有继任组、或处于 preparing/waiting_previous(正在创建或等待原组收尾)
— 117115 400 继任方案不合法 同一个端点:目标可行性判定不是 feasible、缺继任原因、复用项没有成功结果/版本不对/不在重规划链内、重规划链超过 8 层、画布校验失败;具体原因进 data.reason
—(doc/76 新增,无旧体) 117116 409 这个项目还需要迁移目录后才能使用 项目容器已有 layout.json 之外的条目却没有 layout.json:新读写入口统一拒绝,先跑离线 -migrate-project-layout;不做新旧双读

4.2e 后台命令面(doc/82,2026-11-15 新增)

117117–117119 归后台命令。端点真源在 doc/82 §6.3(列表/详情/输出/停止)与 §7(提交拒绝)。

旧 error 新 code HTTP message 出处
—(doc/82 新增,无旧体) 117117 404 找不到这条命令 GET /api/jobs/:id、GET /api/jobs/:id/output、POST /api/jobs/:id/stop:不存在、跨租户或不可见(读面属主链,不区分三种原因);项目级列表不带单件语义
— 117118 409 这条命令正在停止中,不能重复请求 同一停止端点:上一请求已写 stop_requested 且执行者尚未确认进程组退出;已到终态再停不是错误,回当前终态
— 117119 409 任务仍有后台命令未收口 submit_task_result:执行者名下还有 running/stopping 的命令,结果可能建立在半截输出上;等待或停止并确认终态后再提交

4.3 media 那个 not_found 拆成三种语义

旧的 media 404 有四个出口都写同一个 {"error":"not_found"},前端分不出「你根本没权限看这个项目」和「这个文件真的没有」:

旧出口 新 code message
路径不是 workspaces/<wid>/… 格式 114102 媒体路径不对
VisibleWorkspace 失败(工作区看不见) 114001(已有 codeWorkspaceMissing) 找不到这个项目
workspaceDir 解析失败 114101 找不到这个文件
os.Stat 失败或目标是目录 114101 找不到这个文件
缺 path 参数 111001 请求格式不对(data.reason = 「缺 path」)
路径越出 workspace 且无登录身份(单测探针) 111001 请求格式不对(data.reason = 「路径越出 workspace」)

5. 旧体 → 信封 逐端点对照

端点 换之前 换之后
POST /api/runs 202 {sessionId,runId,messageId}/400 bad_request/400 bad_media/404 session_not_found/409 session_busy/413 message_too_large/500 internal 202 {code:0,message:"",data:{sessionId,runId,messageId}}/400 111001/400 111004(data.reason)/404 112001/409 112101/413 113003(data.limit/data.tokens)/500 111901
POST /api/runs/:id/stop 200 {status}/404 run_not_found 200 {code:0,message:"",data:{status}}/404 112002
POST /api/runs/:id/resume 202 {runId,status,resumeCount}/404 run_not_found/409 not_resumable|run_alive|resume_exhausted 202 {code:0,message:"",data:{runId,status,resumeCount}}/404 112002/409 112102|112103|112104
GET /api/runs/:id 200 {runId,sessionId,status,resumeCount,resumable}/404 run_not_found 200 {code:0,message:"",data:{…}}/404 112002
GET /api/runs/:id/frames 200 {frames,nextOffset,status} 200 {code:0,message:"",data:{frames,nextOffset,status}}(status:"gone" 的 200 语义不变:未知 run 与过期 run 仍然不是 404)
GET /api/runs/:id/changed-files —(doc/78 新增,无旧体) 200 {code:0,message:"",data:{runId,files:[{path,op}]}}/401 111102/404 112002(看不见与不存在同字节)/409 117116(旧布局,与 /files 同判据)/500 111901
GET /api/runs/:id/tasks —(doc/78 新增,无旧体) 200 {code:0,message:"",data:{runId,rows,total,done}}/401 111102/404 112002/500 111901(不读盘,不判旧布局)
GET /api/runs/:id/stream SSE 文本流 不变(见 §6)
GET /api/sessions/:id 200 {liveRunId,runlogOffset,lastRunStatus,lastRunId,workspaceId}/404 session_not_found 200 {code:0,message:"",data:{…}}/404 112001
GET /api/sessions/:id/log 200 {rows,nextOffset}/404 session_not_found 200 {code:0,message:"",data:{rows,nextOffset}}/404 112001
PATCH /api/sessions/:id/workspace 已是信封/404 session_not_found 404 改 112001,成功体不动
PATCH /api/sessions/:id/visibility 已是信封/404 session_not_found 404 改 112001,成功体不动
DELETE /api/sessions/:id 已是信封/404 session_not_found 404 改 112001,成功体不动
GET /api/mcp/servers 200 {servers,count}/400 {"error":"<原始串>"} 200 {code:0,message:"",data:{servers,count}}/400 111005(data.reason)
GET /api/media 200 图片字节/404 not_found/400 bad_request 成功体不变(二进制);404 按 §4.3 拆成 114001/114101/114102,400 改 111001
GET /api/memory/items 200 {items}/500 internal 200 {code:0,message:"",data:{items}}(行字段集随 doc/65 §4.2 换代:layer/scope/state/quote/source,见 doc/65 §6.5)/400 111002(state 非法)/409 118001(markdown 模式)/500 111901
GET /api/memory/jobs 200 {jobs}/500 internal 200 {code:0,message:"",data:{jobs}}(行字段集随 doc/65 §4.5 换代:kind/targetLayer/leaseUntil/claimEpoch/nextAttemptAt)/409 118001(markdown 模式)/500 111901
GET /api/memory/dialogue 200 {chunks}/500 internal 200 {code:0,message:"",data:{chunks}}/500 111901(两种模式都保留,不设模式守卫)
GET /api/memory/recall 200 {block,memoryHits,dialogueHits,injectedRunes}/400 bad_request/500 internal 200 {code:0,message:"",data:{…}}(键序 block→dialogueHits→injectedRunes→memoryHits)/400 111001(缺 q)/409 118001(markdown 模式)/500 111901
POST /api/dev/clean-sweep(-dev only) 200 {swept,watermark}/500 sweep_failed 见 §8 待拍 D1

6. 三样明确不动的

  1. GET /api/media 的成功体。它回的是图片字节(http.ServeContent),不是 JSON。套信封会把图片变成 base64 的 JSON——那是把 doc/32「对话里只存 path、显示时才换回字节」的设计推翻。只换它的错误分支。
  2. SSE 帧面。GET /api/runs/:id/stream 回的是 text/event-stream,每一帧是 data: {帧JSON}。帧是长连接里的事件,不是某个 HTTP 响应的 body——信封在这里没有位置。流前面的 401 已经是信封(viewRun 里写的),流的 event: gone 保持原样。
  3. HTTP 状态码与 204。204 没有 body,这条是 AGENTS.md 原话。

7. 施工顺序(细节在 tmp/A7-信封迁移/)

一拍一个端点组,每拍做完停下验收:

拍 做什么 为什么这个顺序
A7-1 码表常量 + 全局 500 出口(internal())+ sessions 读面与删除面 先定码(后面每一拍都靠它);internal() 是全仓 76 处调用的公共出口,一改全场生效,放在第一拍才不出现「有的端点换了、有的没换」的半迁移状态;sessions 面最小、依赖最少
A7-2 runs 读面(status / frames / log) 纯读,验收最容易
A7-3 POST /api/runs(写面主战场,含 413/409) 错误语义最多的一拍,单独立拍
A7-4 stop / resume(含 409 三态) 依赖 A7-3 定下的码
A7-5 memory 四端点 + dev journal 独立一族,互不依赖
A7-6 mcp servers + media 错误分支 成功体特殊(列表/二进制),单独处理
A7-7 前端拆包(api.ts + chat.ts) 后端换完再统一换前端,见 §8 待拍 D2
A7-8 契约文档同步 + 收口 19v6-01/19v6-04/doc/28/doc/30/doc/32 字节同步

8. 已拍(2026-10-21,施工前)

9. 收口

换完之后,前端只有一个拆包入口(api.ts 的 request):看 code 决定跳不跳登录页,把 message 弹出来,data 是业务体。后端每个失败出口都带着一个互不重叠的数字码,页面不再靠拆 message 的句子来分支——这就是这一笔解决的东西。