飞书文档发布器 (Feishu Doc Publisher)#

将 Markdown 文件发布为飞书在线文档，完整支持表格等富文本样式。

前置条件#

1. 用户需要在飞书开放平台创建应用并获取 FEISHU_APP_ID 和 FEISHU_APP_SECRET。

2. 应用需要具备以下权限：

   • docx:document — 读写新版文档
   • drive:drive — 查看、评论、编辑和管理云空间中所有文件 (必须：用于配置文档分享权限及移交 Owner)
   • docx:document:readonly — 只读新版文档（可选）

3. 安全建议：

   • 建议创建专用的飞书应用，仅授予文档读写权限（最小权限原则）。
   • 妥善保管 App Secret，避免泄露；如疑似泄露请立即轮换凭证。
   • 仅发布你确实需要上传到飞书的 Markdown 文件，避免发布包含敏感信息的文件。

安装#

本技能无需额外安装第三方依赖包，使用纯 Python 标准库编写。仅需确保您的环境中已安装 Python 3 即可。

如果需要配置全局凭证（可选），您可以手动创建 ~/.config/feishu-doc-publisher/.env 文件并写入凭证信息。

使用方式#

发布 Markdown 文件到飞书#

当用户要求将一个 Markdown 文件发布到飞书时，执行以下命令：

bash

python3 {baseDir}/scripts/publish.py "<markdown_file_path>"

参数说明：

• <markdown_file_path>：待发布的 Markdown 文件路径（必填）

输出示例：

text

✅ 文档发布完成
📄 文档标题: 五一家庭出游计划
📄 文档 ID: FiMLd0a9so1tgLxp3rncj2AEnob
🔗 文档链接: https://feishu.cn/docx/FiMLd0a9so1tgLxp3rncj2AEnob
📊 成功: 85, 失败: 0

发布并指定自定义标题#

bash

python3 {baseDir}/scripts/publish.py "<markdown_file_path>" --title "自定义文档标题"

发布到指定目录#

bash

python3 {baseDir}/scripts/publish.py "<markdown_file_path>" --folder "<folder_token>"

folder_token 可以从飞书文件夹 URL 中获取。

设置公共链接权限（外部公开与组织内分享）#

bash

# 赋予组织内获得链接的人可编辑权限
python3 {baseDir}/scripts/publish.py "<markdown_file_path>" --share tenant-edit

支持的权限选项：

• tenant-read: 组织内可阅读
• tenant-edit: 组织内可编辑
• public-read: 互联网可见可阅读
• public-edit: 互联网可见可编辑

注意：设置互联网可见需要您的飞书应用拥有相应的权限，且飞书企业管理后台未禁止将文档分享到组织外。

移交文档所有权 (Transfer Owner)#

由于文档由脚本(机器人)创建，机器人默认是最高权限的 Owner。为便于后续您在飞书中管理该文档，可以在发布时将其所有权“过户”给指定的人类账号。 支持使用企业邮箱（ email）或 openid、 userid 等标识：

bash

python3 {baseDir}/scripts/publish.py "<markdown_file_path>" --owner "email:your_name@company.com"

成功过户后，机器人将被降级，该人类账号将成为文档在飞书系统中的最终 Owner，可在飞书中随意调整分享和人员权限。

自动化提示: 如果不想每次都在命令行输入 --owner，您可以在任意生效的 .env 文件中配置统一的环境变量 FEISHU_ADMIN。

脚本会自动通过内容推断您的身份类型：

• 包含 @ 符号，自动按 email 邮箱移交。
• 以 ou_ 开头，自动按 openid 移交。
• 其他情况，默认按内部 userid 工号移交。

env

# 在 .env 中增加如下配置，即可实现发文后全自动过户！
FEISHU_ADMIN=your_name@company.com

支持的 Markdown 元素#

元素支持状态说明标题 (h1~h6)✅自动映射为飞书标题层级段落✅普通文本段落加粗✅**text** 格式_斜体_✅*text* 格式删除线✅~~text~~ 格式行内代码✅反引号格式超链接✅[text](url) 格式表格✅完整表格样式，含表头有序列表✅1. item 格式无序列表✅- item 格式待办事项✅- [ ] item 格式分隔线✅--- 格式引用✅> text 格式代码块✅三反引号格式

技术实现#

1. 先调用飞书 blocks/convert API 将 Markdown 转为飞书 Block 结构
2. 创建空白飞书文档
3. 非表格内容使用 children 接口批量插入
4. 表格使用 descendant 接口插入（需要重建临时 block ID）
5. 插入失败时自动回退为纯文本格式

错误处理#

• 如果发布脚本报 token 获取失败，检查 FEISHU_APP_ID 和 FEISHU_APP_SECRET 是否正确
• 如果报权限不足，确认飞书应用已开启文档相关权限
• 表格插入失败会自动回退为纯文本段落，不影响整体文档发布

配置说明#

环境变量加载优先级（由高到低，找到即生效）：

1. 系统环境变量: 系统中已存在的 FEISHU_APP_ID / FEISHU_APP_SECRET
2. OpenClaw 统一配置: ~/.openclaw/.env
3. 专属全局配置: ~/.config/feishu-doc-publisher/.env
4. 当前工作区配置: 执行该工具的当前目录或上级工作区目录中的 .env 文件
5. Skill 本地目录: 项目根目录下的 .env 文件

.env 文件格式：

text

FEISHU_APP_ID=cli_xxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx

规则#

• 始终通过 {baseDir} 引用脚本路径
• 发布前确认环境变量 FEISHU_APP_ID 和 FEISHU_APP_SECRET 已配置
• 脚本会自动按照预设优先级加载相关的 .env 配置文件