跳转到内容
tool-bridge

运行时 HTTP 参考

本页描述客户端实现时需要的当前版本公开 HTTP 形状，不替代目标实例的运行时自描述，也不承诺跨 pre-launch 版本保持不变。精确工具名、命令、JSON Schema、Search capability 和可见路径必须以对应版本实例返回为准；升级前还要核对 release notes 与对应版本代码。

BaseURL 与认证

Section titled “BaseURL 与认证”

业务请求以网关 BaseURL 为根，通常使用 Bearer SK：

Authorization: Bearer tbk_...

缺失、未知、已禁用或已过期的 SK 返回 HTTP 401，body 仍使用 permission_denied。不要在 URL、query、日志或错误报告中传递 SK。

少数树外路由无需 Bearer：GET /healthz、Dashboard 静态资源、OAuth callback，以及携带自身限时签名 token 的 ~ref 下载。公开不等于能证明业务数据面健康。

路径模型

Section titled “路径模型”
  • 树路径用 / 分隔，按 segment 比较；
  • 根路径在运行时用空 path 表示，HTTP 上对应 BaseURL；
  • 普通节点路径不能包含空段或 ~ 保留段；
  • system、ui 是基础保留根，部署可追加；
  • URL segment 应逐段编码，不要把 / 编进单个工具名再依赖服务端猜测。

当前保留段包括 ~help、~tree、~search、~feedback、~mcp、~register、~describe、~authorize、~skill。客户端不应注册这些名字。

端点总览

Section titled “端点总览”
方法与路径 认证 作用
GET /healthz 否 进程/Worker 健康与版本摘要，不是完整 readiness
GET /~help 是 根帮助和当前身份可见顶层节点
GET /<path>/~help 是 节点帮助；工具子路径可返回单工具完整 schema
GET /<path>/~tree?depth=N 是 当前身份裁剪后的子树；根用 /~tree
POST /~search 是 可选全局工具搜索；宿主未启用时 404
POST /<node> 是 信封调用 {tool,arguments}
POST /<node>/<tool> 是 直接工具调用，body 是 arguments
GET/POST/DELETE /<path>/~feedback... 是 读取、提交、投票和管理路径 Feedback
ALL /~mcp 是 将当前 Bearer 身份动态投影成 MCP server
GET /system/device/ws?deviceId=... 是 WebSocket upgrade，Device 反向连接
POST /<path>/~register 是 高级反向注册入口，受 register/registerPaths 约束
POST /<path>/~authorize 是 受支持节点的网关托管 OAuth 发起

Dashboard 位于 /ui/；OAuth callback 和 ~ref 主要由网关生成的流程使用，客户端不应自行构造 token/state。

~help 内容协商

Section titled “~help 内容协商”
Terminal window
curl -H "Authorization: Bearer $TB_SK" \
  https://tb.example.com/tools/docs/~help


curl -H "Authorization: Bearer $TB_SK" \
  -H "Accept: application/json" \
  https://tb.example.com/tools/docs/search/~help
Accept Content-Type 用途
缺失、未知或 text/markdown text/markdown; charset=utf-8 人与通用 Agent 阅读，默认
text/plain text/plain; charset=utf-8 紧凑 Help DSL
application/json application/json; charset=utf-8 结构化 Help JSON 和 JSON Schema

节点级工具帮助通常是索引形态；对 <node>/<tool>/~help 下钻获取完整 input/output schema。Help DSL 消费者应忽略未知新行以支持协议演进，但写请求的未知参数不能静默忽略。

~tree

Section titled “~tree”
Terminal window
curl -H "Authorization: Bearer $TB_SK" \
  -H "Accept: application/json" \
  'https://tb.example.com/~tree?depth=2'

树默认深度 2，上限 8。响应节点包含 path、kind、description，以及可选 online/children/truncated。truncated:true 表示深度、总节点预算、remote 边界或环检测阻止了完整展开；客户端应继续对需要的子路径查询，而不是把未返回节点判定为不存在。

非根子树 path 必须是真实且可见的节点。树结果已经过 read 裁剪，但这只是展示；每次调用仍重新授权。

Section titled “全局工具 Search”
Terminal window
curl -X POST \
  -H "Authorization: Bearer $TB_SK" \
  -H "Content-Type: application/json" \
  -d '{"query":"document search","opts":{"mode":"keyword","limit":20}}' \
  https://tb.example.com/~search

body 只接受 query 和可选 opts；opts 只接受 mode、limit、cursor。semantic mode 需要额外 capability。结果会按当前身份重新检查 read/call，并从节点回读工具表；索引不是授权真源。

Search 路由是根级 POST /~search，不是 GET /<path>/~search。Context namespace 的 Search 是对该节点发送 tool: "Search" 的另一套数据面能力。

