原型PRD 说明

一、建设目标与范围

通过连接器接入外部 MCP 服务，让用户在 DF AI 对话、专家等场景中使用授权范围内的工具能力。

• 展示预置外部服务及用户创建的自定义连接器；内置连接器不对外展示，分类仅保留“全部”。
• 支持配置、授权、连接、工具发现、断开和异常反馈。
• 优先支持远程 Streamable HTTP，兼容 SSE。
• 自定义 STDIO 暂不纳入本期真实连接范围，不能将保存配置视为连接成功。

二、页面功能

1. 连接器列表

以卡片展示名称、图标、简介、连接状态及操作入口，支持搜索。点击卡片查看连接器介绍、配置及可用工具；通过创建入口新增自定义连接器。列表中的连接状态必须来自后端真实会话，不得仅依赖前端缓存。

2. 自定义连接器创建

提供“表单填写”和“JSON 配置”两种方式。

JSON 配置需解析并校验服务名称、地址、传输方式、请求头等字段。一期每次处理一个 MCP 服务；多服务配置应明确提示，不能静默只导入其中一个。“Skill 使用说明”仅作为使用参考，不得覆盖系统规则、权限校验或危险操作确认。

3. 保存与测试连接

保存配置与建立连接是两个动作。

• 保存：记录配置，不代表已授权或已连接。
• 测试连接：执行 MCP 初始化及工具列表获取，返回结果。
• 测试结束：释放临时会话，不占用正式连接。
• 测试不得自动调用写入、修改、删除等工具。
• 需要 OAuth 时，提示完成授权后再连接。

当前原型要求已连接的自定义连接器先断开再编辑。正式开发可沿用该规则，避免配置更新与运行中的会话不一致。

4. 正式连接

用户点击连接后，后端负责：配置校验 → 获取或校验凭据 → MCP 初始化 → 获取工具列表 → 保存会话 → 返回连接结果。

连接过程中显示加载状态，防止重复点击，并支持取消。取消后，迟到的成功响应不能将连接器重新变为“已连接”；后端应关闭取消请求对应的会话。

5. 可用工具与调用

连接后展示服务实际返回的工具名称、描述及参数要求。

• 使用当前会话发现的工具及参数结构。
• 后端校验工具是否允许调用、参数是否合法。
• 区分请求失败与工具执行失败，不能只依据 HTTP 200 判断成功。
• 写入、修改、删除等操作执行前展示操作对象及影响，由用户确认。
• 工具返回内容作为外部数据处理，不能改变平台权限或系统规则。

6. 在对话与专家中使用

连接器选择器仅展示当前用户有权使用且已成功连接的内容。

• 未连接、已失效或正在授权的连接器不可选择。
• 断开后，同步更新列表、选择器及专家关联状态。
• 已关联的连接器失效时，保留关联记录并提示重新连接。
• AI 使用连接器时，由后端将可用工具纳入当前请求，再执行工具调用。

“连接器卡片显示已连接”不等于“对话已具备自动调用能力”；AI 工具编排链路需要技术单独实现。

三、状态与反馈规则

• 未连接：配置已保存，可发起连接。
• 连接中：显示加载，可取消，禁止重复连接。
• 待授权：提供授权入口，允许取消等待。
• 已连接：会话有效，已发现可用工具。
• 无可用工具：握手成功但工具为空，提示检查工具名单或权限。
• 授权失效：提示刷新凭据或重新授权。
• 连接失败：展示原因及重试入口。
• 已断开：不再参与工具选择和调用。

错误信息应区分：地址错误、认证失败、权限不足、工具名单为空、网络异常、超时及服务返回错误。禁止在提示中输出完整密钥或令牌。

四、授权与权限规则

1. 使用平台统一用户体系

连接配置、授权凭据和 MCP 会话绑定 DF AI 登录用户及所属组织。不得使用客户端 IP、浏览器本地标识或前端传入的用户 ID 作为唯一身份依据。

2. 可见权限与远端权限分别校验

• “公开”指平台范围内可见，不代表公开到互联网。
• 用户能看到连接器，不代表自动获得创建者的远端访问权限。
• 用户身份授权的连接器，由使用者分别完成授权。
• 共用应用凭据的连接器，需要管理员配置，并限制可使用人员和资源范围。

平台可见权限、MCP 工具权限、第三方资源权限三层都应生效。

3. 凭据管理

• Token、API Key、App Secret 由后端加密保存。
• 前端使用掩码展示，不保存到 localStorage 或页面源码中。
• 日志、埋点及接口错误统一脱敏。
• 根据服务提供的有效期管理令牌，支持刷新或重新授权。
• 断开 MCP 会话与撤销第三方授权分别处理，文案应说明实际影响。

五、后端实现规则

1. 连接服务

采用 MCP SDK 实现初始化、工具发现、工具调用和会话释放。浏览器通过 DF AI 后端访问 MCP 服务，后端统一处理认证、超时及错误；静态 HTML 本身无法完成整套真实连接能力。

2. 服务地址校验

• 正式环境原则上使用 HTTPS；本机 HTTP 仅用于开发环境。
• 后端校验目标域名、解析后的 IP 和重定向地址，限制非授权内部地址。
• 不接受地址中嵌入用户名、密码等认证信息。

3. 会话管理

每个会话至少关联用户、连接器、配置版本、授权身份、工具列表和连接状态。配置或凭据变化后，应建立新会话，避免复用旧配置。服务重启后需重新建立连接或明确标记失效，不能保留虚假的“已连接”。

4. 调用记录

记录调用人、连接器、工具、时间、耗时及结果状态。参数与返回内容按敏感字段脱敏。写操作不能因网络超时而盲目自动重试，避免重复创建或重复修改。

六、开发联调候选

• 飞书：远程 MCP、UAT／TAT、允许工具名单、应用权限和文档权限。
• 腾讯广告：MCP KEY 与 Marketing API access_token 的配置及失效反馈。
• 巨量引擎：官方服务配置、授权账户及工具发现。
• 有道云笔记：SSE 连接、API Key、笔记检索与读取。
• 腾讯 ima：核实官方接入方式；若仅提供 OpenAPI，需先封装为 MCP 服务。

腾讯 ima、有道云笔记为开发测试候选，尚未完成实际联调。测试使用专门账号与测试内容。

七、验收标准

1. 保存配置后显示“未连接”，不能直接显示成功。
2. 有效配置能够完成初始化并获取工具列表。
3. 空工具列表、无效凭据、权限不足和超时有明确反馈。
4. 连接取消、断开及会话失效能同步到所有关联界面。
5. 工具调用按真实返回结果判定成功或失败。
6. 不同用户的授权、会话及资源访问范围相互隔离。
7. 前端、日志和报错不暴露真实密钥。
8. 对话及专家仅使用有权访问且连接有效的工具。
9. 写操作有确认机制，超时不会导致盲目重复执行。

八、当前原型与正式开发的边界

现有原型已包含配置表单及本地 MCP 运行服务代码，可作为开发参考；当前静态页面不能独立完成真实连接。正式开发仍需完成平台后端部署、用户身份绑定、凭据管理、令牌刷新、AI 工具编排和真实联调。本说明不代表上述能力已通过生产验收。