tako 文档 GitHub

17 · 后续计划:本版只做笔记

性质:讨论稿,第四稿,未定案。2026-10-12。前三稿讨论过执行、搜索、子代理折叠、手动停止、笔记。跨度太大。本版只做笔记,并且按 Hermes 内置笔记的形状来做,使以后能接上它的外挂召回和事后检查,而不必改表、改工具名。

施工状态(2026-10-12 回填):已定案并落地。 §7(笔记)全落地、M1–M6 六拍验收全过(台账 tmp/17-笔记/,验收后清理):memory 工具(add/replace/remove)进父池、notes 表(PG 第五张表)、主代理与子代理同一份起手快照、写入四件(工具结果清单+已用行 / 三次记数+第 4 次劝停 / 写入拒隐形字符+存量毒行占位 / workspace 级 advisory xact 锁与插入同事务)、折叠提示词「规矩按原句保留」一句。§7.1 接缝表逐条兑现——检索函数、第二个写入函数、第二个检查模型、向量表均未建。§3–§6 当时均未施工(§3/§4 已于 2026-10-15 落地,见下条补记;§5 已于 2026-10-15 落地,真源改在 doc/22;§6 已于 2026-10-17 落地)。2026-10-15 补:四件之 3 的句式词表裁除、写入检查只留隐形字符一档(见 19v6-90 十七次修订)。

施工状态补记(2026-10-15):§3、§4 已落地(台账 tmp/17-bash执行工具/、tmp/17-手动停止/,验收后清理)。bash 进池(stdout·stderr 各 32 KB 上限 / env 白名单五项;无自动超时,2026-10-15 用户裁——手动停止就是它的逃生口)+ coder.md 落地(doc/23);stop 端点 + 进程内取消注册表 + 看门狗 CAS 0 行 cancel + EndRun stopped 分支 + 页面「已停止」收口全过验收。施工中另抓到并修复一个真卡死:多段命令 fork 的孙进程持有 stdout/stderr 管道写端,kill 只杀 bash,cmd.Run 卡死在等管道 EOF——以 cmd.WaitDelay 收口。§5(web_search)已于 2026-10-15 落地,真源改在 doc/22;§6(子代理折叠)已于 2026-10-17 落地,见 §6 标题下施工状态。

