Agent Tool Connectors：统一 Agent 接入

1. 目标与核心原则

平台是用户与 SaaS 之间唯一的授权与凭据边界，是 Agent 与 SaaS 之间唯一的接入面。产品命题：把 Agent 侧接入面收敛为标准、静态、无 Secret 的最小合同。

2. 系统结构

四个部件、三层。云端 Gateway 是控制面与聚合面；用户本机的 Host Runtime（可选安装）承载凭据注入；Agent 只见到一个 URL 和一个 PATH 目录。

部件职责边界

Host 侧进程与权限模型

• 一个 User 绑定一台 active Linux Host；Host 无任何公网监听，控制通道由 Host 出站建立。
• 平台服务（Forwarder、Vault、proxy）以专用 agent-connectors 系统 UID 运行；Agent 使用另一个无特权 UID。两者数据目录互不可读写。
• Agent UID 不能读取任何 Token 文件；它只能通过 loopback 端点使用能力。

3. 用户流程

用户永远不需要：管理 Token、改 Agent 配置、感知某家 SaaS 走哪条路径。连接对象是"用户 ↔ SaaS 账号"，与 Agent 无关——连一次 Slack，用户所有 Agent 都能用；换 Agent 不需要重新授权。

对话内连接（平台 meta-tools）

Gateway 通过同一个 /mcp 暴露连接管理元工具：sider.list_connections（已连接/可连接清单）、sider.request_connection（发起授权，返回浏览器 URL）、sider.connection_status（轮询结果）。Agent 由此在对话内引导用户完成连接，无需各家自建连接 UI。

4. 连接管理界面：Portal 与接入方自建 UI

连接管理有两个消费方：终端用户（用平台自带 Portal）与有界面能力的接入方产品（在自己的应用里为其用户内嵌连接管理）。两者共享同一套底层：Portal 本身就是 Connections API 的第一个客户，接入方能做到的 Portal 都能做到，反之亦然。

4.1 连接状态机（所有界面共享）

4.2 平台 Portal 原型（可交互）

下面是可交互原型（模拟数据）。点"连接"会打开模拟的第三方授权窗口——先是该 SaaS 自己的登录页，然后是授权同意页（scope 列表，可授权或拒绝），成功后经固定落地页跳回 Portal。其余可体验：Supabase 的 projectRef 额外输入、等待授权的轮询态、管理抽屉（多账号、审计摘要、通知开关、二次确认断开）、失效重连、Host Runtime 未安装时 native_cli 的安装引导（右上角开关模拟）。交互合同以 4.1 状态机与 4.3 API 为准。

• 连接点击后跳转 SaaS 授权页；回调落地页只有三态（成功 / 已取消 / 失败），不含任何参数回显，数秒后自动回到目录页。
• 需要额外输入的 Provider（如 Supabase 的 projectRef）在跳转前以单字段表单收集，输入约束由 Catalog 声明。
• native_cli 类 Provider 在 Host Runtime 未安装时，连接入口显示"需要本机组件"并引导安装，而不是失败。
• 多账号：同一 SaaS 显示为同一张卡的多个账号行（以 accountHint 区分），不是多张卡。

4.3 接入方自建 UI：Connections API

面向接入方应用界面的 HTTP API（meta-tools 面向 Agent 的 LLM，二者能力对等、同一底层）。接入方通过平台 OAuth 为其用户取得 user-scoped 凭据（scope：connections:manage）后调用。

4.4 推荐接入界面（接入方按此蓝图实现）

• 授权必须在系统浏览器或独立窗口完成；禁止内嵌 WebView 代填——接入方永远接触不到用户的 SaaS 凭据。
• 断开必须二次确认，并明确后果：该账号工具立即从所有 Agent 消失、凭据删除。
• 多账号 Provider 必须展示 accountHint，调用时由用户或 Agent 用 accountId 选择。
• 连接成功后建议就地提示"你的 Agent 现在可以使用 <SaaS> 的工具了"，把连接动作与能力生效直接关联。

4.5 会话内入口示例：Sider Channel 输入框（可交互）

