Agent X-Ray

Runtime Notes Skills Source About

Source/

正在取 rounds/round-websearch/round-websearch.md…

FILES

这是本站自己的源码,与线上运行的版本一致;快照随每次发版更新。

苏ICP备2025204887号-2

苏公网安备32011402012723号

Source/rounds/round-websearch

round-websearch.mdMIT

本站自己的源码,只读浏览:左边点文件,右边看内容。

快照 4131b57 · 发布 2026-09-10 · 350 个文件 · 3.8 MB

GitHub ↗

FILES

apps/

deploy/

docs/

rounds/

round-01/

round-02/

round-03/

round-04/

round-05/

round-06/

round-07/

round-08/

round-09/

round-10/

round-11/

round-bun/

round-cards/

round-cards2/

round-crosslink/

round-gsearch/

round-imagegen/

round-leak/

round-mobile/

round-mobile2/

round-perf/

round-skills/

round-source/

round-tabs/

round-title/

round-toolcards/

round-tools/

round-usage/

round-visitor/

round-webfetch/

round-websearch/

round-websearch.md20.9 KB

BACKLOG.md66.5 KB README.md1.8 KB TEMPLATE.md1.4 KB

runner/

tools/

.gitattributes0.5 KB .gitignore1.6 KB .gitleaks.toml3.6 KB AGENTS.md2.5 KB CLAUDE.md50.2 KB LICENSE1.0 KB README.md3.8 KB ROUNDS.md142.5 KB dev.ps128.9 KB skills-lock.json1.8 KB

rounds/round-websearch/round-websearch.mdmarkdown · 20.9 KB · 243 行

copy

Round WEBSEARCH — agent 联网搜索工具(第一个外呼组工具)

状态:已完成(2026-09-02;所有者裁定不发 130,四条 130 实跑验收并入下一次预发升级,见「本轮实测」末段)

轮次编号沿用 R-BUN / R-VISITOR 的横切轮命名(非 R0–R11 线性序列的一员)。插在 R11 之前:上线之后再动 agent 的工具集,等于让生产环境当第一个试验场。

目标

给 pi agent 加一个 web_search 工具:经 Responses API 网关在服务端完成检索与综述, 返回一段带来源的答案;端点/凭据/限额经 MCP 管理面配置;搜索的过程在右栏三视图里看得见。

可证伪:配好 provider 并开启工具后,问一个模型知识截止之后的问题, ① 对话区给出带来源链接的答案;② 右栏 Timeline 出现 tool_execution_start · web_search → tool_execution_update · web_search ×N → tool_execution_end · web_search; ③ SSE 原始流里搜不到 Authorization / key 明文。

前置

R6(MCP 管理面 + ConfigEncryptionKey 加密入库)、R7(工具注册与 tool_config、daily_quota)已完成
需要一个目标域白名单内的搜索网关凭据(DeepSeek 或自建 AI 网关),经 MCP 写入,不入 Git
130 预发可用(R9/R-VISITOR 留下的 compose 形态)

范围裁定(开工前确认,写在这里免得后面反复)

问题	裁定	理由
规则 8(不实现设计稿没有的功能)是否被触发	否	design/Agent Runtime Workbench.dc.html:1162 就画着 mkTool('web_search', 'MCP', '外呼', '联网搜索(服务端 key · 域白名单 · 计入日限额)', 'on'); §1 开篇与第 4 层也早写了「后续生图、联网搜索等插件」。本轮是,不是长新功能

这是本站自己的源码,与线上运行的版本一致;快照随每次发版更新。

补齐既定边界

文档(规则 9:先改文档)

docs/security.md —— 威胁模型加第 5 条(外部内容注入);§1 第 1 层加「工具分两组」表 + 外呼组六条附加约束;第 2 层表清单补 websearch_config;第 4 层加 R-WEBSEARCH 落地补记;§3 加 websearch key 口径
ROUNDS.md —— 进度表加行 + 本轮拆解
rounds/round-websearch/round-websearch.md —— 本卡

apps/api/agent/migrations/008_websearch.up.sql —— websearch_config 表 + daily_quota.searches 列 + web_search 启停种子(默认关)
apps/api/agent/secrets.ts —— ConfigEncryptionKey 声明抽出(现在有两个消费方)
apps/api/agent/websearch-config.ts —— 运行期 websearch 配置的只读来源(读不到回 null 而非抛)
apps/api/agent/websearch.ts —— 外呼实现:域白名单 / responsesUrl / SSE 解析 / 双计时器 / 字节上限 / 来源抽取 / 阶段上报
apps/api/agent/tools.ts —— makeWebSearchTool 工厂 + ToolRefusal + loadEnabledTools 消费 websearch 配置(含指纹)
apps/api/agent/quota.ts —— reserveSearch(一条带条件的原子 UPSERT)
apps/api/agent/runtime.ts —— 重建日志改打工具名(指纹现在含 sha256)
apps/api/mcp/store.ts + apps/api/mcp/tools.ts —— 四个 websearch_* 管理 tool

