tako 文档 GitHub

搜索怎么接厂商:一个工具名,还是每家有每家的工具

模块:运行引擎 · 工具(doc/22 + tmp/22-网络搜索-切新api)|状态:已落地(2026-10-15 首版,2026-10-18 二稿换接口并改始终落盘)|证据:doc/22-网络搜索.md、internal/runengine/websearch.go

1. 场景与病灶

用户让 tako 查一句今天才能知道的公开事实,并在回答里给出处链接。

链路走到 researcher 就断了:agents/researcher.md 写着「当前没有联网检索能力」,父池里也没有搜索工具。它只能在终稿里写「未能查证」。公开网页上那句话,这次回答里不会出现。

要补的一环很小:researcher 在自己的消息里调用一个普通函数,程序去搜,把标题、链接、摘要写进这次 tool_result。researcher 据此写报告。主线程的上下文里仍然只有这份报告,不出现搜索原文。

真正难的不是「发一个 HTTP」,而是一个工具名怎么覆盖多家厂商:tako 的模型可以按租户、按子代理换成不同的 ref(deepseek/deepseek-flash、tencent-token-plan/deepseek-v4-flash……)。搜索如果不能跟着这次对话实际打到的厂商走,换个模型搜索就坏。

2. 候选与代价

候选 做法 好处 代价
A 厂商工具类型挂在聊天请求上 请求 tools 里写 {"type":"web_search"},厂商服务器自己搜 零本地实现 DeepSeek 的 Responses API 文档把这个类型标成忽略:请求能发出去、搜索不发生、模型仍可能用记忆回答。而且 tako 的验收要看 name=web_search 的帧——厂商在服务器里搜完写进回复时,这对帧不会出现
B 一律打 Moonshot POST /v1/tools/search(doc/17 §5 原建议) 不论聊天模型是谁,都打同一家按次接口 与当轮模型无关,换 ref 不会把搜索弄丢 把搜索绑死在一家身上;后来的决定是各家模型自己的搜索都放进同一个工具,不先绑死
C 两个工具名让模型挑 searchfree_search 和「DeepSeek 搜索」都注册 听起来灵活 两个名字都在时,模型会两个都调,或者挑听起来更强的那个;对方忽略内置搜索时,它还会用记忆写一份看起来查过的报告
D 单一工具名 + 内部按厂商选实现(选定) 工具名只有 web_search、参数只有 query;各家的搜索是函数内部的一行实现 模型看不见「厂商差异」,不会挑错;换 ref 时搜索跟着走 各家实现要分别手打验证;每次加一家要加一个函数

选 D。判断键是这次对话实际打到的厂商 id——生效 ref 里斜线前面那一段。

3. 厂商 id 从哪来(不要读 ADK 内部状态)

工具执行时要知道「谁在调用」。父池这一份函数主代理和 researcher 共用;researcher 的规格若写了 model:,两边的 ref 不同。用装配时写死的主 ref 会搜错端点。

候选:读 eino 的 react state AgentName。不能用——它对主代理的值是 "yktako" 而不是空字符串(空串 = 主代理只是帧事件层的约定),且那是 compose 图执行期的内部结构,eino 只为准出兼容性导出,工具读了就是焊死在别人的内部表示上。

改法是一个只干一件事的小 middleware:BeforeAgent 返回 context.WithValue(ctx, key, 名字)——eino 把这个 ctx 流进该 agent 的整张图执行,所以它触发的工具调用都读得到。主代理挂写 "" 的,子代理在装配处挂写规格名的。

工具执行时读标记:

4. DeepSeek 那一行:两次翻转

版本 做法 为什么被换
一稿(2026-10-15) Anthropic 兼容端点 + 服务端 web_search_20250305 + 模型按 citations 写 JSON 摘要 活体发现 10/10 全是「无摘要」:DeepSeek 的兼容层把 citations 标记为 Ignored,原始响应里连该键都没有。同日用户拍「先 fix 现在的」「不是换哦」——在现有 Messages 路上让模型搜完只回 [{"url","summary"}] JSON
二稿(2026-10-18 晚) 直打 POST https://api.deepseek.com/v1/tools/search,不经过模型 用户翻案「换成 DeepSeek 新 search api」——同日「不是换哦」裁定作废。新接口每条自带 summary(页面原文抽取),实测 0.43s(旧路 5.15s)、$0.75/千次、5 QPS。旧 Messages 路删除不兼容

关键差别:摘要从「模型转述」(依赖模型行为和 citations)换成「页面原文自带」——不依赖任何模型行为,快 10 倍,代价是摘要可读性从均匀成段的「读书笔记」变成极差 38 倍的「复印片段」(65–2492 字)。

请求细节:{"query":"<query>","need_content":false};只取 title/url/summary;无 url 的项丢掉、url 去重;results 空或去重后无 url → 这次搜索失败,走兜底。60 秒上限只兜「ctx 没被取消但厂商不回」;run ctx 取消时 HTTP 自动一起停。

