tako 文档 GitHub

25 · 子代理进程内折叠

性质:正式版。2026-10-16。

取代 doc/17 §6 作为施工真源。doc/17 其余章节与 §6 旧文作历史讨论稿;正文一句指向即可,不搬施工史与翻案长文。

点头开工前不写 tmp/ 台账、不改代码。本篇不加端点、不加帧 kind、不加表。

处置拍板(已推荐;用户点头开工时可当定案):per-name 互斥 + 给上游供 repro/PR;不做强制重建绷带;不做 per-delegation 重装。WrapModel 换模型本拍不碰。 翻案(2026-10-23 用户拍):「per-delegation 重装」以壳化变体落地——run 起手仍解析并缓存全部装配输入(工具池 / 模型 / 快照段),agent tools / agent system 观测面与拒载时机维持 run 级不动;只有 eino 实例(NewChatModelAgent + NewAgentTool)推迟到模型真正调用委派时、每次委派新建即弃(subagentShell,agents.go,与 resume 共用 assembleSubagentTool 装配核)。旧拍「不做」针对的是连装载时点一起挪走的全量变体;壳化变体保住了当初钉在 run 起手的全部约束。

施工状态(2026-10-17):已落地,A1/A2/A3 三拍验收全过(台账 tmp/17-子代理折叠/,验收后清理)。 补记(2026-10-23):壳化装配落地(头注翻案同批)——子代理实例从「每场 run 一份」缩为「每次委派一份」,#1177 的同场同名并行委派路径随之消除(实例级共享可写状态不跨委派存活);跨会话/跨租户的主 run 实例共享路径仍登记(§6 处置跟进)。 A1 = agentFoldHandler(midfold.go)挂进子代理装配点:估/折/滤与主 midfold 同链同参 (同 counter / CompactLimitFor / 摘要器 / fileEffects,newAgentSpecHandler 加折叠链五参), root 的 foldBox 只读不写(只读 box.run/box.session 两个标识符)、无 AfterAgent、无实例字段; 与折叠同拍补齐 doc/24 在子代理侧的滤思考 + Usage 估长度。A2 = §3 错误形状落地(补记见彼处)。 A3 = bash 写路径经 command 扫描钉进子代理摘要端到端(零代码,纯验收)。 主证活体:fold run r_01M551XDQ60VZE7ZKKE2459XP9(12000 窗,researcher 四折 21881→1683 tok、 四行 agent fold 全部 钉 1 路径: markers.txt);失败路径 run r_01M5504380NTV8999TJ3P4H8B0 (摘要 0/3 → 错误文本进主线程 → root 未重试 → terminal complete)。 验收跑在 doc/26 护栏落地前(彼时 researcher 还拿得到 bash);护栏落地后重跑按 §10 注换 coder。 实录勘误三条见 §10。

1. 要解决的事

子代理连着调工具,正文堆在自己的进程内消息列表里。压缩今天只挂在主代理上。窗口满了终稿出不来,主线程只能看到委派失败。

本拍只压子代理进程内那份消息列表。不往 run_model_messages 插行,不占用主 run 的 seq=0。runlog 里已写下的工具行不动。主线程仍只收终稿。

历史讨论见 doc/17 §6。

2. 怎么压

与主 run 同一条摘要链、同一把 -compact-window,不另设旗标。顺序固定:

  1. 估长度(对齐 doc/24 §5、§6)
  2. 决定折不折
  3. 放行前滤上一枪 ReasoningContent(对齐 doc/24 §3)

估 / 折 / 滤细节对齐 doc/24 与主 midfold。滤思考与 Usage 估长度要从主 midfold 抽出共享——子代理今天只有 callerStampMiddleware,没有这些逻辑。

3. 错误形状

摘要失败,或不调用子代理主模型、把错误文本当作这次委派的工具结果交回去 → 父 run 保持 complete。

厂商以「上下文超长」拒收 → 同一形状错误文本当委派工具结果,父 run 同样 complete。终稿出不来是同一类事,不让一次委派把整场 run 打成 error。

其他错误原样上抛(手动停止的 ctx 取消维持裸上抛——那是真的要停,转成文本会骗过模型继续干活)。

落地补记(2026-10-17):折叠链错误的判定走文本不走 errors.Is——子代理 handler 的错误到委派 工具之间隔着 ADK graph 的 [NodeRunError] 包裹层,Go 错误链不保证端到端保留(活体实证,主证 run 的 错误文本里可见该前缀);与溢出判定用报文正则同一理由。落地形状 = 折叠链错误统一以 foldChainErrorMark = "子代理折叠链:" 前缀上抛(agentFoldHandler 两个错误出口包装),委派工具 InvokableRun 两分支转换:文本含哨兵 → 错误:子代理 <名> 上下文折叠失败:…;IsOverflowError 命中 → …上下文窗口溢出:…;两路都当工具结果返回(err = nil)。单测 TestDelegationToolConvertsFoldFailures 四格钉(含 [NodeRunError] 壳不干扰判定)。

4. middleware 无状态

折叠挂在 ADK middleware 上,追加进子代理装配处已有的 Handlers 列表(今天已有 callerStampMiddleware)。

同场 run 可并行同名委派(eino ToolsNode 默认并行,tako 未改串行)。一次装配里 middleware 实例只有一份,两个 goroutine 可同时进。

禁令:实例字段里不许存任何一次调用专属的东西(计数器、上一份摘要、上一次估出的长度)。一次调用状态只走参数与 ADK 交给它的那份 state。

