子代理档案放哪里:文件是索引,不建 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 把它反转为「不重接」:
- 半截现场的工具副作用已经部分发生(写了文件、发了请求),续跑要逐项处理幂等;
- 干净重跑更可靠,且与 doc/30 的 run 级语义一致——journal 重放对中断的工具调用只回一句「引擎不会自动重跑这次调用,需要的话请重新发起」;
- 省掉 running lease / 尾轮重试一整层复杂度。
结果:半成品 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. 现状
- 仍有效:纯文件 + 三件约定(目录布局 / metadata / terminal)当索引;resume 只认完整档案;新实例成链;窗口与清扫继承 doc/37;同会话可见;模型侧工具入口(页面入口由 doc/44 的「继续」补上,做法是把指令追加到输入框,不让页面起第二场 run)。
- 已翻转:「从断点重接半截档案」方案作废(v4);「建 PG 目录表」不再考虑。
- 未做:跨会话 resume、跨会话子代理用量统计、事件溯源级 replay、常驻后台子代理。
- 同族问题:子代理折叠与窗口 → 子代理窗口谁来压;规格与工具边界 → 子代理规格与工具边界;崩溃后 run 的状态语义 → 崩溃后这场run算什么状态;页面入口 → 前端可用性欠账。