feishu-cli-read

飞书文档阅读技能

从飞书云文档、电子表格或知识库读取内容，转换为 Markdown 格式后进行分析和展示。普通电子表格使用 sheet export --format markdown，知识库 sheet 使用 wiki export。

前置条件

• feishu-cli：如尚未安装，请前往 riba2534/feishu-cli 获取安装方式
• 已完成认证（feishu-cli auth login）
• App 权限：需要 docx:document 或 docx:document:readonly（普通文档）、wiki:wiki:readonly（知识库）
• Token 解析（所有读命令通用）：doc export / wiki export / sheet export 等读类命令统一走"User 优先 + Tenant 兜底"——优先用 token.json 里的 User Token，未找到回落 App Token。所以读他人文档时只要 auth login 一次，后续不用再传 --user-access-token。详见下方"User Token 优先级链"小节。

核心概念

Markdown 作为中间态：本地文档与飞书云文档之间通过 Markdown 格式进行转换，中间文件存储在 /tmp 目录中。

使用方法

feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assets
feishu-cli wiki export <node_token_or_url> --output

获取文档元信息（doc get）

读取文档基本信息（document_id、revision_id、title），用于在 export 之前确认目标、或拿 revision_id 作为后续 API 调用参数。同样走"User 优先 + Tenant 兜底"。

列出文档所有块（doc blocks）

doc export 拿不到结构化块树时（例如要分析每个块的类型、定位特定块、查 raw API 响应），用 doc blocks。默认列出第一页（500 块），加 --all 自动分页拉完。

知识库读类（wiki get / nodes / spaces）

知识库的"目录结构遍历三件套"，配合 wiki export 完成"找到节点 → 读内容"的链路。三个命令都走"User 优先 + Tenant 兜底"。

wiki get — 查节点元信息

返回字段：space_id / node_token / obj_token（用于文档 API） / obj_type（docx/sheet/bitable/...） / title / has_child。

wiki nodes — 列出空间或父节点的子节点

wiki spaces — 列出当前身份可见的所有知识空间

电子表格读类（sheet read / list-sheets）

sheet export --format markdown 适合"整表导出阅读"；要按精确范围读单元格、或先列出工作表元信息，用下面两个命令。

sheet list-sheets — 列出电子表格的所有工作表

返回 sheet_id / title / 索引 / 隐藏状态，配合 sheet read 的 SheetID!A1:C10 范围语法用。

sheet read — 读指定范围单元格

执行流程

1. 解析参数

   • 判断 URL 类型：
     • /docx/ → 普通文档，使用 doc export
     • /wiki/ → 知识库文档，使用 wiki export
   • 如果是 Token，根据格式判断类型

2. 导出为 Markdown（含图片下载）

   普通文档:

   feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assets

   文档内嵌电子表格块默认会自动展开为 Markdown 表格，便于直接阅读和分析；如果要保留 <sheet .../> 标签用于 roundtrip，追加 --expand-sheets=false。

   doc export 会自动解析 User Access Token（如已登录），解析优先级（与 cmd/utils.go::resolveOptionalUserTokenWithFallback + internal/auth/resolve.go::ResolveUserAccessToken 实现完全一致）：

   1. --user-access-token 命令行参数（若该 token 等于 token.json 中已过期的 access_token，且 refresh_token 仍有效，自动刷新）
   2. FEISHU_USER_ACCESS_TOKEN 环境变量（同样支持本机身份延伸的自动刷新）
   3. ~/.feishu-cli/token.json（通过 auth login 保存；access_token 过期则用 refresh_token 自动续期并写回）
   4. config.yaml 中的 user_access_token（静态配置，不会自动刷新）
   5. App Token 兜底（资源 API 也会接受，以租户身份访问；遇到 1770032/forbidden 等错误时说明该文档对 App 不可见，必须走前 4 步拿到 User 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

   普通电子表格:

   feishu-cli sheet export <spreadsheet_token> --format markdown --output /tmp/feishu_sheet.md

   不指定 --sheet-id 时会读取所有可见工作表；只看单个工作表时加 --sheet-id <sheet_id>。

   重要：务必使用 --download-images 参数下载文档中的图片到本地，否则只能看到 feishu://media/<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 权限）
   • --expand-sheets：展开文档内嵌电子表格为 Markdown 表格（默认开启；设为 false 时保留 <sheet .../> 标签）

3. 读取文本内容

   • 使用 Read 工具读取导出的 Markdown 文件
   • 分析文档结构和文本内容

4. 读取并理解图片内容

   • 检查 --assets-dir 指定的目录是否有下载的图片
   • 使用 Read 工具逐个读取图片文件（Claude 支持多模态，可直接理解图片内容）
   • 将图片内容整合到文档分析中

   # 列出下载的图片
   ls /tmp/feishu_assets/
    
   # 使用 Read 工具查看图片
   # Read /tmp/feishu_assets/image_1.png
   # Read /tmp/feishu_assets/image_2.png

5. 报告结果

   • 提供文档摘要（包含图片内容描述）
   • 保留 Markdown 文件和图片供用户进一步操作

输出格式

向用户报告：

• 文档标题
• 文档结构概要（标题层级）
• 内容摘要（关键信息）
• 图片内容描述（如有图片）
• Markdown 文件路径（供后续使用）
• 图片文件路径（如有下载）

支持的 URL 格式

示例

# 读取普通文档
feishu-cli doc export <document_id> --output /tmp/feishu_doc.md --download-images --assets-dir /tmp/feishu_assets
feishu-cli doc export https://xxx.feishu.cn/docx/<document_id> --output /tmp/feishu_doc.md
 
# 读取知识库文档
feishu-cli wiki export <node_token> --output /tmp/feishu_wiki.md --download-images --assets-dir /tmp/feishu_assets
feishu-cli wiki export https://xxx.feishu.cn/wiki/<node_token> --output /tmp/feishu_wiki.md
 
# 读取普通电子表格为 Markdown
feishu-cli sheet export <spreadsheet_token> --format markdown -o /tmp/feishu_sheet.md

导出格式说明

导出的 Markdown 支持以下飞书特有块类型的转换：

使用 --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. 常见错误

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>

注意事项

1. 识别目录节点：目录节点的内容是子节点列表，不是实际文档内容
2. 公式内容：导出的 LaTeX 公式保持原文，可直接被 Markdown 渲染器显示
3. 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 环境变量是否正确