apps/api/agent/websearch.test.ts(注入 fetch,不打真实网络)
apps/api/agent/sandbox.test.ts / mcp.test.ts 增量用例

#	检查	命令 / 期望
1	编译与测试全绿	dev.ps1 check + dev.ps1 test 全过,且 npx tsc --noEmit 干净(复审第 1 轮加:前两者都不跑全量 tsc)
2	迁移 008 可施加且幂等	本机 dev.ps1 起库自动跑;deploy/migrate.sh 在 130 上重跑不报错
3	域白名单挡得住	单测:https://evil.tld/v1、https://api.deepseek.com.evil.tld、http://api.deepseek.com(非 https)、带内嵌凭据的 URL 全部被拒;MCP 写入侧同样拒
4	访客控不到网络原语	静态核验 + 单测:runWebSearch 的 URL/headers/model/toolType 只来自配置;query 只进 body 的 input,且有 300 字上限(schema maxLength)
5	SSE 解析正确	单测:delta 累积 / response.completed 优先 / response.failed 与 response.incomplete 报错 / [DONE] 与半条 JSON 不炸 / 非 text/event-stream 时按普通 JSON 降级
6	双计时器与字节上限	单测:空闲超时与总超时分别产出对应 kind;超过 4 MiB 中断
7	凭据不外泄	单测:任何抛出的 message 与 details 都不含 apiKey;/trace/stream 抽查无 Authorization;websearch_providers_list 只回掩码
8	限额生效且原子	单测:daily_search_limit=N 时第 N+1 次 reserveSearch 回 false;并发调用不超发
9	未配 provider 时不注册	单测:tool_config 开着 web_search 但表空 → loadEnabledTools 丢弃并记日志,names 不含它
10	配置变更下一轮生效	单测:改 websearch 配置 → EnabledTools.fingerprint 变化(会话据此重建)
11	右栏看得见搜索流程	130 实跑:Timeline 出现 tool_execution_update · web_search ×N;Lifecycle 的 tool_call / tool_execution / tool_result 三节点点亮;进度条数受 MAX_PROGRESS_EVENTS(30)封顶
12	MCP 四个 tool 可用	130 上 websearch_provider_upsert → websearch_providers_list → websearch_set_default → websearch_provider_delete 全通,写操作进 mcp_audit
13	DeepSeek 与网关两条配置都跑得通	130 实跑:同一份代码分别配 api.deepseek.com 与自建网关,各搜一次都拿到带来源的答案
14	前端零改动	git diff --stat apps/web/ 为空

不改前端页面样式(规则 7)。本轮连组件都不碰:搜索流程走既有的 34 事件通路进视图
不加设计稿没有的功能:不做 Perplexity、不做「抓指定网址」(2026-09-03 起「读访客指定网址」由 R-WEBFETCH 以沙箱执行组 egress 档的 skill web-fetch 承担,不在 api 进程内、不经本工具;本条对 web_search 一字不改)、不做搜索结果缓存表
不给工具任何形式的 URL / host / header 入参——那是 SSRF,不是搜索
不把 websearch 的 token 折进 daily_quota.tokens(那是聊天 provider 的账)
不在工具体内读 process.env / 读库 / 解密

审查方式:/codex:review --background(changes against main;前两轮用全量范围)
结论:整改后 PASS。四轮共 6 条 findings(3×P1 + 3×P2)全部核验属实、全部采纳整改, 没有一条以「概率低」「会被替换」为由放行;第 4 轮零 findings,缺陷门禁关闭 (第 3/4 轮按 CLAUDE.md 收到「上一轮整改 diff」:--base 0c36322 / --base 4355cdf)

第 1 轮(2026-09-01,基线 4f338e1)

