跳转到内容
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 应逐段编码，不要把 / 编进单个工具名再依赖服务端猜测。
  • 标识符大小写不敏感并规范化为小写；规范化后的冲突会以 invalid_argument 拒绝，不会任选一个。

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

端点总览

Section titled “端点总览”
方法与路径 认证 作用
GET /healthz 否 进程、实例和安装状态，不是完整 readiness
GET /livez 否 进程存活；恒 200，不探后端依赖
GET /readyz 否 就绪探测；探 PG/Redis 等后端，未就绪或 draining 返回 503
GET /~help 是 根帮助和当前身份可见顶层节点
GET /<path>/~help 是 节点帮助，默认工具索引；加 ?schemas=1 带回全节点 schema，工具子路径返回单工具完整 schema
GET /<path>/~tree?depth=N 是 当前身份裁剪后的子树；根用 /~tree
POST /~search 是 可选全局工具搜索；宿主未启用时 404
POST /<node>/<command> 是 唯一命令调用形态；路径取自 cmds[].path，body 是 arguments 对象
GET/POST/DELETE /<path>/~feedback... 是 读取、提交、投票和管理路径 Feedback
ALL /~mcp 是 将当前 Bearer 身份动态投影成 MCP server
POST /~device/operations/get 是 查询一条当前 caller owner/admin 可见的 durable device operation
POST /~device/operations/list 是 按 deviceId 分页列出当前身份可见的 operation
POST /~device/operations/cancel 是 取消 queued operation，或为 claimed operation 请求协作式取消
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

节点级工具帮助默认是不含 schema 的索引。取 schema 有两条路：对 <node>/<tool>/~help 下钻拿单工具完整 input/output schema；或对节点级加查询参数 ?schemas=1 一次带回该节点所有工具的 schema。?schemas=1 严格只认字符串 1，且仅对 mcp/http/tool 与设备 tool 节点有效（builtin/directory/context/skillhub 本就带全量 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。当前 mode 仅为 keyword；opts 还支持 limit、cursor、detail: compact|full、matching: best|all、minCoverage、pathPrefix、effects 和 federation: local|recursive。默认 compact，detail: full 才带完整 schema；Search 默认 limit 10，最大 200。

递归范围需要 search:federated capability，结果附带来源与 partial 状态。coverage 表示查询词覆盖情况，不是语义相似度。每项仍按当前身份重新检查 read/call，并回读权威节点；索引不是授权真源。

keyword mode 做字面子串检索：不会翻译、扩同义词或承诺语义映射。连续中日韩文文本会用短片段补充召回，但英文查询不会自动命中只有中文描述的工具。跨版本升级可能重建派生索引并让旧 cursor 失效；客户端遇到 cursor invalid_argument 时，应以同一 query、无 cursor 重新开始，而不是解析或修改 cursor。

Search 路由是根级 POST /~search，不是 GET /<path>/~search。Context namespace 的 search 是该节点声明的命令；调用方仍应使用对应 cmds[].path 直连。

唯一调用形状

Section titled “唯一调用形状”

命令是节点下的虚拟叶子。调用方从 owner 的 ~help 取得 cmds[].path，再原样向该完整路径 POST；body 直接是 arguments JSON 对象。这个规则对 builtin、Context、Device、Skillhub、MCP、HTTP 与 Plugin/SDK 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 语义等价 {}。cmds[].path 已经包含命令叶子，客户端不得从 owner path 与 command name 重建 URL，也不得向 owner 路径发送 {tool,arguments}。先读 ~help（下钻命令级，或节点级 ?schemas=1），不要从 URL 或旧教程猜 schema。

plugin/v2 endpoint 是网关到 Plugin 的内部传输边界，内部 body 合法保留 {tool,arguments}；它不是公开 HTBP 调用形状。公开请求与 Plugin 内部 wire 不可互相套用。

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

Device delivery 与 Mailbox

Section titled “Device delivery 与 Mailbox”

设备 tool 命令可以在 ~help 的 cmds[] 上声明 delivery：缺省 realtime，另有 mailbox 和 both。调用方在普通 arguments body 顶层加入保留的 ~delivery，为本次调用选择 realtime|mailbox|fallback：

