tako 文档 GitHub

19v6-05 · tool loop(T 系列)

本篇是 doc/19-v6 文档集的 tool loop 篇:Eino ADK 底座、工具消息的两个投影、sub agent(AgentTool)、 工具目录与 tool_search、观测 Handler 脚手架。 契约字节真源仍是 19v6-01——本篇涉及的帧新 kind 与 agent 字段已随 T2(2026-10-08,七修)落 19v6-01; model 字段(2026-10-10 纠偏,帧/行同带)已补 19v6-01,随 T3-1b/T3-2 落地; 本篇是 tool loop 的机制裁定真源。 立项:2026-10-08(用户拍板:循环走 Eino ADK);执行台账 = tmp/19-v6/planning.md §11 + todos「T 系列」。 T4/T5 已落地(2026-10-20):工具分级(direct/deferred)+ tool_search(BM25 首版)A1–A4 四拍完成—— A1 ad1ab6b(toolsearch.go:分词/BM25/检索/run-local box + 单测)、A2 a190f4d(子代理保留名与 显式挂载)、A3 纯验收(激活集只活一场 run)、A4 回归与收口(单测补网、A1/A2 话本重跑、四个 API 字节零变化)。落地细节与验收实录见 §5 尾条与 tmp/19-v6/todos.md。

0. 术语(2026-10-08 用户裁;2026-10-10 补 3 条模型侧术语)

先看「观测 / 存储」侧三个词,三种形状 / 住处 / 消费者,勿混:

词 形状 住处 消费者 粒度
Model message OpenAI messages(role/content/tool_calls) 主线程 → run_model_messages 表;子代理 → 只在进程内(AgentTool runner state) worker 组装模型输入 消息
runlive 帧(kind + agent + model + 负载) Redis tk:runlive:{runId} LIST(TTL 300s) frames API(客户端轮询) 帧
runlog 活动行(role/agent/model/text/payload) PG runlog_entries log API 消息

再看「模型选型 / 客户端」侧三个词(§4 开始大量用,先钉死定义):

词 形状(正向定义) 住处 消费者 例子
ref 字符串,格式 = 厂商ID / 模型ID。唯一身份:带厂商命名空间,避免同名模型撞车。 不单独存:从环境变量 TAKO_MODEL 读、或从子代理 md 的 model: 行读 ResolveModel 解析它、ModelRegistry 拿它当缓存 key、帧/行里的 model 字段存它 deepseek/deepseek-v4-flash、anthropic/claude-sonnet-4、ollama/qwen2.5-coder:14b
ChatModel 实例 一个具体的 HTTP 客户端:里面装好了 baseURL、API Key、协议(openai/anthropic)、模型 ID。无状态,不记任何对话。 进程内存(Go struct) ChatModelAgent / AgentTool 的 loop 用它发 LLM 请求 主 worker 启动时 config.Open() 返回的那一个;子代理按 ref 新建的那些
ModelRegistry 一张进程内的懒加载缓存表:map[ref]ChatModel实例。懒加载 = 进程启动时是空的,第一次用到某个 ref 才解析并建客户端,之后同样的 ref 直接复用。 进程内存(Go struct,带读写锁防并发重复建) 装配层(BeforeAgent)把子代理规格转成 ChatModelAgent 时用它取实例 一条规格写了 model: anthropic/claude-sonnet-4,第一次遇到时 ModelRegistry 去解析环境变量、建 claude 客户端、存进 map;下一条同样写了这个 ref 的规格直接拿 map 里的,不再重复解析

index 概念表对 runlive/runlog 的定义不变;本篇钉死的是「模型输入侧叫 Model message、观测侧叫帧/runlive」, 以及两者永不混写:子代理的 Model message 不进 mh、帧不进 mh。

1. 底座:Eino ADK

2. 工具消息的两个投影

同一次工具调用,两个投影各自成形状(种类由 role 取值承载,2026-10-07 已裁):

3. 帧契约扩展(已落 19v6-01 §2,2026-10-08 七修)

4. sub agent:AgentTool 自组装