#	级别	findings	核验	处理
1	P1	fetch 默认跟随重定向,而白名单只校验原始 URL —— 白名单内端点上的开放重定向可把请求送到白名单外/内网	属实,且比描述更严重:bun 实测同源重定向下 Authorization: Bearer … 原样跟过去(见下)	采纳:redirect: "manual" + 3xx 单独判为 kind:"redirected"。判据写进 docs/security.md §1 外呼组约束 2
2	P1	systemPromptFor 把 web_search 混进「它们不能访问服务器或网络」那句;且 promptSnippet/promptGuidelines 走 systemPromptOverride 后送不到	属实。前半:提示词逐字在说这个联网工具不能联网。后半:pi 源码 resource-loader.js:383 是 override ? override(base) : base,我们的实现忽略入参 → base 里那两节丢失	采纳:提示词按两组分段;注入防御从 promptGuidelines 搬进 systemPromptFor,并在工具定义处留注释挡住「再加回去」
3	P2	非流式 JSON 走 res.json(),整体缓冲、绕开 MAX_RESPONSE_BYTES	属实,且同一问题还存在于错误体的 res.text()(codex 没提到那一处)	采纳:抽 readTextCapped,流式 / 非流式 / 错误体三条路径共用同一个上界

三条都补了回归用例(整改后 dev.ps1 test 12 文件 / 260 项全过,较整改前 +7): redirect 模式与 3xx 拒绝 · 非流式 JSON 的 4 MiB 上界 · 非 JSON 非 SSE 回 upstream_failed · systemPromptFor 分组四条(含「教程库那一句的名字列表里不许出现 web_search」)。

这一轮 codex 的价值主要在第 2 条:那是个不会让任何东西报错的缺陷 —— 编译过、测试过、搜索也偶尔能用,只是模型收到一条自相矛盾的高优先级指令,表现为「时灵时不灵」。本机门禁与我自己的用例都照不到它,因为它根本不在代码的行为里,在提示词的语义里。

第 2 轮(2026-09-02,基线 0c36322;仍为全量范围)

#	级别	findings	核验	处理
4	P1	abortCause 的比较过不了 tsc --noEmit(TS2367);「blocks encore check/the build」	前半属实:实测 tsc --noEmit 报两条 TS2367 —— TS 不追踪闭包里的赋值,按「初始 null + try 块里那次直接赋值」把变量窄化成 "oversize" \| null。后半不成立:dev.ps1 check 与 dev.ps1 test 都是绿的,Encore 的构建也不跑 tsc	采纳:改成「掐断时直接存要抛的 WebSearchError」,判据变成一次真假判断,不再有字符串比较;顺带去掉了那条永远走不到的 oversize 分支与重复的消息拼装。整改后 tsc --noEmit 干净
5	P2	readTextCapped 读缓冲响应体时不重置空闲计时器 —— 响应头很快、body 慢的上游会在持续有数据的情况下被空闲超时掐掉	属实,且是我上一轮引入 readTextCapped 时带进来的(此前 res.json() 同样不重置,只是没人看得见)	采纳:readTextCapped(res, onChunk),两个调用点都传 resetIdle,与 SSE 路径同一套判据

两条都补了回归用例(dev.ps1 test 261 项全过):非流式响应分块慢送(每块 40ms、空闲窗口 60ms)必须成功而不是被自己掐死;tsc --noEmit 纳入本轮验收 #1。

这一轮暴露了一个门禁的洞:dev.ps1 check 与 dev.ps1 test 都不跑全量 tsc。不是构建阻塞(Encore 的构建也不跑),但类型错误只能靠 IDE 或人工发现。补门禁属新增机制、不在缺陷整改范围,已记 rounds/BACKLOG.md 待所有者裁定; 本轮自己每次整改后手动跑 npx tsc --noEmit。

第 3 轮(2026-09-02,--base 0c36322 —— 只审上一轮的整改 diff)

#	级别	findings	核验	处理
6	P2	SSE 超限分支只抛错、不再 abort 也不 cancel 已锁定的 reader,底层连接可能一直活着;重复触发会积累连接与缓冲	属实,而且是我上一轮自己引入的回归。删 ctrl.abort() 时我写的注释是「ctrl 随作用域结束」—— 那句话是错的:AbortController 被 GC 不会取消 fetch。readTextCapped 自己 finally 里有 reader.cancel(),唯独 SSE 这条路径没有	采纳,但不按 findings 的建议只补那一个分支:把 ctrl.abort() 收进 runWebSearch 的 finally。分支会长新的(将来多一种中途失败就多一处漏),而「离开函数 = 连接一定被放掉」是不会漏的结构性保证;成功路径上流已读完,那次 abort 是无害空操作

回归用例覆盖三条离开路径(中途抛 / 读完后抛 / 正常成功),判据是「传给 fetch 的 signal 最终是否 aborted」—— 真实 fetch 正是靠它断连接的。dev.ps1 test 262 项全过。