4.4 蓝图在 Sider Channel 里的具体落点：输入框左下角常驻"连接器"按钮（对应产品截图中标注的位置，交互对标 Claude 的 "Add connector" 菜单）。点击向上弹出连接器菜单——已连接的显示状态、未连接的可直接发起（走同一个第三方授权窗口）。下面的示例与 4.2 的 Portal 原型共享同一份状态：在菜单里连接 Notion，Portal 的卡片会实时同步，反之亦然——这正是"菜单只是 Connections API 的另一个消费者"的直观演示。

• 菜单内直接发起连接：同一个第三方授权窗口、同一个状态机；连接完成后工具经 tools/list_changed 立即可用于当前会话，菜单徽标数同步 +1。
• 菜单是轻量入口，只做状态一览与发起连接；账号管理、审计、断开等重操作跳转 Portal（或接入方的完整管理页）。
• 入口按钮常驻但不打扰：无连接时引导首连，有失效连接时显示琥珀色状态提示重连。

5. Agent 接入合同

合同全部内容只有两项。没有按品牌定制的 Adapter、没有平台对 Agent 配置文件的写入与所有权、没有续期触碰。

目标 Agent 的接入命令（2026-07-29 实测）

# Claude Code —— 写入 .mcp.json（project scope）或用户配置
claude mcp add --transport http connectors http://127.0.0.1:14323/i/<bindingId>/mcp

# Codex —— 写入 ~/.codex/config.toml 的 [mcp_servers.connectors]
codex mcp add connectors --url http://127.0.0.1:14323/i/<bindingId>/mcp

# OpenClaw —— probe 成功后写入 openclaw.json 的 mcp.servers.connectors
openclaw mcp add connectors --url http://127.0.0.1:14323/i/<bindingId>/mcp --transport streamable-http

Agent 能力矩阵（新 Agent 按能力接入，不做品牌枚举）

6. 三条调用路径

Agent 侧完全统一（tools/list → tools/call）；每家 SaaS 走哪条路径由平台 Catalog 决定，Agent、Host 与用户都不能选择或覆盖。Catalog 是 Provider trust root。

初始 Provider Catalog

Agent --tools/call linear.create_issue--> Forwarder（注入短期Token）--> Gateway /mcp
    Gateway: 鉴权 -> 定位该用户的 Linear Connection -> Vault 解密 Linear Token
          -> 调 Linear API -> 归一化结果（无凭据泄漏）-> 返回

Agent --tools/call slack.post_message--> Gateway /mcp
    Gateway: 定位用户的 Slack Connection + Token -> 以平台身份创建独立上游 MCP session
          -> 调 mcp.slack.com -> 归一化结果 -> 返回

Agent shell: ntn search "会议记录"
    PATH 命中 shim -> 本机凭据注入 proxy（loopback）-> 注入用户 Notion Token -> Notion API

7. 审计与可见性

连接即全可用：用户在 OAuth 授权时已经给出同意，平台不做事前审批、不打断任何调用。交互式确认（"要不要执行这一步"）是 Agent 侧的既有职责——人与对话上下文都在 Agent 那一侧（如 Claude Code 的工具确认、OpenClaw 的 ask 模式）。平台提供的是被动可见性与事后控制，对三条路径一致生效。

三层可见性（全部零打断）

风险分类（仅作元数据，不驱动拦截）

• 风险分类从上游工具 hint 与名称推导，成本趋近于零；用于审计标注与通知筛选，不用于事前拦截。
• 保留分类元数据意味着未来的团队/企业形态可以在其上叠加策略开关（如"生产库 delete 需管理员批准"），无需重新架构；个人形态默认永不拦截。
• 审计与通知只记录参数摘要、风险与结果摘要；不记录凭据与原始敏感内容。

8. 凭据生命周期

四类凭据、四个落点。任何一类都不进入 Agent 的配置、argv、日志或普通环境。

短期 Token 续期链

• fetch 服务以独立动态 UID 持长期续期凭据向 Gateway 换取短期 Token 响应；apply 以 agent-connectors UID 把新 Token 写入 Forwarder token 文件。全链路不触碰 Agent。
• 续期使用稳定 requestId 与 CAS，容忍响应丢失后的幂等重试。
• 会话不中断要求：Gateway 的 MCP session 所有者必须仅由 userId + hostId + instanceId + credentialGeneration 构成，不含 tokenId；续期只换 tokenId、不换 generation，因此进行中的 MCP session 跨续期继续有效（已实验证实，见第 13 节 E6）。
• 旧短期 Token 在新 Token 生效后立即失效（服务端只认实例当前 tokenId）。

