tako 文档 GitHub

09 · 设计了解(Eino 机制笔记)

文件性质与修改权限(先读):本文件是开发者对本项目设计、以及自己不甚了解的知识点的记录, 分两类,权限不同——

性质:机制笔记。新系列第九篇,从旧《设计了解》改写:WrapInvokableToolCall 的时机、 endpoint 是什么、adkrun.Run 的两个标识(checkpointID 与 root)都保留并按当前代码刷新锚点, 另加两节定案后新引入、也最容易被误读的机制:BeforeAgent 注入工具、session 值随 checkpoint 落盘。 关联:《06》§3.4 是从守卫视角看同一批钩子,本篇是"读 Eino 源码时的随手笔记"。 末五节(§6–§10)是通用 Go 与 Eino 接入笔记:编译期断言提前发现接口漏实现、map 无序靠 order 保障顺序、 接口切片字面量把 middleware 拼进 handlers 链、Handlers/Middleware/handler 三个名字与钩子串行执行、 //go:embed 把厂商目录编译进二进制。 §11 补记一个被命名误导的契约:interrupt 信号树里 IsRootCause=true 的是叶子(真因), 祖先走 Parent 链;adk 的字段文档与实现表述互斥,adkrun 的过滤是防御性写法(当前为 no-op)。 §12 拆开 resume 的中段:ResumeWithParams 只做「恢复现场 + 立公告板」,重入时 AppendAddressSegment 按地址认领数据挂到 ctx,wrapper 重跑时自己读走——两端靠地址相遇,无函数调用相连。 版本:eino v0.9.21;行号以该版本为准。

1. WrapInvokableToolCall:决策之后、执行之前的干预点

internal/guard/middleware.go 里的三个 handler 都实现了 WrapInvokableToolCall。 Eino 的注释原文只说了 "called at request time when the tool is about to be executed" (adk/handler.go:193)——这句话其实已经暗示了时机。

WrapInvokableToolCall 的触发时机正是:LLM 决策完成之后、工具真正被执行之前。

也就是说,模型吐出 tool call 之后,等 tool 真跑起来再拦就晚了; 理想的拦截点只有一个,就是这里。

2. "endpoint" 是什么

InvokableToolCallEndpoint 的定义(adk/handler.go:34)只有一行:

type InvokableToolCallEndpoint func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error)

它就是真正干活的那个工具执行函数本身(handler.go:32 注释原文: "the function signature for invoking a tool synchronously")。 框架把实际的 tool invokable 抽象成了这个统一签名——不用关心工具是 bash 还是写文件, 调用方式永远是「传 JSON args,返回 string 结果」。

于是 WrapInvokableToolCall 的职责就很好理解了:框架把 endpoint(真工具)交给你, 你必须返回一个新的函数。这个新函数变成了实际被调用的入口,而 endpoint 在你手里:

2.1 硬拒时 Agent 会中断吗?

不会。要分两种情况看:

硬拒(return string, nil):agent 的 run 循环继续走。 这条 string 作为这个 tool call 的"结果"回填进消息历史,轮次正常往下走—— 模型下一轮看到 "permission denied,不要重试相同路径",通常就会改道或收手。 准确的说法是:当前这次工具调用从未发生,但整个 agent 思考循环没有中断。 这不是偷懒,是刻意的沟通策略:如果抛 error,模型只能看到 "tool execution failed", 不知道为什么错,容易傻乎乎重试;返回一句解释性的 string,模型知道"是人拒绝的、因为什么、别重试"。

interrupt(ask 分支的 compose.StatefulInterrupt):这个才是真正的中断—— 整个 run 被挂起,进程返回、状态存 checkpoint,等人审批后 resume。 恢复时走 ownInterrupt 的 stored 分支:拒绝时也是返回 string 而非 error,同样回填给模型。

整个 guard 的本质就是三个字:包、查、调——包住 endpoint,每次调用先查规则/中断状态,决策对了才碰 endpoint。 同一个 endpoint 类型也解释了为什么审批恢复后能"原样重放":savedCall 里存的就是 args, resume 时拿 stored.Args 重新喂给同一个 endpoint 即可。

