从 ~help 到调用

tool-bridge 的核心使用方式不是记住一份静态工具列表，而是在当前身份、当前路径和当前部署上读取运行时契约，再按契约调用。

本页面向 Agent、CLI 用户和客户端开发者。它解释稳定的发现算法和两种 HTTP 调用形状；具体工具名与参数来自目标实例对应层级的 ~help，可选 capability 来自 ~describe。

前置条件

• 一个可访问的 tool-bridge BaseURL；
• 一把至少能读取目标路径、并能调用目标工具的 SK；
• 可选：已安装 tb CLI。

还没有网关时，先完成5 分钟本地启动。

发现入口各自解决什么问题

入口	用途	关键边界
入口	用途	关键边界
———————––	———————————————––	—————————————————
/<node>/~help	读取节点说明、命令或工具索引	工具 Provider 的节点级结果不含完整 schema
/<node>/<tool>/~help	读取单工具的完整描述、调用路径与 JSON Schema	MCP/HTTP/Plugin/SDK Tool 的参数真源
/<path>/~tree	浏览当前路径下的可见子树	用来导航，不替代工具 schema
/<path>/~describe	读取 Search、Context、Skillhub 等可选 capability	未装配可选 capability 时可能返回 404
/~search	在启用 Search 的宿主中查找可调用工具	可选 capability；结果仍会按身份复核和裁剪
/<path>/~feedback	读取附着在路径上的使用经验	高分条目也可能进入 ~help
/<base>/~mcp	把当前 SK 可见的工具投影给 MCP Client	工具集合随身份和运行时变化

~search 并非所有部署都有。一键 Cloudflare 模板当前没有 D1 Search，公开 SDK 当前也没有 SearchIndex 注入项。调用前请求根 ~describe 并确认 capabilities 包含 search；未装配时 ~describe 或 ~search 返回 404 是预期的 fail-closed 行为。

1. 从父路径开始

CLI：

tb tree --depth 2
tb help tools
tb help tools/docs

HTTP：

curl \
  -H "Authorization: Bearer $TB_SK" \
  https://tb.example.com/tools/docs/~help

如果路径不存在或当前身份无权读取，服务端都可能返回 404。客户端不应借助错误差异枚举隐藏节点。

成功证据

返回内容来自目标路径，并且只列出当前 SK 可见的工具。不要以 Admin SK 的结果替代实际 Agent 身份验证。

2. 先读工具索引，再下钻完整 schema

~help 支持三种表示：

Accept	适用对象
未指定或 text/markdown	人类、通用 Agent、调试
text/plain	需要紧凑 token 表示的 Agent，返回 Help DSL
application/json	程序化客户端，返回结构化 Help JSON 和 JSON Schema

先请求节点级结构化帮助，取得工具名、摘要和 cmds[].path：

curl \
  -H "Authorization: Bearer $TB_SK" \
  -H "Accept: application/json" \
  https://tb.example.com/tools/docs/~help

对于 MCP、HTTP、Plugin 或 SDK Tool 节点，这一层是索引，不包含完整 inputSchema。选定 search 后继续请求工具级帮助：

curl \
  -H "Authorization: Bearer $TB_SK" \
  -H "Accept: application/json" \
  https://tb.example.com/tools/docs/search/~help

CLI 可以用对应的输出模式：

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

精确 flag 以当前安装版本的 tb help --help 为准。

程序应从工具级 Help JSON 的 JSON Schema 读取 required、类型、枚举和嵌套字段，不要从节点索引或 Markdown 示例反向推断 schema。Help DSL 的未知扩展行应被忽略，以便协议增量演进；未知的安全写入参数则不能静默接受。

Search 或 Context capability 使用独立的 ~describe：

curl \
  -H "Authorization: Bearer $TB_SK" \
  -H "Accept: application/json" \
  https://tb.example.com/~describe

3. 选择调用形状