5. 摘要套摘要

摘要行拿不到 mh 坐标(RunID / Seq 落库才发)。它只以消息形状留在子代理进程里。第二次折叠时,上一次摘要会被当成普通历史再摘一次。

可接受。不落库补救。子代理跑完即弃,多套一层只影响终稿措辞密度。

6. eino #1177(台账登记)

上游 issue #1177:ChatModelAgent 实例共享 msgConf.cancelCtx,并发 Run 复用同一实例时有 data race。v0.9.21 未修。

在 tako 当前接线下(无 adk.WithCancel、停靠 Go ctx):cancelCtx 多半是 nil 写 nil——有 -race、无功能串线。将来若用 WithCancel,才有 stop 串线风险。

台账如此登记。勿按「不上互斥就不能上线」写。

处置跟进(2026-10-23):委派路径已壳化(头注翻案同批)——子代理实例每次委派新建,同场同名并行不再共享实例,本路径的写字竞态消除,per-name 互斥的 #1177 动机随之被吸收(该拍仍「采纳」未施工,是否另有动机未重拍)。仍共享实例的是主 run 实例(worker.go 造,跨会话跨租户):当前接线 nil 写 nil,维持登记;将来启用 adk.WithCancel 前必须先解决——主实例没有名字可分,per-name 互斥对它不适用,选项回到 doc/28 §10.3 的治根/换实例两路。

7. 处置(已推荐,点头开工可当定案)

项 拍板
per-name 互斥 采纳。同名委派串行化;异名仍可并行
给上游供 repro/PR 采纳。治根走 #1177
强制重建绷带 不做
per-delegation 重装 不做 翻案(2026-10-23):壳化变体落地——装载输入与观测面维持 run 级,只有实例推迟到每次委派(subagentShell,agents.go);resume 与之共用装配核
WrapModel 换模型 后话,本拍不碰

returnDirectly 主 / 子均为空已坐实,但不当作采用强制重建绷带的理由。

8. 明确不做

翻掉的边界:

9. 依赖(已落地)

10. 验收

剧本:

  1. 调小折叠窗口
  2. 用 bash 造长高熵输出(例:python3 -c 'import secrets;print(secrets.token_hex(15000))'),不用 web_search
  3. 子代理连着产生两份长结果;第二次模型调用前,前一次长结果已被摘要替换

委派对象(2026-10-16 doc/26 落地后):这出戏要委派 coder——researcher 的有效名单里 已经没有 bash(也没有写类工具),第 2 步在它身上跑不出来。折叠 handler 挂在子代理装配循环里、 对每条规格都挂,所以日志行同形,只是名字换成 agent fold coder:。重跑时注意 coder 与 researcher 的两处差别:① coder 的系统提示更短 ⇒ 同一窗口档下用量基线更低,压测窗口按新基线重选; ② coder 的正文要求「批量活先写成脚本再跑、结果写进文件」,剧本措辞必须明确禁止它把输出写进文件 再 wc(模型自作聪明截断,折叠就不触发——见 tmp/17-子代理折叠 台账的发现 1)。

两行 dev 日志格式钉死(验收读它们):

agent fold <名字>: <前>→<后> tok; 钉 <n> 路径: <逗号连接>
agent usage <名字>: 基线 … + 可见输出 … + 新增 … = … tok,limit …

硬门槛:

web_search 仅作旁证:密钥齐时可另投一次,看同样出现 agent fold 行。这条旁证的委派对象与上面相反:coder.md 的 tools: 白名单里没有 web_search,只有 researcher 有(doc/26 的排除项不含它)——所以旁证要委派 researcher,剧本要委派 coder。

验收实录(2026-10-17,三拍全过,详见台账 tmp/17-子代理折叠/),三条剧本勘误与一条设计验证:

  1. 窗口怎么选(压测窗的隐藏前提):root 与子代理的用量基线都含工具 schema(vendor 报的 prompt_tokens ~3.4k tok 起步),且两边区间重叠(root ~3.4k 起、researcher ~3.7k 起)。 「子代理必折、root 必不折」要求 limit 高于 root 全场用量——12000 窗(limit 9600)实测安全; 800/2400 会连 root 一起折(root 的摘要同样撞上限 → 整场 error,剧本根本没走到 A2 分支)。
  2. 摘要上限下失败是随机的:小窗档摘要上限 1024 tok(min(limit/2, 1024),root 不折前提下的下限) 对高熵材料(随机十六进制)的验货拒收是随机的——同材料一场一次过、一场 0/3。A2 的错误文本是 失败时的保险,不是让失败必现的开关。另:foldInput phase 2 每档再摘要,第一档过而后续档灭时 折叠链同样报错(首轮 A3 第二折的死法,compact.go 结构对照坐实)。
  3. 自截复发:发现 1 在新剧本下复发过一次(把输出存进 shell 变量只报 first40/last20)—— 「禁止 head/tail/wc/变量截断」的明令在任何窗口档都不能省。
  4. §5「摘要套摘要」首次活体验证:早前结果的 8 位前缀随摘要压缩丢失后,模型自己重跑命令补取 (hex 实跑 4 次),终稿仍拿到两组不同 8 位——「可接受、不补救」的裁定经受住了实测。

11. 所以这解决了什么

子代理多轮工具往返时,进程内消息能在交终稿前自行压短。主线程形状不变:只收终稿,库里不出现子摘要行。估 / 折 / 滤与主 midfold 同链同窗;摘要失败与厂商上下文超长拒收都变成委派工具结果,父 run 保持 complete。