2.2 为什么叫 "endpoint"

  1. go-kit 的继承。Go 微服务圈(CloudWeGo 与 go-kit 一脉都受影响)有个经典模式: type Endpoint func(ctx, req) (resp, error)——把任何服务调用统一抽象成一个"单一函数端点", middleware 在它外面包洋葱层。eino 的 InvokableToolCallEndpoint func(ctx, args, opts...) (string, error) 与 go-kit 的 Endpoint 形状几乎一致,只是 request/response 换成了 JSON string。
  2. "链的终点"语义。Middleware 一层套一层,责任链总得有个终点。 任何一层执行 endpoint(ctx, args, ...) 就是"把控制权沿链传到最深处,让真工具干活"。 叫它 handler 也行,但 handler 容易混淆(外面那层也是某种 handler), endpoint 强调的是链的端点:这是最后一站,穿过它就出了框架、进了实现。
  3. 对应"调用点"而非"实现"。它不是工具本身(tool.InvokableTool 有自己的 schema、definition), 而是工具在框架视角下的统一调用面——就像 API endpoint 是"你发请求打到的地方", 不关心后面代码怎么写。框架只认这个签名,所以才能做到:无论模型吐什么工具, 都能被同一种方式包裹和重放。

简单说:endpoint = 中间件洋葱的最内层,名字借自 go-kit / HTTP 世界,强调"统一签名的最终执行点"。

3. BeforeAgent:往本轮工具表里加工具的钩子

任务看板不是靠 WrapInvokableToolCall 拦已有的工具,而是先把自己的四个工具塞进去—— 这件事发生在 BeforeAgent:

// 签名(adk/handler.go:142)
BeforeAgent(ctx context.Context, runCtx *ChatModelAgentContext) (context.Context, *ChatModelAgentContext, error)

4. session 值为什么"免费"随 checkpoint 落盘

任务看板的镜像(adk.AddSessionValue(taskboard.SessionKey, snapshot))能在 interrupt 时跟着落盘, 靠的是 eino 对 session 的序列化声明,不是我们写了额外代码:

一句话:"落盘不依赖模型自觉"里的落盘,是 eino 的 session 序列化白送的;我们只负责把快照类型注册好。

5. adkrun.Run 的两个标识:checkpointID 与 root

驱动层的入口是 internal/adkrun/turn.go:77:

func Run(ctx context.Context, runner *adk.Runner, agent adk.Agent, checkpointID string,
    input []*schema.Message, sink Sink, ask Ask) ([]*schema.Message, error)

参数里有两个"标识",管的是两件互不相干的事:

它们唯一的交点在时间上:resume 之后 Run 的 for 循环会再调一次 consume(iter, root, sink)(turn.go:86),也就是恢复后新产生的事件仍然按同一个 root 过滤、经 sink 呈现。由同一个参数承载、同一次 Run 内不变,这一点天然成立。

5.1 checkpointID:CheckPointStore 里的键,是"暂停 / 恢复"的 join key

Run 里它只出现两次(turn.go:80-82、:109):

if checkpointID != "" {
    opts = append(opts, adk.WithCheckPointID(checkpointID)) // 暂停时按这个键存快照
}
...
iter, err = runner.ResumeWithParams(ctx, checkpointID, &adk.ResumeParams{Targets: targets}) // 按同一个键取回

两个阶段在 eino 里各自做了什么(eino v0.9.21):

  1. 暂停:runner.Run(..., adk.WithCheckPointID(id)) 把 id 放进 options.checkPointID; 守卫中间件里 compose.StatefulInterrupt(guard/middleware.go 的 toolGuard / filesystem 两处; 定义在 compose/interrupt.go:130)让图停下时,typedRunnerHandleIterImpl 把整个 run 状态 (runContext:session、ReAct 循环进度、InterruptID2Address / InterruptID2State、 EnableStreaming,外加 interrupt 载荷)gob 序列化后写进 store[id]——就是 adk/runner.go:330-331 那句 if checkPointID != nil { runnerSaveCheckPointImpl(...) }。 事件流最后以 Action.Interrupted 收尾。
  2. 恢复:ResumeWithParams → runnerLoadCheckPointImpl(adk/interrupt.go:223) 读 store.Get(ctx, checkpointID);读不到就是那行 checkpoint[%s] not exist (adk/interrupt.go:230)。读回来后 core.PopulateInterruptState(:243)把中断点状态 还原进 ctx,core.BatchResumeWithData(adk/runner.go:241)把 Targets 注进 ctx, 然后从暂停点继续跑。

internal/adkrun/turn.go:16 的 Store(编译期断言 var _ adk.CheckPointStore 在 :26-27) 就是这个 store 的内存实现,注释原文"进程退出就没了,够演 interrupt"。