9. Remote MCP 上游合同要点

remote_mcp 路径把 SaaS 官方 Hosted MCP 纳入平台。以下是实现必须满足的合同要点；Catalog 中的 endpoint 与 origin allowlist 是信任根。

OAuth 发现与信任链

• 发现链固定：Catalog protected-resource metadata URL → RFC 9728 Protected Resource Metadata → authorization_servers[0] → RFC 8414 Authorization Server Metadata → authorization / token / registration endpoint。
• Catalog 固定两层 origin allowlist（Authorization Server origin 与 OAuth endpoint origin）；所有 discovered endpoint 必须 HTTPS 且命中 allowlist。
• OAuth start 与 callback 都必须重新执行发现，且 callback 侧结果必须与 state 中保存的一致；metadata 请求禁止跟随 redirect。
• 始终发送 PKCE S256。metadata、DCR、token、identity 请求统一 20 秒超时、1 MiB 响应上限。
• Client 策略两种：configured_only（部署方预配置 Client ID/Secret，如 Slack、Box）与 dynamic_if_unconfigured（未配置时走 DCR，如 Supabase、Atlassian；临时 Client Secret 立即加密入 Vault，拒绝/过期必须清理）。
• Connection 必须有稳定 externalAccountId（如 Slack teamId:userId、Box /users/me 的 id）；identity 查询失败则整个 callback 失败，不得创建无稳定身份的 Connection。同 User 多账号按稳定 ID 新增，不得互相覆盖。

凭据并发：CAS 与 refresh lease

• 同一加密 credential 的 Token 刷新、refresh lease 与工具快照都通过 getVersioned + compareAndSwap 修改；禁止无条件整体覆盖。
• refresh lease 必须在上游 I/O 前通过 CAS 获得——并发请求只允许一个使用可能单次轮换的 refresh token；等待者观察到 Token lineage 变化后直接采用 winner。
• 访问 Token 距到期不足 60 秒预刷新；上游 401 允许一次强制刷新加单次重试。lease TTL 30 秒；连续 16 次 CAS 冲突后失败关闭。
• snapshot writer 与 refresh writer 互不覆盖对方的并发写入。

上游 MCP client 与预算

• 每次上游操作创建独立 MCP client 与 session，不跨 User、Connection 或请求复用；协商协议 2025-06-18（fallback 2025-03-26）；SSE 增量解析并在取到匹配 id 后立即取消。
• 工具快照保存在对应 Connection 的加密 credential 内，不得跨 User 或账号共享。
• 工具名只接受 [A-Za-z0-9_.:/-]（≤120，加前缀后 ≤128）；平台附加参数为 accountId（多账号选择），与上游冲突时用 _connector_account_id fallback，双冲突则该工具失败关闭；平台参数调用上游前必须剥离。
• 多账号暴露同名工具时，仅 schema、风险与参数选择完全一致才聚合，否则隐藏。
• 上游错误对 Agent 归一化，不回显 Bearer Token、OAuth 响应或内部 endpoint。

10. 架构决策记录

两个关键架构决策及其依据，按长期质量（干净的职责边界、可独立迭代、不产生日后要偿还的过渡形态）选定。

11. 实施阶段

从零构建的交付顺序。每阶段独立可发布、可验收；后一阶段不阻塞前一阶段上线。

12. Forwarder 合同规格

本节由可运行原型与 13 项合同测试验证得出（原型脚本见 experiments/agent-integration/）。规格覆盖路由、注册表、Token、头透传、流式与失败语义。

定位与进程模型

路由

实例注册表与 Token 文件

# instances.json（agent-connectors 私有，0600；mtime 变化即热加载，新增 bind 无需重启）
{
  "<bindingId>": {
    "instanceId": "<AgentInstance id>",
    "upstreamUrl": "https://<gateway>/mcp",     // 仅允许 HTTPS 或 loopback HTTP
    "tokenFile": "/var/lib/agent-connectors/mcp-forwarder/<instance>.token"  // 必须绝对路径
  }
}

