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 为例:
- 成功 202 → 裸 JSON(旧的)
- 401 没登录 →
{"code":111102,…}(新的) - 404 会话不存在 →
{"error":"session_not_found"}(旧的)
同一个 curl 调用,成功和失败要用两种方式解包。这才是「必须一次换干净」的核心理由。
2.3 前端与测试的现状
web/src/api.ts的request<T>()是旧面的唯一入口:成功直接return (await res.json()) as T,失败把整个 body 当ApiErrorBody({error: string})。web/src/chat.ts有 5 处读旧字段:投递失败提示(e.body?.error)、续跑失败提示、以及两个判定函数isSessionBusy(认session_busy)和isSessionNotFound(认session_not_found)。web/src/auth.ts与configureApi.ts已经是信封拆包(body.code !== 0分支、Envelope<T>类型)。- 后端测试里只有
resume_test.go3 处断言旧字段(body["error"] == "run_not_found"/"not_resumable");media_test.go/stream_test.go/mcpconf_test.go断的是状态码和包含关系,不直接断旧字段。
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}}
规则四条:
- HTTP 状态码一个字不改。还是 400/401/403/404/409/413/429/500。状态给网关分类,业务码给页面区分同一种状态里的不同原因。
data里就是原来那个业务体,字段名一个都不改。{"liveRunId":"r_1","runlogOffset":1}→data里还是{"liveRunId":"r_1","runlogOffset":1}。这次只换外壳,不顺手改字段名。- 失败时
data是null,但键必须在。有额外诊断信息(图片为什么不合法、消息超了多少)就放data里,message只放人话。 - 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. 三样明确不动的
GET /api/media的成功体。它回的是图片字节(http.ServeContent),不是 JSON。套信封会把图片变成 base64 的 JSON——那是把 doc/32「对话里只存 path、显示时才换回字节」的设计推翻。只换它的错误分支。- SSE 帧面。
GET /api/runs/:id/stream回的是text/event-stream,每一帧是data: {帧JSON}。帧是长连接里的事件,不是某个 HTTP 响应的 body——信封在这里没有位置。流前面的 401 已经是信封(viewRun里写的),流的event: gone保持原样。 - 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,施工前)
- D1 · dev-only 端点也换信封。
POST /api/dev/clean-sweep、GET /api/dev/runs/:runId/journal一并换(落在 A7-5 / A7-6)。DELETE /api/dev/reset不动——它是全库 TRUNCATE(AGENTS.md 有专门警告),改它的响应体零收益,只增加手滑风险。 - D2 · 前后端节奏:后端逐拍换,前端在 A7-7 一次性换。 不留兼容层、不留过渡开关(AGENTS.md 明令)。代价是 A7-1 到 A7-6 期间本地前端是坏的——验收全程用 curl,这本来也是运行引擎阶段的纪律。
- D3 · 新码编号按 §4.2 的提议定案:
111004、111005、112101~112104、113003、114101、114102。铺下去之后不再改。
9. 收口
换完之后,前端只有一个拆包入口(api.ts 的 request):看 code 决定跳不跳登录页,把 message 弹出来,data 是业务体。后端每个失败出口都带着一个互不重叠的数字码,页面不再靠拆 message 的句子来分支——这就是这一笔解决的东西。