从 ~help 到调用

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

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

前置条件

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

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

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

入口	用途	关键边界
/<node>/~help	读取节点说明、命令或工具索引	默认是索引、不含 schema；加 ?schemas=1 可一次带回该节点所有工具 schema
/<node>/<tool>/~help	读取单工具的完整描述、调用路径与 JSON Schema	单工具权威契约，含 outputSchema、示例；只取一个工具时最省 context
/<path>/~tree	浏览当前路径下的可见子树	用来导航，不替代工具 schema
/<path>/~describe	读取 Search、Context、Skillhub 等可选 capability	未装配可选 capability 时可能返回 404
/~search	在启用 Search 的宿主中查找可调用工具	可选 capability；结果仍会按身份复核和裁剪
/<path>/~feedback	读取附着在路径上的使用经验	高分条目也可能进入 ~help
/<base>/~mcp	把当前 SK 可见的工具投影给 MCP Client	工具集合随身份和运行时变化

~search 是可选 capability。标准 Node 装配 PG Search，公开 Embedded SDK 根入口默认不提供 SearchIndex 注入项。客户端先读取根 ~describe；未装配时使用树和节点 help 继续发现。默认 Search 返回 compact 结果，只有 detail: full 或 CLI --schemas 才请求完整参数 schema。

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。每个 cmds[].path 已经是包含命令叶子的完整可执行路径：

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

节点级结果默认是索引：每个工具一行，只给工具名和一句话摘要，不含 inputSchema。这样一个工具很多的节点也不会一次撑爆上下文。索引里“没显示 schema”不等于“没有参数”，Markdown 会区分“schema 未在索引展示”和“未声明参数”两种情况。

从这里有两条取 schema 的路径。需要单个工具的完整契约时，下钻工具级帮助——只取一个工具最省 context，并且它才返回 outputSchema 与完整 description：

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

想一次拿到整个节点所有工具的 schema，用可选快路径 ?schemas=1：

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

?schemas=1 只对 MCP、HTTP、Plugin/SDK Tool 以及设备代注册的 tool 节点有效；builtin、directory、Context、Skillhub 节点本就带全量 schema，该参数对它们无效果。它严格只认字符串 1，?schemas=true 或裸 ?schemas 都不会触发。工具很多的节点用它会显著增大响应，这正是默认保留索引形态的原因。

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

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

tb help <path> --schemas 对应 ?schemas=1。精确 flag 以当前安装版本的 tb help --help 为准。

程序应从结构化 Help JSON 的 JSON Schema 读取 required、类型、枚举和嵌套字段——无论它来自 ?schemas=1 的节点级 schema 还是工具级帮助，都不要从 Markdown 示例反向推断 schema。Help DSL 的未知扩展行应被忽略，以便协议增量演进；未知的安全写入参数则不能静默接受。

设备 tool 命令还可能在 cmds[] 带 delivery: realtime|mailbox|both。它描述命令能走哪些通道，不等于本次调用策略；调用方仍需显式选择 realtime、mailbox 或 fallback。离线设备及其 Mailbox-capable 命令不会因为 presence 为 offline 就从发现结果中消失。

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

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

3. 原样调用完整命令路径

tool-bridge 只有一种公开调用形状：POST <cmds[].path>，body 直接是 arguments 对象。命令是节点下的虚拟叶子；builtin、Context、Device、Skillhub、MCP、HTTP 和 Plugin/SDK Tool 都使用同一规则。

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

{
  "query": "tool-bridge"
}

CLI 使用相同路径：

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

不要用 node.path + cmd.name 重建命令身份，也不要向 owner 节点发送 {tool, arguments}；旧公开信封已经删除。路径段和命令名大小写不敏感、运行时规范化为小写；客户端仍应直接使用当前 cmds[].path，不要自行改写。具体命令与参数只是示例，请用节点级 ~help 选择命令，再用命令级 ~help（或节点级 ?schemas=1）取得真实 schema。

外部 Plugin 的 plugin/v2 endpoint 是网关内部传输边界，仍使用 {tool, arguments}。那不是调用方可见的 HTBP 路径，不能把两层 wire 互相套用。

Device Mailbox 仍复用同一条命令 POST，只在 arguments 顶层增加保留控制字段 ~delivery；CLI 对应 tb call --delivery。它不是第二个 enqueue command。fallback 只在 gateway 明确知道实时调用尚未派发时入队，详细行为见Device 离线投递与 Mailbox。

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 索引选择工具与高分 Feedback，再取 schema：单个工具下钻工具级 ~help，整节点批量用 ?schemas=1
4. 在本地校验 arguments
5. 原样 POST 到 cmds[].path，body 直接发送 arguments 对象
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 只接受 keyword，semantic 会被拒绝；Context 内的 search 是另一套 provider capability。

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

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

下一步

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