可安装连接器框架设计

Poco 的连接器目录来自管理员安装的 ZIP 包。仓库和镜像不预置业务连接器；空数据库启动后目录为空。连接器包声明展示、管理员配置、用户授权、工具策略和可选 Skill，也可以携带一个受信任 Python 程序实现非标准协议。

第三方包的字段、示例和程序 JSON 协议见连接器安装包开发手册。

1. 设计目标

框架保证以下契约：

• 包版本不可变，数据库投影、S3 归档和运行快照可以互相校验。
• 管理员配置与用户凭据分开保存，密钥不通过公开 API 返回。
• 一个 Run 从创建到结束始终使用同一包版本、工具集和授权代次；凭据可按既有授权机制正常刷新。
• 包更新保留定义、配置、发布状态和连接；只有授权契约变化才要求用户重新授权。
• 工具默认拒绝，只有包清单明确声明的工具能暴露给 Agent。
• Connector Skill 从运行快照锁定的归档加载，不能被后台更新悄悄替换。
• 框架提供标准远程 MCP 和 OAuth；特殊 REST API 或授权通过包内程序实现。

2. 数据模型

ConnectorDefinition

连接器定义是当前生效版本的管理投影，保存：

• 固定 key、当前 package_version 和 manifest_revision。
• 管理员公开配置与加密密钥配置。
• 草稿、已发布或已禁用状态，以及排序。
• configuration_revision 和 authorization_fingerprint。

定义 UUID 在更新中保持不变，因此用户连接和历史运行仍指向同一个逻辑连接器。

ConnectorPackageVersion

每次安装产生一条不可变版本记录，包含完整清单与翻译投影、归档摘要、大小、S3 key 和安装人。<connector_key, package_version> 与 <connector_key, manifest_revision> 都唯一。

S3 对象位于：

connectors/packages/<key>/<package_version>/<manifest_revision>-<record_id>.zip

Backend 与 Executor Manager 都先校验归档 SHA-256，再安全解压并校验目录内容摘要。缓存按 <key>/<manifest_revision> 隔离，并使用进程间文件锁避免同版本并发落盘。

ConnectorConnection 与 ConnectorCredential

连接表只保存账号展示信息、授权状态、授权指纹、授权代次、scope、公开元数据和健康状态。凭据表单独保存加密密文、凭据版本、过期时间以及刷新租约。

用户断开连接时，服务先让连接退出可用状态，再通过撤销任务调用 provider；业务模块不直接接触明文凭据。

ConnectorAuthorizationSession

授权会话保存挑战类型、一次性状态摘要、PKCE 上下文、授权意图、目标连接、配置版本与授权代次。开始、提交、回调和取消都校验当前定义版本，防止旧页面覆盖新授权。

3. 包加载与投影

安装接口分两步：

1. inspect：安全解压临时文件，校验清单、翻译、资源、Skill、程序入口、版本和目标 key，返回管理员填写表单所需的投影。
2. install/update：再次独立校验上传内容与配置，上传 S3、预热校验缓存、写入版本记录和当前定义，在同一数据库事务中提交。

S3 上传发生在数据库提交前。提交前的校验失败会尝试回滚、清理缓存和刚上传对象；commit 异常时提交结果可能未知，因此有意保留归档，避免已提交记录引用丢失包。上传本身失败时数据库不发生变化。

已发布连接器默认向所有正常登录用户开放。管理员可以在连接器配置中把可见范围改为指定团队和用户，定义上的 visibility_restricted 标记是否限定范围，允许的团队和用户记录在 connector_visibility_scope_items；限定范围后即使团队或用户被删除导致记录清空，也只对管理员可见，不会退回全部用户可见。管理员始终可见。目录展示、详情、账号授权（发起、表单提交、OAuth 回调）和任务运行都会校验可见范围；不在范围内的用户已有连接会出现在“不可用的连接”中，只能断开。

清单 presentation.category 是连接器分类的唯一来源。安装或更新包时，Backend 按该值在分类管理中确保存在一条 connector 类型分类（名称默认等于该值）；管理员可在分类管理中修改名称、排序或停用，停用后连接器显示为未分类。连接器分类不能在分类管理中手动新建，仍被已安装连接器使用时不能删除。