施工状态补记(2026-10-16):§6 的设计正文已按当天两项裁定回填(三步一起做 = 估长度→折→滤思考;厂商「上下文超长」拒收也转错误文本),并补上两条当天核出来的事实:折叠 middleware 必须无状态(同一场 run 里主代理能并行发两次同名委派,eino ToolsNode 默认并行),以及摘要行拿不到 mh 坐标导致的「摘要套摘要」代价。验收剧本从 web_search 换成 bash 长输出。台账 tmp/17-子代理折叠/,2026-10-17 三拍(A1/A2/A3)全部落地,施工状态与实录勘误见 §6 标题下补记。同日又核出第三件事实并写进 §6「实例竞态」段:eino ChatModelAgent 实例体内有 ADK 自己的共享可写字段(msgConf.cancelCtx,上游 #1177,v0.9.21 未修),middleware 无状态管不到它;「主 run 柄恒 nil、子代理柄非 nil」的原因与该竞态的两个触发路径(同场同名并行委派会咬人、跨会话主 run 只报 race)均已记录,处置(per-name 互斥 / 登记 / 给上游供 repro)待拍。同日再回填一轮讨论:per-run 可变维度在 eino 的承载方式对照表(模型走 WrapModel 换、槽位不可写)、tako 换模型挂点已在(AgentLogHandler.WrapModel + agentModelTable)、rebuildGraph 当场重建 msgConf 的窄条件、「强制重建」作为等 #1177 的临时绷带候选(成立依据 + 三条 hack 理由 + 三条件),以及待坐实/待拍清单——均见 §6 新增各段。

点头之前不写 tmp/ 台账、不改代码。本版不加端点、不加帧 kind。

第 3 节到第 6 节是已经讨论过的后话,本版不施工。

1. 本版做什么

本版只在现有的一场 run 上加笔记。

用户说过「deck 放在 output/deck.html,以后改这个文件,不要重建」→ 模型在同一次请求里看见 memory 工具和它的说明 → 调用 add,带上整理句和用户原句 → 程序写入 PostgreSQL → 下一场 run 起手把还有效的行渲染成快照,接进主代理的系统提示,也接进子代理的规格正文后面。

四个 API 的路径和字节不变。memory 的调用走现有的 tool_call / tool_result。

本版不做:执行工具、网络搜索、子代理内部折叠、手动停止、按当轮消息去检索旧笔记、另开一个模型检查要不要记、技能包。这些以后接的时候,笔记的表和工具名保持不动。接法写在第 7.1 节。

1.1 以前排过的五件事(本版不施工)

现在一场委派的链路是:

用户发消息 → 主代理调用 agents/*.md 装出来的工具 → 子代理在自己的进程内消息里调父池里的工具 → 主线程只收到终稿(超过 50 KB 截断)→ 这场 run 占着会话闸,直到它自己结束。

前四件本版不做。第五件就是本版。五件事当时分别接在这些环上。

  1. 执行工具。 子代理能 write_file,没有工具跑 python3 agg.py。40 个日志的聚合做不完。
  2. 网络搜索。 researcher.md 的正文写着没有联网检索。父池里也没有搜索工具。要外部事实时,它只能在终稿里写「未能查证」。
  3. 子代理自己的折叠。 压缩只挂在主代理上。子代理连着搜、连着读,正文堆在它自己的窗口里,终稿还没交出来窗口就满了。50 KB 回传上限管的是主线程看见多少,不管子代理自己装得下多少。
  4. 手动停止。 没有取消端点。搜索或脚本不返回,这场 run 一直占闸,同一会话的下一条消息一直 409。租约到期只会让看门狗停止续约,代码里写明它不主动掐模型流。
  5. 两边读同一份笔记。 子代理看不见主线程的历史和摘要。主代理若没把「不要重建 deck」写进任务文字,子代理就当没有这句。要两边自己都读得到,库里得先有这份笔记。

2. 以后再做的顺序

笔记本版做完之后,若继续,顺序仍是:执行工具 bash(同一改动里给 researcher 写白名单)→ 手动停止 → web_search → 子代理进程内折叠。细节在第 3 节到第 6 节,本版不拆台账。(这条顺序四步都已落地;括注里「同一改动里写白名单」翻了两次——2026-10-12 作废白名单改成纯继承,2026-10-16 再翻成 exclude_tools 排除名单,见 §3.1 头注与 doc/26。)

3. 执行工具(本版不做)

施工状态(2026-10-15):已落地(台账 tmp/17-bash执行工具/)。本节设计与实装一致,除超时刀一处翻案(2026-10-15 用户裁):不设自动超时——手动停止(§4)先落地正是为取消这把刀:跑多久的裁定权在人手里,stop 随时掐、watchdog 判死也掐;自动 60 秒会误杀本来就合法的长命令(构建、装依赖)。32 KB 上限照装(管输出不管时间)。cmd.WaitDelay = 3s 照留:手动停止的 cancel 路径同样撞孙进程持管道的卡死(cmd.Run 卡在等 EOF,deadline 只杀直接子进程救不了,见头注补记)。记录面补角(同日用户裁「Qoder 的标准」):记录制(命令+最终输出落 runlog、执行中不逐块流)在非正常死亡时不缺角——被终止的 bash 把死前已收输出拼进错误文本(「bash 被终止,死前输出:…+原因」),卡死的命令事后可查「做到哪」。流式帧(tool_progress)登记不施工。

池子里增加 bash。参数字段 command。工作目录是 workspace 根,用 bash -c 执行,不走登录 shell。

fileops.go 已经按 command 字段扫描重定向和 cp / mv 这类写路径。工具的 file_effect 必须是 write。登记成 none 或留空时,分类函数直接返回,command 不会被扫,折叠就钉不上这些路径。纯 ls 扫不出写路径,不产生记录。python3 agg.py 在脚本内部 open 出来的文件,扫描看不见,19v6-07 已登记为不追完备。

成功和失败都是工具结果文本,带退出码、stdout、stderr,run 不因此变成 error。

单次必须超时。推荐 60 秒,待拍。 (2026-10-15 翻案:不设自动超时,见本节头注) 没有超时刀,一条 sleep 会占住闸——占住由人收:手动停止随时掐,watchdog 判死也掐。子代理仍然没有总时限。

stdout、stderr 各有字节上限。推荐单路 32 KB,超出截断,并写明「把需要的内容写进文件」。第一拍不另做溢出落盘。

子进程环境只留 PATH、HOME、TMPDIR、LANG、LC_ALL。否则 env 会把模型密钥打进永久 runlog。

符号链接逃出 workspace、以及 bash 仍能访问网络,和 19v6-08 对文件工具的登记相同,这一拍不补。危险命令规则表也不在这一拍。

验收打在跑着的引擎上:投一条消息让它执行 python3 -c "print(424242)",frames 里有 name=bash 的 tool_call 和 tool_result,结果文本含 424242 和退出码 0。

3.1 researcher 的白名单:和 bash 进池同一改动

本节作废(2026-10-12 用户拍),2026-10-16 翻案:护栏真源改在 doc/26,形状是 exclude_tools 排除名单,不是下文这份白名单。 原裁定:不再给 researcher 写 tools: 白名单;researcher 长期保持不写这一行、纯继承父池。bash 进池后 researcher 自动获得命令执行能力,安全面改收在 bash 工具自身的超时 / 截断 / env 白名单。tmp/17-bash执行工具/planning.md D4 的名单步骤随之作废,该拍施工前按新决定重写。下文保留原文备查;第 5 节里「researcher 已经不是继承」的表述一并作废。

翻案的具体内容(2026-10-17 落地):

researcher.md 今天没有 tools 这一行。装载时这一行缺席是空指针,子代理拿到父池的一份拷贝,父池加什么它就有什么。bash 若先单独进池,下一场 run 的调研规格就能跑命令。所以封口和进池写在同一次改动里,不能先发布工具、过几天再改文件。

装载不新写。每场 run 起手,BeforeAgent 先拿走父池快照,这时子代理工具还没挂上,快照里只有 NewWorker 装进池子的那些工具。然后读 agents/*.md。tools 只有三种字节,代码里没有「继承但去掉某一个」(2026-10-17 起有了:第四态 exclude_tools = 继承父池减去列出的名字。四态表只在 doc/26 §3 有一份,这里不复制——同一机制不留两处真源。下面三条是当时的原文,仍逐条成立):

子代理拿到的是父池里的同一个工具对象。路径闸和「错误变成工具结果」不用再包一层。

bash 这一次改动做两件事。第一件,NewWorker 的池子在现有文件工具后面加上 bash,仍然排在拍快照之前,白名单才挑得到它。第二件,researcher.md 写成下面这份名单,里面没有 bash。名单按 worker.go 里的构造顺序写,末尾保留 memory——它在本版(第 7 节)已经先进父池,这里漏掉就等于 researcher 静默丢掉笔记,正是本节要防的事故:

tools:
  - get_time
  - write_file
  - read_text_file
  - read_file
  - edit_file
  - move_file
  - create_directory
  - list_directory
  - directory_tree
  - get_file_info
  - search_files
  - read_media_file
  - memory

只做了第一件、文件还是旧的:下一场 run,researcher 继承到 bash。名单里写了 bash、池子里还没有:这条规格拒载,主代理暂时不能委派调研,run 本身不失败。

这一拍不改 researcher 的正文。正文里「手里有 get_time」和它实际已能读写文件,是改名单之前就有的不一致。搜索那一拍改正文时一起改掉。

agents/coder.md 是后一拍的新文件,不靠继承。规格全文、白名单和验收在 doc/23-coder规格.md(讨论稿,未点头)。那篇把原先那份名单改成 write_file、read_text_file、edit_file、list_directory、search_files、memory、bash。点头前以那篇为准,本段不再单独当施工依据。它必须等 bash 已经在父池里,否则按上面的规则整条拒载。

4. 手动停止(本版不做)

施工状态(2026-10-15):已落地(台账 tmp/17-手动停止/)。本节设计与实装一致;额外落地一处行为变更:看门狗续约 CAS 0 行时 cancel 本场 run(跨副本 stop 的传播路径,同时改掉「租约自然过期不掐流」的现状,用户拍「掐」)。

用户看见搜索或脚本停不下来,要能自己停。

做什么。 新增 POST /api/runs/{runId}/stop。库里把这场 run 从 running 改成 stopped 的更新带条件 status='running'。更新到 1 行,才算这次停止赢得了和正常收尾的竞态。更新到 0 行,说明已经是 complete 或 error,读出当前状态返回,不改写。19v6-90 四修裁掉取消端点,缺的就是这场竞态和半截 draft 的去留,这里把它们定下来。

闸。 stopped 和 complete、error 一样放闸、给 runlive 设 TTL、删 draft。同一会话的下一条消息不再 409。

流要真的断。 只改数据库不够。看门狗在续约失败时只停止续约,不掐模型流(worker.go 的注释写的就是这条)。持有这场 run 的进程要把 Run 的 context 取消掉。子代理的调用已经在 ctx.Done() 上返回。bash 用同一个 context 起进程,取消时杀掉进程。请求若打到没跑这场 run 的副本,那一副本改完库就返回;跑着的副本在下一次续约(dev 默认约 10 秒)看见 stopped 再取消 context。本进程能对上 run 时不等这 10 秒。

历史里留什么。 不写一条假装说完的 assistant 行,和 error 一样。已经完成的 tool_call / tool_result 写入 runlog,agent 列照旧。不写的话,停之前花掉的搜索在刷新之后看不见,下一场模型也不知道做到哪。半截还没返回的工具调用不补一条假结果。用户那一行在开跑时已经落库,保留。

页面收口。 现有 web/src/chat.ts 只认两种结局。terminal 的 status 是 error 时,气泡转错误,不拉 log。否则去 log 里找这条 run 的 assistant 行来替换半截气泡;找不到就也转错误。stopped 不写 assistant 行,不改页面的话,人看见的是失败。停止这一拍改这一处:status 为 stopped 时,保留已经流出来的文字,标成停止,不去找终稿,也不转错误。页面上不加按钮。人要停,这一拍用 curl。

历史形状。 工具行今天是整场结束时从内存里一次写入的,不是边跑边落。stopped 的收尾走同一条写入,只写已经配对的 tool_call / tool_result,不写 assistant。下一条用户消息会和上一条用户消息挨在一起。现有折叠按两家模型都接受连续 user 消息来做,这里不加占位回复。

打到正在跑这场 run 的进程,立刻取消 context。打到别的副本时,跑着的那侧最坏等一个续约间隔(dev 默认 10 秒)才看见 stopped 再取消。这一拍不为了更短再做通知。

这一拍不做什么。 不单独停子代理而让主线程继续。停的是整场 run。主线程还想接着说,是后面的用例。

验收。 投一条会调用 bash、命令是 sleep 120 的消息。随即 POST /api/runs/{runId}/stop。frames 的 terminal 里 status 为 stopped。GET /api/sessions/{sessionId} 的 liveRunId 为空。再投一条普通消息,得到 202,不是 409。log 里有停之前已经返回的工具行,没有这条 run 的 assistant 行。

5. 网络搜索(本版不做)

当前方案在 doc/22(讨论稿,未定案)。下面几段是原先的 Moonshot POST /v1/tools/search 建议,不再作为施工依据。施工顺序不变:仍排在执行工具和手动停止之后。

Kimi 这边要分开三样东西。

建议。 tako 的工具名 web_search,参数 query。执行时调用 Moonshot 的 POST /v1/tools/search(要更全的结果再换 search_pro,待拍)。返回给模型的是标题、链接、摘要,单次有字节上限,推荐 8 KB。上限超出时截断并写明条数,不把原始网页灌进上下文。fetch_url 不在这一拍:抓整页是折叠之前最容易撑满窗口的动作。

没配密钥时,工具结果是明确的错误文本,run 继续。搜索这一次改动同样绑在一起,原因在第 3.1 节:researcher 已经不是继承。只把 web_search 放进父池,它的白名单里没有这个名字,调研规格看不见搜索,也不会因此拒载。同一改动里做三件事:父池加上 web_search;researcher.md 的名单末尾加上 web_search;正文删掉「没有联网检索」,改成可以搜索,查不到就写未能查证并带上错误文本,并写明它能读文件、不能跑命令。coder.md 的白名单不加 web_search。

结果超上限时按整条丢掉后面的条目,不从一条链接的中间切开。

file_effect 登记 none。它不碰 workspace 里的路径。

上两段已过期(2026-10-18 二稿,doc/22 §3):web_search 切到 DeepSeek /v1/tools/search 并改「始终落盘」——结果全文写 .tako/search/<runId>_<n>.md(沿本文件 §3.3 search_history 的 spill 机制),工具返回只有描述段(条数/token/路径),8192 上限与「整条丢」不再适用; file_effect 登记 write(程序命名新文件、一次一写,理由同 search_history)。本节其余 文字作 2026-10-12 拍板时点留档。

验收。 配好密钥后投「用 web_search 查一句今天的公开事实,回答里带一条来源链接」。frames 里有 name=web_search,tool_result 里有 http。没配密钥的那次,结果文本以「错误:」开头,terminal 仍是 complete。

6. 子代理的折叠

施工状态(2026-10-17):已落地(台账 tmp/17-子代理折叠/,A1/A2/A3 三拍验收全过)。A1 = agentFoldHandler 挂进子代理装配点(只折子代理自己的 state,root 的 foldBox 只读不写;与折叠同拍补齐 doc/24 的滤思考 + Usage 账单触发)。A2 = 失败路径:折叠链错误(文本哨兵判定,ADK graph 的 [NodeRunError] 包裹层不吃 Go 错误链)与厂商溢出拒收(IsOverflowError)都转成委派的错误文本结果、父 run 保持 complete,手动停止维持裸上抛。A3 = bash 写路径经 command 扫描钉进子代理摘要端到端。实测(12000 窗 / limit 9600 / 小窗档摘要上限 1024 tok):researcher 连续四折 21881→1683 tok,四行 agent fold 全部 钉 1 路径: markers.txt(第二折起路径继承自上一折摘要里的 file-ops 块);失败路径活体 = 摘要验货拒收 0/3 → 错误文本进主线程 → 父 run complete。三条实录勘误:① root 与子代理的用量基线都含工具 schema(vendor prompt ~3.4k tok 起),压测窗口必须给 root 全场用量留余量;② root 拿到错误文本后重试是合法行为,重试把长输出拉进主线程再撞主线程折叠墙仍是 run error(主线程行为不变);③ 上限 1024 下验货拒收随机(同材料一场一次过一场 0/3),A2 是失败兜底不是失败必现开关。 更正指向(2026-10-23):本节「实例竞态」段中「子代理路径下每个委派派生各自非 nil 的取消柄」的推导已过期——对着 eino v0.9.21 逐行复核:deriveCheckpointAwareSubAgentCancelContext 在父作用域为 nil 时返回 nil(tako 不用 adk.WithCancel、ctx 不挂 eino 作用域),子代理路径与主 run 同为 nil 写 nil。现行结论、处置与施工真源在 doc/25 §6/§7(壳化装配 2026-10-23 已落地:子代理实例每次委派新建,本段 race 的触发路径一消除;触发路径二——主 run 实例跨会话共享——仍登记)。本节该段及以下时间线推演保留作历史诊断,不作施工依据。

19v6-10 第 10 节当时不压子代理,理由是它的状态跑完即弃、回传有上限、摘要没有下一个读者,主线程把这次委派当成一次普通工具往返,随主 run 一起折叠。

多轮搜索把这个理由里的「没有读者」打破了。读者是子代理自己的下一次模型调用。它在交终稿之前就要把前几轮搜索结果挤出去,否则终稿出不来,主线程的折叠没有东西可折。

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

登记的代价(不补救)。 摘要行因此拿不到 mh 坐标——RunID / Seq 是落库时才发的身份——它只以消息形状留在子代理进程里。于是第二次折叠时,上一次的摘要在它眼里就是一条普通历史消息,会被连同新料再摘一次:摘要套摘要。主 run 没有这个问题,因为它的摘要落在 seq=0、下一次折叠从库里读回、认得出那是摘要。子代理跑完即弃,多套一层只影响终稿的措辞密度,不值得为它单开一条落库路径。

挂在谁身上。 折叠挂在 ADK 的 middleware 上(子代理装配处今天已经有一个 callerStampMiddleware,新挂件追加进同一个 Handlers 列表)。这个 middleware 实例在一次装配里只有一份,而同一场 run 里,主代理可以在一条消息里并行发两次同名委派——eino 的 ToolsNode 默认并行执行同一条 assistant 消息里的多个 tool_call,tako 从没把它改成串行——两个 goroutine 于是同时进同一个实例。所以它不许在字段里存任何一次调用专属的东西(计数器、上一份摘要、上一次估出的长度);一次调用的状态只走它自己的参数和 ADK 交给它的那份 state。跨 run、跨 session 不共享实例(子代理是每场 run 起手装配的),那不是这条禁令的依据。

实例竞态(eino 侧,2026-10-16 核实)。 上面那句「一次调用的状态只走它自己的参数和 ADK 交给它的那份 state」就 state 而言成立,但不充分:ChatModelAgent 实例体内还有一层 ADK 自己的共享可写字段,middleware 无状态管不到它。以下两段把这件事讲透(事实均已对着 eino v0.9.21 源码逐行核实)。

舞台与角色。 期待的多租户用法(上游 issue #1177 的 Production scenario 原文):进程启动时建一个 ChatModelAgent 实例——tako 里就是 NewWorker 造出的主代理实例(worker.go:207)。之后每个用户的每条消息,都是往这同一个实例发一次 Run(ctx, ...):甲的请求开 run A(goroutine A),乙的请求开 run B(goroutine B)。会话闸只保证「甲自己同时最多一场」,甲和乙之间没有任何互斥——这是合法用法,上游也认为这是该支持的。

两个道具的真身:

每个 goroutine 进闭包后做的三件事(eino v0.9.21 adk/chatmodel.go:1145-1148 源码真身):

cancelCtx := mp.cancelCtx              // ① 取本场自己的柄
msgConf.cancelCtx = cancelCtx          // ② 写进【共享的】msgConf
msgConf.modelWrapperConf.cancelContext = cancelCtx
g, err := newReact(ctx, msgConf)       // ③ 读 msgConf,建本场的图

注意②③的配合:先写后读。单跑时这就是「把本场的柄装进本场的图」,完全正确——顺序复用的对照实验(A 跑完再跑 B)race detector 是干净的。

出事的时间线——两个 goroutine 各自做①②③,调度随便穿插,最坏的一种:

时刻 goroutine A(甲的 run) goroutine B(乙的 run) msgConf.cancelCtx 的值
t1 ①取到甲的柄 —
t2 ②写入甲的柄 甲的柄
t3 ①取到乙的柄 甲的柄
t4 ②写入乙的柄 乙的柄
t5 ③读 msgConf → 把乙的柄装进甲的图 乙的柄
t6 ③读 msgConf → 把甲的柄装进乙的图 甲的柄

t5 是病灶:A 读的瞬间,字段里躺的是 B 刚写的值。两个柄互换装机完毕。

后果分两个版本:

端到端链路,病灶标在哪一环:

甲点停止 → POST /runs/A/stop → CAS 翻库(只翻A行)
  → runCancels 按 runId 取 A 的 CancelFunc → cancel 甲的柄
    → 【病灶环】甲的图从共享 msgConf 读到的柄
      → 同名并行委派:读到乙的柄 → 甲停不下,乙被误杀
      → 跨会话主 run:读到 nil → 无事发生,race detector 报警

病灶精确位置:「cancel 甲的柄」到「甲的图真正响应停止」之间,隔着一个被并发写坏的共享读源。库、闸、context 传递每一环都按 run 隔离,全对;错的是 eino 实例体内这一份没上锁的共享配置。

上游实锤:issue #1177(2026-08-05)与本节逐字同发现——共享 reactConfig.cancelCtx 在并发 Run 复用同一实例时 data race;#775(并发 Compile race)已修,#1177 仍开着,v0.9.21 本地亲读源码确认未修(issue 记载 v0.10 alpha 亦未修);#1170(callback handler slice race)也开着。官方示例(eino-examples/adk)全是单会话控制台脚本,没有任何多租户共享实例的演示;框架对 run 内并发(同名工具并发调用)是显式支持的,run 间并发没有防护。eino 处于「想让一个实例能被多租户并发复用、但还没走到」的灰色地带——两个极都不能假设。修法提案(#1177 里的 repro + 每调用浅拷贝 msgConf + 验证清单)与本节推的「msgConf 每调用一份」一致;其 repro 测试可直接借用为本拍验收剧本的底座(两个会话并发 + stop 其一)。

为什么主 run 的柄恒 nil、子代理的柄非 nil。 这个分界不是「主/子」身份决定的,是「谁给可选参数、ctx 里有没有现成作用域」决定的。

主路径:Run 入口调用 resolveRunCancelContext(chatmodel.go:484-507)——o.cancelCtx(Run 的可选参数)为空,且主 run 的 ctx 里没人塞过 eino 作用域(tako 的 ctx 是 worker 自造的纯 Go context)→ 返回 nil。可以没有的原因:eino 图执行器每个节点边界都查 ctx.Done(),「整 run 掐死」靠 Go context 就够——tako 的手动停止正是这么实现的(runCancels 存的就是 Go CancelFunc)。cancelContext 这层是选配的高级能力:安全点停止(模型调用完再收)、业务中断(HITL 审批)、checkpoint/断点续跑、abort-only 递归中止。tako 全都没用,字段就是 nil。

子路径:非 nil 不是选配,是 eino 每次调用自己造的。typedAgentTool.InvokableRun 每次走 extractAndDeriveAgentToolCancelCtx(agent_tool.go:325-330)→ 每场委派派生一个全新的子作用域。原因:子代理是寄居在父 run 里的执行体,eino 必须握着一个每场委派独立的取消作用域才能管理它的生命周期——父 run 被 stop 时信号怎么传进子代理的图、按安全点收尸还是立即打断,都挂在这上面。

非 nil 的到底是什么:eino 自造的「取消作用域」对象(cancelContext,cancel.go:355-400)——不是 Go context,是一组信号通道 + 父子链 + 图中断挂钩 + 安全点配置:cancelChan(普通停止,下一个安全点收)、immediateChan(立即打断图)、doneChan、recursiveChan(父死子死)、parent 指针、root 标记,外加 setGraphInterruptFunc 与 CancelAfterChatModel/CancelAfterToolCalls 安全点配置。派生时还会起两个传播 goroutine 盯着父作用域的两类信号(源码注释警告:结束不调 markDone() 这两个 goroutine 会泄漏)。所以每个委派的 cancelContext 是一场调用一份的私有物,还带着自己的看护 goroutine。

收拢:主路径 nil = 图里没装 eino 取消层,停止全靠 Go ctx(跨 run 天然隔离)→ 竞态只是「写 nil 读 nil」的内存模型违规,不咬人;子路径非 nil 且每场委派各一份 = 图里装的是有内容的私有柄,被交错后 A 的图真可能拿着 B 的柄 → stop 串线,咬人。共享 msgConf 的问题恰在于:它把本该各归各的私人物品放在公共黑板上写。

对本拍的处置(2026-10-16 登记,待拍)。 在 eino 修好(#1177 合入后升级)之前,「同一实例别被两个 goroutine 同时进」是唯一可靠的安全绳:同名并行委派用 per-name 互斥(异名并行不受影响);跨会话主 run 的 nil 竞态可只登记不处理(功能无害,eino 升级时跟进);或给上游供 repro/PR 走治根路;若本拍排期早于 eino 修版、又不想带「同名并行委派 + stop 串线」上线,还有第四条过渡路——强制重建绷带(见下)。

per-run 可变的维度与 eino 的承载方式(2026-10-16 讨论回填)。 once/frozen 架构对「跨 run 变化」只友好两种回答:ctx 驱动的间接层或per-run 装配;凡 per-run 要变的维度都该走这两条路,写字段是违例。按维度对表(eino v0.9.21,行号均已核实):

维度 per-run 可变? eino 的承载
模型(每次调用生效哪个) 产品可选 WrapModel 包装链(handler.go:254,wrappers.go:1049/1137 每调用执行);ModelFailoverConfig;或槽位里放「路由器模型」按 ctx 分发
消息/指令 tako 需要 BeforeModelRewriteState(handler.go:171)改写 state;或构造时自定义 GenModelInput
工具清单 可能 BeforeAgent 改 ChatModelAgentContext 副本(handler.go:90-127),toolUpdated 走 WithToolList + 每 run 重采 toolInfos
工具拓扑(空→非空) — 触发 rebuildGraph,当场重建 run func = 全新 msgConf(见下两段)
cancelCtx 必须 无通道 → 写在共享 msgConf 上 = #1177
maxIterations / 模型槽位 / agentName — 不在 ChatModelAgentContext 可改字段内,只有新实例

cancelCtx 是唯一「必须 per-run 变」却没有间接层的维度——这就是 #1177 的全部实质。

模型:可以「换」,挂点已在 tako(立项为后话)。 「每个 session 选不同模型」不需要动实例:msgConf.model 槽位 once 冻死、永远不该写;每次模型调用前的包装链给 middleware 留了 WrapModel 钩子,在包装里读 ctx 决定委托给哪个真客户端即可,槽位里那个只是默认值。tako 侧两个前提件已有:AgentLogHandler.WrapModel(agentlog.go:65)已在主代理链上,其注释明写此位点用途为「重试 / 换模型 / 改造输出流」;agentModelTable(agents.go:180-225)已按 run 携带「agent 名 → 模型身份」表(主代理为空串条目,BeforeAgent 写入)。主代理 per-session 模型的最小落地形状:Run 起手按 session 偏好定 rootRef 填表 → 一个 WrapModel middleware 查表委托。子代理规格的 per-spec 模型(frontmatter model: 字段)今天已走「每场 run 装配各自实例」实现。红线:换模型走包装,写字段是 #1177 同款坑。

拦截点全景与 rebuildGraph(钩子能不能「不用 default msgConf」)。 middleware 接口 TypedChatModelAgentMiddleware(handler.go:115 起)的 per-call 钩子:BeforeAgent(每 run 前,可改 Instruction/Tools/ReturnDirectly/ToolSearchTool 的副本)、BeforeModelRewriteState(每次模型调用前改写 state)、WrapModel、WrapToolCall、AfterAgent;另有构造期的 GenModelInput。「不用 default msgConf」的最强形态存在:rebuildGraph=true 时 getRunFunc 当场 buildReActRunFunc(ctx, runtimeBC)(chatmodel.go:1426-1443)——新造 msgConf,连嵌套 modelWrapperConf 都是新的。但触发条件是窄启发式(chatmodel.go:837):仅「工具 0→非 0」或「returnDirectly 0→非 0」为真;改指令、增删工具大多不重建,复用缓存闭包 + 每 run 新 toolInfos。

强制重建:等 #1177 的临时绷带(候选,待拍)。 机制上成立:重建路径上 msgConf 每调用新分配、共享那份无人写,#1177 的写字竞态对两条触发路径(同场同名委派、跨会话主 run)都消失;代价≈一次结构体分配(重活两路本来每跑都付:genToolInfos、newReact、chain.Compile)。逼法:middleware 在 BeforeAgent 往 runCtx.ReturnDirectly 塞一项,使 rebuildGraph 恒真(前提:该代理 once 的 returnDirectly 为空——主代理装配处未配此字段,worker.go:209-214,待坐实)。认定为 hack 而非修法的三条理由:①扳机是框架内部启发式、非公共 API,且 ReturnDirectly 有真实行为含义(该工具被调用即直接返回),塞假名是语义污染;②升级脆性最要命——eino 将来若加「无实质变化不重建」的短路,并发安全被静默拆除、race 悄悄回归,比不防更糟(虚假安全感);③只盖住 msgConf 一层,middleware 实例共享的纪律(本节前文)不因它改变。若采纳须带三条件:-race 实测坐实(#1177 的 repro 稍改即是);注释写明依赖 eino v0.9.21 chatmodel.go:837 的行为、eino 每次升级必重验;台账标明 #1177 合入即拆。

待坐实 / 待拍清单(2026-10-16)。 ① 主代理与各子代理实例 once 的 returnDirectly 是否均为空(决定绷带扳手对全部代理可用,还是只对部分可用);② 本拍处置四选如何拍:per-name 互斥 / per-run 装配 / 给上游供 repro / 强制重建绷带(可组合);③ 主代理 WrapModel 按 agentModelTable 换模型,立项为后话;④ 上一轮文档审查的 4 处过期引用(§3.1 说 doc/23 未点头、§2 残留 researcher 白名单句、19v6-08 网络登记错挂、§5 说 doc/22 未定案)与台账同步(实例竞态登记为已知风险、验收剧本借 #1177 repro)均待点头。

怎么压。 用主 run 同一条摘要链,也用同一把 -compact-window,不另设旗标。「同一条链」在 doc/24 落地之后是三件事,顺序固定:先按账单估长度,再决定折不折,放行前把上一枪的思考滤掉。

顺序之外的部分不变:子代理工具调用里的写路径,用现有的 extractFileOps 钉在它自己的摘要末尾。摘要模型沿用主 run 的那个,不因为子代理换了 model 就再开一家。

不做的后果。 researcher 搜四五次,窗口满,委派以上下文错误结束。用户看到的是失败,不是报告。

验收。 把折叠窗口调小,让子代理连着产生两份长结果。第二次模型调用之前,子代理侧的输入里前一次的长结果已经被摘要替换;主线程的 run_model_messages 不出现子代理的摘要行;终稿仍回到主线程,且两份结果各自的关键信息都还在终稿里。

「子代理侧的输入」今天没有任何观测面(主 run 有 midfold 那两行日志,子代理一行都没有),所以这一拍同时加两行 dev 日志,格式钉死:agent fold <名字>: <前>→<后> tok; 钉 <n> 路径: <逗号连接> 与 agent usage <名字>: 基线 … + 可见输出 … + 新增 … = … tok,limit …。验收读的就是它们。

长结果用 bash 造(python3 -c 'import secrets;print(secrets.token_hex(15000))',约 30000 字符高熵 ≈ 8–9k tok),不用 web_search:搜索要外部厂商,cf2bde3 的验收窗口里 searchfree 就宕过一次(doc/22 第 9 节的预案),真源里的验收剧本得能自己复现。web_search 降级为旁证——配好密钥时另投一次,看同样出现 agent fold 行。

这一拍不改 19v6-10 里主 run 的折叠,也不改 doc/24 的公式、旗标与提示词。翻掉的是两句边界:19v6-10 的「子代理内部不压」,和 doc/24 第 8 节的「不给子代理新挂折叠」。

7. 笔记,以及两边怎么共享

持久共享要先有记忆层。这一层做的时候就把读路径接到两边,不另立「共享」项目。

库。 PostgreSQL 一张表,按 workspace 绝对路径分开。现在没有用户表,不加 user_id。一行含 kind(agent 或 user)、content、quote、source_run_id、source_seq、superseded_by。替代是新插一行,旧行的 content 不改,只填指针。未替代的 content 合计:agent 2200 字,user 1375 字,超出拒绝新增。quote 超过 200 字拒绝,不截断。

模型怎么会去调用。 程序不读用户那句话,也不判断它是不是规矩。没有另一个模型事后检查「要不要记」。模型只会使用这次请求里列出来的工具。它看不看 memory,取决于这次请求里有没有这个工具,以及说明里写了什么时候该用。

用户消息是:

deck 放在 output/deck.html,以后改这个文件,不要重建。

这一轮发给模型的请求里,除了这句话,还有两样东西。

第一样在工具表里,和其他工具并列。memory 的说明固定写成:

把以后每一场 run 都要遵守的事实写进笔记。笔记会进以后每一场的系统提示,所以只写短句。
action=add 是新的一条,必须带 quote,quote 是用户原句。
action=replace 是用户改了口,用快照里那条 content 全文定位旧行,并带上新的 quote。
不写:任务进度、刚做完的步骤、从文件里能再读到的内容。

没有这段说明,模型只看见一个名字,不知道该在用户说完规矩的这一轮使用它。

第二样在系统提示末尾。第一次是:

笔记:(空)

模型把用户消息、这段说明和这份空快照放在同一次请求里看,自己决定这一轮要不要调用。它调用时,参数是:

{"action":"add","kind":"agent","content":"deck 在 output/deck.html,以后只改这个文件,不要新建。","quote":"deck 放在 output/deck.html,以后改这个文件,不要重建。"}

content 是它整理后的句子,措辞可以和用户不一样。quote 是它从用户消息里抄下来的原句。程序看到 quote 非空且不超过 200 字,才插入一行,并自己填上这场 run 的 id 和这条消息在 runlog 里的位置。它也可以先干活、稍后再调用。没调用,表里没有新行。

同一会话里如果它忘了调用,折叠提示词仍要求把规矩的原句留在摘要里,这场会话的后几轮还可能看见。新开的会话没有这场摘要,规矩就丢了。

模型若漏了 quote:

{"action":"add","kind":"agent","content":"deck 在 output/deck.html,以后只改这个文件,不要新建。"}

工具结果是错误文本,表里没有新行。它可以再调一次,把原句补上。add 和 replace 一律要非空 quote,因为这次调用的参数里没有别的字段能表示「这句要不要留原话」。remove 不带 quote。搜索、折叠、委派都不检查 quote。

过了一周,用户改口,消息是「deck 可以重建了」。这次请求的系统提示末尾已经不是空的,而是上次写下的那条:

笔记(本场开始时读取,本场中途的写入要到下一场才进入这里):
- deck 在 output/deck.html,以后只改这个文件,不要新建。
  原话:「deck 放在 output/deck.html,以后改这个文件,不要重建。」

模型看见旧的 content 还在,说明里又写了改口用 replace,才会发出:

{"action":"replace","kind":"agent","content":"deck 可以重建。","quote":"deck 可以重建了。","old_content":"deck 在 output/deck.html,以后只改这个文件,不要新建。"}

old_content 必须和快照里那条 content 全文一致。程序新插一行,旧行的 content 和 quote 保持「不要重建」那句不动,只把 superseded_by 指向新行。快照只读新行。快照里没有旧句时,它不知道该定位哪一行。旧原话留在库里,两周后用户问「我说过不要重建吗」,对质打开的是旧行的 quote 和 runlog 位置,不是后来改写过的 content。

工具。 memory,action 为 add / replace / remove。replace 和 remove 用参数 old_content 定位,它必须等于未替代行的 content 全文。定位不到或多行命中就返回错误文本。本版只把 memory 放进父池。researcher.md 没有 tools 行,会继承到它。以后若给它写白名单,名单里要保留 memory,否则它失去笔记——这个「以后」已由 doc/26 兑现(2026-10-16):researcher 走的是 exclude_tools 排除路(2026-10-18 翻案后排除清单只剩 bash),memory 不在排除项里,仍在有效名单中,并由 agents_test.go 的 TestShippedAgentSpecToolGuards 逐名钉住。coder.md 本版不建。

本版必须一起做的四件,否则形状接不上 Hermes。

  1. 成功和因超上限被拒绝的工具结果,都带回这个 workspace 里还有效的条目,以及已用字数,例如 agent 40/2200。快照在本场开始时定死,同一场里的下一次 replace 只能拿工具结果里的 content 全文当 old_content。
  2. 同一场 run 里,超上限、定位失败、原话为空这类写入失败记到 3 次。第 4 次的结果写明:停止再调 memory,先回复用户。否则笔记满了的时候,模型会一直重试,用户等不到回复。
  3. content 和 quote 在写入时检查:含有零宽、bidi 控制符这类人眼不可见的字符(17 码点,清单 = notes.go 的 noteInvisibleRunes)就拒绝,不插入。已经在库里的行,渲染快照时换成占位文字,写明用 remove 删掉;库里的原文留着。不做的话,一句夹带不可见字符的话,从下一场起就排在系统提示里,人审时却看不见那些字符。句式词表 2026-10-15 裁除:句式拦不住语义——纯中文写法(「禁用 system prompt」)一条不命中,把锚词换成中文、写全角都能绕,清单列不尽;隐形字符清单有限、能枚举尽、与语言无关,拦的是「能不能藏」不是「说了什么」。裁定与实测见 19v6-90 十七次修订。
  4. 检查剩余字数和插入新行在同一笔数据库事务里,锁住这个 workspace 的笔记。笔记不按会话分。两个会话同时各写一笔,会同时以为没超上限。一个会话里「同时只有一场 run」管不到这件事。

快照只放还有效的行,不放按当轮消息检索出来的文字。 以后若要做 Hermes 那种「这一轮才想起的内容」,那段文字接在当轮用户消息末尾,并标明不是新的用户输入,不进系统提示。本版没有这段检索,函数也不留。留一个永远返回空串的函数,没有调用方。

写入只走一个函数。 工具是它现在的调用方。以后的事后检查若要写笔记,调用同一个函数,从而经过同一道字数上限、原话检查和隐形字符检查。本版不建第二个写入入口,也不建第二张表。

快照。 每场 run 起手读一次未替代的行,渲染成一段文字。根代理的 Instruction 在 NewWorker 时已经写成 SystemPrompt(),不能靠改那个启动字符串。快照和这句拼成这一场的系统提示,本场后续调用都用这份,工具写库不回写它。子代理装配时,规格正文后面接同一份快照。

不接的后果:根代理记得不要重建,coder 的正文里没有这句,它仍会新建文件。

同一场里子代理写进库的新行,主代理的这份快照看不见,主代理也看不见子代理的那次工具调用。主代理这一场只看得到终稿。新行从下一场 run 起进入两边的快照。这够用在「下一会话还记得」。若要求同一场后半段就看见,系统提示的字节会在一场里变掉。

不共享的东西。 不把主线程的模型历史复制给子代理。隔离就是为了让那 40 份日志和搜索原文留在子代理里。

折叠提示词加一句:被折掉的原文里,用户明确说过的规矩按原句留在摘要里。不从摘要自动往笔记表插行。

验收。 一场 run 里用 memory 记下 deck 的路径和原话。新会话问 deck 在哪,回复含路径,且没有 write_file 去新建。deck 那句不写进交给 researcher 的任务文字,只靠规格正文后接的快照:装载时打出的子代理 system 日志行(M5 引入的 dev 观测面)里能读到这句。库里 replace 之后旧行 content 不变。

行数被上限住,全部进快照。本版不建检索口、向量表、T-Mem,也不建外挂提供者。

7.1 怎样才算接得上以后的 Hermes

以后要接的 本版留出的缝 本版不建的
当轮才想起的旧笔记,接在用户消息末尾 系统提示里只有起手快照,没有按这句话检索出来的文字 检索函数、向量表
事后另一个模型检查要不要记 写入只有一个函数,字数上限和隐形字符检查在函数里面 第二个模型、第二张表
压缩前把即将丢掉的消息交出去提取 摘要提示词里多一句「规矩按原句留下」。提取若要入库,仍走那个写入函数 压缩前再调一次模型
多用户 表按 workspace 分。以后要按人分,加列,不换表 user_id
coder 这类新规格 工具在父池里。新规格的白名单要显式写上 memory 才看得见 coder.md

8. 本版不再问的数

笔记字数上限用 agent 2200、user 1375。同一场写入失败记到 3 次,第 4 次让模型停止再调 memory。这两处用 Hermes 内置笔记的默认,本版不再单独立项。

执行、搜索、停止的数字仍在第 3 节到第 5 节,本版不施工,也不再问。

9. 所以这解决了什么

本版之后,新会话的系统提示里能读到上次写下的原话和路径。主代理和子代理读的是同一份快照。表和工具名按 Hermes 内置笔记的用法留着:以后要加当轮检索或事后检查,调用方增加,存储不用换。执行、搜索、子代理折叠、手动停止仍按第 3 节到第 6 节,不在本版。

10. 点头之后才做的事

台账的第一拍是跑着的引擎上调用 memory。验收:投一条消息要求记下 deck 那句原话,frames 里有 name=memory 的 tool_result,文本含 agent 的已用字数;新开会话再问 deck 在哪,回复含 output/deck.html。四个 API 的路径不变。一拍做完停下。