tako 文档 GitHub

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 就是全部契约面:

心智模型一条循环:投递拿 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) 考古的人

注意事项(跨切面不变量,改哪篇都适用)


使用说明