安装包清单继续要求 permission_key 等于 feature.connector.<key>，该字段仅保留包格式约束，不创建功能权限，也不参与目录展示、账号授权或任务运行的角色权限检查。

管理员可以从连接器管理页永久移除连接器。移除请求会立即停用定义，为所有需要调用 provider 的活动凭据创建撤销任务，删除 Poco 中的用户连接、凭据和授权。定义和全部包版本会保留到撤销任务结束，再由维护 worker 自动删除并为每个包归档创建持久化清理任务；任务历史中的运行快照保留为审计记录。维护 worker 随后清理本地包缓存和 S3 归档，失败时按退避时间持续重试，成功后才删除清理任务。

4. 授权和运行组合

框架按当前包清单组合授权策略与运行适配器：

表格列出典型组合。授权策略与运行适配器独立组合：标准授权可搭配 program runtime，program 授权也可搭配符合凭据绑定约束的 remote MCP runtime，最终以清单校验为准。

标准 OAuth 使用授权码与 PKCE S256，支持公共和机密客户端、固定端点与 MCP 发现、刷新和撤销。URL 校验拒绝凭据和 fragment；固定授权、令牌、撤销端点必须与 issuer 同源，MCP 发现结果还要匹配预期 issuer。

远程 MCP 适配器负责 initialize、tools/list、tools/call、HTTP header 凭据绑定、输入输出 schema 校验和内容类型转换。一个远程 MCP 连接器可以声明单个服务，也可以让多个服务共享同一授权、transport 和凭据绑定；多服务工具发现并行执行，工具来源随运行快照保存，调用时路由回对应服务。包内程序通过严格的单次 stdin/stdout JSON 协议实现相同接口，因而上层授权服务和运行服务无需知道具体第三方系统。

5. 工具快照

任务创建时，Backend 使用独立数据库会话读取连接器、刷新凭据并发现工具，避免在访问第三方服务期间占用主事务。发现完成后，主事务对相关定义加共享锁，重新核对版本和授权指纹，再写入 Run。快照包含：

• 定义 key、UUID、包版本、清单摘要、归档摘要、大小和 S3 key。
• 配置版本、授权指纹、授权代次和凭据版本。
• 已允许工具的稳定 SDK 名称、上游服务来源、schema、effect、确认策略、重试策略和工具集摘要。
• 包内 Skill 的路径和内容摘要。

内部调用接口收到工具请求后逐项比较快照和当前数据库状态，按快照指定的不可变包版本重新发现工具，再解密凭据并调用第三方服务。包与配置版本、授权身份/代次、状态和工具集合必须匹配。正常凭据刷新允许更新 credential_version；刷新后重新核验稳定配置，持续变化才失败，不能把任意凭据版本变化当作必然拒绝。

SDK 工具名由连接器 key、工具 key 和连接 UUID 生成，避免不同连接器或多个账号的同名工具互相覆盖。执行结果只接受统一的文本、图片、音频、资源链接和内嵌资源类型。

写入、删除和未知风险工具必须使用 retry: never。该策略只禁止 Poco 层重复发起工具调用，不约束供应商 SDK 或 CLI 的内部传输重试。每次非只读调用都有稳定的 invocation_id；连接器可将其传递为上游幂等键。非只读调用发生超时或连接中断时，系统返回“结果未知”，要求先查询供应商状态，禁止直接重试。声明为 user_required 的工具在即时前台对话 Run 中由 Executor 创建专用确认请求，前端展示连接器、账号、风险和结构化参数，用户可以拒绝或单次允许，每次调用都需要单独确认。Backend 在调用 Provider 前使用行锁校验并消费单次批准。定时任务、OpenAPI 后台运行等非交互 Run 不创建确认请求，也不进入等待状态；系统校验 Run 创建时锁定的连接器快照与当前配置、授权和工具集仍然一致后，直接执行相关操作。

6. 更新并发

