飞书文档发布器 (Feishu Doc Publisher)
将 Markdown 文件发布为飞书在线文档，完整支持表格等富文本样式。
前置条件
- 用户需要在飞书开放平台创建应用并获取
FEISHU_APP_ID和FEISHU_APP_SECRET。 - 应用需要具备以下权限：
docx:document— 读写新版文档docx:document:readonly— 只读新版文档（可选）
- 安全建议：
- 建议创建专用的飞书应用，仅授予文档读写权限（最小权限原则）。
- 妥善保管 App Secret，避免泄露；如疑似泄露请立即轮换凭证。
- 仅发布你确实需要上传到飞书的 Markdown 文件，避免发布包含敏感信息的文件。
安装
运行安装脚本（交互式配置凭证 + 安装依赖 + 注册到 OpenClaw）：
bash {baseDir}/install.sh
安装脚本会以交互方式提示输入凭证（Secret 输入时不回显），并安全写入
~/.config/feishu-doc-publisher/.env。
使用方式
发布 Markdown 文件到飞书
当用户要求将一个 Markdown 文件发布到飞书时，执行以下命令：
node {baseDir}/scripts/publish.js "<markdown_file_path>"
参数说明：
<markdown_file_path>：待发布的 Markdown 文件路径（必填）
输出示例：
✅ 文档发布完成
📄 文档标题: 五一家庭出游计划
📄 文档 ID: FiMLd0a9so1tgLxp3rncj2AEnob
🔗 文档链接: https://feishu.cn/docx/FiMLd0a9so1tgLxp3rncj2AEnob
📊 成功: 85, 失败: 0
发布并指定自定义标题
node {baseDir}/scripts/publish.js "<markdown_file_path>" --title "自定义文档标题"
发布到指定目录
node {baseDir}/scripts/publish.js "<markdown_file_path>" --folder "<folder_token>"
folder_token 可以从飞书文件夹 URL 中获取。
支持的 Markdown 元素
| 元素 | 支持状态 | 说明 |
|---|---|---|
| 标题 (h1~h6) | ✅ | 自动映射为飞书标题层级 |
| 段落 | ✅ | 普通文本段落 |
| 加粗 | ✅ | **text** 格式 |
| 斜体 | ✅ | *text* 格式 |
| ✅ | ~~text~~ 格式 | |
行内代码 | ✅ | 反引号格式 |
| 超链接 | ✅ | [text](url) 格式 |
| 表格 | ✅ | 完整表格样式，含表头 |
| 有序列表 | ✅ | 1. item 格式 |
| 无序列表 | ✅ | - item 格式 |
| 待办事项 | ✅ | - [ ] item 格式 |
| 分隔线 | ✅ | --- 格式 |
| 引用 | ✅ | > text 格式 |
| 代码块 | ✅ | 三反引号格式 |
技术实现
- 先调用飞书
blocks/convertAPI 将 Markdown 转为飞书 Block 结构 - 创建空白飞书文档
- 非表格内容使用
children接口批量插入 - 表格使用
descendant接口插入（需要重建临时 block ID） - 插入失败时自动回退为纯文本格式
错误处理
- 如果发布脚本报 token 获取失败，检查
FEISHU_APP_ID和FEISHU_APP_SECRET是否正确 - 如果报权限不足，确认飞书应用已开启文档相关权限
- 表格插入失败会自动回退为纯文本段落，不影响整体文档发布
配置说明
环境变量加载优先级（先找到的优先）：
- 全局配置:
~/.config/feishu-doc-publisher/.env - 项目目录: 当前工作目录下的
.env文件 - 系统环境变量: 已设置的
FEISHU_APP_ID/FEISHU_APP_SECRET
.env 文件格式：
FEISHU_APP_ID=cli_xxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx
规则
- 始终通过
{baseDir}引用脚本路径 - 发布前确认环境变量
FEISHU_APP_ID和FEISHU_APP_SECRET已配置 - 脚本会按 全局配置 → 项目目录 → 系统环境变量 的顺序自动加载
.env - 首次使用前需在
{baseDir}目录下执行npm install安装依赖