• Token 逐请求从 tokenFile 读取——续期热替换天然生效，无缓存失效问题。
• tokenFile 缺失或为空：503 token_unavailable，fail closed，不得调用上游。
• Token 不得出现在任何响应、日志或错误信息中。
• 续期 apply 的唯一落点就是 tokenFile；不触碰任何 Agent 的配置、state 或进程。

头透传（白名单制，未列出的一律丢弃）

流式与失败语义

• 上游响应头到达即 flush 给 Agent——SSE 无事件期 Agent 的 fetch 会一直等 headers（实验实证的关键实现要点）。
• 响应 body 逐 chunk 透传，禁止整体缓冲；JSON 与 SSE 同一条路径。
• Agent 断开连接必须 abort 对上游的请求，不留悬挂连接。
• 上游不可达：502 upstream_unreachable，不泄漏上游细节；内部异常：500 归一化。

合同测试清单（原型已全部跑通，实现必须逐项覆盖）

13. 实验验证记录

方案的关键假设已用可运行原型与真实 Agent CLI 验证（环境：本地 Gateway + 约 100 行 loopback Forwarder 原型；脚本与复现步骤见下）。

已验证（2026-07-29 本机实测）

待验证（发布前完成）

复现步骤

# 1. 起本地 Gateway（任何实现了第 6 节 /mcp 合同的 Gateway 均可）
npm run dev

# 2. 起 Forwarder 原型（默认 127.0.0.1:14330 → 127.0.0.1:8787/mcp）
cd experiments/agent-integration
printf '%s' "$DEV_AGENT_TOKEN" > current-token
TOKEN_FILE=./current-token node forwarder.mjs

# 3. E1+E6：透传与 Token 热替换（10 项断言）
TOKEN_FILE=./current-token GOOD_TOKEN="$DEV_AGENT_TOKEN" node e1-e6-client.mjs

# 4. E1-SSE：增量透传（模拟 SSE 上游 :14340）
TOKEN_FILE=./current-token UPSTREAM=http://127.0.0.1:14340/ node forwarder.mjs &
node e1-sse-incremental.mjs

# 5. E4：官方配置命令（隔离，不污染真实配置）
claude mcp add --scope project --transport http connectors http://127.0.0.1:14330/mcp   # 空目录内
CODEX_HOME=$(mktemp -d) codex mcp add connectors --url http://127.0.0.1:14330/mcp
openclaw --profile e4test mcp add connectors --url http://127.0.0.1:14330/mcp --transport streamable-http

14. 验收标准（发布门禁）

• 三家目标 Agent 各自只用第 5 节的官方命令 + 一行 URL 完成接入，配置文件中无任何 Secret。
• 任一 Agent 上：连接新 SaaS 后不改配置即可在（至多下一次）tools/list 中看到新工具并成功调用。
• 续期发生时：Agent 配置零变更、Agent 进程零重启、进行中的 MCP session 不中断（签名 Token，staging 验证）。
• Native CLI 在仅 PATH 注入下可用：OpenClaw 用官方 config set tools.exec.pathPrepend；allowlist 部署由用户官方命令自助添加；staging 完成一次真实 LLM turn 的 exec 冒烟。
• Forwarder 通过第 12 节全部 13 项合同测试。
• meta-tools 对话内连接闭环：未连接 → 授权 URL → 浏览器授权 → connected → 调用成功。
• Portal 三页面全流程可用（目录 → 授权落地 → 管理/断开），覆盖第 4 节状态机全部状态。
• 接入方仅用 Connections API（不依赖 Portal）即可实现完整连接管理界面：列表、发起授权、轮询、断开、审计摘要。
• 每个 remote_mcp Provider 完成真实 E2E：授权、稳定 identity、tools/list、只读调用、写操作、refresh rotation、revoke。
• 两个 User 交叉验证：Connection、Token、工具快照、审计记录互不可见。
• 第 8 节凭据落点表逐条复核：每类凭据只出现在声明的落点，Agent 侧无任何凭据痕迹（配置、argv、日志、普通环境）。

15. 安全边界