tako 文档 GitHub

子代理档案放哪里:文件是索引,不建 PG 目录表

模块:运行引擎 · 子代理委派与持久化(doc/39)|状态:已落地(2026-10-21 S1–S3)|证据:doc/39-子代理持久化与resume.md、internal/runengine/{subagent_wire.go,resume_subagent.go,agents.go,archive_sweep.go}

1. 场景与病灶

researcher 子代理跑两小时、十几个工具调用,折叠成三行摘要回主对话。用户想追问「那个对比表的数据源是哪几个?」——父 agent 手里没有:子代理的现场在跑完那一刻即弃(doc/25 原话:「无 AfterAgent:子代理 state 跑完即弃,没有取货口」)。只能从头交代背景重跑一遍。

副故事:子代理在跑的时候,人只能看 Redis 帧流推给页面的片段;库里没有按实例组织的持久化档案——runlog_entries 按 run 混排、无父子配对结构。崩死的委派连「死在哪」都要翻混排日志。

两个故事同根:完整跑完的子代理,价值在过程里;而过程只活在内存。 追问接不上、过程查不了。

要补这件事,必须回答一个存储问题:每次委派的档案放哪儿、谁当索引、过期怎么回收。 摆上桌的直觉是「建张表」——但表会带来一整套额外的缝:写表与写文件两份真源、清理要同时清两边、跨副本要处理行锁。设计要回答的正是:能不能不建表,还找得到、删得掉、查得着。

2. 候选与代价

候选 做法 好处 代价
A PG 目录表 + 内容存表 每次委派一行,消息序列序列化进列 查询强、跨会话 SQL 聚合方便 与运行现场(文件)两份真源;写表与跑并行要事务;清理要清两处;跨副本多一层一致性
B 纯 wire 文件(选定) 每实例一份 JSONL,目录布局 + 首行 metadata + 尾行 terminal 当索引 少一张表、少一类清扫、少一层一致性缝;tail -f 能看过程;删会话随 .tako/ 级联回收 跨会话 SQL 聚合审计没有;定位靠约定,读错约定就找不到
C 只存折叠后的摘要 把三行摘要落库 便宜 追问需要的是过程与工具结果,摘要里没有;等于把故事一原样保留
D 事件溯源 journal(Kimi wire 形态的完整版) 每行一条事件、重放折状态 可回放、可审计 引擎级改造;与 Redis 帧流 / runlog 形成第二、第三真源;resume 只需消息序列,不需要事件粒度
E 更简单:不给入口 保持「跑完即弃」 零改动 用户每次都要重讲一遍背景;过程永远黑箱

选 B。判断依据不是「文件比数据库好」,而是索引是否必须是一张独立的表。这里定位一个实例只需要三件事,而且三件都天然长在文件上:

要定位什么 从哪读
哪个实例 文件名 <sa_id>.jsonl(sa_ + ULID,创建时铸,免并发撞号)
哪个规格 / 哪场 run / 是否续跑 首行 metadata(agent_name、model_ref、run_id、resumed_from、created_at)
是否完整、何时结束 尾行 terminal(status、result、finished_at)→ 完整档案的标志

目录布局 sessions/<sid>/.tako/subagents/ 本身就是「按会话」这层索引。真需要跨会话聚合时,从 metadata 反向同步出一张表即可——那是查询需求出现后的加法,不是今天的必需。

3. 档案的真身与四个消费方

一行 JSONL 长这样:

