端点不得吐(所有者裁定,ROUNDS.md R-TOOLS):execute 函数本体、ActiveWebSearchConfig 的任何字段 (baseUrl / key / model / provider)、dailySearchLimit 与当日用量、tool_config 的 enabled 状态。

派生式:新增工具时不需要再看这个面板一眼(所有者裁定 2026-09-02)

要解决的是「每次发版顺便处理一下 Tools 面板的展示」这件事本身。光把端点写成「遍历注册表」不够 —— 画板 1f/1g 上有两样 pi 的 ToolDefinition 没有的东西(工具分组、输出形态说明), 它们才是会反复要人手工补的地方。三条一起才成立:

1. 单一事实源 = META 常量。每个工具的展示字段与它的定义写在同一处,定义由 META 构造。 改 schema 必然改 META,面板不可能落后;面板永远不是第二个要改的地方。
2. 分组按注册路径派生,不手写。在 TOOL_REGISTRY → 纯函数组;在 SESSION_TOOL_REGISTRY → 会话绑定组; 走 makeWebSearchTool → 外呼组。分组本来就等于注册路径,手写只会写错。
3. 输出形态是 META 的必填字段(TypeScript 强制)。漏写不是「面板少一行」而是编译不过 —— 拦在写工具的那一刻,不是拦在发版前。

META 不许含配置值,这是结构性的而不是靠自觉:META 定义在闭包外面, makeWebSearchTool(cfg) 的 cfg 与 sessionRename(ctx) 的 ctx 在那个作用域里根本不存在。 今天没人往 description 里插「每日 N 次」,不代表明年没人插;放在闭包外面之后,插不进去。

已知的一个洞,要写进实现注释:派生只覆盖它认识的构造路径。今天是三条(两个注册表 + makeWebSearchTool), 将来有人加第四条构造路径且不进 META,派生法看不见它。验收 #2 的双向集合相等把这个洞收到 「加工具必经的两个地方」上 —— 见下。

验收

禁止

默认继承两条:不改前端页面样式(规则 7);不加设计稿没有的功能(规则 8)。本轮另加:

• 不做启停/限额展示。所有者已裁定面板只读且静态;想改口径回所有者层面重定,不在实现或审查循环里自行决定。
• 不碰工具的执行逻辑。把定义改写成 {...META, execute} 是本轮交付物,但 execute 体内、guarded、 loadEnabledTools 的注册与丢弃判断、配额、外呼实现一行不改;改写前后既有测试用例必须原样通过。
• 不为面板另建一份手工目录。那正是本轮要消灭的东西(见「派生式」一节)。
• 前端不得按工具名硬编码任何东西——没有 switch (tool.name)、没有 name → 中文/颜色 的映射表。 一律按后端给的 group 渲染(三组的色值是固定的,工具不是)。否则问题只是从后端搬到前端: 新工具在 API 里自动出现,在页面上却没文案没样式。
• 不新增迁移、不动 tool_config 表。
• 不改 Timeline / Chain View / Lifecycle Map 三个面板,也不改左侧聊天区与顶部导航。
• 不为「Timeline 的 tool_call 行点进去跳到 Tools」做联动——设计稿没有这条交互,想要就先改设计稿。

待所有者裁定(不要在本轮自行决定)

目录是静态的:5 个工具全列。若 web_search 未配置或被 tool_config 关掉,面板仍会列出它—— 这与「不显示启停状态」是同一枚硬币的两面。若所有者认为「列了但用不了」比「泄配置面」更糟, 再单独裁定改口径。

代码审查

• 审查方式:codex /codex:review --background --scope branch(分支对 main 的全量 diff)
• 轮次范围:第 1、2 轮全量(CLAUDE.md 审查范围:只有前两轮用固定全量范围)
• 一个操作坑:companion 用 process.cwd() 找仓库,Claude Code 的后台 Bash 任务不继承会话 cwd,第一次报 「This command must run inside a Git repository」;命令前加 cd <worktree> 即可

第 1 轮(1 条 findings:0×P1 · 1×P2)

整改内容与理由:

• 改的是契约描述,不是 capText。给标注预留空间等于改工具结果的实际内容长度(模型少看到几十个字符), 属工具执行逻辑,任务卡「禁止」段明写不碰;而且它是为一条 P2 新增行为,按 CLAUDE.md 审查边界不该做。
• 字段改名 resultCharLimit → resultBodyCharLimit,注释写清「正文预算,标注另加,整段结果可略长于 N」; 脚注文案加「正文」二字(「工具结果正文统一 8000 字符上限 — 超出显式标注截断,不静默丢尾」)—— 画板原句按字面读确实不准,改文案不改机制。
• 测试从「N 不截、N+1 截」收紧为「N 字符原样;N+1 字符 = 前 N 字符原样 + 标注,且总长 > N」,把这条语义钉死。
• dev.ps1 gen 重生成生成物(只有这个字段与注释变化,slug 噪音照旧还原两行)。
• 整改提交:062d4a1;整改后 dev.ps1 test 14 文件 291 用例全过、dev.ps1 check 通过、api/web tsc 0 错误、浏览器脚注实测。

第 2 轮(零 findings):全量复审(分支对 main)。原文:「No actionable correctness, security, or compatibility defects were identified in the changes. The new catalog endpoint, generated client integration, and Tools panel are consistent with the repository's design and security constraints.」

• 结论:整改后 PASS(缺陷门禁)。两轮共 1 条 findings(0×P1 · 1×P2),采纳整改;末轮零 findings。 合并 main 与「与 R11 的先后」按任务卡头部所述待所有者裁定。

失败处理

同一验收项针对性整改后连续 2 次验证仍不过 → 写 rounds/round-tools/BLOCKED.md,停下呼人。禁止放宽验收标准自我通过。

