选择你的使用路径
选择 tool-bridge 时需要回答两个独立问题：
- 网关运行在哪里？ Node/Docker、Cloudflare Workers，还是嵌入现有应用；
- 能力从哪里进入树？ 内置集成、MCP、HTTP、Context、Device、Plugin 或另一棵远端树。
宿主决定存储、运维和长连接实现；接入方式决定上游协议和凭证。两者可以自由组合，例如在 Cloudflare 网关挂载一个 MCP Server，也可以在 Node 网关接入本地设备。
先确定你的目标
Section titled “先确定你的目标”| 你的目标 | 建议起点 |
|---|---|
| 第一次体验，不想配置云账户 | 5 分钟本地启动 |
| 在内网或单台服务器长期运行 | 部署 Node / Docker |
| 最少步骤部署到边缘 | Cloudflare 一键部署 |
| 需要完整 Cloudflare gateway、Search 或源码定制 | 从源码部署到 Cloudflare |
| 已有 Node 22+ 应用，希望注册本地函数 | 嵌入现有应用 |
| 只想让一台内网机器暴露有限 shell/文件 | 接入本地设备与服务 |
比较三种宿主
Section titled “比较三种宿主”| 维度 | Node / Docker | Cloudflare Workers | 嵌入式 SDK |
|---|---|---|---|
| 权威状态 | SQLite | Workers KV | 调用方注入 StateStore |
| 对象存储 | 本地文件 | R2 | 调用方注入 ObjectStore |
| Search | SQLite 索引 | 完整源码形态使用 D1；一键模板不含 D1 | 当前公开 SDK 不提供 SearchIndex 注入 |
| 设备长连接 | Node WebSocket | Durable Objects + WebSocket hibernation | 可用 connect() 反向连接远端；网关侧能力取决于宿主装配 |
| 一致性 | SQLite 强一致 | KV 认证与注册读取存在最终一致窗口 | 取决于注入实现 |
| 运维责任 | 主机、TLS、卷、备份 | Cloudflare 资源、域名、secret、配额 | 完全由现有应用承担 |
| 适合 | 内网、自托管、快速闭环 | 边缘、低主机运维、设备连接 | 应用内本地工具、定制宿主 |
所有宿主共享同一套应用语义，但它们不是完全相同的基础设施。不要把 Node 的 SQLite 行为假设成 Workers KV 的强一致保证，也不要把完整源码 gateway 的 D1 Search 假设成一键模板的默认能力。
Node / Docker：掌控主机与状态
Section titled “Node / Docker：掌控主机与状态”选择它，如果你：
- 已有 Linux 主机、NAS 或内网容器平台；
- 需要 SQLite 的本地强一致状态；
- 希望对象文件与数据库一起备份；
- 接入的上游主要在内网，且能自己处理 TLS/反向代理。
不适合只想完全免主机运维，或希望天然在全球边缘就近接入的团队。
开始前准备：一套 Secret 注入方式、持久卷、反向代理的 WebSocket upgrade、备份和恢复路径。先完成本地启动，再按部署 Node / Docker生产化。
Cloudflare 一键部署：最短的边缘路径
Section titled “Cloudflare 一键部署：最短的边缘路径”Deploy Button 会把模板复制到你的 GitHub 和 Cloudflare 账户，并创建 KV、R2、Durable Objects 与 Static Assets。它适合快速得到一个带 Dashboard 和设备通道的边缘网关。
它不适合需要完整内置 catalog bundle 或 D1 Search 的场景。一键模板当前没有 D1 binding，因此不能静态假设存在 ~search。选择前阅读Cloudflare 一键部署，部署后用根 ~describe 检测 Search capability。
Cloudflare 源码部署：完整 gateway 与定制
Section titled “Cloudflare 源码部署：完整 gateway 与定制”从 tool-bridge 源码 checkout 运行 tb init cloudflare --repo .，向导会创建 KV、R2、D1 和 Durable Objects，构建 Dashboard 与完整 gateway，并验证根 ~help。
选择它，如果你需要：
- D1 工具搜索；
- 完整内置 integration catalog；
- 自己控制 gateway 构建和源码版本；
- 通过 CI 做可审计的重复部署。
代价是你需要维护 checkout、依赖、Cloudflare 认证和账户特定资源。账户 ID、域名和资源 ID 不应推回公共模板。详见从源码部署到 Cloudflare。
嵌入式 SDK：把树带进你的应用
Section titled “嵌入式 SDK：把树带进你的应用”SDK 适合已有 Node 22+ 应用，希望程序化注册本地 Tool/Context，并把 tb.fetch 挂到现有 HTTP 宿主。调用方必须决定 StateStore、对象存储、密钥、生命周期和外部暴露方式。
当前发布包是 Node 22 目标，并依赖 Node 的 node:os 与 WebSocket 实现；Fetch 风格的 tb.fetch 不表示这个包可以直接嵌入 Cloudflare Workers。需要 Workers 时使用一键模板或完整 Cloudflare gateway。
它不是“少配置的托管服务”：MemoryStateStore 只适合示例和测试；生产持久化与备份由你负责。SDK 的网关侧设备能力也不会凭空出现，必须由宿主装配。详见嵌入现有应用。
再选择能力接入方式
Section titled “再选择能力接入方式”| 来源 | 什么时候选 | 凭证与验证 |
|---|---|---|
| 内置集成 | catalog 已提供目标 provider，希望少写适配代码 | 按 export 契约写 SecretStore；以挂载路径 ~help 验证 |
| MCP Server | 上游已经提供 Streamable HTTP MCP | 使用 authRef/OAuth；验证 discovery 与真实 tool call |
| 声明式 HTTP | 上游是稳定、简单的 HTTP API | 定义工具 schema/请求映射；复杂逻辑应改用 Plugin |
| Context | 目标是对象、文档或知识内容 | 根据 capability 使用 Get/List/Put/Search；凭证只入 SecretStore |
| Device / SDK connect | 能力在内网或本机，云端不能主动访问 | 设备专用 SK、registerPaths、shell/fs 白名单 |
| 外部 Plugin | 需要代码适配、多个 exports 或独立扩缩 | plugin/v2、TLS、PLUGIN_TOKEN、注册/探活/挂载 |
| Federation | 另一团队已经运行 HTBP 服务 | host allowlist、远端专用 SK、skRef、HTTPS 与环检测 |
一个稳妥的决策流程
Section titled “一个稳妥的决策流程”- 先用本地 Docker 验证你的真实上游能否被发现和调用；
- 为测试 Agent 创建受限 SK，证明路径权限满足预期；
- 再根据一致性、网络位置和运维责任选择生产宿主；
- 部署后重新读取目标实例的
~describe、节点级~help和工具级 schema，不要把开发实例能力清单直接当生产事实； - 完成生产上线检查清单。
- 想立即试用：进入5 分钟本地启动；
- 已选宿主：进入 Node/Docker、Cloudflare 一键部署、Cloudflare 源码部署或嵌入式 SDK；
- 已有网关：从使用内置集成或挂载 MCP Server开始接入能力。