19 · 运行引擎架构 v6(index)
本文取代 v5。本文是 doc/19-v6 文档集的 index:目录 + 概要 + 概念表 + 注意事项 + 使用说明。 版本口径:v6 是**第六代运行引擎(连同描述它的文档集)**的代际编号,不是对外服务版本,也不是 API 版本。代码在
yk-tako-eino/,文档在doc/19-v6/,两边是同一代的两种载体。 契约细节分篇,见下方目录。最近修订(2026-10-20 二十修:T4/T5 合批,BM25 首版):用户裁「一步到位把 T5 也做了」——T4 分级 + tool_search 与 T5 BM25 同批施工,BM25 即首版(不先做名称/描述直出过渡);同拍澄清 mh 只记 tool_search 的调用/结果,不记工具 schema 与激活状态(激活集是 run 状态,每轮用 run 内完整目录 重建声明面
state.ToolInfos——direct + 已激活;不能对当前 ToolInfos 做减法,deferred 项首轮已被移出)。 代码未动、四个 API 字节零变化;演进见19v6-90二十修。 更早演进(初版定位、一~十九修)见19v6-90-演进记录.md。2026-10-07 文档集拆分:原单文件拆为本 index + 四篇 + 演进记录,内容逐字节搬运、只改写交叉引用。 引用约定:
19v6-NN=doc/19-v6/19v6-NN-….md;不要再用旧「doc/19 §N」(§ 号跨文件会漂)。2026-10-08 新增 19v6-05(T 系列 tool loop 立项):机制裁定真源(Eino ADK 底座 / 术语 / 工具双投影 / sub agent / 工具目录)。帧新 kind 与
agent字段等契约扩展已随七修落 19v6-01(2026-10-08 T2);model字段随十修补记、委派样例随十三修补(2026-10-12,T3 落地)。
概要
第一步只跑一件事:投一条消息,轮询看着回复一点点生成、定稿。四个 API 就是全部契约面:
POST /api/runs—— 创建 run(= 投递消息;含首条消息懒建会话)——字节真源 19v6-01 §1GET /api/sessions/{sessionId}—— 状态查询(活 run + runlog 高水位),reconcile 的唯一入口 —— 19v6-01 §4GET /api/runs/{runId}/frames—— 拉生成中帧(eventOffset,run 内)—— 19v6-01 §2GET /api/sessions/{sessionId}/log—— 拉定稿历史(runlogOffset,全局)—— 19v6-01 §3
心智模型一条循环:投递拿 runId → 轮询 frames 看生成 → terminal / gone / liveRunId 变空任一触发收口 → 拉 log 用 assistant 全文替换半截气泡(总流程见 19v6-02)。
概念表
全文反复出现的词,先在这里钉死:
| 概念 | 是什么 |
|---|---|
| session(会话) | 服务端登记的资源。首条消息投递时含铸;未登记一律 404。没有跨 client 同步。 |
| message | 一条对话消息,role 区分:用户投递的是 user,模型产出的是 assistant。messageId 仅 user 消息有、客户端生成、请求前就有,不参与排序。 |
| run | 一次执行。本步:消费一条 user message、产出一条 assistant message。同一 session 同时最多一场(闸保证)。 |
| 帧(frame) | runlive 列表里的一项(一个 JSON),描述一场 run 的一个事件。七种:start / delta / tool_call / tool_result / usage / resume / terminal;每帧带 agent(空 = root)与 model(生效 ref;空 = 非模型产物)。不是 SSE data:,是拉取响应里的数组元素。usage(doc/27)与 resume(doc/30)是后加的两种,kind 清单会随机制增长——客户端按 kind 分派、未知 kind 忽略。 |
| agent / model | 帧与 runlog 行的两个来源字段(恒在):agent = 产出该帧/行的 agent 名,空 = root;model = 生效模型 ref(厂商/模型),空 = 非模型产物(start/terminal/user 行)。子代理委派时两者带非空值(T3;机制见 19v6-05 §4)。 |
| eventOffset | runlive 的游标:run 内序号,start=1、每 delta +1、terminal 占末。拉 frames 用它(GET /api/runs/{runId}/frames = LRANGE runlive:{runId} N N+W-1)。定稿、runlive 过期后即失效,不是历史地址。 |
| runlogOffset | runlog 的游标:session 内全局序号,跨 run 单调,每条定稿记录占一个,永久有效。GET /api/sessions/{sessionId} 返回它的高水位、GET /api/sessions/{sessionId}/log 拿它当游标。永久有效 ⇒ 双向合法:往前拨补新、往回拨翻旧。初始值取 max(0, 高水位 - 窗口),不是 0。 |
| W(单批上限) | 服务端对两个拉取端点的单批返回条数上限(dev 默认 200,可配)。被截断时 nextOffset = 本批末条 offset,客户端从它续拉即补齐——没有「一次拿全部」。 |
| runlive | Redis LIST,键 runlive:{runId}:一场 run 的生成过程帧序列。开跑建、每 delta 追加、定稿压 terminal 并设 TTL(到期自动清)。客户端经 GET /api/runs/{runId}/frames 轮询它看正在生成的回复。 |
| runlog | PG 表 runlog_entries(序号列 seq):session 的定稿记录序列(role:user/assistant + 工具扩展行 tool_call/tool_result;每行带 runId+role+agent+model+text,扩展行带 payload),seq 即 runlogOffset。永久,历史真源,经 GET /api/sessions/{sessionId}/log 有界读(seq > N ORDER BY seq LIMIT W)。 |
| delta | kind:delta 帧的 text 是增量片段(非累计全文)。客户端按 eventOffset 顺序追加进该 run 的气泡。 |
| run 结束 | run 侧收尾:running → 终态 status(本步 complete/error;stopped 后续 loop)。压 terminal 帧、给 runlive 设 TTL、放闸、删 runepoch——无条件,不管结局如何闸必放。入口 endRun(sessionId, runId, status)。 |
| 定稿 | message 侧收尾:assistant 碎片 → 一条完整 message 记录(runlog 追加 assistant 全文记录)。只有 status=complete 那一次发生;此后该回复的权威内容以 runlog 为准。run 结束与定稿同一笔原子写——拆名不拆原子性,否则客户端能观察到「闸已放、历史还没那行」的窗口。error 结局不进历史(runlog 永远只有定稿记录),残缺输出不进历史。 |
| 收口 | 客户端见 frames 的 terminal(或 liveRunId 变化 / frames 已 gone)→ 拉 log 拿那条 assistant 全文,按 runId 替换用 delta 拼的半截气泡。 |
| 闸 | runs 表上的 one_live_run_per_session 部分唯一索引(UNIQUE (session_id) WHERE status='running'):插入活行成功 = 抢到 run;失败 = 409 session_busy。进程死亡由租约列 lease_until 判死(watchdog 续约;租约过期读侧即不算活)。 |
| liveRunId | GET /api/sessions/{sessionId} 返回的当前活 run id;"" = 会话闲着(无 running run)。 |
| reconcile(对账) | refresh / reconnect 共用的纯轮询流程:查 session → 拉 log 补历史 → 有活 run 则轮询 frames → 见 terminal 收口。无长连接、无挂流。 |
没有合并语义,没有 inbox,没有跨 client 同步。
目录
| 篇 | 管什么 | 谁在读 |
|---|---|---|
19v6-01-契约-四个API.md |
§0 范围 + 四个端点的请求/响应/错误字节 | 写客户端的人、写验收的人 |
19v6-02-reconcile与双游标.md |
客户端纯轮询总流程;对齐游标 vs 翻页游标 | 写客户端的人 |
19v6-03-存储形态与生命周期.md |
PG 四表 + Redis 两键(三搬两留一消失)、闸 = 部分唯一索引、生命周期、真源划分、多副本 | 改 engine 的人 |
19v6-04-验收-curl.md |
curl 手打用例 1–7(含委派 sub agent + 回传裁剪)+ 期望字节 | 验收的人 |
19v6-05-tool-loop.md |
T 系列机制裁定:Eino ADK 底座、工具双投影、sub agent(AgentTool)、工具目录/tool_search(T4/T5 2026-10-20 指令开工、合批施工)、帧扩展(已随七修落 01)、§4 实施口径(T3 已落地) | 改 engine 的人 |
19v6-06-deferred-tools与缓存机制.md |
T 系列附属:工具 deferred 加载与缓存机制(纯背景篇:client mode 已为终态底座,hosted mode 2026-10-21 裁定不接) | 改 engine 的人 |
19v6-07-compact.md |
compact 机制裁定:触发形态 / 折叠算法 / 摘要调用规格(C2 施工面)/ 落库事务边界 / 前方登记 | 改 engine 的人 |
19v6-08-file-tools.md |
F 系列文件工具族:workspace 约束 / 11 工具契约表 / 装配登记(lint 转正)/ 与 fileOps 咬合 | 改 engine 的人 |
19v6-09-溢出修复层.md |
溢出修复层立项方案:两层检测(报错匹配 + 截断检测)/ 强制压缩只重试一次 / trim 落二期。一期 A1–A4 + 三期(预留重裁)2026-10-12 落地 | 改 engine 的人 |
19v6-10-mid-run-fold.md |
mid-run fold:触发面 / 没有第二写点 / 计数基数 / 三件套不变量闸门。2026-10-12 用户判定 A5 完成 | 改 engine 的人 |
19v6-90-演进记录.md |
初版定位 + 一~二十修全文(当前形态为什么长这样;十四修 = 笔记层落地,真源 doc/17;十五修 = 三期预留重裁;十六修 = 同会话历史查找,真源 doc/21;十七修 = 笔记写入检查裁到隐形字符一档,真源 doc/17;十八修 = hidden 语义校正;十九修 = hidden 档删除、只留 direct/deferred;二十修 = T4/T5 合批、BM25 首版、mh 与激活集分家,真源 19v6-05 §5) | 考古的人 |
注意事项(跨切面不变量,改哪篇都适用)
- 纯拉模型:无 SSE / 长连接 / 推送 / heartbeat(19v6-01 §0)。
- 拉取一律有界:单批上限 W 管两个拉取端点;没有「一次拿全部」(19v6-01 §0)。
- 两种游标别混:对齐游标只前进;翻页游标是临时值、不回退对齐游标(19v6-02)。
- 闸在共享存储不在进程:
runs表one_live_run_per_session部分唯一索引(WHERE status='running')——插入失败本身就是 409;进程死亡由租约列lease_until兜底(watchdog 续约、租约过期读侧即判死)(概念表「闸」、19v6-03)。 - runlog 只增不删:只追加、永久、历史真源;任何失败路径都不删行(19v6-03)。
- run 结束与定稿同一笔原子写;
error结局不进历史(概念表「run 结束」「定稿」、19v6-03 生命周期)。 - 帧的头尾是应用层造的生命周期标记:
start由投递事务压、terminal由endRun造;provider 的 done 事件不产生帧(实现裁定见tmp/19-v6/planning.md§5 第 8 条)。 - 「从未存在」与「已过期删除」不区分:frames 对未知 run 回 200
gone而非 404(19v6-01 §0)。 - 没有用例逼出的端点不进契约;需要时照既有通道扩,不预留字段(19v6-90 四修)。
使用说明
- 真源分工:本目录(
doc/19-v6/)= 契约真源;tmp/19-v6/planning.md+todos.md= 执行台账(阶段、脚手架与转正、储备裁定 §8)。冲突以本目录为准,回头改台账。 - 引用约定:
19v6-NN=doc/19-v6/19v6-NN-….md。代码注释与台账引用分篇用「19v6-NN §N / 「标题」」。 - 改契约:动任何一个端点的字节 → 同步改 19v6-04 的 curl 期望、重跑 baseline(台账 A4-1 ①–⑫)、补一条修订记录进 19v6-90。
- 演进记录只追加不篡改;版本号跳不跳由用户判定(AGENTS.md)。
- v5 及更早版本已废:不作论据、不作施工面(AGENTS.md)。