第 4 轮(2026-09-02,--base 4355cdf)

零 findings。 审查者原文:「The change correctly aborts the internal fetch controller in the function's finally block, covering success, upstream failure, timeout, cancellation, and oversize paths without altering the public result behavior. TypeScript compilation succeeds, and no additional blocking issues were identified.」

(第一次跑到一半被会话中断、无完成记录,重跑一次得到上述结论;两次都是 --base 4355cdf。)

第 3 轮的教训比 findings 本身重要:上一轮我为了修 P1 顺手删了一行 ctrl.abort(), 并给它编了一个听起来合理、实际错误的理由(「随作用域结束」)。整改动作本身也会引入缺陷, 这正是缺陷门禁要求「有采纳整改就必须再发一轮复审」的原因;把第 3 轮范围收到整改 diff 恰好让这类回归无处可藏。

同一验收项针对性整改后连续 2 次验证仍不过 → 写 rounds/round-websearch/BLOCKED.md,停下呼人。

本机门禁(2026-09-01)

dev.ps1 check:通过(迁移 008 施加成功,app 起得来)
dev.ps1 test:12 文件 / 262 项全过(本轮新增 29 项;基线 233)。其中 10 项是 codex 三轮 findings 的回归用例,见「代码审查」段
npx tsc --noEmit:干净(复审第 1 轮起纳入验收 —— 前两条命令都不跑全量 tsc)
git diff --stat apps/web/ 为空 → 验收 #14(前端零改动)通过

