docs/wiki/集成扩展/数据源导入开发.md
WeKnora 的数据源导入模块支持从外部平台（飞书、企业微信、Notion、Confluence 等）自动导入和同步内容到知识库。用户可配置数据源连接，选择需要同步的资源，并通过手动触发或定时调度自动完成内容的增量/全量同步。
数据源绑定到知识库，一个知识库可接入多个数据源。凭证使用 AES-256-GCM 加密存储。
数据源导入与 IM集成开发 都涉及飞书集成，可考虑共享飞书应用凭证
| 连接器 | 认证方式 | 增量同步 | 删除同步 |
|---|---|---|---|
| 飞书 (Feishu) | OAuth2 (Tenant Access Token) | ✅ | ✅ |
wiki:wiki:readonly、drive:drive:readonly、drive:export:readonly、docx:document:readonly注意：飞书国际版（Lark）同样支持，自动适配
https://open.larksuite.com的 API 地址
飞书新版云文档（docx）的解析路径由环境变量 FEISHU_DOCX_PARSE_MODE 控制（作用于 app 服务，对飞书知识库和飞书云盘两个连接器同时生效）：
| 模式 | 值 | 解析路径 | 图片与文档关联 | 速度 | docx 内附件 |
|---|---|---|---|---|---|
| export（默认） | 留空 / export | 异步导出 -> .docx 二进制 -> docreader 解析 | ✅ 图片 inline 进父文档，parent_chunk_id 关联 | 慢 | 丢失 |
| blocks | blocks | blocks API -> Markdown | ❌ 图片作为独立知识条目，与文档割裂 | 快 | 保留 |
优缺点对比：
parent_chunk_id 建立同知识条目父子关联，三个场景都能关联图片内容；代价是同步变慢（异步导出 + docx 解析）、docx 内附件丢失、图片 OCR/caption 依赖多模态配置。![图片]() 占位符，图片单独下载成独立知识条目，检索 / Wiki / 智能体无法把图片内容关联回文档；但同步快、保留 docx 内 file block 附件。配置方法：默认即为 export，无需设置；需要 blocks 模式时在 .env 或 docker-compose.yml 的 app 服务环境变量中设置 FEISHU_DOCX_PARSE_MODE=blocks，重启 app 服务生效。详见 飞书云盘数据源接入说明。
外部平台 API → Connector → ConnectorRegistry → DataSourceService → WeKnora Core (知识入库管道)
核心设计模式：
| 模式 | 用途 |
|---|---|
| Adapter Pattern | 统一不同平台的差异 |
| Registry Pattern | 按类型动态查找连接器 |
| Strategy Pattern | SyncMode（增量/全量）、ConflictStrategy（覆盖/跳过） |
| Cursor-based Pagination | 增量同步基于 SyncCursor 跟踪变更 |
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/datasource/types | 获取可用连接器类型 |
| POST | /api/v1/datasource/validate-credentials | 验证凭证 |
| POST | /api/v1/datasource | 创建数据源 |
| GET | /api/v1/datasource?kb_id=xxx | 列出数据源 |
| POST | /api/v1/datasource/:id/sync | 手动触发同步 |
| POST | /api/v1/datasource/:id/pause | 暂停 |
| POST | /api/v1/datasource/:id/resume | 恢复 |
Connector 接口（Validate、ListResources、FetchAll、FetchIncremental）ConnectorRegistry