设计原则

tool-bridge 并不是简单给各种 API 再包一层。它试图让“如何发现”“谁能调用”“凭证放在哪里”和“能力来自哪里”共享一组可执行边界。

运行时契约是真源

公共文档适合解释稳定概念，不能准确描述某个实例在某个身份下的实时能力。工具列表、参数 schema、启用的 provider 和反馈都可能随部署配置而变化。

因此：

• Agent 应从当前路径的 ~help 开始；
• 结构化客户端应请求 Accept: application/json 并消费返回的 JSON Schema；
• 本站不维护一份假装完整的静态工具注册表。

最小权限，deny 优先

SK scope 由路径和动作组成。当前动作包括 read、write、call、register 与 admin。

授权判断遵循两条规则：

1. 只授予完成任务所需的最小路径前缀与动作；
2. allow 与 deny 同时命中时，deny 胜出。

调用者无权看见的路径返回 404，而不是暴露其存在的 403。这样可以降低通过错误差异枚举树结构的风险。

密钥只按引用进入配置

上游 API key、OAuth token 与远端 SK 进入 SecretStore；节点只保存 authRef 或 skRef。可读的 providerConfig 不是密钥容器，因为有节点读取权限的身份可能看到它。

密钥也不应出现在：

• URL 和 query string；
• CLI 参数与可共享的 shell history；
• 普通日志、错误详情和调用历史；
• 仓库、镜像或公开构建产物。

调用者身份不透传给上游

本地 SK 只用于 tool-bridge 自身的认证授权。访问 MCP、HTTP、plugin provider 或远端网关时，出站身份来自节点引用的 SecretStore 凭证。

这一边界避免本地调用者无意中获得上游身份，也避免远端系统看到不属于它的本地 SK。

联邦默认关闭

remote 节点可以把另一套 HTBP 服务挂载为本地子树，但联邦默认 fail closed：

• host allowlist 为空时，不允许任何远端；
• 生产目标要求 HTTPS，本地开发例外必须显式开启；
• 本地调用者 SK 不发送给远端；
• 网关执行跳数限制、环检测和远端路径校验。

联邦是树与树之间受控的组合，不是一个任意 URL 代理。

三个入口保持对等

公开能力应同时能通过 HTTP、tb CLI 和 Dashboard 管理或使用；MCP 投影面向兼容客户端。某个入口能绕过其他入口的治理规则，或管理另一入口无法表达的状态，都应被视为契约缺口。