AVL Code

第十二节 外部工具服务接入

智能体管理器 →「配置工具」面板支持连接任意标准协议的工具服务（例如 Notion、内部 API、私有知识库）。

注意与 设置 → 提供商 区分：后者配置的是大模型供应商，与这里的外部工具服务是两回事。

12.1 添加一个外部服务

  1. 输入区模式滑块旁的齿轮（智能体管理器）→「配置工具」→ 添加服务。
  2. 选择通道：
    • Streamable HTTP（默认）/ SSE：填写接入地址（URL）+ 凭证 — 适合云端服务。现代 MCP 服务多用前者；两者填错时连接会自动协商回退，不必纠结选哪个。
    • stdio（本地进程）：填写要启动的命令行（如 npx -y @some/mcp-server） + 环境变量 — 直接在本机起一个子进程作为 MCP server，不必再要求对方提供 HTTP 地址，方便接 npm / pip 上现成的 MCP 实现。
  3. 填写：
    • 名称：例如 notion。
    • 凭证：从对方平台获取的访问令牌（HTTP / SSE 通道）；或子进程要的环境变量（stdio 通道）。
  4. 启用。

界面已重做：新建表单、后端详情、健康看板、安装确认弹窗整体改为更克制的数据表质感 — 技术信息用等宽字体披露、发丝级边框、状态圆点，整体更清爽专业。

12.1.1 远程 MCP 的 OAuth 登录

对于需要登录的远程 MCP 服务，新建流程内嵌OAuth 2.1 + PKCE 授权：

  • 建的时候就能登录：授权入口放在「新建 MCP」流程里（不再藏在建好之后的详情），点「OAuth 授权」会跳浏览器走标准授权码 + PKCE 流程，本机回环回调收到 token 后自动落地。
  • 自动续期：access token 在到期前用 refresh_token 在启动时 / 后台自动换新，授权成功后界面即时反馈并刷新状态，不必反复手动重连。
  • public client（无 client_secret）和带 client_secret 的 confidential client 都支持；endpoint 可通过 .well-known 自动发现，也可手填。

12.1.2 安装确认弹窗：权限与依赖一目了然

装一个 MCP 后端 / 插件前，安装确认弹窗会把以下内容披露给你：

  • 要披露的工具权限：会启用哪些工具、各自的允许 / 询问 / 禁用默认值。
  • 声明的工作模式：permissionMode / allowed-tools 等约束（来自插件 manifest）。
  • 对本机的依赖：如需要 node / python / git 等本机命令、操作系统、平台架构限制。
  • 远程工作区下额外给出轻量提示，避免装上对方机器没有的依赖。

12.2 工具命名空间

外部服务暴露的工具会被自动加上前缀（例如 notion.search、notion.create_page），在工具列表里独立成组，互不冲突。

12.3 实时生效

新连上的外部服务下个回合即对助手可见，不必重开对话。这一特性让你可以在对话过程中随时增配服务。

开启工具分类延迟加载（默认开启，见 §9.2.1）时：会话进行中新连上的服务会直接可用，不用等助手主动加载；新开会话后才回到"用到时才加载"。

12.3.1 单独设置某个服务是否延迟加载

在智能体管理器 →「配置工具」Tab 里，每个外部工具服务都有一个「延迟加载该服务的工具」开关：

  • 开启（默认）：该服务的工具不常驻，助手用到时才加载。
  • 关闭：该服务的工具始终可用 —— 适合你高频使用的服务。

若全局的「工具分类延迟加载」已关闭，所有工具本就常驻，此开关暂不起作用，界面会直接说明。

助手在系统提示词里会被告知你接入了哪些外部服务，并附上每个服务的工具数量与几个示例工具名，因此即使工具暂未加载，它也知道该找谁。

12.4 异常处理

  • 断连重试：后端断开会自动指数退避重试。
  • 错误抽屉：错误信息会拼接服务端原始返回，便于定位是凭证过期、网络不通还是服务端故障。
  • 就绪探测：连接建立后 AVL Code 会先做一次 ping，确保对端真正可服务再登记到工具列表。
  • 后端一时缺席不再整体失效：某个后端暂时缺席 / 未就绪时，工具调用过去会返回「unknown tool」协议错误把工具整体拖垮；现在对未知工具做兜底处理，并在需要时按需重连、自愈，等后端就绪后自动恢复可用。

12.4.1 MCP 健康看板

MCP 配置 → 健康看板 按后端展示每个 MCP 的调用次数 / 失败率 / 响应耗时（P50 / P95），一眼看出哪个服务慢、哪个在报错；某后端最近一次失败的错误信息也会在该行展开，便于定位。

数据来自 MCP 网关的环形缓冲统计（最近一段时间窗口），实时刷新。

12.5 安全 — 凭据国密加密存储（VAULT）

  • MCP 后端的鉴权令牌（HTTP Bearer AuthToken）和 stdio 子进程的环境变量整张 map 不再明文落盘，统一存进国密加密的凭据库（SM4-GCM + HKDF-SM3、与本机 machineID 绑定，跨机即失效）。
  • OAuth refresh_token + 续期元数据同样进 VAULT，绝不入 zmcp.yaml 主配置、绝不入日志。
  • 存量配置自动迁移：旧的明文凭据下次使用时被动迁移到 VAULT 加密存储，无需手工干预；machineID 不可达 / 变化时优雅降级（回退提示重输），不会神秘失败。
  • 冷启动 401 修复：之前带鉴权的 HTTP MCP 服务在电脑 / 应用冷启动后第一次调用会报 401——根因是 zMCP 网关子进程的归档 key 错误使用了每次启动都变的临时 127.0.0.1:<端口> URL，而 App 父进程是按稳定的 workspaceID 落库，导致 Load 恒 miss、回退到「存量被动迁移已清空」的明文（即空字符串），最终发了个空 Bearer 头被后端拒绝。本版改为读写两端都用稳定的 workspaceID 当 key，冷启动后正常带凭据连上、无需手动重配。
  • 凭证以加密形式存储在本机，不会随同对话内容上传到模型。
  • 第三方 stdio 服务拿不到网关管理密钥：以标准输入输出方式启动的第三方 MCP 服务不再继承工具网关的管理密钥，第三方进程不会持有本不该拥有的网关管理权限。
  • 可在智能体管理器 →「配置工具」中针对每个外部服务独立设置工具权限策略。