┌─ 三条具体规格(agents/*.md) ───────────────────────────────────────────────┐
│                                                                           │
│  ① researcher.md  :什么都没写(写法一·隐式继承)                            │
│  ② writer.md      :model: inherit(写法二·显式继承)                       │
│  ③ code-review.md :model: anthropic/claude-sonnet-4(写法三·指定 ref)    │
│                                                                           │
└───────────────────────────────┬───────────────────────────────────────────┘
                                │
                                ▼
             run 起手扫盘(BeforeAgent → LoadAgentSpecs → parseAgentSpec)
                                │
                                ▼
                   parse 只拆语法:model 字符串原样带出
                   (不判断是继承还是 ref,判断留到下一步)
                                │
                                ▼
              ┌──────── 装配层分流(同一次 BeforeAgent) ────────┐
              │                                                 │
              │  ① researcher.md  → 没写 model 这行            │
              │  ② writer.md      → "inherit"                  │
              │        │                                         │
              │        └──► 走「继承分支」                      │
              │              直接用主 worker 已有的那个         │
              │              deepseek/deepseek-v4-flash 实例    │
              │              (不查 ModelRegistry、不新建)           │
              │                                                 │
              │  ③ code-review.md → "anthropic/claude-sonnet-4"│
              │        │                                         │
              │        └──► 走「指定模型分支」                  │
              │              调 ModelRegistry.Get(ctx, ref)     │
              │              ref = "anthropic/claude-sonnet-4" │
              │                    │                            │
              │                    ├─ 缓存命中(之前有别的      │
              │                    │    规格也写了这个 ref)    │
              │                    │    └─► 直接拿 map 里的     │
              │                    │         ChatModel 实例用   │
              │                    │                            │
              │                    └─ 缓存未命中(第一次用)   │
              │                         │                        │
              │                         └─► 与 TAKO_MODEL       │
              │                              走完全相同的链:    │
              │                              ResolveModel +     │
              │                              build 建客户端     │
              │                              → 成功:塞进缓存    │
              │                                         返回    │
              │                              → 失败:没配 Key / │
              │                                         厂商不  │
              │                                         存在等  │
              │                                         └─► 这  │
              │                                             条  │
              │                                             规  │
              │                                             格  │
              │                                             不  │
              │                                             装  │
              │                                             载  │
              │                                             +   │
              │                                             log │
              │                                             一  │
              │                                             行  │
              └─────────────────────────────────────────────────┘
                                │
                                ▼
              每条成功装载的规格 → ChatModelAgent{Model: 它拿到的实例}
                                │
                                ▼
                         包成 AgentTool → 挂进 runCtx.Tools
                         (本 run 的工具列表就齐了)
                                │
                                ▼
              同时产出一张「agent 名 → 生效 ref」的小表
              (例:researcher→deepseek/x,code-review→anthropic/s4)
              写帧、写 runlog 时,按 agent 名查出 ref,填进 `model` 字段
              (契约见 19v6-01 §2/§3)

ModelRegistry.Get 到底在做什么?(最小伪代码,30 行以内讲明白):

// ModelRegistry 就是进程内一张带懒加载的缓存表。
// 注意:这是解释性伪代码,不是产品代码。产品代码细节(double-check、锁粒度等)落地时再抠。
type ModelRegistry struct {
    mu    sync.RWMutex
    cache map[string]*ChatModel // key = ref,value = 已经建好的 HTTP 客户端
    env   Env                   // 进程启动时的环境变量快照(Key/BaseURL 都从这里读)
}

func (r *ModelRegistry) Get(ctx context.Context, ref string) (*ChatModel, error) {
    // 1. 先查缓存:之前有人用过这个 ref → 直接返回
    r.mu.RLock()
    if m, ok := r.cache[ref]; ok {
        r.mu.RUnlock()
        return m, nil
    }
    r.mu.RUnlock()

    // 2. 缓存空 = 第一次用到这个 ref。走与 TAKO_MODEL 完全相同的解析链:
    //    ResolveModelWithRef(r.env, ref) → 查出厂商、Key、baseURL、协议
    //    build(ctx, resolved)            → 按协议建对应的 HTTP 客户端(openai / claude)
    resolved, err := ResolveModelWithRef(r.env, ref)
    if err != nil {
        return nil, err // 没配这家的 Key / 厂商不在目录 / ref 格式错 → 上层拒载该规格
    }
    chatModel, err := build(ctx, resolved)
    if err != nil {
        return nil, err
    }

    // 3. 塞进缓存。下次同样的 ref 就不用再走解析 + 建客户端了。
    r.mu.Lock()
    defer r.mu.Unlock()
    if m, ok := r.cache[ref]; ok { // double-check:并发下可能别人刚好塞了
        return m, nil
    }
    r.cache[ref] = &ChatModel{Chat: chatModel, Protocol: resolved.Provider.Protocol, Ref: resolved.Ref}
    return r.cache[ref], nil
}

几个有意这样设计、不按直觉改的点(别看到进程内就想搬去共享存储):

6. 表新增汇总

表 新增 落地拍 说明
run_model_messages tool_calls TEXT、tool_call_id TEXT T2 ✅ OpenAI assistant/tool 形状;§8.2 已预告
runlog_entries agent TEXT(空=root)、payload TEXT(JSON) T2 ✅(两列,2026-10-08)/ T3(agent 非空) payload 单列 TEXT:结构化字段种类差异大、稀疏列展不开 tool_calls 数组;「零 JSONB」原裁针对消息表(§8.6 收口)
runlog_entries model TEXT(空 = 非模型产物) T3-2(2026-10-10 登记) 与帧同义的生效 ref(厂商/模型):user 行空 / root 行 = 主 ref / 子代理行 = 该规格生效 ref——md 改 model 的持久验证面(帧是 TTL 的实时视图,本列是永久真源)
sessions / runs 不动 — fork 的 forked_from 列随 T2 树状会话 loop 再加(§7)

7. 挂账(本 loop 不做)

8. 与既有篇的关系