tool-bridge 支持两种稳定 HTTP 形状。

直接调用工具路径

当 URL 已经指向一个具体工具时，body 直接是 arguments：

POST /tools/docs/search
Authorization: Bearer <scoped-sk>
Content-Type: application/json

{
  "query": "tool-bridge"
}

向节点发送工具信封

当请求指向工具节点时，body 包含工具名与 arguments：

POST /tools/docs
Authorization: Bearer <scoped-sk>
Content-Type: application/json

{
  "tool": "search",
  "arguments": {
    "query": "tool-bridge"
  }
}

builtin、Context、Skillhub，以及工具名无法安全放进单个 URL segment 的场景使用信封。普通 tool 节点可以使用工具级 ~help 中声明的直接调用 path；信封仍是所有节点 kind 的兼容入口。客户端不应从本站示例猜测 path 或参数。

CLI 同时支持两种表达：

tb call tools/docs --tool search --args '{"query":"tool-bridge"}'
tb call tools/docs/search '{"query":"tool-bridge"}'

具体工具与参数只是示例，请用节点级 ~help 选择工具，再用工具级 ~help 取得真实 schema。

4. 校验并处理结果

发送前用 Help JSON 中的 schema 校验参数。失败时读取稳定错误信封：

{
  "code": "invalid_argument",
  "message": "Human-readable summary",
  "retryable": false
}

• 程序分支使用 code，不要解析 message 文案；
• 只有 retryable: true 且请求本身幂等或可安全重试，才自动重试；
• 404 同时覆盖不存在和不可见，不应自动换 Admin SK 探测；
• rate_limited 应遵守退避，invalid_argument 应回到最新 schema 修正请求。

完整错误和分页约定见运行时 HTTP 契约速查。

推荐的 Agent 循环

1. 使用自己的 scoped SK 读取当前路径 ~help
2. 若目标不明确，读取 ~tree；根 ~describe 声明 Search 时才使用 ~search
3. 从节点 ~help 选择工具，再从工具级 ~help 读取结构化 schema 与高分 Feedback
4. 在本地校验 arguments
5. Tool 可按工具级 ~help 的 path 直接调用；通用实现可使用 envelope
6. 按错误 code / retryable 处理结果
7. 只有遇到可复用的真实经验时，向具体路径提交 Feedback

这个循环的关键是每次依据当前身份发现。节点挂载、virtualize、权限和 provider schema 都可能变化，静态 prompt 中的旧工具列表不能覆盖运行时事实。

MCP Client 如何进入同一循环

MCP Client 连接 /<base>/~mcp 后，tool-bridge 会把该 SK 当前可见的工具投影为 MCP 工具。它与“把一个外部 MCP Server 挂载到 tool-bridge”是相反方向：

• 挂载 MCP Server：MCP 是上游，tool-bridge 消费它；
• /<base>/~mcp：tool-bridge 是 MCP Server，外部 MCP Client 消费它。

两者都不产生绕过权限的新通道。

常见失败

~tree 看得到节点，但调用 404

可见通常需要 read，调用还需要 call。检查目标 SK 的 action；如果工具被 virtualize 隐藏或重命名，也应重新读取目标 ~help。

参数看起来正确但返回 invalid_argument

不要照抄本站示例或另一个实例的 schema。请求目标实例的 Help JSON，确认 required、枚举和字段类型。

~search 返回 404 或 semantic 模式被拒

先检查根 ~describe 是否声明 search 或 search:semantic capability。未声明的模式必须 fail closed。

/healthz 成功但任何带 SK 请求都失败

健康端点不验证认证数据面。检查 BaseURL、SK 是否属于该实例、是否 disabled/expired，以及宿主是否复用了旧状态。

下一步

• 阅读权限、SK 与可见性，用真实 Agent 身份重复发现循环；
• 参考运行时 HTTP 契约速查实现客户端；
• 接入内置集成、MCP或HTTP API验证完整流程。