xinmi/docs/wiki/集成扩展/飞书云盘数据源接入说明.md

# 飞书云盘数据源使用说明

飞书云盘数据源(`feishu_drive` / `lark_drive`)可以把飞书/Lark 云盘某个文件夹下的文档和文件自动同步到 WeKnora 知识库,支持增量同步、定时同步和子文件夹递归。

---

## 1. 前置条件:创建飞书应用

1. 登录[飞书开放平台](https://open.feishu.cn/app)(Lark 用户使用 [Lark 开放平台](https://open.larksuite.com/app)),创建**企业自建应用**。
2. 记录应用的 **App ID**(`cli_` 开头)和 **App Secret**,配置数据源时需要填写。
3. 按下节表格开通权限,并**发布应用版本**(权限修改后必须重新发布才生效)。

> 注意:飞书(open.feishu.cn)和 Lark(open.larksuite.com)是两个独立体系,应用不通用。同步飞书云盘用飞书应用,同步 Lark Drive 用 Lark 应用,凭据不能混用。

---

## 2. 所需权限(详细)

在应用后台「权限管理」中开通以下 **3 个权限**:

| 权限标识 | 名称 | 用途 | 缺少时的表现 |
|---|---|---|---|
| `drive:drive:readonly` | 查看云空间中的文件 | 列举文件夹内容(list API)、下载云盘普通文件 | 加载文件夹/同步时报 403,提示「需先将文件夹分享给应用所在的群」 |
| `drive:export:readonly` | 导出云文档 | 把 docx/doc/sheet/bitable 导出为 docx/xlsx 再解析 | 云文档类文件同步失败 |
| `docx:document:readonly` | 读取新版文档内容 | 通过 blocks API 解析 docx 文档正文与附件(导出失败时的主路径) | docx 文档解析失败或回退导出也失败 |

说明:

- 与「飞书知识库」连接器相比,云盘**不需要** `wiki:wiki:readonly`,其余权限相同。
- list API 本身还接受 `drive:drive`(读写)或 `space:document:retrieve` 作为替代,但推荐只开只读的 `drive:drive:readonly`,最小授权。
- 权限开通后必须**创建并发布新版本**,否则接口仍报无权限。

---

## 3. 关键一步:把文件夹分享给应用

飞书的权限模型要求:即使应用开通了上述 API 权限,也只能访问**被显式分享给它的文件**。

1. 创建一个飞书（Lark）群或复用某个飞书（Lark）群
2. 将需要导入的**飞书云盘管理者**拉进群
> PS: 不拉进群也会导致没有访问权限
3. 在飞书云盘中打开目标文件夹;
4. 点击「分享」/「··· → 添加协作者」,把文件夹分享给**应用所在的群**(把应用拉进一个群,再将文件夹分享给该群),权限给「可阅读」即可;
5. 子文件夹和其中的文件会随父文件夹一起获得授权,无需逐个分享;
6. 如果之后新增的文件同步报 403,检查该文件是否在这棵已分享的目录树下。

这是一次性操作,但不做的话,加载文件夹会直接报「应用无权访问该文件夹」。

---

## 4. 配置数据源(四步)

入口:知识库 → 设置 → 数据源 → 新建数据源,选择「飞书云盘」。

### 第 1 步:选择类型

选择「飞书云盘」(国际版选「Lark Drive」)。

### 第 2 步:配置凭证

填写 App ID 和 App Secret,点击下一步时系统会自动测试连接(验证 tenant_access_token 能否获取)。此步只验证应用身份,不验证文件夹权限。

### 第 3 步:选择范围

1. 在「云盘文件夹 Token」输入框填入目标文件夹的 `folder_token`,**或直接粘贴文件夹的完整链接**(飞书 `https://xxx.feishu.cn/drive/folder/<token>` 或 Lark `https://xxx.larksuite.com/drive/folder/<token>`,系统按路径自动提取 token,两种链接都支持);
2. 点击「加载」,列出该文件夹下的完整目录树;
3. 勾选要同步的文件/文件夹,支持逐级展开、全选/折叠分支。

注意:

- **不支持云空间根目录**(根目录不分页且不返回快捷方式),必须选择具体文件夹;
- 加载失败时按提示处理:403 → 回到第 3 节分享文件夹;token 无效 → 重新从文件夹 URL 复制。

### 第 4 步:同步策略

| 配置项 | 说明 | 默认值 |
|---|---|---|
| 同步计划 | cron 表达式,默认每 6 小时一次;留空则只手动触发 | `0 0 */6 * * *` |
| 同步模式 | 增量(按修改时间游标)/ 全量 | 增量 |
| 冲突策略 | 内容变更时覆盖 / 跳过 | 覆盖 |
| 同步删除 | 源端删除的文档**只计数,不自动删除知识库内容**,需在知识库手动删除 | 开启 |

保存后数据源开始按策略运行,也可在数据源卡片上手动「触发同步」。

---

## 5. 支持的文件类型

| 云盘类型 | 处理方式 |
|---|---|
| `docx` / `doc`(新旧文档) | blocks API 解析正文与附件,失败时回退导出为 docx 解析 |
| `sheet` / `bitable`(表格/多维表格) | 导出为 xlsx 解析 |
| `file`(普通上传文件,如 PDF/PPT/图片) | 直接下载后按文件类型解析 |
| `shortcut`(快捷方式) | 自动解析为目标文件同步(快捷方式不能指向文件夹) |
| `folder`(文件夹) | 递归遍历 |
| `mindnote` / `slides` / `board` | 不支持,跳过 |

补充行为:

- docx 中的**附件**会作为独立知识条目同步(与父文档关联,父文档更新时自动清理已移除的附件);
- 文档内嵌图片会尝试 OCR/多模态解析,未配置对象存储或 VLM 时自动跳过,不影响正文同步。

---

## 6. docx 解析模式与环境变量

飞书新版云文档(docx)有两种解析路径,由环境变量 `FEISHU_DOCX_PARSE_MODE` 控制。该变量作用于 WeKnora **app 服务**(不是数据源配置),对飞书云盘和飞书知识库两个连接器同时生效。

### 模式对比

| | export(默认) | blocks |
|---|---|---|
| 环境变量值 | 留空 / `export` | `blocks` |
| 解析路径 | 异步导出 API -> .docx 二进制 -> docreader 解析 | blocks API -> Markdown |
| 图片与文档关联 | ✅ 图片 inline 进父文档,`parent_chunk_id` 关联 | ❌ 图片作为独立知识条目,与文档割裂 |
| 检索 / Wiki / 智能体能否关联图片 | 是 | 否 |
| 同步速度 | 慢(异步导出 + docx 解析) | 快 |
| docx 内附件(file block) | 丢失(.docx 导出不含) | 保留,作为独立条目 |
| 所需权限 | `drive:drive:readonly` + `drive:export:readonly` | `drive:drive:readonly` + `drive:export:readonly` + `docx:document:readonly` |

### 为什么图片关联有差异

- **export 模式**:导出 .docx 后由 docreader 解析,图片 inline 进父文档(与普通 docx 上传一致),通过 `parent_chunk_id` 建立同知识条目的父子关联,三个场景都能在一次检索中把图片内容与文档一起返回。
- **blocks 模式**:走 blocks API,图片 block 渲染成空 `![图片]()` 占位符,图片单独下载成独立知识条目,与父文档只有元数据级弱关联。WeKnora 的检索、Wiki 构建、智能体问答链路都不会把图片内容关联回文档,图片和正文是割裂的。

### 配置方法

在 WeKnora 服务的 `.env` 或 `docker-compose.yml` 的 app 服务环境变量中设置:

```env
FEISHU_DOCX_PARSE_MODE=blocks
```

不设置或设为 `export` 即用默认模式。修改后需重启 app 服务生效。

### export 模式的代价

- **同步变慢**:每个 docx 都要走异步导出(创建任务 + 轮询 + 下载)+ docreader 解析,比 blocks API 慢。
- **附件丢失**:docx 内 file block 附件不随 .docx 导出下载,如需附件用 blocks 模式或单独同步。
- **图片内容依赖多模态**:图片 inline 后 OCR/caption 由多模态服务异步生成,未配置对象存储或 VLM 时图片只存储不生成内容(前端展示正常,但检索层面仍弱)。

### 选择建议

- 需要图片内容在检索 / Wiki / 智能体中与文档关联:用默认 **export**。
- 只需文档正文、要保留附件、追求同步速度:用 **blocks**。

---

## 7. 同步行为说明

- **增量同步**:以文件修改时间为游标,只拉取上次同步后变更的内容;中断后从断点续传。
- **部分失败不中断**:某个子文件夹无权限或某个文件下载失败时,该条目记为失败,其余内容继续同步,失败明细可在「同步日志」中查看。
- **更新语义**:内容变更的文件会先删除旧知识条目再重建,解析期间该文档短暂不可用,属正常现象。
- **安全约束**:为避免误删,源端删除的文件不会自动从知识库移除(见第 4 步「同步删除」)。

---

## 8. 常见问题

| 现象 | 原因与处理 |
|---|---|
| 「请输入具体文件夹的 folder_token,不支持云空间根目录」 | 输入为空或粘贴的是根目录链接,换具体文件夹链接 |
| 「应用无权访问该文件夹。请…分享给应用所在的群」 | 未完成第 3 节的分享,或分享的对象不是应用所在的群 |
| 「应用凭证无效或缺少云盘权限」 | App ID/Secret 错误,或第 2 节权限未开通/未发布版本 |
| 「folder_token 不存在或已删除」 | token 复制有误,从文件夹「分享 → 复制链接」重新获取 |
| 同步日志中部分条目失败 | 点开日志看失败阶段:`list_children` 多为子文件夹未授权,`fetch` 多为单文件权限或类型不支持 |
| 知识列表中来源显示 | 云盘同步的文档来源标记为「飞书云盘」,与知识库同步的「飞书」区分 |