连接器与知识库检索
可安装连接器的用户授权、运行链路，以及独立 WeKnora 知识库包的部署方式。
连接器把平台管理员安装的第三方能力与用户自己的授权账号连接起来。连接器 ZIP 声明展示、配置、授权、工具策略和可选 Skill；Backend 保存包版本、管理员配置和用户密文凭据，并作为 Executor 调用第三方系统的唯一网关。
连接器框架不预置任何业务连接器。全新部署的目录为空，管理员需要先安装并发布所需 ZIP 包。
WeKnora 是独立安装包的部署示例，其具体第三方字段和可用版本需以实际包清单与服务文档为准；仓库提供通用框架，不能据此推断全新部署已内置知识库连接器。
1. 管理员和用户流程
管理员在 管理后台 → 连接器管理 完成以下操作：
- 上传 ZIP 并检查包名称、key、版本、授权方式和配置字段。
- 填写包声明的管理员配置并安装。新定义处于草稿状态。
- 发布、停用、调整顺序或上传更高版本的同 key 包。
所有正常登录用户都可以在侧边栏 连接器 页面查看已发布定义，并建立自己的连接。连接动作会返回跳转授权、凭据表单或直接完成三种结果。用户可以停用、重新授权或断开自己的连接；断开后，本地凭据立即失效，支持上游撤销的包由后台撤销任务处理。
即时对话、API 访问和定时任务的能力选择器只显示状态正常且已启用的连接。connector_connection_ids 是当前配置选择的完整集合，最多 20 个；空数组表示不使用连接器。API 会话和定时任务会在每次运行前根据当前连接状态重新生成受限运行快照，包、配置、授权身份和工具集合必须匹配；正常凭据刷新可更新凭据版本。专家与专家团分享携带依赖声明，由导入者绑定自己的账户；对话副本、公开产物续聊不会复制授权。
2. 运行链路
Run 快照记录包版本、清单与归档摘要、配置版本、授权指纹、grant revision、credential version、工具集摘要及 Skill 摘要。Backend 调用前逐项复核，包、配置、授权身份、连接状态和工具集合不匹配时明确失败；正常凭据刷新允许更新 credential version，并使用刷新后的凭据。Frontend、Executor Manager 和 Executor 都不会取得第三方明文凭据。
包更新使用排他锁，并拒绝仍有未完成 Run、处理中授权或活跃凭据刷新租约的连接器。这样一次 Run 不会在执行中途切换包版本。
完整实现边界见可安装连接器框架设计，第三方开发规范见连接器安装包开发手册。
3. WeKnora 独立连接器
WeKnora 以独立的 knowledge-base ZIP 包安装，不再由 Poco 代码或 Docker 镜像内置。包使用 Python provider 实现 WeKnora 特有的 OAuth 交换、知识检索响应转换和打开服务地址。
管理员安装时填写：
| 字段 | 说明 |
|---|---|
base_url | WeKnora 的 HTTP(S) Origin，不包含路径、参数或账号信息 |
client_id | WeKnora 集成应用 Client ID，必须以 wkapp_ 开头 |
client_secret | WeKnora 集成应用 Client Secret，必须以 wks_ 开头 |
WeKnora 中登记的回调地址必须是：
${BACKEND_URL}/api/v1/connectors/oauth/callbackBACKEND_URL 必须是最终用户浏览器可访问的 HTTP(S) Origin。Backend 还必须能够访问 WeKnora Token 与检索 API。
发布后，所有正常登录用户都可以连接自己的账号。首次连接使用授权码与 PKCE S256，用户在 WeKnora 授权页选择一个或多个空间。重新授权会带 prompt=consent，新选择完整替换旧授权范围；取消授权页不会破坏原连接。
Token 响应需要包含 wkic_ 开头的 API Key、API-Key token type、连接 ID、knowledge.read scope 和 /integrations/launch/ 下的 launch path。Backend 加密保存凭据和连接元数据，浏览器不会收到 API Key。
包向 Agent 暴露只读 search 工具。调用 POST /api/v1/knowledge-search，使用 X-API-Key 和 {query} 检索该用户当前授权的全部空间。WeKnora 返回 401 或 403 时，连接会进入需要重新授权状态，后续调用明确失败。
“打开知识库”位于连接器详情动作中，由 provider 根据已校验的 WeKnora Origin 和 launch path 生成。侧边栏不再提供 WeKnora 专属入口。
4. 升级已有环境
迁移会删除没有真实配置、密钥或引用的旧内置知识库定义，让新环境保持空目录。如果旧定义已有管理员配置、用户连接、授权会话、撤销任务或已安装包记录，迁移会保留定义。最新迁移会清理连接器功能权限及角色关联，连接器向所有正常登录用户开放。
保留的旧定义没有可执行包时，管理页会显示包缺失。管理员应从该连接器行上传 knowledge-base 的独立 ZIP；更新会保留定义 UUID、排序、发布状态、仍声明的配置和用户连接。因为旧内置实现已经删除，系统不会建立兼容运行路径。
升级部署只需应用全部 Alembic head，不再运行目录同步脚本。随后在管理后台安装或更新所需连接器包。
5. 上线检查
- 排空使用该连接器的运行，应用最新 Backend Alembic 迁移。
- 确认 S3 对 Backend 和 Executor Manager 均可读写或读取。
- 上传 WeKnora ZIP，确认包 key 为
knowledge-base且版本符合预期。 - 填写 Origin、Client ID、Client Secret 并发布。
- 用真实账号验证首次授权、取消、重新授权、知识检索和打开服务。
- 验证凭据过期、上游授权撤销、连接停用与上游
401、403的处理。
仓库内的模拟测试只证明 Poco 侧协议与数据边界。真实 WeKnora 版本、网络、TLS、回调和账号授权仍需在部署环境验收。