所以:checkpointID 是一次"被挂起的执行"在 store 里的句柄,是 Run 与 ResumeWithParams 之间唯一的连接键。没有它,人做完审批也没有东西可以"接着跑"。

顺带解释循环的顺序:history = append(history, msgs...)(turn.go:87)发生在检查 interrupts 之前,所以中断前已经产生的事件(比如那次要求调用工具的助手消息)不会丢—— 最终 history 是跨越 interrupt / resume 边界的完整一轮产出。

5.2 root:主 agent 的名字,决定"谁说的话进历史"

root := agent.Name(ctx)(turn.go:78),值来自 config.AgentName():全仓库单点定义 "yk-tako" (internal/config/model.go:28 的 const agentName,由 :31 的 AgentName() 暴露), 唯一入口的 ChatModelAgentConfig.Name 写它。

root 只有两个用途:

  1. 筛历史(turn.go:143):if msg != nil && event.AgentName == root { ... }—— 只有 root 的消息进返回给调用方的 history;
  2. 加前缀(cmd/yktako/sink.go:22-25 的 newREPLSink):非 root 的 agent 事件带 [子代理名] 前缀,终端里分得清谁在说话——T1 前这段逻辑在 adkrun,随打印一起搬走。

为什么必须筛:runner 会 emit 整个 agent 层级的事件——DeepAgent 的子代理、AgentTool 包住的内层 agent 都有自己的 ReAct 循环和 tool 消息。而 history 是下一轮喂回 root agent 的输入, 必须是结构合法的对话序列(user + root 的 assistant(带 tool calls)/ tool 回执); 子代理内部的 tool 消息混进来,对 root 来说就是"没有对应 tool call 的 ToolMessage",接口直接 400。

这个参数原来是要脚本手写的(旧签名 Run(ctx, runner, checkpointID, root string, ...))。 改掉它是因为手写的那份与 ChatModelAgentConfig.Name 重复:对不上时不报错也不 panic, 只是 history 悄悄变空、子代理前缀不打了,属于最难查的那种错(turn.go:64-70 记了这笔账)。 现在 root 从"将要被 runner 跑的那个 agent"自己取,名字错位的可能性直接消失。

历史注:turn.go 里还留过 writeTodosTool / formatTodoReceipt(认官方 write_todos 回执、 打印任务清单)与 ensureNudgeCall(修"有 tool_calls 但没有对应 ToolMessage"的配对问题,同一类 400 风险)。 前者由《02》Task 4 换成看板投影(认 taskboard.IsBoardTool),后者已随 internal/planning 删除。 保留这一句是为了让读者知道:这个文件里的行号会随任务推进变化,锚点以当前代码为准。

6. 编译期断言:把「漏实现」提前到编译期

Go 是结构化类型(structural typing):类型不需要声明 implements,只要方法集 ⊇ 接口要求的方法集 就算实现了该接口——缺一个方法都不算。问题是「缺方法」平时不显形,直到某处把值赋给接口变量才报错, 而报错位置可能离类型定义十万八千里。于是本仓库在每个实现接口的类型旁边钉一行:

// 编译期校验 handler 实现了 adk.ChatModelAgentMiddleware。
var _ adk.ChatModelAgentMiddleware = (*handler)(nil)   // internal/taskboard/middleware.go:27

拆开看这行语法在做什么:

哪些改动会被它当场抓住:

  1. 升级 eino 后接口新增方法,而 handler 和内嵌的 BaseChatModelAgentMiddleware 都没提供;
  2. 覆盖的方法签名改错(参数/返回值类型对不上接口);
  3. 误删内嵌字段——这正是下一段的坑:方法提升让「谁补齐了哪些方法」读代码看不出来 (见 §3,handler 只写了 BeforeAgent,其余全靠 adk.BaseChatModelAgentMiddleware 提升), 光看类型定义没法肉眼确认方法集是否全覆盖,只能让编译器验。

没有断言时,这些错误会推迟到「第一次把值赋给接口」处(比如 New 的 return &handler{...}) 才暴露,甚至随依赖升级悄悄潜伏;有断言则错误直接钉在类型定义旁边,一行注释说明校验的是什么。

本仓库的同类断言:internal/guard/middleware.go 的 toolGuardHandler、 internal/adkrun/turn.go:26-27 的 var _ adk.CheckPointStore(Store 内存实现)。 这也是 AGENTS.md 把「实现接口必须配编译期断言」定为硬性规则的原因: 接口归属靠注释给人看,方法集完整靠断言给编译器验,两者缺一不可。

