名称： feishu-doc-reader
描述： 使用飞书开放 API 读取和提取飞书文档内容
元数据： {"moltbot":{"emoji":"📄","requires":{"bins":["python3","curl"]}}}

飞书文档阅读器

此技能支持使用飞书开放 API 读取和提取飞书文档内容。

配置

设置技能

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

{
  "app_id": "在此处填写你的飞书应用 ID",
  "app_secret": "在此处填写你的飞书应用密钥"
}

2. 确保脚本可执行：

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

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

使用方法

基本文档读取

读取飞书文档需要文档令牌（可在 URL 中找到：https://example.feishu.cn/docx/DOC_TOKEN）。

使用 Shell 脚本（推荐）：

# 首先确保环境变量已设置
./scripts/read_doc.sh "你的文档令牌"

# 或显式指定文档类型
./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 "你的文档令牌"
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

支持的文档类型

• Docx 文档（新版飞书文档）：支持完整的内容提取，包括块、元数据和结构
• Doc 文档（旧版）：支持基本元数据和有限的内容提取
• 表格：支持完整的电子表格数据提取和表格导航
• 幻灯片：支持基本元数据（内容提取需要额外权限）

功能特性

增强的内容提取

• 结构化输出：清晰的 JSON 格式，包含文档元数据、内容块和层级结构
• 完整的块访问：全面访问所有文档块，包括文本、表格、图片、标题、列表等
• 块层级关系：正确处理块之间的父子关系
• 文本提取：自动从复杂的块结构中提取文本
• 表格支持：正确解析表格的行列结构
• 图片处理：提取图片 URL 和元数据
• 链接解析：提取内部和外部链接

支持的块类型

• text：纯文本和富文本内容
• heading1/2/3：具有正确层级的文档标题
• bullet/ordered：支持嵌套的列表项
• table：包含单元格和格式的完整表格结构
• image：包含令牌和元数据的图片块
• quote：引用块
• code：支持语言检测的代码块
• equation：数学公式
• divider：水平分隔线
• page：分页符（用于多页文档）

错误处理与诊断

• 详细的错误信息：清晰解释常见问题
• 权限验证：在发起请求前检查所需权限
• 令牌验证：在处理前验证文档令牌
• 重试逻辑：对临时性网络错误自动重试
• 速率限制处理：优雅处理 API 速率限制

安全特性

• 安全的凭证存储：支持环境变量和安全文件存储
• 无凭证日志记录：凭证不会出现在日志或输出中
• 最小权限原则：仅使用必需的 API 权限
• 访问令牌缓存：高效重用令牌以减少 API 调用

命令行选项

主文档阅读器

# 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 - 读取电子表格内容

错误处理

常见错误及解决方案：
- 403 禁止访问：检查应用权限和文档共享设置
- 404 未找到：验证文档令牌是否正确以及文档是否存在
- 令牌过期：访问令牌有效期为 2 小时，需要时刷新
- 应用 ID/密钥无效：在飞书开放平台仔细检查你的凭证
- 权限不足：确保你的应用具有所需的 API 权限
- 99991663：应用无权访问该文档
- 99991664：文档不存在或已被删除
- 99991668：令牌过期，需要刷新

示例

提取具有完整结构的文档

# 读取文档
./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

安全注意事项

• 切勿提交凭证：将应用密钥排除在版本控制之外
• 使用最小权限：仅请求你的用例所需的权限
• 安全的文件权限：为密钥文件设置适当的文件权限（chmod 600）
• 环境隔离：为开发和生产环境使用不同的应用
• 访问审计：定期审查你的应用可以访问哪些文档

故障排除

认证问题

1. 在飞书开放平台验证你的应用 ID 和应用密钥
2. 确保应用已发布并具有所需权限
3. 检查环境变量或配置文件是否正确设置
4. 使用 test_auth.py 脚本测试以验证凭证

文档访问问题

1. 确保文档已与应用共享或在可访问的空间中
2. 验证文档令牌格式（应以 docx_、doc_ 或 sheet_ 开头）
3. 检查文档是否需要额外的共享权限

网络问题

1. 确保你的服务器可以访问 open.feishu.cn
2. 如果在受限环境中运行，请检查防火墙规则
3. 脚本包含针对临时性网络故障的重试逻辑

块相关特定问题

1. 空的块响应：文档可能为空或没有可访问的块
2. 缺少块类型：某些块类型需要额外权限
3. 不完整的层级结构：使用 --include-children 标志获取完整的块树

参考链接

• 飞书开放 API 文档
• 文档 API 参考
• 块 API 参考
• 认证指南
• 表格 API 参考