Federation 连接多棵树
Federation 用 remote 节点把另一套 HTBP 服务挂成本地子树。调用方仍使用本地 BaseURL 与本地 SK；网关以节点专用的远端 SK 访问上游，因此它是受控的服务账号代理，不是任意 URL 转发器。
适用与不适用
Section titled “适用与不适用”适合跨团队、跨环境组合多棵 HTBP 树，同时保留各自管理权与凭证边界。
不适合把普通 REST/MCP URL 当 remote：remote 目标必须理解同形 ~help、~tree 和调用契约。也不适合希望“本地用户身份自动传到远端”的场景；本地 SK 明确不会透传。
三道前置闸门
Section titled “三道前置闸门”- Host allowlist：空列表拒绝全部 remote；管理员必须先允许目标 host suffix；
- 远端专用 SK：保存进本地 SecretStore，由 remote 节点
skRef引用； - 本地路径权限：创建者需要目标路径
register，使用者需要本地 remote 路径的read/call。
远端仍会用专用 SK 做第二层授权，所以本地 allow 不会绕过远端 deny。
开始前应理解权限、SK 与可见性以及密钥、出站身份与安全边界；Federation 的 skRef 绝不能替换为本地调用者 SK。
1. 允许远端 Host
Section titled “1. 允许远端 Host”tb federation lstb federation add team-b.example.comtb federation ls --json传入的是裸 host suffix，不含 scheme、端口或路径。team-b.example.com 可以匹配其子域，但不会匹配 notteam-b.example.com。
tb federation ls 合并两类来源：
source: env：部署期基线，不可通过 API 删除；source: store：运行时添加，可用 CLI 删除。
2. 保存远端专用 SK
Section titled “2. 保存远端专用 SK”在远端网关签发只允许所需子树和动作的 SK，然后写入本地 SecretStore：
tb secret set --name team-b-sk < team-b.sk不要使用远端 Admin SK，也不要把本地调用者 SK 存为远端身份。remote 的出站权限应小于等于该挂载实际需要的能力。
3. 创建 Remote 节点
Section titled “3. 创建 Remote 节点”tb server add teams/team-b \ --remote-url https://tb.team-b.example.com \ --sk-ref team-b-sk \ --description "Team B 工具树"--base-url 始终表示 CLI 当前访问的本地网关；远端地址只能用 --remote-url。绑定 skRef 需要调用者对 system/secret 有 admin，防止受限注册者借用平台已有高权限凭证。
4. 验证联邦子树
Section titled “4. 验证联邦子树”tb server lstb tree teams/team-b --depth 2tb help teams/team-b# 将 tools/search 替换为远端 ~tree/~help 返回的真实相对路径REMOTE_TOOL_PATH=tools/searchtb help "teams/team-b/$REMOTE_TOOL_PATH"再完成一次远端只读调用。成功证据包括：
- 本地树把远端路径正确加到
teams/team-b前缀下； - 远端
~help的 command path 没有逃逸挂载节点； - 本地只读但无 call 的 SK 能发现、不能调用；
- 本地无 read 的 SK 得到 404；
- 远端专用 SK 无权限的能力即使本地允许也不能访问；
- 日志只记录 actor、节点、skRef 名称和目标，不记录 SK 明文。
随后按从 ~help 到调用完成一次最小、只读的真实远端调用。
- 生产 remote 默认要求 HTTPS；
- 注册时和调用时都会检查 allowlist，防止配置漂移后继续访问；
- 本地 Bearer 不进入出站 Authorization；
skRef无法解析时返回不可用，不会匿名访问；X-TB-Via用于环检测和跳数上限；- 远端返回的路径、树和帮助都按不可信协议数据校验；
~tree和 MCP 投影有深度、节点、远端请求预算，不能无限递归。
| 现象 | 处理 |
|---|---|
remote baseUrl 不在白名单 |
先用 tb federation add <host>，并确认 suffix/端口写法 |
| HTTP URL 被拒 | 生产改用 HTTPS；本地开发例外必须由部署者显式开启 |
skRef 无法解析 |
Secret 不存在、主密钥不可用或名称错误；不要去掉 skRef 匿名重试 |
| 本地 404 | 当前本地 SK 没有该路径 read，或远端路径不存在 |
| 本地 403 | 可见但没有本地 call |
| 远端拒绝 | 专用远端 SK scope 不足、过期或已吊销；在远端处理 |
unavailable 提到环/跳数 |
检查 remote 拓扑和实例标识，不要无边界增加跳数 |
| 树能展开但 MCP discovery 失败 | 联邦子树超过 MCP 的远端发现预算；缩小挂载/权限或直接使用 HTBP |
先卸载 remote 节点，停止本地新流量：
tb server rm teams/team-btb server ls如果没有其他 remote 使用该 host，再删除运行时 allowlist：
tb federation rm team-b.example.comenv 基线无法用 API 删除，需要修改部署配置并重新部署。最后确认没有其他节点引用远端凭证，再删除本地 Secret，并在远端吊销对应 SK：
tb secret rm team-b-sk该顺序让每一步可验证，避免先删远端 SK 导致本地节点长时间处于模糊故障状态。