12. 外部智能体、技能、插件与外部注册中心
完整版章节。内容按 2026.10 主线代码核对；具体入口以当前许可、账号权限和交付环境为准。
本章说明「管理控制台 → 搭建」下的四个入口：「外部智能体」「技能」「插件」和「外部注册中心」。四项均属于「基础功能」，由租户管理员或「系统管理员」维护；成员在能力中心的「外部智能体广场」「技能广场」和「插件广场」页签中使用已授权的对象。
12.1 接入外部智能体
「外部智能体」用于接入由其他系统提供、遵循外部智能体（A2A）协议的 Agent 服务。页面包含「Agent 目录」和「任务中心」两个标签。「Agent 目录」列出「名称」「来源」「状态」「协议版本」「健康」「调用方」「接入时间」和操作。
- 选择「接入外部智能体」，打开「接入外部智能体」向导。
- 在「来源」步骤选择「名片 URL 拉取」并填写 Agent Card 地址（如
https://agent.example.com/.well-known/agent-card.json），或选择「粘贴 AgentCard JSON」。 - 「凭据绑定」步骤只作提示，上游凭据在注册后于 Agent 详情中配置（见第 12.2 节）。
- 在「连通测试」步骤选择「开始测试」，确认提示「连通正常」及延迟。
- 在「完成」步骤核对「名片名称」「协议版本」和「签名校验」（「有签名」或「无签名」），然后完成注册。注册后 Agent 处于「待审批」状态。
- 在「Agent 目录」对该 Agent 选择「批准」或「拒绝」。只有已批准的 Agent 才能签发调用方 Token 和分发给成员。
网关为每个外部智能体提供独立的调用入口，调用方无需知道上游地址：
| 项目 | 地址 |
|---|---|
| 调用入口（RPC） | <网关地址>/api/v1/agent-gateway/a2a/<Agent ID> |
| 改写后的 Agent Card | <网关地址>/api/v1/agent-gateway/a2a/<Agent ID>/.well-known/agent-card.json |
改写后的 Agent Card 只保留展示字段，服务地址全部替换为网关地址，上游地址、文档与图标链接、扩展声明和签名不对外暴露。Agent 详情中并排展示「原始 Card」和「改写后 Card（网关入口）」，便于核对。
Agent 详情的「名片地址」旁可重新拉取名片。上游名片中的端点变更后，已保存的凭据绑定会暂存，需重新审批后才会再次注入。
从外部注册中心同步的 Agent 在列表中只能「查看Card」，不能单独删除，需通过注册源统一管理（见第 12.7 节）。手动接入的 Agent 删除后，其网关调用凭据同时失效。
12.2 配置上游凭据与调用方 Token
上游凭据：在 Agent 详情的「上游凭据」区域设置「凭据归属」：「企业共享」或「无需凭据」。「鉴权方式」由 Agent Card 声明决定，页面不能自选，支持「API 密钥」「基础认证」和「Bearer 令牌」。保存后，网关调用上游时注入该凭据；切换为无需凭据时，保存后解除绑定，调用时不注入任何凭据。
以下情况不能通过该区域配置：
- Agent 声明 OAuth2/OIDC 鉴权时，页面提示需单独配置；
- mTLS、Cookie 或查询参数中的 API 密钥不受支持。
调用方 Token：管理员可为外部调用方签发访问令牌。
- 在 Agent 详情的「调用方 Token」区域选择「签发」。
- 在「签发调用方 Token」中填写「标签」（如
acme-workbuddy），选择「有效期」：1 天、7 天、30 天、90 天或「永久有效」，默认 30 天。 - 复制「Token 明文」。明文仅此一次展示，关闭后无法找回；令牌以
zg_a2a_开头。 - 列表显示「标签」「前缀」「过期时间」「最近使用」「状态」和「签发时间」。不再使用时选择「吊销」，吊销后最多 15 秒内全站生效，不可恢复。
改写后的 Agent Card 声明两种调用鉴权：网关签发的 Bearer 令牌，以及授权码加 PKCE S256 的 OAuth 授权。
12.3 分发外部智能体与发布为 MCP 工具
发布与可用范围：Agent 详情的标签包括「详情」「可用范围」「调用情况」和「操作审计」。在「详情」中打开「发布」，把 Agent 上架到能力中心的「外部智能体广场」；再在「可用范围」中按「所有用户」「部门」「职能组」或成员授权，并设置「开始生效」「结束生效」，预设为「7 天」「30 天」「自定义」「长期有效」。「外部智能体广场」只向已获授权的成员展示已批准的 Agent。
外部智能体的部门授权按成员的直属部门匹配。需要覆盖子部门成员时，应同时添加子部门或改用职能组授权。
发布为 MCP 工具：在 Agent 详情打开「发布为 MCP 工具」，状态显示为「已发布」。发布后，成员可在 MCP 客户端中通过网关提供的外部智能体 MCP 桥接调用该 Agent。关闭后，已有的 MCP 配置立即不可调用。
成员接入：成员在「外部智能体广场」打开 Agent 详情，按客户端类型选择接入方式：
| 区域 | 适用客户端 | 操作 |
|---|---|---|
| 「原生协议接入」 | 原生支持外部智能体协议的客户端 | 选择「令牌有效期」后「获取外部智能体配置」，配置包含 Card 地址、调用地址和一次性展示的 Bearer 令牌；可「复制配置」「下载配置」或「撤销 Token」 |
| 「WorkBuddy / MCP 接入」 | MCP 客户端；仅在 Agent 已发布为 MCP 工具时显示 | 选择「获取 MCP 配置」，把生成配置中的 mcpServers 条目合并到客户端配置文件，不要覆盖其他已有条目 |
租户在安全策略中关闭 Token 接入时，成员不能生成外部智能体或 MCP 调用配置。
12.4 监控外部智能体与查询任务
健康与探活：Agent 详情的「健康」显示「正常」「不可达」或「未知」。需要立即确认时选择「立即探活」。
调用情况：「调用情况」标签展示「调用趋势」，以及「调用量」「成功率」「平均耗时」「P95耗时」「当前并发」和「限流」「熔断」状态；「最近调用」列出每次调用的时间、调用来源、用户、状态、耗时和结果。外部智能体调用的限流与熔断在流量规则中配置（需要「动态路由」许可模块），见第 15 章。
操作审计：「操作审计」标签记录该 Agent 的注册、审批、凭据和分发变更。
任务中心：「任务中心」标签列出经网关发起的外部智能体任务。
- 按「全部 Agent」「全部状态」筛选，或在「按 taskId 搜索」中输入任务标识。
- 列表显示「Task ID」「目标 Agent」「调用方」「状态」「开始时间」「耗时」和「最近更新」。状态包括已提交、执行中、待输入、待授权、已完成、失败、已取消和被拒绝等。
- 展开任务查看「状态节点」，核对状态变化历史。
- 需要终止时选择「取消任务」。网关会向目标 Agent 发送取消请求，能否终止取决于对端实现。
外部智能体接入完成的标志是：名片可读取、已批准、探活正常、凭据与端点匹配、可用范围正确，并且「调用情况」和「任务中心」能看到真实调用。某一步成功不能替代其他步骤。
12.5 导入与分发技能
「技能」页面管理本租户可分发给成员的技能（Skill）。列表可按「状态」「分类」筛选，或在「搜索技能或分类」中搜索。
导入技能：选择「添加技能」，在同一对话框中选择一种来源：
| 来源 | 操作 |
|---|---|
| 公共目录搜索 | 在「搜索 registry」中输入关键词，搜索对接 skills.sh 公共目录 |
| 来源坐标或地址 | 在「技能来源」中填写名称或地址，支持 skills.sh 名称（如 react-best-practices）、owner/repo@skill、gitlab:group/repo、github.com/owner/repo#v1.2、ClawHub 地址、站点发布的 .well-known 技能清单地址或压缩包下载地址 |
| 本地上传 | 在「或上传技能包」中选择 .zip 文件，压缩包内须包含 SKILL.md |
- 填写来源后选择「分析来源」。上传
.zip只触发风险分析，不会立即安装。 - 页面列出发现的候选技能，以及每个技能的风险等级、检查清单和准入结论。可选择「查看内容」预览技能文件。
- 对允许安装的技能选择「确认安装」。
单个下载包上限为 20 MiB。内网环境无法访问公共目录时，需由部署管理员把搜索与下载地址配置为私有镜像（部署参数 LP_SKILLS_SEARCH_API_BASE、LP_SKILLS_DOWNLOAD_BASE、LP_CLAWHUB_API_BASE）。
安装前检查：所有来源在安装前经过同一套检查，覆盖 SKILL.md 与附件中的提示注入、凭据外泄、破坏性命令、路径穿越，以及可执行文件与脚本、依赖安装、Shell 执行、外部网络访问、宽泛权限与敏感数据等十五项内容。检查基于规则匹配，不做语义分析。
检查结果按六级风险判定：「纯指南」「知识资产」「受管集成」「本地执行」「外部 / 高敏」「禁止级」。准入结论如下：
| 结论 | 含义 |
|---|---|
| 「允许安装」 | 风险等级在租户准入线内 |
| 「企业策略拒绝」 | 风险等级超出租户准入线 |
| 「安全规则阻断」 | 命中提示注入、凭据外泄、破坏性命令或路径穿越等禁止项，判为「禁止级」，一律阻断 |
| 「扫描不完整，按高风险处理」 | 检查未能完整执行 |
| 「分析失败」 | 来源无法解析或下载 |
页面以风险标尺展示「你所在企业的准入线」和该技能超出准入线的档数。租户准入线默认为「外部 / 高敏」，不能设为「禁止级」，管理员导入同样受准入线约束。调整准入线通过开放 API。
分发：技能详情的标签包括「信息」「可用范围」和「下载记录」。在「信息」中打开「发布」，再在「可用范围」中按所有用户、部门、职能组或成员授权，并设置生效与失效时间，到期自动失效。授权给部门时，其下级部门的成员同样获得授权。
下载记录：成员在能力中心「技能广场」打开技能详情，选择「下载 Skill 包」，或复制安装链接与安装命令。管理员在技能详情的「下载记录」中查看每次下载的「时间」「下载方式」（Registry 拉取或手动下载 zip）和「下载人」。
维护：在技能详情选择「编辑」修改「名称」「描述」「分类」，或选择「从来源重新导入」获取来源的最新版本。选择「删除」时，页面列出已分发目标数量及引用关系，需二次确认；删除后技能无法恢复，相关分发一并移除。
12.6 导入与导出插件
插件把技能和远程 MCP 服务打包为一个插件包，供外部智能体工具整体安装。「插件」页面列出「插件」「状态」「更新时间」和操作，工具栏提供「导入」「导出为插件」和「刷新」。
导入插件包：
- 选择「导入」，在「导入插件包」中选择「插件包(.zip)」。需要参考格式时选择「下载示例包」。
- 选择「预览」，核对将要导入的组件及其是否受支持。
- 选择「导入」。包内的技能组件与技能导入使用同一套安装前检查，超出租户准入线或命中禁止项的技能会使导入被拒绝。
导出为插件：
- 选择「导出为插件」，在「导出为 Agent 插件」中填写「插件名」「版本」「描述」和「许可证」。
- 勾选要打包的「技能」和「MCP 服务」。只有远程（Streamable HTTP 或 SSE）MCP 服务可导出，其他服务显示「不可导出」；名称含非 ASCII 字符的技能需手动填写「技能 slug」。
- 选择「预览」核对内容，然后选择「导出」下载 zip，或选择「保存到平台」把同一份包保存到本租户的插件列表。
导出的插件包不含任何凭据：MCP 服务只带服务地址，请求头为空，凭据只以需求声明的形式写入，目标端需自行配置。打包前平台还会检查请求头名称和取值，发现疑似凭据时拒绝导出。
分发与发布：插件详情的标签包括「概览」「组件」「来源与供应链」和「分发」。
- 在列表中对插件选择「分发」，按可用范围向成员授权。
- 在详情的「分发」标签中选择「申请发布」，把插件发布到内部分发目录，状态依次为「审核中」「已发布」。发布申请需经平台审核；插件在发布后又更新时状态为「待重新发布」，需「重新申请发布」。不再提供时选择「下架」，之前发出的安装链接随即失效。
发布本身不授予使用权限，成员能否使用仍由可用范围决定。成员在能力中心「插件广场」页签打开插件详情，可「复制个人插件源链接」用于安装。
12.7 同步外部注册中心
「外部注册中心」用于接入 Nacos 命名空间，按轮询间隔把其中的外部智能体和 MCP Server 同步到网关。当前仅支持 Nacos。
- 选择「新建源」，在「新建外部注册源」中填写「名称」「地址」「命名空间」和「轮询间隔（秒）」。轮询间隔默认 30 秒，最小 5 秒。
- Nacos 需要认证时填写「用户名」和「密码」，两者必须成对填写；匿名访问可留空。
- 选择同步对象：「同步外部智能体」「同步 MCP Server」。
- 按需打开「自动批准（信任源）」。打开后同步进来的条目无需逐个审批即可代理调用。
- 选择「保存」，然后选择「测试连接」。结果显示可同步的外部智能体数、MCP 数和跳过的模板数；不支持的 REST 转 MCP 模板会被跳过。
- 在列表中选择「立即同步」，或等待按轮询间隔自动同步。列表显示「健康」「最近同步」和「启用」状态。
同步规则如下：
- 同步进来的外部智能体和 MCP 服务仍需在各自的可用范围中显式分发，成员才能看到。「自动批准」不改变这一点。
- 同一注册源的同一条目重复同步时更新原记录。被拒绝的条目在下次同步时回到待审批状态。
- 上游条目连续两次轮询都不存在时才视为删除：外部智能体被停用，MCP 服务被归档并吊销其网关令牌。单次同步结果为空或删除超过一半时，平台暂停删除并标记为降级。
- 删除注册源会吊销其同步进来的 MCP 网关令牌，并移除已同步的外部智能体和 MCP 服务；之后可重新接入。