用途
read-feishu-doc 用于读取和提取飞书（Lark）文档的内容，通过飞书官方 Open API 实现。它适用于需要以程序化方式获取飞书文档结构化数据的场景，例如将文档内容接入自有系统、做内容分析或数据提取。
主要能力
该技能支持读取以下文档类型：
- Docx 文档（新版飞书文档）：完整内容提取，包含块结构、元数据和层级信息。
- Doc 文档（旧版）：基础元数据和有限内容。
- Sheets 电子表格：完整表格数据提取，支持工作表导航。
- Slides 幻灯片：基础元数据（内容提取需要额外权限）。
内容提取与结构能力包括：
- 结构化输出：干净的 JSON，包含文档元数据、内容块和层级。
- 完整块访问：可访问全部文档块，包括文本、表格、图片、标题、列表等。
- 块层级：正确的父子关系。
- 文本提取：从复杂块结构中自动提取文本。
- 表格支持：按行列结构正确解析表格。
- 图片处理：提取图片 URL 和元数据。
- 链接解析：提取内部和外部链接。
支持的块类型包括：text（纯文本与富文本）、heading1/2/3（带层级的标题）、bullet/ordered（支持嵌套的列表项）、table（完整表格结构与单元格格式）、image（带 token 和元数据的图片块）、quote（块引用）、code（带语言检测的代码块）、equation（数学公式）、divider（水平分隔线）、page（多页文档中的分页）。
使用方式
配置
在 ./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 - 读取电子表格内容
错误处理与诊断
- 详细错误消息：对常见问题给出清晰说明。
- 权限校验：请求前检查所需权限。
- Token 校验：处理前验证文档 token。
- 重试逻辑：对临时网络错误自动重试。
- 限流处理：优雅处理 API 限流。
常见错误与解决方案：
- 403 Forbidden：检查应用权限和文档分享设置。
- 404 Not Found：确认文档 token 正确且文档存在。
- Token 过期：访问令牌有效期为 2 小时，需按需刷新。
- App ID/Secret 无效：在飞书开放平台核对凭证。
- 权限不足：确保应用具备所需 API 权限。
- 99991663：应用无权访问该文档。
- 99991664：文档不存在或已删除。
- 99991668：Token 过期，需要刷新。
安全特性
- 凭证安全存储：支持环境变量和安全文件存储。
- 不记录凭证日志：凭证不会出现在日志或输出中。
- 最小权限：仅使用必要的 API 权限。
- 访问令牌缓存：高效复用令牌以减少 API 调用。
安全说明：
- 永不提交凭证：将应用密钥排除在版本控制之外。
- 使用最小权限：仅请求用例所需的权限。
- 安全文件权限：为密钥文件设置正确的权限（chmod 600）。
- 环境隔离：开发和生产使用不同的应用。
- 审计访问：定期审查应用可访问的文档。
适用场景
适用于需要从飞书文档、电子表格或幻灯片中程序化提取内容的场景，例如将飞书文档内容同步到其他系统、进行内容分析、或构建基于飞书文档的自动化流程。
示例
提取带完整结构的文档：
读取文档
./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
故障排查
认证问题：
- 在飞书开放平台核对 App ID 和 App Secret。
- 确保应用已发布并具备所需权限。
- 检查环境变量或配置文件是否正确设置。
- 使用 test_auth.py 脚本验证凭证。
文档访问问题：
- 确保文档已分享给应用或位于可访问空间。
- 验证文档 token 格式（应以 docx_、doc_ 或 sheet_ 开头）。
- 检查文档是否需要额外分享权限。
网络问题：
- 确保服务器可访问 open.feishu.cn。
- 在受限环境中检查防火墙规则。
- 脚本内置针对临时网络故障的重试逻辑。
块相关问题：
- 空的块响应：文档可能为空或没有可访问的块。
- 缺少块类型：某些块类型需要额外权限。
- 层级不完整：使用 --include-children 标志获取完整块树。
限制
- 访问令牌有效期为 2 小时，需要按需刷新。
- Slides 内容提取需要额外权限，当前仅支持基础元数据。
- 旧版 Doc 文档仅支持基础元数据和有限内容。
- 需要飞书应用具备相应的 API 权限，且文档需分享给该应用或位于可访问空间。
- 部分块类型可能需要额外权限；配置文件和凭证需自行妥善保管，不应提交至版本控制。