7. map 是无序的:顺序用 order 切片 / 排序另行保障

Go 的 map 迭代顺序规范就不保证(运行时故意随机化,防止代码依赖插入序)。 range map 不报错、不 panic,只是每次顺序都可能不同——凡是要把 map 内容 输出给人或模型看的地方,顺序必须自己保障,否则同一份数据两次渲染的顺序都会抖。

本仓库两处实例:

  1. 任务看板(internal/taskboard/taskboard.go:66-71):

    type Store struct {
        mu     sync.Mutex
        tasks  map[string]*Task
        order  []string // 创建顺序,看板按它排
        nextID int
    }

    分工是:tasks map 负责按 taskId 的 O(1) 寻址(Get/Update), order []string 负责创建顺序——Create 在同一把锁里 s.order = append(s.order, id), List/Snapshot 一律 range s.order 再回查 map、跳过 deleted。 于是看板(board 渲染的 📋 任务看板)永远按创建序输出, 模型每轮看到的清单顺序稳定,单测断言也不受 map 随机性影响。

  2. provider 发现(internal/config/resolve.go:94-108):byID map 存结果、 order 切片记首见顺序;扫环境变量前先收集 key 再 sort.Strings(keys) (注释原话「按变量名排序,结果稳定」)。map + order + 显式排序三件套, 与看板是同一个套路。

三个坑点:

一句话:map 只管寻址,顺序是另一份数据结构的职责;要稳定输出,就在写入时顺手记 order, 或在输出前显式排序,二者选其一,别指望 range 帮你。

8. []adk.ChatModelAgentMiddleware{boardMW}:接口切片字面量与 append 拼链

cmd/yktako/main.go:50 组装 handlers 的那行,拆成三截看:

handlers := append([]adk.ChatModelAgentMiddleware{boardMW}, guard.Handlers(engine, guard.Options{WorkspaceRoot: cwd})...)

拼完 handlers = [boardMW, toolGuard, filesystem, PII]。顺序即注册顺序: BeforeAgent 按这个序串行执行(taskboard 先注入工具), WrapInvokableToolCall 也按它包裹(命令守卫最外、PII 最贴工具,见《06》)。

为什么 boardMW 装得进去,两层原因:

  1. Go 是结构化类型(见 §6):*handler 内嵌 adk.BaseChatModelAgentMiddleware, 基类给出全部钩子的空实现,*handler 只覆盖 BeforeAgent——方法集依然覆盖接口要求, 编译器就认。middleware.go:27 的 var _ adk.ChatModelAgentMiddleware = (*handler)(nil) 正是把这件事提前交给编译器验。
  2. 其实 taskboard.New 的返回类型本来就是 adk.ChatModelAgentMiddleware (middleware.go:31,return &handler{...} 在函数边界已完成隐式装箱)。 boardMW 在 main 里已经是接口值,装进同类型切片是平凡操作。 接口值 =(动态类型 *handler, 动态值),切片元素存的就是这对信息。

adk.ChatModelAgentMiddleware 是别名,不是新类型(adk/handler.go:259):

type ChatModelAgentMiddleware = TypedChatModelAgentMiddleware[*schema.Message]

单个 = 是类型别名:它就是泛型接口 TypedChatModelAgentMiddleware[M] 在 M = *schema.Message 时的另一个名字。写 []adk.ChatModelAgentMiddleware 和写 []adk.TypedChatModelAgentMiddleware[*schema.Message] 完全等价,前者短得多。

与 §3 的分工:§3 讲每个 handler 轮到自己时怎么改 runCtx;本节讲这些 handler 以什么类型、按什么顺序排进 ChatModelAgentConfig.Handlers 这条链。

一句话:[]接口{初值} + append(切片, 另一个切片...) 是 Go 拼接口切片的标准写法; 一个值能不能装进去只看方法集,与它在哪儿定义、谁先返回无关。

9. Handlers 字段、Middleware 接口、handler 实现:三个名字指同一批东西

读 eino 和本仓库代码容易被三个名字绊住:字段叫 Handlers、接口叫 ...Middleware、 实现类型叫 handler(internal/taskboard/middleware.go:20、guard 的 toolGuardHandler 等)。 它们指的是同一批对象:

叫法 出处
Handlers 配置字段 ChatModelAgentConfig.Handlers []TypedChatModelAgentMiddleware[M](adk/chatmodel.go:401)
ChatModelAgentMiddleware 这批东西的接口类型(adk/handler.go:259 的别名;基类 BaseChatModelAgentMiddleware 同理)
handler eino 源码文件 handler.go、内部变量 a.handlers、文档用语 "interface-based handlers"(chatmodel.go:314);本仓库的实现类型名也跟这个

为什么接口名里带 Middleware:历史包袱。旧 API 是 struct 型的 Middlewares []AgentMiddleware(chatmodel.go:310-312,已标 Deprecated,注释原话 "Use Handlers instead");新 API 把字段换成 interface 型的 Handlers, 接口名保留了 Middleware 词根(它们干的确实还是中间件的活:包模型调用、包工具执行)。

规律:看到字段/文档说 Handlers,看到类型名说 Middleware,看到文件/变量/本仓库类型说 handler—— 一回事。 说"注册进 Handlers 的 middleware"不算错,只是把两个名字各取一半。

9.1 执行模型:注册顺序 = 钩子顺序,串行传递 runCtx

config.Handlers 在构造时存进 a.handlers(chatmodel.go:565),之后每个钩子点 都用同一个模式按序串行消费(chatmodel.go:820,BeforeAgent 为例;:865 的 AfterAgent 同型):

for i, handler := range a.handlers {                    // 按注册顺序
    ctx, runCtx, err = handler.BeforeAgent(ctx, runCtx) // 串行:上一个的输出是下一个的输入
    if err != nil {
        return ctx, nil, fmt.Errorf("handler[%d] (%T) BeforeAgent failed: %w", i, handler, err)
    }
}

三个推论:

  1. 顺序由注册时的 append 定死:cmd/yktako/main.go:50 拼出 [taskboard, 命令守卫, 文件守卫, PII]——BeforeAgent 阶段 taskboard 先注入工具, 守卫三件套的 BeforeAgent 是基类空实现、原样透传。
  2. 同一个顺序也管工具执行时的包裹:handlersToToolMiddlewares(a.handlers) (chatmodel.go:912)把这批 handler 转成 WrapInvokableToolCall 链, 注册序 = 外层在前,所以是《06》说的"命令守卫最外、PII 最贴工具"。
  3. runCtx 是逐手传递的状态:nRunCtx := *runCtx 的拷贝语义(§3)+ 循环里的 runCtx = 返回值,合起来保证每个 handler 看到的都是前一个改完的版本, 且谁都不动别人的原值;任一环报错,整个 run 以 handler[i] 定位失败并中止。

一句话:Handlers 是字段名、Middleware 是接口名、handler 是源码与实现的称呼; 顺序在 append 进切片那一刻就定死,钩子沿序串行、靠 runCtx 逐手交接。

10. //go:embed:编译期把文件"焊"进二进制

internal/config/catalog.go:13-14 就是全部用法:

//go:embed provider-catalog.json
var catalogJSON []byte

很多人第一眼会以为"变量名 catalogJSON 配上了 provider-catalog.json,所以自动赋值"—— 不是。绑定是位置式的,与变量名无关。编译器做的事等价于:

var catalogJSON []byte = <紧邻指令里那个文件的全部原始字节>

决定装哪个文件的是指令后面的路径,变量只是接收方。实测://go:embed some/other.json 紧贴 var catalogJSON []byte,装进去的就是 other.json;反过来 //go:embed provider-catalog.json 配 var anything []byte 一样成立。