5. 结果放哪:结果全文落盘,只回一段描述

候选 做法 好处 代价
A 结果内联进 tool_result 把 10 条标题+摘要全文返回 一次调用就够 一次搜索几千 token 灌进上下文;摘要越长越糟
B 超上限才落盘(一稿) 字节上限内内联,超了才写文件 小结果不走盘 模型看到两种形状;记忆/折叠链要处理两套
C 始终落盘 + 只回描述(选定,2026-10-18) 全文写 <workspace>/.tako/search/<runId>_<n>.md,工具返回条数、路径、token 数 形状恒定;上下文零负担;8192/800 的上限不再需要 模型要多一步 read_file 才能看内容

选 C。file_effect 从 none 改成 write——文件名是程序命名的、一次一写、永不覆盖,与 search_history 截断落盘同性质(提取程序只扫调用参数,参数里只有 query 没有 path,不靠猜 query 字符串记账)。

描述段每个成分都有用途:条数让模型判断有没有命中;token 数给「读不读」提供代价感(数字来自引擎折叠链的同一份 TokenCounter,两本账不打架;counter 为 nil 时不报,宁缺不发明「字节÷4」);路径指到落盘文件。

落盘写失败或旁路调用没有 noteBox 时,降级为「结果仅本次可见(未能写入文件)」——模型必须知道内容去哪了。

6. 同族小裁定

小问题 裁定 代价 / 备注
工具名 只有 web_search,参数只有必填 query 不加第二个名字;以后加一家只是表里加一个函数
查询上限 超 128 字截到 128,不报错 接口收 1–128 字、超了整次 400;检索词截断无信息损失争议,报错只会白烧一次兜底
空查询 不发 HTTP,Go error「查询是空的」 由 wrapToolErrors 包成「错误:」开头
兜底 searchfree 没有厂商实现 / 密钥缺失 / 厂商失败时打 https://searchfree.site/api/search 它是脚手架;转正不在本篇。查询原文会发到这个站点,站点不稳定(2026-10-18 探针 RemoteDisconnected)
两处都失败 Go error 串联两句原因,模型看见「错误:」,run 仍 complete 不把半截响应当结果
失败原因写法 只有 HTTP 状态或一句短错误 不贴响应正文、不贴密钥
结果为空 成功但去重后一条链接都没有 = 失败 不把空结果交给模型
researcher 怎么拿到它 进父池;researcher 用 exclude_tools(只排 bash)继承,有效名单含 web_search TestShippedAgentSpecToolGuards 金样钉住——有人把 web_search 写进排除项,go test 就红
要不要再包成子代理 不包 包成子代理的话主线程收到的是搜索器写的综述,综述把标题和链接吞掉,帧上的 name 也不再是 web_search
fetch_url 本篇不做 抓整页是折叠之前最容易撑满窗口的动作
不接的厂商 Moonshot、智谱、Brave、Tavily、Google 以后加一家:表里加函数,先用那家密钥手打一次,响应里要有 http;打不通的不登记

7. 证据

方案:doc/22-网络搜索.md §2(三种接法对照)§3(工具契约 + 始终落盘装配)§4(按厂商选择 + ctx 标记)§5(deepseek 行,2026-10-18 晚整节重写)§6(searchfree 兜底)§7(researcher 规格)§8(不做清单)。

台账:tmp/22-网络搜索/(首版)、tmp/22-网络搜索-切新api/(二稿)。旧 Messages 路的台账 tmp/22-网络搜索-摘要修复/ 已于 2026-10-21 清理。

代码符号:

位置 是什么
internal/runengine/websearch.go:29 callerNameKey:ctx 标记键
internal/runengine/websearch.go:43 callerStampMiddleware:BeforeAgent 写调用方名字
internal/runengine/websearch.go:54 webSearchDesc:工具 schema 说明
internal/runengine/websearch.go:67 newWebSearchTool
internal/runengine/websearch.go:73 webSearchFn:按厂商选实现 + 兜底链
internal/runengine/websearch.go:151 deepseekSearch:直打 /v1/tools/search
internal/runengine/websearch.go:193 searchfreeSearch:兜底
internal/runengine/websearch.go:264 renderSearchFile:落盘文件格式
internal/runengine/websearch.go:281 describeSearchResult:描述段

复核命令:

cd yk-tako-eino
grep -n "tools/search\|searchfree.site\|callerStampMiddleware" internal/runengine/websearch.go
grep -n "web_search" internal/runengine/agents_test.go
grep -n "web_search" agents/researcher.md

活体验收(2026-10-15 首版,2026-10-18 二稿):A1 手打两家端点(DeepSeek web_search_tool_result 10 条含 http);二稿手打 /v1/tools/search count=10 0.43 秒返回 10 条、每条带 snippet/summary;同 query 摘要 619–796 字节、terminal complete。

8. 现状