feishu-doc-read

name	feishu-doc-read
description	读取飞书云文档内容（纯文本/富文本块/Markdown）。当用户分享飞书文档链接、要求获取/阅读/抓取/解析飞书云文档时使用。基于飞书开放平台 docx/v1 API，独立于主代码。
family_id	feishu-doc
family_label	飞书文档族
family_summary	处理飞书云文档的读取、同步与双向落盘；命中后再区分读取还是写回。
family_trigger_examples	飞书文档, 云文档读取, 文档同步
risk_level	low
variant_rank	10
metadata	{"category":"feishu"}

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()