注册外部 Plugin

外部 Plugin 适合把复杂供应商 API、认证、响应归一和业务校验封装成稳定 provider。它与内置 catalog 使用相同的 plugin/v2 descriptor/envelope，但生命周期不同：外部 Plugin 必须显式注册、探活和管理。

什么时候选择 Plugin

适合：复杂 OAuth 或多字段凭证、供应商错误归一、多步调用、专用重试、同时导出 tools 与 context、需要独立扩缩容。

不适合：已有标准 MCP server、只有少量规则简单的 REST 操作，或只是希望在网关里运行任意不可信代码。Plugin 与网关交换受控信封，但进程内 binding 与网关同权；只装配可信代码。

先理解三层契约

1. Manifest 描述部署和生命周期：id、plugin/v2、endpoint、transport auth、health path、enabled；
2. /~describe 描述 exports：每个 export 是 tools/v1 或 context/v1，并声明认证与配置形态；
3. Operations 描述具体工具、Context 动词、schema 和副作用。

一个 Plugin 可以有多个 export。挂载时必须选择与节点 kind 对应的 export；不要从 manifest 猜它“是工具还是 Context”。

前置条件

• Plugin 已提供 /healthz、/~describe 和 plugin/v2 调用信封；
• 公网 endpoint 使用 HTTPS；本地 HTTP 只能由网关显式开启开发例外；
• 当前 SK 对 system/plugin 有 admin；
• transport token 与上游业务凭证已经分开规划；
• 挂载目标满足 register/registerPaths，绑定业务凭证还需 system/secret:admin。

不熟悉路径授权或 authRef 时，先阅读权限、SK 与可见性和密钥、出站身份与安全边界。

1. 选择 transport 认证

外部 Plugin 到网关之间的 transport auth 不等于 Plugin 调上游的业务凭证。

使用预先共享的 bearer secret 时，先保存 transport token：

tb secret set --name orders-plugin-transport < plugin-transport.token

创建 plugin-manifest.json：

{
  "id": "orders",
  "protocolVersion": "plugin/v2",
  "endpoint": "https://orders-plugin.example.com",
  "auth": {
    "kind": "bearer",
    "secretRef": "orders-plugin-transport"
  },
  "healthPath": "/healthz",
  "enabled": true
}

也可以使用 platform-token：注册响应会返回一次性 Plugin token，必须立即注入 Plugin 宿主的 PLUGIN_TOKEN 等 Secret 配置。明文无法从 registry 再读回。

2. 注册并检查 descriptor

tb plugin register --file ./plugin-manifest.json
tb plugin health orders
tb plugin get orders

注册时平台会校验 manifest，探测 endpoint，并抓取 ~describe。成功不只意味着 healthz 为 200：protocolVersion、exports、profile、methods、auth/mountConfig 声明也必须一致。

查看 tb plugin get orders 输出的每个 export。它会提示 tool/context 对应的挂载命令。多 export 时始终显式传 --export。

3. 挂载 tool export

如果 actions 是 tools/v1：

tb tool mount tools/orders \
  --kind tool \
  --provider orders \
  --export actions

若 export 需要上游业务凭证，先把它作为另一条 Secret 保存，再用 --auth-ref 挂载。transport secret 与业务 secret 不应复用。

tb secret set --name orders-upstream < upstream.key

tb tool mount tools/orders \
  --kind tool \
  --provider orders \
  --export actions \
  --auth-ref orders-upstream

非敏感实例 URL、workspace、region 等才进入 --config key=value。精确字段以 export 的 mountConfigFields 为准。

4. 挂载 context export

如果 documents 是 context/v1：

tb ctx mount context/orders \
  --provider orders \
  --export documents

Context 的真实动词由该 export 的 methods/capabilities 决定。不要因为另一个 export 可写，就假设此 namespace 也有 Write/Delete。

成功证据

tb plugin health orders
tb plugin get orders
tb help tools/orders
# 将 list_orders 替换为上一条 ~help 返回的真实工具名
TOOL_NAME=list_orders
tb help "tools/orders/$TOOL_NAME" --json
tb call tools/orders --tool "$TOOL_NAME" --args '{}'

还应验证：禁用 Plugin 后挂载调用失败；错误不会泄漏 transport/upstream token；Context export 的 ~help 只列实际 methods；需要凭证的 export 在凭证无效时尽早失败。通用发现与调用证据见从 ~help 到调用。

安全边界

• 外部托管 Plugin 未配置 transport token 时必须 fail closed；
• Plugin 上游凭证来自挂载节点的 authRef，不放进 providerConfig；
• 跨源 redirect 不能携带 Authorization、自定义敏感头或 secret body；
• endpoint、descriptor 和上游返回都是不可信输入，必须由协议和 schema 校验；
• 进程内 binding 只能由宿主显式装配，不能靠注册一个 binding: 名字凭空加载代码；
• 内置 catalog 项不需要注册，不要把它们复制进 system/plugin 制造两份状态。

常见失败

现象	处理
manifest 被拒	只接受严格 plugin/v2 字段；删除旧 kind 等字段，检查 endpoint/healthPath
health 正常但注册失败	~describe 的 protocolVersion、exports、auth 或 methods 不合法
多 export 挂载失败	显式指定 --export，并使用匹配的 tb tool mount 或 tb ctx mount
调用 unavailable	Plugin disabled/不可达、transport secret 失效、binding 未装配或业务 authRef 无法解析
Plugin 401	区分 transport token 与上游业务 token，确认没有混用
Context 动词缺失	export 未声明/实现该 method；以节点 ~help 为准
HTTP endpoint 被拒	公网必须 HTTPS；本地开发例外不要带进生产

卸载、注销与回滚

先找出并卸载所有引用该 Plugin 的节点：

tb tool rm tools/orders
tb ctx unmount context/orders

确认业务流量已停止，再注销：

tb plugin rm orders
tb plugin list

最后才评估删除 transport 和上游凭证：

tb secret ls
tb secret rm orders-plugin-transport
tb secret rm orders-upstream

不要先注销 Plugin 再留下大量悬空挂载，也不要让 plugin rm 自动删除可能被复用的 Secret。版本升级可先注册新 id、挂到新路径完成验收，再切流并回收旧版本。

下一步

• 如果 provider 已被宿主内置：改用内置集成目录；
• 如果只有简单 REST：考虑声明式 HTTP；
• Context export 的使用方式见Context；
• 精确 manifest/export 字段以对应版本 plugin-sdk、目标实例 tb plugin get 和 tb --help 为准；
• 注册、transport 或调用异常：进入故障排查与升级。