10.1 硬性条件(附实测报错)

  1. // 与 go:embed 之间不能有空格——它是编译器指令(Go 1.16+),不是注释。 写成 // go:embed 不报错、不警告(go vet 也查不出),只是静默退化成普通注释、 变量保持零值;在本仓库的后果是启动才报 解析厂商目录: unexpected end of JSON input, 错误信息完全指不到真正的笔误。
  2. 文件必须导入 embed,哪怕一个符号都不用:import _ "embed"。少了它编译报 go:embed requires import "embed" (or import _ "embed", if package is not used)。
  3. 只能修饰包级 var(单个,或在 var (...) 块里)。函数内报 go:embed cannot apply to var inside func;变量类型不是 string / []byte / embed.FS 报 go:embed cannot apply to var of type int;指令后面没有变量报 misplaced go:embed directive。
  4. 路径相对源码文件所在目录:可以进子目录(//go:embed assets/data.json), 但不能含 ..(报 invalid pattern syntax)。
  5. 文件/模式必须在编译期就匹配上:pattern nono.json: no matching files found。 注意这是编译错误——"文件不存在"这类运行期风险被整个消灭了。
  6. []byte / string 只能装恰好一个文件://go:embed *.json 匹配到两个时报 invalid go:embed: multiple files for type []byte。多个文件或整个目录要声明成 embed.FS (读时 fs.ReadFile("other.json");all: 前缀才会带上 .、_ 开头的文件)。
  7. 指令与 var 之间只允许空行或 // 行注释(实测夹一个空行仍生效;多条 //go:embed 可叠加到同一个 var)。

10.2 运行期语义与选它的理由

编译时文件字节被写进可执行文件(只读数据段),运行期 catalogJSON 就是个普通 []byte: 无 os.Open、不依赖工作目录、二进制拷到哪都能跑;改 JSON 必须重新编译,二进制体积 += 文件大小。

catalog.go 选 embed 而不是 os.ReadFile,图的不是"方便",是把保证挪到编译期: 厂商目录"一定在"成为构建的一部分,mustPresets()(catalog.go:88)的 panic 只剩 "JSON 格式坏"一种触发方式;同时部署零配置、零路径依赖。代价是目录不能在部署后热改—— 要覆盖只能走环境变量三级覆盖(resolve.go:50-75),这本来就是设计的一部分。

一句话://go:embed <相对路径> = 编译期把该文件内容赋给紧邻的包级 var; 认的是"位置 + 路径"而不是变量名,文件缺失、类型不符当场编译失败, 唯一的静默坑是 // 后多打出的那个空格。

11. interrupt 信号树的方向与 IsRootCause:一个被命名误导的契约

本节记录一个真实的误读案例与排查结论。它同时是一道很好的面试题: 「InterruptContexts 里装的是真因还是祖先?」——答对的前提是分清两种「root」。

11.1 症状:adkrun 里那行没人解释得清的过滤

internal/adkrun/turn.go:147-156:

for _, point := range event.Action.Interrupted.InterruptContexts {
    if point != nil && point.IsRootCause {
        interrupts = append(interrupts, point)
    }
}
if len(interrupts) == 0 {
    interrupts = append(interrupts, event.Action.Interrupted.InterruptContexts...)
}

一个自然但方向反了的读法:「信号树会在 root 汇聚,root 拥有所有叶子的中断, 所以 IsRootCause==true 的应该是树根,这行过滤是在挑祖先。」 实情恰好相反:IsRootCause=true 的是叶子(最内层真正按下暂停的组件), 树根(最外层包装者)恰恰是 false,永远不会进列表。

根源是术语撞车:root cause(因果起点,在树底)与信号树的 root(结构顶端)指向两端。 英文一个词,中文若都叫「根」,必错。

11.2 事实一:哪端是 true,由「有没有子节点」现场决定

core.Interrupt(internal/core/interrupt.go:88-125)创建信号时只做一句判定:

if len(subContexts) == 0 {
    myPoint.IsRootCause = true   // :102-103
}

「没有子节点」= 这个组件不是替谁传话,是它自己发起了中断。 对照项目里一条完整的包装链:

guard 的 WrapInvokableToolCall
  └ compose.StatefulInterrupt(...)           → 叶子信号:无 Subs,true
      (internal/guard/middleware.go:119 / :192)
ToolsNode 捕获各工具错误
  └ WrapInterruptAndRerunIfNeeded            (compose/tool_node.go:1217)
  └ CompositeInterrupt(..., errs...)         → 父信号:Subs=[这些错误],false
      (compose/tool_node.go:1246;实现 compose/interrupt.go:174-237)
ChatModelAgent 捕获 compose 中断
  └ FromInterruptContexts + TypedCompositeInterrupt → 再包一层父,false
      (adk/chatmodel.go:970-971)
Runner 顶层
  └ interruptSignal = 最外层信号             (adk/runner.go:314)

画成树(Runner 手里的 is 就是最外层那个;中间层数随嵌套深度变化):

信号树(从 Runner 的 is 往下看)              IsRootCause
└─ ChatModelAgent composite                     false   ← 结构性「树根」,拥有所有叶子
   └─ ToolsNode composite                        false
      └─ guard StatefulInterrupt 的叶子           true   ← 列表里只有它

CompositeInterrupt 保住了这棵树:裸的 *core.InterruptSignal 直接收下 (compose/interrupt.go:216-220),最后统一 core.Interrupt(ctx, info, state, cErrs)(:232)—— 父节点因有子节点,IsRootCause 保持 false。

11.3 事实二:导出列表只收真因,祖先走 Parent

ToInterruptContexts(internal/core/interrupt.go:249-298)从树顶往下遍历,每个节点都看, 但只 append 真因(:274-276):

if currentCtx.IsRootCause {
    rootCauseContexts = append(rootCauseContexts, currentCtx)
}

官方文档把不变量写得明白(pkg.go.dev,ToInterruptContexts):

a list of user-facing InterruptCtx objects for the root causes of the interruption. Each returned context has its Parent field populated..., allowing traversal up the interrupt chain.

即:列表恒为真因;祖先只经 Parent 链可达,且在链上恒为 false—— eino 自己的测试断言这一点(compose/resume_test.go:339 的 assert.False(t, rootCause.Parent.IsRootCause))。

Parent 链不是装饰,是跨层桥接的必需品:FromInterruptContexts(:202-247) 沿 Parent 往上回溯、逐级 getOrCreateSignal 重建整棵树(rootSignal 收在最顶端,:236), adk/chatmodel.go:970 那种跨 agent 边界的中断才能带着完整地址链重新上抛。 变量命名再次埋雷:这个顶端叫 rootSignal——结构性树根,与 IsRootCause 的「真因」反向。

11.4 事实三:v0.9.21 全部导出点都走同一个函数

给 InterruptContexts 赋值的地方穷举:compose/graph_run.go:631/787、 adk/runner.go:299/315、adk/interrupt.go:72/107/143、adk/workflow.go:616—— 全部调用 core.ToInterruptContexts。 推论:「列表里混有祖先」在当前版本不会发生。adkrun 那行过滤在标准 ADK 路径上是 无害的 no-op;if len==0 兜底防的是罕见退化形态(如 legacy 包装丢子树, 见 compose/interrupt.go:197-211),不是日常路径。

11.5 事实四:文档自相矛盾,官方测试还在传播防御写法

字段注释(adk/interrupt.go:52-54)说:

InterruptContexts provides a structured, user-facing view of the interrupt chain. Each context represents a step in the agent hierarchy that was interrupted.

照字面读 = 列表是混合的、祖先也在,过滤当然必要。这与 ToInterruptContexts 的文档正好相反。

而 eino 自己的测试就写着这行过滤(adk/agentic_react_test.go:1155-1162、:1310-1316):

for _, intCtx := range interruptEvent.Action.Interrupted.InterruptContexts {
    if intCtx.IsRootCause {
        rootCauseID = intCtx.ID
        break
    }
}

于是形成闭环:字段文档暗示混合 → 官方测试/示例防御性过滤 → 使用者照抄。 没有哪个开发者有义务靠读实现来猜对。

11.6 结论:机制没错,契约缺陷

对本仓库的实践结论:internal/adkrun/turn.go:147-156 的过滤保留无害 (意图自明 + 防御),但真正承担正确性的是 targets[point.ID] = decision (turn.go:97-107)与只回答 point.Info;想验证「no-op」判断,去掉 if 条件跑全量测试, 标准 adk 路径应全绿。

一句话:列表装的是真因(叶子),树根只是携带者;IsRootCause 判断的是「手里这个 ctx 是提问者还是信封」——「root」一词同时指向因果起点与结构顶端,是这个 API 最坑人的地方。

12. resume 的中段:Targets 与 GetResumeContext 如何相遇(地址钥匙 + ctx 公告板)

承接 §5(checkpointID 是 join key)与 §11(真因与列表)。本节回答: adkrun 写的 Targets 和 guard 读的 GetResumeContext 分居两个文件、互不引用, 中间到底发生了什么?结论先行:两端没有任何函数调用相连,耦合发生在运行时 ctx 里—— 中断时树把「ID ↔︎ 地址」登记进 checkpoint,resume 时 AppendAddressSegment 按当前地址认领 Targets 里的数据挂到 ctx,wrapper 重跑时自己读走。

12.1 症状:两端互不引用,跨度大得可疑

12.2 事实一:ResumeWithParams 只做两件事——恢复现场 + 立公告板

resumeInternal(adk/runner.go:210-242)里:

ctx, runCtx, resumeInfo, err := runnerLoadCheckPointImpl(...)  // :211 读回整个执行现场
...
ctx = setRunCtx(ctx, runCtx)                                   // :237 现场进 ctx
...
if len(resumeData) > 0 {
    ctx = core.BatchResumeWithData(ctx, resumeData)            // :241 Targets 进 ctx
}
...
aIter := ra.Resume(ctx, resumeInfo, opts...)                   // :252 重新驱动 agent

12.3 事实二:重入时 AppendAddressSegment 按地址认领

resume 不是「跳到断点」,而是从 checkpoint 恢复现场后沿地址链重入 (ADK 层用 GetNextResumptionPoints 找出该重入的子链路,adk/interrupt.go:419/444)。 执行每下钻一层,框架就调一次 AppendAddressSegment(ctx, 类型, ID, 子ID) (internal/core/address.go:118-187)生成本层地址;而这个函数后半段顺便查公告板:

for id_, addr := range rInfo.id2Addr {
    if addr.Equals(currentAddress) {
        runCtx.interruptState = generic.PtrOf(rInfo.id2State[id_])  // :157 旧状态挂上
        ...
        if !used {
            runCtx.isResumeTarget = true                            // :171 回执挂上
            runCtx.resumeData = rData
        }
    }
}
// :175-184 自己没被点名、但有子孙被点名 → isResumeTarget=true(只当导管,不领数据)

地址对上号的瞬间,数据被挂到该组件的 ctx 上——不是参数传下来的,是自查出来的。 地址之所以能对上,是因为工具段的地址子 ID 就是 tool_call_id,重入时从 checkpoint 恢复的同一条消息历史里取回,前后一致。

12.4 事实三:wrapper 重跑,自己读信

被中断的节点重入 = 它的执行链原样再走一遍,所以 WrapInvokableToolCall 包出的函数 自然再跑一次。这不是「框架悄悄帮你执行」,而是首次执行路径的直接复用,没有任何 resume 专用分支;read 端只在 guard 自己写的两行里(guard/middleware.go:98-99):

if stored, ok := ownInterrupt(ctx, kindToolGuard); ok {  // GetInterruptState:认出「我被打断过」
    decision, decided := resumeDecision(ctx)              // GetResumeContext:取回执

GetInterruptState / GetResumeContext(internal/core/resume.go:28-41、86-104) 都只是当前 addrCtx(internal/core/address.go:81-86)的薄读取器——不看 Targets、 不看信号树、不看 checkpoint。这就是为什么 middleware.go 里「看不到跨度」:它不需要看到。

12.5 为什么读代码会觉得跨度大:三个隐性耦合

  1. 数据耦合,不是调用耦合。写入端写 targets[point.ID],读取端被 core 按地址匹配后 自动挂数据;两端唯一共识是那把钥匙(ID/地址),没有任何函数把两边连起来。
  2. 词汇在边界换名三次:Targets(ADK 词汇)→ id2ResumeData / resumeData (core 词汇)→ GetResumeContext(compose API)。同一个 map,三个名字。
  3. 重入是隐式的:hook 语义是「每次工具即将执行时调用」,resume 重入天然再次触发; 不先知道「resume = 重入」,就会以为哪里藏了个开关。

12.6 全链路一图(把 §5 与 §11 串起来)

中断时刻:
  guard StatefulInterrupt(叶子信号)
    → 层层 CompositeInterrupt 成树
    → SignalToPersistenceMaps 压成 id2addr / id2state(core/interrupt.go:330-353)
    → 随 runContext 写进 CheckPointStore(adk/runner.go:330-331)
    → ToInterruptContexts 导出真因列表给 adkrun(turn.go 拿到 point.ID / point.Info)

resume 时刻:
  targets[point.ID] = decision
    → runnerLoadCheckPointImpl 读回 id2addr / id2state(adk/interrupt.go:223-249)
    → PopulateInterruptState:状态表进 ctx(:243)
    → BatchResumeWithData:回执表进 ctx(runner.go:241)
    → 重入被中断的节点链(GetNextResumptionPoints,adk/interrupt.go:419/444)
    → AppendAddressSegment 按当前地址认领状态与回执,挂到 addrCtx(address.go:154-184)
    → wrapper 重跑,GetResumeContext 读走决定
    → 批准:真工具执行,输出成 ToolMessage;拒绝:拒绝文案成 ToolMessage
    → ReAct 循环继续下一轮模型调用

一句话:中断时树当登记员,把「ID ↔︎ 地址」写进 checkpoint;resume 时按地址认领、 数据挂在 ctx 上;wrapper 重跑时自己读走——没有传话员,只有认领。