Terminal window
curl -X POST \
  -H "Authorization: Bearer $TB_SK" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-tb-idempotency-key: sync-acme-app-20260901" \
  -d '{"repository":"acme/app","~delivery":"fallback"}' \
  'https://tb.example.com/device/build-01/ops/sync?ttlSeconds=900'

网关在路由前移除 ~delivery，设备 handler 只收到业务 arguments。其他 ~ 前缀控制字段会被拒绝；非 device-backed tool 命令也不接受 ~delivery。

请求策略 HTTP 结果与含义
realtime 实时成功返回 200，并带 x-tb-delivery: realtime
mailbox 成功持久化返回 202 operation detail，并带 x-tb-delivery: mailbox
fallback both 命令先实时调用；只有 gateway 明确知道调用尚未派发时才返回 202，否则保留实时结果或返回结果未知错误

ttlSeconds query 与 x-tb-idempotency-key header 只在可能入队时有意义。idempotency key 最长 255 字符，作用域包含 caller owner；同一业务动作的安全创建重试应复用同一个值。

operation 管理面使用固定 JSON body：

POST /~device/operations/get
{"deviceId":"build-01","operationId":"dop_..."}


POST /~device/operations/list
{"deviceId":"build-01","opts":{"states":["queued","claimed"],"limit":50}}


POST /~device/operations/cancel
{"deviceId":"build-01","operationId":"dop_..."}

创建 operation 时已通过完整命令路径的 read/call 权限。后续 get/list/cancel 允许同一 caller owner 的其他 SK，或对完整 targetPath 有 admin 的身份；无权查看的单条 operation 以 404 隐藏，list 也不会通过 items/cursor 泄漏其他 owner 的记录。

/~device/mailbox/claim|renew|complete 是设备 SDK 的数据面，不是 Agent 的第二套调用入口。设备凭证每次请求都要重新认证并匹配原 operation 的 device identity。普通调用方只使用命令 POST 与 operations/* 管理面。

状态、取消、result_unknown 和设备 journal 的完整边界见Device 离线投递与 Mailbox。

安装与实例管理

Section titled “安装与实例管理”
入口 身份与用途
GET /~setup/status 无需 SK，只返回安装阶段、实例身份和配对状态
GET /~setup/defaults x-tb-setup-token，读取脱敏安装默认服务
POST /~setup/configure、/~setup/recover 本机 setup / recovery 配对 token
POST /system/config/<command> 对应路径 admin；schema / get / status / validate / update / apply
POST /system/storage/<command> 对应路径 admin；后端 test、activate、凭证更新等
POST /system/deployment/<command> 对应路径 admin；期望设置与本机执行器任务
POST /system/maintenance/<command>、/system/keys/<command> 对应路径 admin；专项维护、轮换与备份
POST /system/store/<command> read / write 加对象 owner 检查

具体 body 使用节点 ~help 的严格 schema。普通 Admin SK 不能代替本机配对 token；保存 desired revision 不等于实际 apply。完整操作见配置、后端与维护。

Store 上传数据面 PUT /~store/uploads/<uploadId> 使用 x-tb-store-upload 窄授权，标准 Node relay 成功直接返回 descriptor；该 token 不应进入 body、URL 或日志。Store URI 是稳定身份，读取和显式分享生成的短期 ref 才是 bearer。使用流程见Store。

权限语义

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；Search 默认 10。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 https://tb.example.com/livez
curl https://tb.example.com/readyz
curl -H "Authorization: Bearer $TB_SK" \
  -H "Accept: application/json" \
  https://tb.example.com/~help

这三个公开端点分工不同：/livez 恒 200 只报进程存活，适合编排器的 liveness 探针；/readyz 在运行态探测 PG、active S3 和已配置 Redis，未初始化、恢复、维护或 draining 时返回 503，适合 readiness 探针与摘流量判断；/healthz 返回版本、实例与安装状态。它们都不验证认证数据面：healthz/livez 200 只证明公开健康处理成功。完整验收还需要：认证 help、受限 SK 的 allow/deny/404、目标工具 schema（工具级下钻或节点级 ?schemas=1），以及一次无破坏性真实调用。

客户端安全清单

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

下一步

Section titled “下一步”