跳转到内容
tool-bridge

使用内置集成目录

内置集成适合“网关已经打包了对应 provider，我只需要提供凭证和非敏感配置”的场景。它省去了手写 HTTP 工具表或单独托管 Plugin，但不会把所有实例变成同一份静态集成商店：实际可用项由网关构建产物决定。

什么时候选择它

Section titled “什么时候选择它”

适合：

  • 目标实例的 catalog 已包含所需服务；
  • 希望由平台管理上游凭证，并统一进入 ~help、权限和 Search；
  • 希望用一条命令完成凭证保存与节点挂载。

不适合：

  • catalog 没有该 provider：考虑外部 Plugin或声明式 HTTP；
  • 已有标准 Streamable HTTP MCP server：直接挂载 MCP更清晰；
  • 只是临时调用一个不可信 URL：不要为了省步骤绕过出站与凭证边界。

前置条件

Section titled “前置条件”
  • CLI 已通过 tb login 指向正确网关；
  • 当前 SK 对 system/catalog 有 read；
  • 挂载时对目标路径有 register，且满足 registerPaths；
  • 需要写凭证时，对 system/secret 有 admin。

如果你还不熟悉这些权限和凭证边界，先阅读权限、SK 与可见性与密钥、出站身份与安全边界。

先确认身份和目录：

Terminal window
tb whoami
tb integration catalog
tb integration catalog --search tavily

如果要在自动化里读取精确契约：

Terminal window
tb integration catalog --search tavily --json

关注选中 export 的四类信息：节点 kind、认证形态、必填凭证字段、非敏感 mount config。provider 有多个 export 时必须用 --export 明确选择。

挂载单值凭证集成

Section titled “挂载单值凭证集成”

凭证优先从 stdin 输入，避免出现在进程列表和 shell history：

Terminal window
tb integration add tools/web-search \
  --provider tavily \
  --key-stdin < tavily.key

如果 export 不需要凭证，不要提供 --key。多字段凭证仍应避免把真实值展开进 argv。先按 catalog 返回的字段名准备一个权限受控的 team-service-credential.json，再通过 stdin 写入 SecretStore：

Terminal window
tb secret set --name team-service-credential < team-service-credential.json


tb integration add tools/team-service \
  --provider team-service \
  --export actions \
  --credential team-service-credential

这里的 team-service、actions 和凭证 JSON 字段只是安全占位，请替换为目标实例 catalog 返回的真实 provider、export 与 credentialFields。CLI 也提供重复 --field key=value 的交互便利入口，但敏感生产凭证优先使用 stdin，避免进入进程列表、shell history 或 CI 日志。

字段究竟哪些属于凭证，以 catalog 为准。只有非敏感、允许被 registry 读回的配置才能放进 --config：

Terminal window
tb integration add notes/team \
  --provider memos \
  --config baseUrl=https://notes.example.com \
  --key-stdin < notes.key

复用已有凭证与 OAuth

Section titled “复用已有凭证与 OAuth”

如果管理员已经保存凭证，可以引用其名称：

Terminal window
tb integration add tools/sentry \
  --provider sentry \
  --credential sentry-oauth-client

当选中 export 声明 OAuth 时，挂载成功只是创建节点，随后还要完成授权：

Terminal window
tb integration auth tools/sentry

自定义域部署应先确认 canonical origin 与 OAuth redirect URI 一致。授权完成后 token 仍保留在网关 SecretStore，不应复制回本机配置。

成功证据

Section titled “成功证据”

不要以“命令退出码为 0”作为唯一证据。按顺序检查：

Terminal window
tb integration ls
tb help tools/web-search
# 将 search 替换为上一条 ~help 返回的真实工具名
TOOL_NAME=search
tb help "tools/web-search/$TOOL_NAME" --json
tb call tools/web-search --tool "$TOOL_NAME" --args '{}'

成功意味着：节点出现在当前身份的树中；~help 给出真实工具与 schema；一次最小、无破坏性的调用得到预期结果。若宿主启用全局 Search，再用 tb search '关键词' 验证投影，但 Search 不是挂载状态的权威来源。完整的 discover-first 验证方式见从 ~help 到调用。

常见失败

Section titled “常见失败”
现象 原因与处理
catalog 为空或找不到 provider 当前宿主没有打包它；不要照抄其他实例，改用 MCP、HTTP 或外部 Plugin
提示必须选择 export provider 有多个 export；重新查询 --json，传入 --export
凭证字段不匹配 选错 export 或使用了静态旧文档；以当前 exportDetails 为准
permission_denied 缺目标路径 register，或写 SecretStore 所需的 system/secret:admin
404 当前 SK 看不到目录或目标路径；404 也可能是可见性裁剪，不要据此枚举
unavailable SecretStore 主密钥、凭证引用、上游网络或 provider 运行时不可用；先查节点 ~help 与安全日志
挂载成功但 OAuth 调用失败 尚未运行 tb integration auth <path>，或 redirect/canonical origin 不一致

卸载与回滚

Section titled “卸载与回滚”
Terminal window
tb integration rm tools/web-search
tb integration ls

卸载只移除节点，不自动删除凭证。这是刻意的安全边界：同一 Secret 可能被其他节点复用。确认没有引用后，再显式处理：

Terminal window
tb secret ls
CREDENTIAL_NAME=team-service-credential
tb secret rm "$CREDENTIAL_NAME"

回滚时建议先卸载新节点、验证旧路径仍可用，再删除仅属于新节点的凭证。不要把“卸载集成”和“销毁密钥”合并成不可恢复的一步。

下一步

Section titled “下一步”