{"type":"metadata","sa_id":"sa_…","agent_name":"researcher","model_ref":"deepseek/…","run_id":"r_…","resumed_from":"sa_…或空","protocol":1,"created_at":"…"}
{"type":"message","msg":{ …assistant,含 tool_calls… }}
{"type":"message","msg":{ …tool 结果… }}
{"type":"terminal","status":"complete","result":"…回传终稿…","finished_at":"…"}
消费方 动作
委派工具 铸 sa_id → 建目录 + 写 metadata → 每轮模型往返后追加消息行 → 终态(含 error)写 terminal → 回传文本带「本次委派实例:sa_…」。中断(ctx 取消/panic)不写 terminal,文件留成半成品
resume_subagent 工具 {id} 拼路径,或 {agent} glob 取该规格最新带 terminal 的实例 → 校验未过窗、消息逐条可解析(末尾半截行丢掉)→ 反序列化 → GenModelInput 注入 [历史…, 新指令]
清扫器 glob 各租户 sessions/*/.tako/subagents/*.jsonl → 有 terminal 且过窗 → 删;无 terminal 且 created_at 过窗 → 删(孤儿);其余跳过。只删文件,不碰表
查询端点 GET /api/sessions/:id/subagents → glob + 读 metadata/末行组装 JSON,标 complete / interrupted,权限同 SessionAccess

4. 最难的一处:半截档案救不救(v4 反转)

初版曾打算「从断点重接」:崩了就从最后一条消息接着跑。v4 把它反转为「不重接」:

结果:半成品 wire 保留到清扫(人 tail 能看死在哪),resume 一律拒绝(「该实例未完成或已中断,请重新委派」);想继续 = 重新委派(新实例),或 resume 一个之前完整跑完的档案。error 终态的档案可以 resume——模型自己会看到上一轮怎么死的。

这条也解释了为什么不需要「判断实例是否正在跑」:created_at 新的半成品自然豁免清扫,created_at 过窗的就是死透的孤儿——不需要 lease 区分死活。

5. 同族小裁定(doc/39 §4 的 S-a…S-k)

小问题 裁定 代价 / 备注
档案存哪 纯 wire 文件,无 PG 表 约定即索引;跨会话聚合审计暂缺,真需要时反向同步出表
resume 入口 模型侧工具 resume_subagent,{id} 或 {agent} 两种寻址 模型不必记 ULID——回传文本与对话内容就是它的记忆
可见范围 先限同会话 文件挂会话目录,SessionAccess 拦会话即拦文件
行格式 消息粒度 JSONL(metadata / message / terminal) 消息是 resume 的最小充分单元;不用事件粒度
resume 产出 新实例,新 metadata 的 resumed_from 指回原档案 原现场不可变,链条可追溯
运行环境跟谁 跟当前 run:作业根用当前 run 的,模型/工具池按当前租户 profile 重新装配 档案只带知识与上下文,不带目录/模型绑定
过期与清扫 继承 doc/37 的 -archive-ttl(默认 7 天),清扫第三类只删文件 同一个数、同一套窗口,不另立
半截重接 不做(v4 反转) 工具副作用幂等成本 > 干净重跑;对齐 doc/30
写入时机 每轮模型往返后追加;写失败只记日志 追加 O(1);档案是增强不是正确性依赖;并发同名委派各写各文件
实例 id sa_ + ULID 免并发撞号;metadata、回传、参数三处一致
与 Kimi 的关系 取形态、不取协议 取「每实例一份、追加写、metadata 首行 + terminal 尾行、版本号」;不取事件溯源与 replay 引擎
折叠后的正文 不进档案 wire 是过程记录;折叠是模型输入的优化,不反向改写档案

6. 证据

方案:doc/39-子代理持久化与resume.md §0(做什么/不做什么)§1(两个故事)§2(名词)§3(现状机制;§3.1 与 Kimi 的关系)§4(S-a…S-k)§5(目录布局与 wire 字节、四个消费方)§6(四条端到端链路:正常委派 / resume / 中断 / 过期 / 删会话)§7(S1–S3 分拍)§9(明确不做:崩溃半截重接、跨会话 resume、常驻后台子代理)。真源关系:折叠 doc/25、装配 doc/34、run 级语义 doc/30、清扫窗口 doc/37 §5.5。

代码符号:

位置 是什么
internal/runengine/subagent_wire.go:50 newSubagentID(sa_ + ULID)
internal/runengine/subagent_wire.go:59 subagentWireDir(会话目录下 .tako/subagents)
internal/runengine/subagent_wire.go:103 openSubagentWire(建文件 + 写 metadata)
internal/runengine/subagent_wire.go:171 finish(写 terminal 行)
internal/runengine/subagent_wire.go:191/207/225 appendRange / appendBefore / appendAfter(每轮追加)
internal/runengine/subagent_wire.go:270-303 wireAppendHandler(挂 middleware 链)
internal/runengine/resume_subagent.go:176-224 locateSubagentArchive(按 id / agent 定位)
internal/runengine/resume_subagent.go:299 validateSubagentArchive(terminal、窗口、解析完整性)
internal/runengine/resume_subagent.go:269 dropPartialTail(丢弃末尾半行)
internal/runengine/agents.go:427 runSubagentGuarded(委派与 resume 共用后半段)
internal/runengine/agents.go:472 中断时不写 terminal(半成品)
internal/runengine/archive_sweep.go:235 sweepSubagentFiles(清扫第三类:只删文件)

复核命令:

cd yk-tako-eino
grep -n "func newSubagentID\|func openSubagentWire\|func (w \*subagentWire) finish" internal/runengine/subagent_wire.go
grep -n "func locateSubagentArchive\|func validateSubagentArchive" internal/runengine/resume_subagent.go
grep -n "func sweepSubagentFiles" internal/runengine/archive_sweep.go
PATH="$HOME/sdk/go1.27.0/bin:$PATH" go test ./internal/runengine -run 'Subagent|Resume|Archive|Locate'

活体验收(2026-10-21,tmp/ws-38):会话 s_01M5D7XEPP9ZC4QMG1V58X0SS6 的实例 sa_01M5D7XFPTZYDEBTCYHTCRYE1G,其 wire 的 SHA-256 在重启与清扫后仍是 71a4d705…d79856455;续跑 run r_01M5D94WR1NK5R96CKRN1T5B6B 完成,新实例 sa_01M5D94XYAGRZX720Q1T4Z74C0,父工具结果以「(本次委派实例:sa_01M5D94XYAGRZX720Q1T4Z74C0)」收尾。半截副本回「该实例未完成或已中断,请重新委派」;过窗副本回「档案已过期」;不存在的 id 回「找不到该子代理档案,请重新委派」。清扫探针删掉过窗且有 terminal 的副本与 created_at 过窗的半成品,窗口内的两种都留下。

7. 现状