飞书文档阅读技能
从飞书云文档或知识库读取内容，转换为 Markdown 格式后进行分析和展示。支持 docx（新版文档）和 sheet（电子表格）两种知识库文档类型。
前置条件
- feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式
- 已完成认证（
feishu-cli auth login） - App 权限：需要
docx:document或docx:document:readonly（普通文档）、wiki:wiki:readonly（知识库） - User Token 权限：若 App 无权访问他人文档，先去飞书开放平台的应用权限管理页面开通
docx:document:readonly，然后feishu-cli auth login授权，doc export会自动读取保存的 User Token
核心概念
Markdown 作为中间态：本地文档与飞书云文档之间通过 Markdown 格式进行转换，中间文件存储在 /tmp 目录中。
使用方法
/feishu-read <document_id>
/feishu-read <node_token>
/feishu-read <url>执行流程
- 解析参数
- 判断 URL 类型： - /docx/ → 普通文档，使用 doc export - /wiki/ → 知识库文档，使用 wiki export - 如果是 Token，根据格式判断类型
- 导出为 Markdown（含图片下载） 普通文档:
feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assetsdoc export会自动解析 User Access Token（如已登录），解析优先级： 找到 User Token 时使用用户身份访问，未找到时回退为 App Access Token（租户身份）。 若遇到code=1770032 forBidden（App 无权限且未登录）或code=99991679 Unauthorized（User Token 缺少 scope），需先在飞书开放平台为应用开通docx:document:readonly，然后完成 User Token 授权：# 第一步：在飞书开放平台 → 你的应用 → 权限管理 → 搜索 docx:document:readonly → 开通 # （或复制 README 的完整权限 JSON 一次性导入） feishu-cli auth login知识库文档:feishu-cli wiki export <node_token> --output /tmp/feishu_wiki.md --download-images --assets-dir /tmp/feishu_assets重要：务必使用--download-images参数下载文档中的图片到本地，否则只能看到feishu://media/<token>引用，无法理解图片内容。 可选参数：
1. --user-access-token 命令行参数 2. FEISHU_USER_ACCESS_TOKEN 环境变量 3. ~/.feishu-cli/token.json（通过 auth login 保存） 4. config.yaml 中的 user_access_token - --user-access-token：手动指定 User Access Token（不填则自动从 ~/.feishu-cli/token.json 读取） - --front-matter：在 Markdown 顶部添加 YAML front matter（含标题和文档 ID） - --highlight：保留文本颜色和背景色（输出为 HTML <span> 标签） - --expand-mentions：展开 @用户为友好格式（默认开启，需要 contact:user.base:readonly 权限）
- 读取文本内容
- 使用 Read 工具读取导出的 Markdown 文件 - 分析文档结构和文本内容
- 读取并理解图片内容
# 列出下载的图片 ls /tmp/feishu_assets/ # 使用 Read 工具查看图片 # Read /tmp/feishu_assets/image_1.png # Read /tmp/feishu_assets/image_2.png
- 检查 --assets-dir 指定的目录是否有下载的图片 - 使用 Read 工具逐个读取图片文件（Claude 支持多模态，可直接理解图片内容） - 将图片内容整合到文档分析中
- 报告结果
- 提供文档摘要（包含图片内容描述） - 保留 Markdown 文件和图片供用户进一步操作
输出格式
向用户报告：
- 文档标题
- 文档结构概要（标题层级）
- 内容摘要（关键信息）
- 图片内容描述（如有图片）
- Markdown 文件路径（供后续使用）
- 图片文件路径（如有下载）
支持的 URL 格式
| URL 格式 | 类型 | 命令 |
|---|---|---|
https://xxx.feishu.cn/docx/<id> | 普通文档 | doc export |
https://xxx.feishu.cn/wiki/<token> | 知识库（docx/sheet） | wiki export |
https://xxx.larkoffice.com/docx/<id> | 普通文档 | doc export |
https://xxx.larkoffice.com/wiki/<token> | 知识库（docx/sheet） | wiki export |
示例
# 读取普通文档
/feishu-read <document_id>
/feishu-read https://xxx.feishu.cn/docx/<document_id>
# 读取知识库文档
/feishu-read <node_token>
/feishu-read https://xxx.feishu.cn/wiki/<node_token>导出格式说明
导出的 Markdown 支持以下飞书特有块类型的转换：
| 飞书块类型 | Markdown 表现 |
|---|---|
| Callout 高亮块 | > [!NOTE]、> [!WARNING] 等 6 种 GitHub-style alert |
| 块级/行内公式 | $formula$（LaTeX 格式） |
| 画板 (Board) | [画板/Whiteboard](feishu://board/...) 链接 |
| ISV 块 (Mermaid) | 画板链接 |
| QuoteContainer | > 引用语法（支持嵌套） |
| AddOns/SyncedBlock | 透明展开子块内容 |
| Iframe | <iframe> HTML 标签 |
使用 --highlight 参数时，带颜色的文本输出为 <span style="color:..."> 标签。
高级：Wiki 目录节点处理
知识库文档可能是目录节点（包含子节点），需要特殊处理。
1. 识别目录节点
当导出知识库文档时，如果 Markdown 内容显示为：
[Wiki 目录 - 使用 'wiki nodes <space_id> --parent <node_token>' 获取子节点列表]说明这是一个Wiki 目录节点（block_type=42），子文档列表存储在知识库元数据中。
2. 获取子节点列表
# 1. 先获取节点信息，记录 space_id
feishu-cli wiki get <node_token>
# 2. 列出该节点下的子节点
feishu-cli wiki nodes <space_id> --parent <node_token>3. 完整处理流程
# 步骤 1：尝试导出文档
feishu-cli wiki export <node_token> -o /tmp/doc.md
# 步骤 2：检查内容
# 如果显示 "[Wiki 目录...]"，说明是目录节点
# 步骤 3：获取节点信息
feishu-cli wiki get <node_token>
# 记录 space_id 和 has_child 字段
# 步骤 4：获取子节点
feishu-cli wiki nodes <space_id> --parent <node_token>
# 步骤 5：逐个导出子节点
feishu-cli wiki export <child_node_token_1> -o /tmp/child1.md
feishu-cli wiki export <child_node_token_2> -o /tmp/child2.md错误处理与边界情况
1. 常见错误
| 错误 | 原因 | 解决 |
|---|---|---|
code=1770032, msg=forBidden | App Token 无权限访问该文档 | 在飞书开放平台应用权限管理页面开通 docx:document:readonly，再 auth login 授权 User Token |
code=99991679, msg=Unauthorized | User Token 缺少 docx:document:readonly scope | 在飞书开放平台应用权限管理页面开通 docx:document:readonly，再重新 auth login |
code=131002, param err | 参数错误 | 检查 token 格式 |
code=131001, node not found | 节点不存在 | 检查 token 是否正确 |
code=131003, no permission | 无权限访问 | 确认应用有 wiki:wiki:readonly 权限 |
code=131004, space not found | 知识空间不存在 | 检查 space_id 是否正确 |
空内容或 Unknown block type | 特殊块类型 | 见「高级：Wiki 目录节点处理」章节 |
2. 边界情况处理
情况 1：文档内容为空
- 检查文档是否真的为空
- 检查是否有权限查看内容
- 检查是否是目录节点（见上文）
情况 2：图片下载失败
- 检查
--assets-dir目录是否可写 - 检查网络连接
- 图片可能已被删除或过期
情况 3：部分块类型无法识别
- 飞书 API 可能返回未知的块类型
- 这些块会显示为
<!-- Unknown block type: XX --> - 这是正常现象，不影响其他内容的读取
情况 4：大型文档
- 超过 1000 个块的文档可能需要分页获取
- 使用
feishu-cli doc blocks <doc_id> --all自动分页
3. 重试机制
如果遇到网络错误或 API 限流：
# 添加 --debug 查看详细错误信息
feishu-cli wiki export <token> --debug
# 等待几秒后重试
sleep 5 && feishu-cli wiki export <token>注意事项
- 识别目录节点：目录节点的内容是子节点列表，不是实际文档内容
- 公式内容：导出的 LaTeX 公式保持原文，可直接被 Markdown 渲染器显示
- Callout 类型：支持 NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS 六种高亮块类型
常见问题
Q: 提示权限不足 / no permission / forBidden
- 确认应用已获得
docx:document:readonly（普通文档）或wiki:wiki:readonly（知识库）权限 - 如果是他人文档且 App 没有被添加为协作者，需要使用 User Token：
1. 在飞书开放平台 → 你的应用 → 权限管理 → 开通 docx:document:readonly 2. 执行 feishu-cli auth login 3. 授权后 doc export 会自动读取，无需额外参数
Q: 文档不存在 / node not found
- 检查文档 ID 或 node_token 是否正确（注意区分
document_id和node_token） - 从 URL 中提取 ID 时确认使用了正确的路径段（
/docx/后为 document_id，/wiki/后为 node_token）
Q: Token 过期 / 认证失败
- 运行
feishu-cli auth status检查当前认证状态 - 如已过期，运行
feishu-cli auth login重新认证 - 如使用 App Access Token，检查
FEISHU_APP_ID和FEISHU_APP_SECRET环境变量是否正确