跳转到内容
tool-bridge

发现、反馈与协作

tool-bridge 的价值不只是“能调用工具”，而是让调用者在执行前拿到当前身份的真实契约，并把验证过的经验留在能力旁边。推荐把发现和反馈做成每个 Agent 的默认循环。

底层的表示协商、direct/envelope 调用与错误处理见从 ~help 到调用；本页聚焦如何把 Search、Feedback 和管理员 Note 接进该循环。

标准循环

Section titled “标准循环”
确认身份 → 浏览/搜索 → 读取节点 help → 读取工具 schema
        → 查看 feedback → 最小调用 → 记录可复用经验

1. 确认目标与可见树

Section titled “1. 确认目标与可见树”
Terminal window
tb whoami
tb tree --depth 2
tb ls tools

树已经按当前 SK 的 read 裁剪。看不到路径不表示平台没有它；404 也可能是可见性保护。不要用不同错误响应枚举隐藏能力。

2. Search 是加速器，不是真源

Section titled “2. Search 是加速器，不是真源”

宿主启用全局 Search 时：

Terminal window
tb search "create document"

结果只包含当前身份可读且可调用的工具，并会回读节点做权限与工具表复核。但 Search 仍是派生索引，可能因宿主未启用而不存在。找不到结果时继续从 tree 和父路径 help 导航。

Context 自己的 tb ctx search 是另一种能力：它搜索 namespace 内的内容，并且只有该 provider 声明 Search 时存在。

3. 逐级读取 ~help

Section titled “3. 逐级读取 ~help”
Terminal window
tb help tools
tb help tools/docs
tb help tools/docs/search --json

节点级 help 用来了解子节点/工具索引；工具级 JSON help 给出完整 inputSchema。默认 Markdown 适合人和 Agent 阅读，DSL 适合紧凑传输：

Terminal window
tb help tools/docs --md
tb help tools/docs --dsl
tb help tools/docs/search --json

客户端应忽略 Help DSL 中不认识的新行，但不能忽略未知写入参数或安全字段。本站示例只建立方向感，schema 服从目标实例。

4. 调用前查看使用经验

Section titled “4. 调用前查看使用经验”
Terminal window
tb feedback ls tools/docs/search

列表只给摘要；需要完整 detail 时：

Terminal window
FEEDBACK_ID=fb_replace_with_real_id
tb feedback get tools/docs/search "$FEEDBACK_ID"

得分靠前的条目也会自动进入该路径 ~help。它们适合记录上游限制、正确参数组合、速率限制、权限前置或已验证的规避方式。

不应记录：SK/token、用户数据、完整敏感 payload、临时 incident 对话、未经验证的猜测。

5. 做最小、可验证的调用

Section titled “5. 做最小、可验证的调用”
Terminal window
tb call tools/docs/search '{"query":"tool-bridge"}'

优先选择 read-only、范围最小的参数。根据 help 中的 effect/confirm 判断风险；这些元数据帮助调用方决策，但服务端 call scope 仍是权威授权。

失败时先区分：

  • 401：身份无效；
  • 404：不存在或不可见；
  • 403：可见但缺动作权限；
  • invalid_argument：回到工具级 schema；
  • unavailable/rate_limited：结合 retryable 和已有 Feedback 决定退避或修配置。

6. 提交可复用 Feedback

Section titled “6. 提交可复用 Feedback”
Terminal window
tb feedback submit tools/docs/search \
  --title "先确认索引范围" \
  --detail "该上游默认只索引公开文档；私有空间需要额外授权。"

其他身份可以投票或撤回自己的票：

Terminal window
FEEDBACK_ID=fb_replace_with_real_id
tb feedback vote tools/docs/search "$FEEDBACK_ID" up
tb feedback vote tools/docs/search "$FEEDBACK_ID" clear

Feedback 权限落在目标路径：读取需要 read；提交和投票还需要 call；管理员删除需要 admin。根路径不接受 Feedback。

用不同身份验证这些 action 与 404 可见性时，按权限、SK 与可见性签发受限 SK。

Feedback 是低频、非权威协作数据。在 Workers KV 上并发提交/投票可能存在最终一致窗口；不要把它当事务、审计、审批或强一致排名。

管理员 Note 与 Feedback 的区别

Section titled “管理员 Note 与 Feedback 的区别”

管理员可给路径设置较稳定的说明：

Terminal window
tb note set tools/docs/search \
  "生产调用前必须确认 workspace；不得搜索未授权私有空间。"

Note 会进入 ~help，适合组织政策、长期前置条件或迁移通知；Feedback 适合使用者验证出的经验并可投票。两者都不能保存 secret。

读取与删除：

Terminal window
tb note get tools/docs/search
tb note rm tools/docs/search

成功证据

Section titled “成功证据”
  • 同一 SK 在 tree、help、Search 中看见一致的授权投影；
  • 工具级 help 的 schema 能解释成功/失败调用；
  • Feedback 列表、详情和 help 中头部条目一致；
  • 新提交 Feedback 可被其他有 read 的身份看到；
  • 去掉 call 后仍可读 Feedback，但不能提交/投票；
  • 管理 Note 更新后重新请求 ~help 可见。

常见失败

Section titled “常见失败”
现象 处理
Search 404 宿主未启用全局 Search；改用 tree/help
工具节点 help 没有完整 schema 节点级是索引；下钻到 <node>/<tool>/~help
Feedback 提交 404 目标路径不可见、悬空或是根路径
Feedback 提交 403 有 read 但没有 call
Feedback 被默认隐藏 净分低；管理员可用 tb feedback ls <path> --hidden 检查
调用失败但旧 Feedback 不适用 读取时间和实例契约，提交经验证的新条目，不盲从排名
Note 更新失败 set/rm 需要管理员权限；服务端校验是权威

清理与回滚

Section titled “清理与回滚”

投错票可以 clear；错误 Feedback 由管理员删除：

Terminal window
FEEDBACK_ID=fb_replace_with_real_id
tb feedback vote tools/docs/search "$FEEDBACK_ID" clear
tb feedback rm tools/docs/search "$FEEDBACK_ID"

错误 Note 用 tb note rm 移除。节点卸载后不要依赖其 Feedback 作为独立知识库；真正稳定的组织知识应进入受版本管理的文档，Feedback 只保留能力附近的短经验。

下一步

Section titled “下一步”