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 在你手里:
- 直接透传:
return endpoint(ctx, args, opts...)—— 放行 - 换参数再调:
endpoint(ctx, stored.Args, opts...)—— 审批通过后恢复原调用 - 不调它,直接返回一段 string —— 硬拒 / 拒绝消息,这条 string 会作为结果回填给模型
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"
- 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。 - "链的终点"语义。Middleware 一层套一层,责任链总得有个终点。 任何一层执行
endpoint(ctx, args, ...)就是"把控制权沿链传到最深处,让真工具干活"。 叫它 handler 也行,但 handler 容易混淆(外面那层也是某种 handler), endpoint 强调的是链的端点:这是最后一站,穿过它就出了框架、进了实现。 - 对应"调用点"而非"实现"。它不是工具本身(
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)ChatModelAgentContext(adk/handler.go:87)里的Tools []tool.BaseTool是本轮的工具表:AgentConfig里配的工具 + 框架隐式加的工具(transfer / exit 之类)+ 前面 middleware 已经加过的工具, 逐步往里追加。返回
*ChatModelAgentContext是有意的拷贝语义:官方和 eino 自己的 plantask (adk/middlewares/plantask/plantask.go:66-73)都这么写:nRunCtx := *runCtx nRunCtx.Tools = append(nRunCtx.Tools, m.tools...) return ctx, &nRunCtx, nil改副本、不动调用方的原值,所以单测可以直接断言"原 runCtx 的工具数没变"。
同一个结构体还有
Instruction字段(BeforeAgent里改它 = 动态改系统提示词)。 我们没走动态改:入口用config.SystemPrompt() + "\n\n" + taskboard.Instruction静态拼接, 理由是这样提示词来源单一、可读,不必藏在钩子里。adk.BaseChatModelAgentMiddleware(handler.go:277起)提供所有钩子的空实现, 所以中间件只需内嵌它、覆盖自己关心的那个钩子——guard 覆盖WrapInvokableToolCall, taskboard 覆盖BeforeAgent。
4. session 值为什么"免费"随 checkpoint 落盘
任务看板的镜像(adk.AddSessionValue(taskboard.SessionKey, snapshot))能在 interrupt 时跟着落盘, 靠的是 eino 对 session 的序列化声明,不是我们写了额外代码:
adk/runctx.go:33-35:runSession结构体上标着CheckpointSchema: persisted via serialization.RunCtx (gob),Values map[string]any就是 session 值。 同文件:48、:54的 laneEvents / agentEventWrapper 有同样的标注——凡是标了这行的字段, 都会随整个 runContext 一起 gob 进CheckPointStore。adk/runctx.go:214的AddSessionValue:func AddSessionValue(ctx context.Context, key string, value any) { session := getSession(ctx) if session == nil { return // 没有 session 就静默返回,不报错 } session.addValue(key, value) }这解释了为什么单测里直接调工具函数不炸——ctx 里没有 runCtx,镜像那步是空操作。
类型必须注册(
map[string]any里的具体类型 gob 认不出来):- eino 自己注册了
gob.Register([]byte{})(adk/interrupt.go:205); - 我们注册了
gob.Register([]Task{})(internal/taskboard/taskboard.go的init); - 另一种是给 gob 起稳定名字:
schema.RegisterName[ApprovalInfo]("tako_approval_info")(internal/guard/middleware.go的init)——审批载荷要跨进程/跨恢复活着,名字必须稳定。
- eino 自己注册了
但正本不能放 session:session 每轮
runner.Run新建,能把父 session 带进子 run 的 option 在 eino 里未导出,外部拿不到。所以跨轮存活的正本是 middleware 自持的*Store, session 里只放"随 checkpoint 走的镜像"(定案见《01》§3、实现见《07》§4.3)。
一句话:"落盘不依赖模型自觉"里的落盘,是 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)参数里有两个"标识",管的是两件互不相干的事:
checkpointID:被挂起的那次执行状态存在哪——CheckPointStore里的键,只有需要审批的入口才给得出值;root:哪个 agent 说的话算这次对话的产出——用来过滤历史、给子代理的消息加前缀。 它由root := agent.Name(ctx)(turn.go:78)从主 agent 自己身上取,不是脚本传进来的。
它们唯一的交点在时间上: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):
- 暂停:
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收尾。 - 恢复:
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 只有两个用途:
- 筛历史(
turn.go:143):if msg != nil && event.AgentName == root { ... }—— 只有 root 的消息进返回给调用方的history; - 加前缀(
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拆开看这行语法在做什么:
(*handler)(nil)是一个类型为*handler的 nil 指针;赋给_后从未被解引用, 运行时什么都不做。编译器只做一件事:检查*handler的方法集是否满足接口。- 用指针类型而不是
handler{},是因为钩子方法都是指针接收者 (func (h *handler) BeforeAgent(...))——只有*handler才有完整方法集, 值类型handler不含这些方法,拿去断言反而会报「未实现」。
哪些改动会被它当场抓住:
- 升级 eino 后接口新增方法,而
handler和内嵌的BaseChatModelAgentMiddleware都没提供; - 覆盖的方法签名改错(参数/返回值类型对不上接口);
- 误删内嵌字段——这正是下一段的坑:方法提升让「谁补齐了哪些方法」读代码看不出来 (见 §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 内容 输出给人或模型看的地方,顺序必须自己保障,否则同一份数据两次渲染的顺序都会抖。
本仓库两处实例:
任务看板(
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 随机性影响。provider 发现(
internal/config/resolve.go:94-108):byIDmap 存结果、order切片记首见顺序;扫环境变量前先收集 key 再sort.Strings(keys)(注释原话「按变量名排序,结果稳定」)。map + order + 显式排序三件套, 与看板是同一个套路。
三个坑点:
- order 和 map 必须同锁读写。看板靠
Store.mu保证原子性, 否则并发下会出现「map 里有、order 里没有」的撕裂——List漏项且无从察觉。 - deleted 不从 order 移除:
Snapshot含 deleted、List过滤, 配合nextID单调自增,order 里不会出现悬空 id,也不需要删项逻辑。 - 别直接
range tasks渲染看板:功能上全对,只是每次顺序都不一样, 属于最难查的「输出抖动」类 bug——测试偶尔挂、模型看到的清单忽前忽后。
一句话: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})...)[]adk.ChatModelAgentMiddleware{boardMW}:接口类型的切片字面量。Go 里[]T{a, b}就是建一个装了初值的切片,T可以是接口——元素放任何实现了该接口的值都行。 这里先造出只含boardMW的单元素切片。guard.Handlers(...)返回的也是[]adk.ChatModelAgentMiddleware(internal/guard/middleware.go:83, 内含三件套 handler 指针)。- 第二个参数后的
...把切片打散成逐个实参传给append,效果是拼接两个切片; 不加...则会把整个切片当一个元素、类型直接不对。
拼完 handlers = [boardMW, toolGuard, filesystem, PII]。顺序即注册顺序: BeforeAgent 按这个序串行执行(taskboard 先注入工具), WrapInvokableToolCall 也按它包裹(命令守卫最外、PII 最贴工具,见《06》)。
为什么 boardMW 装得进去,两层原因:
- Go 是结构化类型(见 §6):
*handler内嵌adk.BaseChatModelAgentMiddleware, 基类给出全部钩子的空实现,*handler只覆盖BeforeAgent——方法集依然覆盖接口要求, 编译器就认。middleware.go:27的var _ adk.ChatModelAgentMiddleware = (*handler)(nil)正是把这件事提前交给编译器验。 - 其实
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)
}
}三个推论:
- 顺序由注册时的
append定死:cmd/yktako/main.go:50拼出[taskboard, 命令守卫, 文件守卫, PII]——BeforeAgent阶段 taskboard 先注入工具, 守卫三件套的BeforeAgent是基类空实现、原样透传。 - 同一个顺序也管工具执行时的包裹:
handlersToToolMiddlewares(a.handlers)(chatmodel.go:912)把这批 handler 转成WrapInvokableToolCall链, 注册序 = 外层在前,所以是《06》说的"命令守卫最外、PII 最贴工具"。 - 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 硬性条件(附实测报错)
//与go:embed之间不能有空格——它是编译器指令(Go 1.16+),不是注释。 写成// go:embed不报错、不警告(go vet也查不出),只是静默退化成普通注释、 变量保持零值;在本仓库的后果是启动才报解析厂商目录: unexpected end of JSON input, 错误信息完全指不到真正的笔误。- 文件必须导入
embed,哪怕一个符号都不用:import _ "embed"。少了它编译报go:embed requires import "embed" (or import _ "embed", if package is not used)。 - 只能修饰包级 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。 - 路径相对源码文件所在目录:可以进子目录(
//go:embed assets/data.json), 但不能含..(报invalid pattern syntax)。 - 文件/模式必须在编译期就匹配上:
pattern nono.json: no matching files found。 注意这是编译错误——"文件不存在"这类运行期风险被整个消灭了。 []byte/string只能装恰好一个文件://go:embed *.json匹配到两个时报invalid go:embed: multiple files for type []byte。多个文件或整个目录要声明成embed.FS(读时fs.ReadFile("other.json");all:前缀才会带上.、_开头的文件)。- 指令与 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 结论:机制没错,契约缺陷
- 机制上树与叶子都必需:树撑住跨层地址(resume 按地址重入),列表给出待回答的问题。
IsRootCause字段真正的用途是区分手里这个 ctx 的角色——列表成员=真因 /Parent链上的祖先=包装——而不是让你过滤列表。这一点框架从未说清。- 缺陷在对外表达:一个冗余的 flag、两段互斥的文档、官方测试亲手示范冗余过滤。
- 若重设计:字段改名
RootCauses []*InterruptCtx并从公共类型删掉 flag;或保留单类型 但把 invariant 写死;或 resume 改发句柄point.ResumeKey()而非裸 ID。
对本仓库的实践结论: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 症状:两端互不引用,跨度大得可疑
- 写入端(
internal/adkrun/turn.go:97-109):targets[point.ID] = decision, 然后runner.ResumeWithParams(ctx, checkpointID, &adk.ResumeParams{Targets: targets})。 - 读取端(
internal/guard/middleware.go:98-107):ownInterrupt+resumeDecision→compose.GetResumeContext[string](ctx)。 - grep 结果:
turn.go里没有compose.GetResumeContext,middleware.go里没有Targets。 两边像是各说各话,却精确地接上了。
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- 解码 checkpoint 得到序列化结构体里的
InterruptID2Address/InterruptID2State(adk/interrupt.go:219-220),随即core.PopulateInterruptState(ctx, ...)(adk/interrupt.go:243)把「哪个 ID 在哪个地址、旧状态是什么」铺进 ctx。 BatchResumeWithData(internal/core/address.go:245-269)只把 map 拷贝进globalResumeInfo.id2ResumeData。到这里为止什么都没「送」给谁,只是立了块公告板。- 提醒(§11 的续集):
InterruptCtx.ID注释说它是「地址拼成的字符串」,但 v0.9.21 实现里 它是中断时生成的 UUID(internal/core/interrupt.go:105/116);把 ID 与地址挂钩的, 正是 checkpoint 里这张id2addr映射。所以Targets的 key 只能照抄point.ID, 不要试图从 key 字面读出地址。
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 为什么读代码会觉得跨度大:三个隐性耦合
- 数据耦合,不是调用耦合。写入端写
targets[point.ID],读取端被 core 按地址匹配后 自动挂数据;两端唯一共识是那把钥匙(ID/地址),没有任何函数把两边连起来。 - 词汇在边界换名三次:
Targets(ADK 词汇)→id2ResumeData/resumeData(core 词汇)→GetResumeContext(compose API)。同一个 map,三个名字。 - 重入是隐式的: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 重跑时自己读走——没有传话员,只有认领。