两种调用形状

Section titled “两种调用形状”

节点信封

Section titled “节点信封”

适用于所有可调用 kind，builtin/context/device/skillhub 推荐使用：

Terminal window
curl -X POST \
  -H "Authorization: Bearer $TB_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"tool":"get","arguments":{}}' \
  https://tb.example.com/system/status

直接工具路径

Section titled “直接工具路径”

适用于 mcp/http/tool 节点的单个工具：

Terminal window
curl -X POST \
  -H "Authorization: Bearer $TB_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"query":"tool-bridge"}' \
  https://tb.example.com/tools/docs/search

直连 body 必须是 arguments JSON 对象；空 body 语义等价 {}。信封必须有字符串 tool，arguments 缺省 {}。先读工具级 ~help，不要从 URL 或旧教程猜 schema。

默认调用响应是 Markdown JSON code fence；需要机器处理时明确发送 Accept: application/json。

权限语义

Section titled “权限语义”

Action 为 read、write、call、register、admin。scope 使用 segment glob，deny 优先、无匹配默认拒绝。

  • 缺 read：对不可见路径返回 404；
  • 有 read、缺具体动作：通常返回 403；
  • Context 动词按能力和动作分别判断，读取通常需要 read，写动词需要 write；
  • Feedback read/list 需要目标路径 read，提交/投票还需 call，删除需 admin；
  • 反向注册还受 registerPaths 收紧；
  • 节点绑定 authRef/skRef 还要求调用者对 system/secret 有 admin。

客户端不能把 ~tree 的可见性当作调用授权缓存，也不能用 404 区分“不存在”和“无权看见”。

Feedback HTTP 形状

Section titled “Feedback HTTP 形状”
GET /tools/docs/search/~feedback
GET /tools/docs/search/~feedback/<id>


POST /tools/docs/search/~feedback
{"title":"先确认索引范围","detail":"私有空间需要单独授权。"}


POST /tools/docs/search/~feedback/<id>
{"vote":"up"}


DELETE /tools/docs/search/~feedback/<id>

vote 只接受 up、down、clear。根路径不接受 Feedback。它是非权威协作数据，不应承担事务、审计或审批。

MCP 投影

Section titled “MCP 投影”

/~mcp 使用本次请求 Bearer 身份生成 tools/list，并把调用回灌到同一 app 权限和 provider。工具名可能经过 MCP-safe 编码，MCP 客户端必须使用 tools/list 返回值。

网关端点无状态，不依赖 Mcp-Session-Id。投影包括 help/list 控制工具；Search 控制工具只在宿主启用该 capability 时存在。联邦子树还受深度、节点和远端请求预算。

分页

Section titled “分页”

通用页面形状：

{
  "items": [],
  "cursor": "opaque-next-position"
}

默认 limit 50，上限 200。cursor 存在表示可继续；客户端原样传回，不解析、不修改，也不把它当授权凭据。Search 会避免通过 cursor 泄漏隐藏命中量，因此空可见页不一定提供继续位置。

错误体与状态码

Section titled “错误体与状态码”
{
  "code": "invalid_argument",
  "message": "safe human-readable summary",
  "retryable": false
}
code 默认 HTTP 含义
not_found 404 不存在或按可见性隐藏
permission_denied 403 已认证但缺动作；未认证特例为 401
invalid_argument 400 body、参数、路径或配置非法
conflict 409 owner/version/占用冲突
rate_limited 429 需要退避，可能 retryable
unavailable 503 上游、Secret、设备或宿主能力不可用；未实现特例可为 501
internal 500 未分类内部失败

只有 rate_limited、unavailable、internal 允许 retryable:true。调用方仍应使用指数退避、总时限和幂等策略；retryable 不等于可以无限重放破坏性操作。

健康与成功证据

Section titled “健康与成功证据”
Terminal window
curl https://tb.example.com/healthz
curl -H "Authorization: Bearer $TB_SK" \
  -H "Accept: application/json" \
  https://tb.example.com/~help

healthz 200 只证明公开健康处理成功。完整验收还需要：认证 help、受限 SK 的 allow/deny/404、目标节点工具级 schema，以及一次无破坏性真实调用。

客户端安全清单

Section titled “客户端安全清单”
  • SK 只放 Authorization header 或受保护配置；
  • 记录 trace/路径/错误码时去除 headers、token 和敏感 arguments；
  • schema 校验在客户端可做快速反馈，服务端错误仍是权威；
  • 遇 404 不做存在性探测；
  • 遇不可解析 authRef 不降级匿名调用；
  • $ref 是短期能力 URL，不永久缓存或传播；
  • 精确 capability、schema、tool name、CLI 参数始终从目标实例和对应版本获取。

下一步

Section titled “下一步”