测试抓到一个真凭据泄漏(验收 #7 的用例直接红)。runWebSearch 原先把上游 4xx 的响应体原样拼进 WebSearchError.message,而网关会把请求头回显进错误体 —— 于是明文 key 进了错误对象。
- 第一反应「调用点已经 safeErrorText 了」是错的:那只保证写进日志的那一行干净, 而一个带着凭据的 Error 会被传递、被别处 catch、被将来某个人直接 console.error(err)。
- 修法是在构造错误的地方就抹掉(redactUpstream),而且要两道:scrubString 打通用形态 (sk- 前缀 / Bearer …),再叠一道本次 key 的精确替换 —— 自定义网关的 key 常是纯十六进制, 通用模式一个都匹配不上。补了一条专门的用例钉住后半道。
zod 4 静默吞掉 .refine 的「函数形式 params」(自查时抓到,没等到审查)。 .refine(check, (v) => ({ message: … })) 是 zod 3 的写法;zod 4.5.4 下它 不报错、不抛,只是把错误消息退回成一句 "Invalid input"(bun 实测)。后果是 websearch_provider_upsert 拒掉一个坏 baseUrl 时,所有者看到的是「Invalid input」而不是「host 不在白名单 / 没写 https / 带了 query」—— 而那句理由正是这个 tool 最有用的产出。改用 superRefine + ctx.addIssue。
- 连带补了一层此前完全没有的测试:mcp.test.ts 原来只测 store 函数, 一个字都照不到 MCP 的入参 schema。新增用假 server 收下 registerTools 的注册配置、再拿真 schema 去 parse 的用例组(baseUrl 六种坏形态 / toolType 白名单 / 超时上下界与库 CHECK 一致),这类「schema 静默不生效」以后会红。
.secrets.local.cue 不随 worktree 走(gitignored)。loadActiveWebSearchConfig 要解密, 没有 ConfigEncryptionKey 时它会走「解不开 → 返回 null」的分支 —— 正例测不了。从主 checkout 拷一份进 worktree 即可(仍不入库)。顺带发现该文件的注释里早就写着 apps/api/{mcp,agent,metrics}/secrets.ts,而 agent 侧此前把声明内联在 llm-config.ts 里; 本轮抽出 agent/secrets.ts 之后那句注释才成立。
dev.ps1 gen 的产物有无关漂移,已回退:apps/web/lib/api-client.ts 只变了两处 —— app slug(936eu → hvcca,BACKLOG 里 R3 那条已记:slug 随生成所在 checkout 变) 与一段 R-VISITOR 时期没跟着重新生成的过期注释。本轮没有新增任何端点, 所以整份回退,不让它污染审查范围。

域白名单落在 shared/websearch-hosts.ts 而不是 agent/websearch.ts:写入侧(mcp)与调用侧(agent) 都要用同一份判据,而 docs/security.md §4 要求两个面互不 import —— 与当初把 redact.ts 下沉到 shared/ 是同一个理由。
多了一个 ToolRefusal:guarded 原先把所有异常换成同一句「查询失败」。对搜索来说「今天额度用完了」和「上游超时」是模型应当据以改变策略的信息(别重试、改用已有知识), 而不是又一次偶发失败。文案仍是本文件写死的常量、仍走 throw(isError 仍为 true), 安全性质与原来完全相同。
store.ts 里重复了两个超时默认值(为了在写入前判 idle > total,给所有者一句能行动的话, 而不是把 CHECK 冲突变成「详见服务端日志」)。重复常量的一致性由测试钉住: mcp.test.ts 从 information_schema.columns 读列默认值比对,漂移就红。

codex 第 1 轮实测补记

fetch 的三种 redirect 模式在 bun 下的实际行为(本地起 http server 实测, 不是照着规范推的)——这条决定了修法选 manual 而不是 error:

text

follow → status 200  body: {"reachedEvil":"/evil","auth":"Bearer sk-secret"}   ← 凭据跟着跳过去了
manual → status 302  type default                                              ← status 可读,能给确定的错误
error  → THREW TypeError UnexpectedRedirect ...                                ← 只能拿到一个笼统异常

选 manual:error 抛出的 TypeError 会掉进通用的 upstream_failed 分支, 「网关配了个重定向」于是看起来像一次普通的上游报错,排查时分不出来。

所有者裁定:本轮不构建镜像、不发 130(2026-09-02)

审查门禁关闭后,所有者裁定直接合并 main 并 push origin,不打包、不发 130 验证。于是验收表里四条依赖 130 实跑的项本轮未执行,并入下一次预发升级(R11 之前的任一次升级都行):

#	未执行的检查	届时怎么验
2	deploy/migrate.sh 在 130 上施加迁移 008	./migrate.sh --status 应显示 7 → 8;重跑为空操作
11	右栏看得见搜索流程	Timeline 出现 tool_execution_update · web_search ×N;Lifecycle 三节点点亮
12	MCP 四个 websearch_* tool 可用	tools/list 从 24 变 28;upsert → list(只回掩码)→ set_default → delete 全通,mcp_audit 有记录
13	DeepSeek 与自建网关两条配置都跑得通	同一份代码分别配 api.deepseek.com 与网关,各搜一次都拿到带来源的答案

为什么这条不是「验收放宽」:本机能验的都验了(域白名单 / 请求形状 / SSE 解析 / 双计时器 / 凭据不外泄 / 限额原子 / 注册闸 / 指纹 —— 全在 dev.ps1 test 里);剩下四条的本质是「真实网关 + 真实 compose 拓扑」,它们在哪一次升级里验都是同一件事。web_search 的种子行 默认关、且没配 provider 就不注册,所以这份代码上到任何环境的默认行为与合并前一模一样 —— 延后验证不引入任何未验证的默认路径。

已经为下一次预发升级备好的东西(本轮实测,不用再摸):

130 当前 IMAGE_TAG=7cc17fe、迁移版本 7、四个容器 Up;ssh 130 别名可用
2026-07-28 的逐请求契约(直接对 /api/mcp 发 JSON-RPC 时,四样缺一不可,少一样各回一种 -32602 / -32020):MCP-Protocol-Version: 2026-07-28 头 · Mcp-Method 头(=body.method)· tools/call 时再加 Mcp-Name 头(=params.name)· params._meta 里带 io.modelcontextprotocol/protocolVersion 与 io.modelcontextprotocol/clientCapabilities。部署前基线已抓:130 @ 7cc17fe 的 tools/list 共 24 个、websearch_* 为 0
升级顺序不变:stop api web → up -d --wait postgres → ./migrate.sh → up -d; 然后由所有者经 MCP 跑 websearch_provider_upsert(key 只能由所有者本人填)+ tool_config_set{web_search, enabled:true},再问一个知识截止之后的问题看右栏

Round WEBSEARCH — agent 联网搜索工具(第一个外呼组工具)

目标

前置

范围裁定(开工前确认,写在这里免得后面反复)

交付物

验收

禁止

代码审查

第 1 轮(2026-09-01,基线 4f338e1)

第 2 轮(2026-09-02,基线 0c36322;仍为全量范围)

第 3 轮(2026-09-02,--base 0c36322 —— 只审上一轮的整改 diff)

第 4 轮(2026-09-02,--base 4355cdf)

失败处理

本轮实测

本机门禁(2026-09-01)

踩到的坑

与计划的偏离

codex 第 1 轮实测补记

所有者裁定:本轮不构建镜像、不发 130(2026-09-02)