Document Feishu file node retrieval issue

ai_knowledge_base_v2/development_records/2026-07-08-feishu-file-node-retrieval.md

@@ -0,0 +1,40 @@
+# 飞书 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 文件下载权限错误。