Feishu Doc Read

Feishu Doc Read

基于 飞书开放平台 - 新版文档 docx/v1 实现：读取飞书云文档的纯文本、富文本块、或转换后的 Markdown 内容，供 Agent 或主程序按需调用。

使用场景

• 用户分享飞书文档链接，要 Butler 读取并理解/摘要/提炼内容
• 后台自动流程或巡检需要从某份云文档同步内容到本地
• 需要把飞书云文档导出为本地 Markdown / 纯文本文件
• 获取文档基本信息（标题、版本号）

快速开始

依赖

• Python 3.8+
• requests（与 butler_bot 主项目一致）

配置来源

与 feishu_chat_history 完全一致：

1. 函数入参 app_id / app_secret（优先）
2. config_provider() -> dict（复用主进程 CONFIG）
3. 环境变量 FEISHU_APP_ID / FEISHU_APP_SECRET
4. 兜底从 butler_main/butler_bot_code/configs/butler_bot.json 读取

飞书应用权限

需要在飞书开放平台为应用开通以下任一权限：

• docx:document:readonly（查看新版文档）— 推荐
• docx:document（创建及编辑新版文档）

同时，调用身份（tenant_access_token）需有目标文档的阅读权限：

• 通过文档页面右上角「…」→「添加文档应用」为应用授权

在代码中调用

from butler_bot_agent.skills.feishu_doc_read import (
    read_feishu_doc,
    download_doc_to_file,
    parse_document_id,
)

# 一站式读取（支持传 URL 或 document_id）
doc = read_feishu_doc(
    "https://xxx.feishu.cn/docx/QvXLdALtMoJcZrxL34vcsI1ynvT",
    mode="raw",  # "raw" | "markdown" | "blocks"
)
print(doc["title"])    # 文档标题
print(doc["content"])  # 纯文本 / Markdown 内容

# 导出到本地文件
path = download_doc_to_file(
    "https://xxx.feishu.cn/docx/QvXLdALtMoJcZrxL34vcsI1ynvT",
    output_path="./工作区/feishu_docs/会议纪要.md",
    mode="markdown",
)

# 只解析 document_id
doc_id = parse_document_id("https://xxx.feishu.cn/docx/QvXLdALtMoJcZrxL34vcsI1ynvT")

能力一览

三种 mode 对比

支持的文档元素

Markdown 转换支持：标题(1-9级)、文本、有序/无序列表、代码块、引用、待办事项、分割线、图片/文件/表格(占位标记)、公式、链接、@用户/@文档、加粗/斜体/删除线/行内代码。

权限与限制

• 需要 docx:document:readonly 或 docx:document 权限
• 调用身份需有目标文档阅读权限（通过「添加文档应用」授权）
• 频率限制：单应用 5 次/秒
• raw_content 接口有文档大小上限（飞书限制）
• blocks 接口单页最多 500 个 block，本 skill 已自动分页

与已有 skill 的关系

三者共享同一套凭证解析逻辑，可直接复用 butler_bot.json 中的 app_id / app_secret。

常见故障与排查

• 403 forbidden：应用未被授权访问该文档。去飞书文档页面「…」→「添加文档应用」。
• 404 not found：document_id 错误或文档已删除。检查 URL 是否正确。
• URL 解析失败：确认是 /docx/ 或 /wiki/ 路径的飞书链接。
• 凭证缺失：同 feishu_chat_history 排查流程，检查 butler_bot.json 或环境变量。

产出路径建议

• 与用户相关：./工作区/with_user/feishu_docs/
• 内部用途：./工作区/feishu_docs/

参考

• 飞书开放平台文档：
  • 获取文档纯文本内容
  • 获取文档所有块
  • 文档概述（document_id 说明）
  • 如何为应用开通文档权限