feishu-doc-reader

用途

feishu-doc-reader 用于通过飞书（Lark）官方开放 API 读取和提取飞书文档内容。它面向需要以程序化方式获取飞书文档、电子表格或幻灯片数据的场景，将文档内容转换为结构化 JSON 输出，便于后续处理或集成。

主要能力

支持多种文档类型：
- Docx 文档（新版飞书文档）：完整内容提取，包含块、元数据和结构。
- Doc 文档（旧版）：基础元数据和有限内容。
- Sheets 电子表格：完整表格数据提取，支持工作表导航。
- Slides 幻灯片：基础元数据（内容提取需要额外权限）。
增强的内容提取：
- 结构化输出：干净的 JSON，包含文档元数据、内容块和层级。
- 完整块访问：可访问所有文档块，包括文本、表格、图片、标题、列表等。
- 块层级：正确的父子块关系。
- 文本提取：从复杂块结构中自动提取文本。
- 表格支持：按行/列结构正确解析表格。
- 图片处理：提取图片 URL 和元数据。
- 链接解析：提取内部和外部链接。
支持的块类型：text（纯文本与富文本）、heading1/2/3（标题层级）、bullet/ordered（支持嵌套的列表项）、table（含单元格与格式的完整表格结构）、image（含 token 与元数据的图片块）、quote（引用）、code（含语言检测的代码块）、equation（数学公式）、divider（分隔线）、page（多页文档中的分页）。
错误处理与诊断：详细的错误信息、请求前权限校验、文档 token 校验、瞬时网络错误自动重试、优雅处理 API 限流。
安全特性：支持环境变量与安全文件两种凭据存储方式、凭据不出现在日志或输出中、仅使用所需 API 权限、访问令牌缓存以减少 API 调用。

使用方式

配置

在 ./reference/feishu_config.json 创建配置文件，填入飞书应用凭据：

{
  "app_id": "your_feishu_app_id_here",
  "app_secret": "your_feishu_app_secret_here"
}

确保脚本可执行：

chmod +x scripts/read_doc.sh
chmod +x scripts/get_blocks.sh

安全提示：配置文件应妥善保管，不要提交到版本控制；建议设置合适的文件权限（chmod 600 ./reference/feishu_config.json）。

基本文档读取

读取飞书文档需要文档 token（位于 URL 中：https://example.feishu.cn/docx/DOC_TOKEN）。

使用 shell 脚本（推荐）：

# 确保先设置好环境变量
./scripts/read_doc.sh "your_doc_token_here"

# 或显式指定文档类型
./scripts/read_doc.sh "docx_token" "doc"
./scripts/read_doc.sh "sheet_token" "sheet"

获取详细文档块

获取包含所有块的完整文档结构：

# 获取完整文档块结构
./scripts/get_blocks.sh "docx_AbCdEfGhIjKlMnOpQrStUv"

# 按 ID 获取指定块
./scripts/get_blocks.sh "docx_token" "block_id"

# 获取包含子块的块
./scripts/get_blocks.sh "docx_token" "" "true"

直接使用 Python 获取块：

python scripts/get_feishu_doc_blocks.py --doc-token "your_doc_token_here"
python scripts/get_feishu_doc_blocks.py --doc-token "docx_token" --block-id "block_id"
python scripts/get_feishu_doc_blocks.py --doc-token "docx_token" --include-children

命令行选项

主文档读取器：

# Python 脚本选项
python scripts/read_feishu_doc.py --help

# Shell 脚本用法
./scripts/read_doc.sh <doc_token> [doc|sheet|slide]

块读取器：

# 获取完整文档块
./scripts/get_blocks.sh <doc_token>

# 获取指定块
./scripts/get_blocks.sh <doc_token> <block_id>

# 包含子块
./scripts/get_blocks.sh <doc_token> "" true

# Python 选项
python scripts/get_feishu_doc_blocks.py --help

所需 API 权限

飞书应用需要以下权限：

docx:document:readonly - 读取文档内容
doc:document:readonly - 读取旧版文档内容
sheets:spreadsheet:readonly - 读取电子表格内容

示例

提取完整结构的文档：

# 读取文档
./scripts/read_doc.sh "docx_AbCdEfGhIjKlMnOpQrStUv"

获取完整文档块：

# 获取所有块及完整结构
./scripts/get_blocks.sh "docx_AbCdEfGhIjKlMnOpQrStUv"

# 获取指定块详情
./scripts/get_blocks.sh "docx_AbCdEfGhIjKlMnOpQrStUv" "blk_xxxxxxxxxxxxxx"

处理电子表格数据：

./scripts/read_doc.sh "sheet_XyZ123AbCdEfGhIj" "sheet"

仅提取文本内容（Python 脚本）：

python scripts/read_feishu_doc.py --doc-token "docx_token" --extract-text-only

适用场景

需要以程序化方式批量读取飞书文档内容并转为结构化数据。
需要获取文档完整块层级（标题、列表、表格、图片、代码块等）用于解析或转换。
需要读取飞书电子表格数据。
需要按块 ID 精确查询文档中的特定块。

限制与注意事项

幻灯片仅支持基础元数据，内容提取需要额外权限。
旧版 Doc 文档仅支持基础元数据和有限内容。
访问令牌有效期为 2 小时，需要按需刷新。
常见错误：403 Forbidden（检查应用权限与文档共享设置）、404 Not Found（确认文档 token 正确且文档存在）、App ID/Secret 无效（在飞书开放平台核对凭据）、权限不足（确保应用具备所需 API 权限）、99991663（应用无权访问该文档）、99991664（文档不存在或已删除）、99991668（令牌过期，需刷新）。
网络方面需确保服务器可访问 open.feishu.cn，受限环境需检查防火墙规则。
块相关：空块响应可能表示文档为空或无可访问块；部分块类型需要额外权限；层级不完整时可使用 --include-children 获取完整块树。
安全建议：不要提交凭据到版本控制、仅申请所需最小权限、对密钥文件设置合适权限（chmod 600）、开发与生产使用不同应用、定期审查应用可访问的文档。
认证问题排查：在飞书开放平台核对 App ID 与 App Secret、确保应用已发布并具备所需权限、检查环境变量或配置文件设置正确、可用 test_auth.py 脚本验证凭据。
文档访问问题排查：确保文档已共享给应用或位于可访问空间、确认文档 token 格式（应以 docx_、doc_ 或 sheet_ 开头）、检查文档是否需要额外共享权限。