# 飞书 file 节点知识库召回问题记录

## 问题现象

后台已经开放多个飞书知识库节点，但用户端和 Agent 调试时实际只召回第一个知识库节点。

## 排查结论

开放知识库范围已经正确传入检索链路，`knowledge_ids` 包含全部启用知识库。但当前飞书直读实现只支持读取 `docx` 节点。

当前线上配置中：

- 第一个知识库节点 `测试知识库` 的飞书 `obj_type=docx`，可以读取。
- 其余多个知识库节点的飞书 `obj_type=file`，标题为 `.md` 文件。

因此后端只成功读取了第一个 `docx` 节点，其他 `.md` 文件节点没有进入候选片段，自然无法被召回。

## 调整决定

飞书知识库直读需要同时支持：

1. `docx`：继续通过 Docx API 读取文档块内容。
2. `file`：通过 Drive 文件下载接口下载文件内容；对 `.md`、`.txt` 等文本文件按 UTF-8 文本解析。
3. 文件夹/父节点：遍历子节点时也需要同时处理 `docx` 和 `file` 子节点。

## 权限要求

读取 `file` 类型节点需要飞书应用开通 Drive 文件下载相关权限，例如：

- `drive:file:download`
- `drive:file:readonly`
- `drive:drive:readonly`

如果应用未开通这些权限，飞书会拒绝下载普通文件节点。此时系统应返回明确错误，提示管理员补充飞书应用权限，而不是静默忽略这些知识库。

## 验收口径

- 启用多个 `.md` 文件知识库节点后，检索候选应能加载这些文件内容。
- AI 请求日志中的 `retrieve_count` 不应长期只有第一个 `docx` 节点。
- 飞书应用权限不足时，应能看到明确的 Drive 文件下载权限错误。