本轮实测

数字

• dev.ps1 test:14 文件 291 用例全过(新增 catalog.test.ts 12 个;既有 sandbox.test.ts / title.test.ts 未改一行)。dev.ps1 check 通过;tsc --noEmit 在 apps/api、apps/web 各 0 错误
• 端点实测(本机 GET /agent/tools):5 条、三组、响应体里除 schema 边界数字外没有任何数字;resultBodyCharLimit: 8000(codex 第 1 轮后改名,见「代码审查」)
• 改动面:后端 2 个新文件(端点 + 测试)+ tools.ts(META 抽取)+ websearch.ts(1 行:MAX_CITATIONS 加 export);前端 1 个新组件 + Workbench.tsx 3 处 + agent-api.ts 1 段 + 生成物;文档 3 处
• git diff -w 核对:五个 execute 体、guarded、loadEnabledTools、buildSessionTools 零改动(session_rename 的 execute 因外层多包了一层 Object.assign 而整体缩进 +2,-w 下为空)

派生式是怎么落地的(对照任务卡「派生式」三条)

1. 单一事实源:五份 META 常量各在自己的工具旁边,定义是 { ...META, execute }。ToolMeta.output 必填、ToolParametersSchema 只认本仓库用到的六个 JSON Schema 关键字 —— 类型不认的进不了 META
2. 分组派生:catalog.ts 的 toolCatalog() 只做三件事:遍历 TOOL_REGISTRY → pure、取 WEB_SEARCH_META → outbound、遍历 SESSION_TOOL_REGISTRY 的 factory.meta → session。没有 name → group 的表
3. 输出形态必填:output 在 ToolMeta 上没有 ?;outputNote 里的数字(50 / 160 / 10)全是模板字面量引用 MAX_ROWS / SNIPPET_CHARS / MAX_CITATIONS,常量改了文案跟着改
4. META 在闭包外面:WEB_SEARCH_META 是模块常量,makeWebSearchTool(cfg) 只是 { ...WEB_SEARCH_META, execute };SESSION_RENAME_META 同理。catalog.test.ts 用一份每个值独一无二的假 cfg 真的构造了一次工具,再 grep 响应 —— 一个值都没出来
5. 已知的洞已写进 toolCatalog() 的注释,兜底是测试的双向集合相等(目录 == 两个注册表 + web_search;tool_config 每个名字都有目录项)

踩的坑

1. worktree 里跑 dev.ps1 test 先红 3 条:sandbox.test.ts 外呼组三条报 ConfigEncryptionKey 未配置。原因是 apps/api/.secrets.local.cue 被 gitignore、只在主 checkout 里,新 worktree 没有;从主 checkout 复制一份后 14/14 全绿。是环境不是代码,与本轮改动无关
2. Encore 类型化端点支持 Record<string, T>(此前仓库里没用过,实测):生成物变成 { [key: string]: ToolParamSchema }。所以入参 JSON Schema 能原样吐出(properties 保持对象),不必为了过 Encore 解析器改成数组形态,前端也就不用把它再拼回去
3. pi 的 TSchema 在 TypeBox v1 里是空接口(export interface TSchema {}),任何对象都可赋值 —— 所以 ToolMeta.parameters 用自定义的 ToolParametersSchema 接口与 ToolDefinition.parameters 交叉时没有冲突。pi-ai 的 provider 适配层只取 name / description / parameters(anthropic-messages.js / openai-completions.js 源码核实),META 摊进定义对象的 output / phases 不会进模型请求
4. dev.ps1 gen 的 app slug 噪音再次出现(936eu → 3vpi6,worktree 是另一个本地 app id,BACKLOG R3 已记):只把那两行还原,其余生成内容(含 deleteSession 文档注释与源码同步)保留 —— 那是生成物本该有的样子

与计划的偏离

• makeWebSearchTool 与 websearch.ts 的 MAX_CITATIONS 加了 export。前者是让测试能「按真实构造路径」拿一份带假配置的定义与目录逐字段比对,并证明配置值进不了目录;后者是让 outputNote 的「来源最多 N 条」引用真实常量。两处实现体一行未动
• 端点响应多一个字段 resultBodyCharLimit(画板脚注「工具结果统一 8000 字符上限」)。它是代码常量不是配置值(不在库里、不在 env 里,设计稿上本来就印着);前端写死一个 8000 就是「第二个要改的地方」,与本轮要消灭的东西同类。测试把它钉在 capText 的真实行为上(N 字符原样;N+1 字符 = 前 N 字符 + 截断标注)。脚注文案比画板多了「正文」二字(「工具结果正文统一 8000 字符上限」):codex 第 1 轮指出 capText 是「正文截到 N 再追加标注」,整段结果会略长于 N,画板原句按字面读是不准确的;改文案不改机制(见「代码审查」)
• SessionToolFactory 从函数类型改成「可调用 + meta」接口(Object.assign(fn, { meta })):面板要读会话绑定工具的 META,而工厂需要 ctx 才能调用 —— 不想为了读一份描述先造一个绑着假会话 id 的工具。buildSessionTools 的调用形式 SESSION_TOOL_REGISTRY[name](ctx) 不变
• .claude/launch.json 加了 api 项:浏览器验证工具要起后端(powershell -File dev.ps1),此前只有 web。非产品代码
• 分组的中文名 / 组注 / 徽标文案在前端(ToolsPanel.tsx 的 GROUPS,按 group 键入):任务卡明确允许「按后端给的 group 渲染,三组的色值是固定的」;组名与组注同样是三组的固定属性(设计稿文案),不随工具变。放后端只会让端点多一段与工具无关的静态文案