更新连接器定义时使用数据库排他行锁。任务创建在写入 Run 前短暂持有同一定义的共享锁，因此更新不能插入正在建立的任务快照。Run 写入后，更新会检查所有引用该定义的未完成 Run；只要存在引用就拒绝更新，所以工具调用期间无需持续持有定义锁。

更新前还会检查：

• 引用该连接器的未完成 Run。
• 正在处理的授权会话。
• 活跃的凭据刷新租约。

未提交的 pending 授权会话会被取消并清除私有上下文。存在任一占用状态时，更新返回明确错误，管理员稍后重试。

移除使用相同的定义排他锁和运行占用检查。定义进入待移除状态后不能再发布、更新配置或安装新版本；所有待处理凭据撤销结束前，系统保留撤销载荷和对应包版本，结束后再自动完成删除。

更新必须上传相同 key 的更高语义版本。系统保留定义 UUID、排序、发布状态、仍声明的管理员配置和用户连接。包移除的配置字段会删除，新必填字段必须在更新时填写。

授权指纹由 authorization_contract_version、授权策略、交互方式、授权字段语义约束、授权选项和 provider 返回的授权身份共同决定。对于使用固定 URL 或 servers 并通过 HTTP Header 携带凭据的远程 MCP，指纹还包括传输协议、解析后的服务器地址及凭据绑定方式；旧版 endpoint.configuration_field 保持原有指纹结构。字段语义约束包括字段名、类型、必填、默认值、数值与长度范围及选项值。指纹变化时，已有连接统一进入 reauthorization_required 并提升 grant revision；文案、图标、Skill 或不影响授权身份的密钥轮换不会使连接失效。

7. Skill 装配

Backend 只把 Skill 索引和摘要写入任务快照，不把文件内容复制到数据库。Executor Manager 按快照从 S3 下载归档，执行与 Backend 等价的路径、文件数、大小、摘要、清单身份和 Skill 目录摘要校验，再把 Skill 交给既有 stager。

这种方式允许 S3 成为包内容的唯一持久来源，同时保证历史任务无法读取其他版本的 Skill。归档丢失、被篡改或摘要不匹配时，任务在准备阶段失败并暴露真实错误。

8. 安全边界

ZIP 校验拒绝目录穿越、绝对路径、反斜杠路径、重复或冲突路径、符号链接、加密文件、超长路径、过多文件和超限解压体积。清单使用严格 Pydantic schema，未知字段直接失败；所有跨文件引用都在安装前验证。

标准远程 MCP 的网络请求统一使用 httpx 和明确超时。凭据只在 Backend 内解密和绑定，前端与 Executor 不接收用户密钥。

Python provider 属于受信任扩展。运行器限制请求、输出、时间、并发和环境变量，并在取消或超时时终止进程组；它不是操作系统沙箱。安装程序包前必须审查源码，因为它仍以 Backend 身份访问文件和网络。

9. 迁移行为

升级迁移删除空的旧内置 knowledge-base 定义和 feature.knowledgeBase 权限，因此全新环境启动后没有任何业务连接器。

如果旧定义已有管理员配置、密钥、用户连接、授权会话、撤销任务或包版本，迁移保留该定义。在对应 ZIP 包重新安装前，管理页会明确显示包缺失，运行不会退回已删除的内置 provider。

最新迁移清理全部 feature.connector.* 功能权限及角色中的对应关联，使连接器退出权限菜单。已有包、管理员配置和个人账号授权保持有效；安装和更新包不再创建权限资源。已删除的权限分配无法通过迁移降级恢复。

WeKnora 作为独立 ZIP 示例发布，框架源码、Docker 镜像、公共配置和侧边栏不再包含其专属逻辑。

10. 验证边界

仓库测试覆盖包结构和引用校验、不可变版本、S3 摘要与缓存、安装失败回滚、更新锁、授权契约变化、程序协议、程序取消、标准静态/OAuth/MCP 组件和运行快照。

真实远程 MCP、真实 OAuth 服务和真实 WeKnora 账号仍需部署方在自己的网络、TLS、回调和账号环境中验收。框架测试证明 Poco 的契约，不代表任何外部服务版本已经通过生产兼容认证。