feishu-doc-publisher

将 Markdown 文件发布为飞书（Feishu/Lark）在线文档。 支持完整的 Markdown 语法，包括标题、段落、表格、有序/无序列表、 待办事项、分隔线、加粗/斜体等富文本样式。 当用户需要将本地 Markdown 文件同步或发布到飞书文档时使用。

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

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

前置条件

1. 用户需要在飞书开放平台创建应用并获取 FEISHU_APP_ID 和 FEISHU_APP_SECRET。
2. 应用需要具备以下权限：
   • docx:document — 读写新版文档
   • docx:document:readonly — 只读新版文档（可选）

安装

运行安装脚本（交互式配置凭证 + 安装依赖 + 注册到 OpenClaw）：

bash {baseDir}/install.sh

也可以通过命令行参数直接传入凭证（非交互模式）：

bash {baseDir}/install.sh --app-id <your_app_id> --app-secret <your_app_secret>

使用方式

发布 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 格式
代码块	✅	三反引号格式

技术实现

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

错误处理

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

配置说明

环境变量加载优先级（先找到的优先）：

1. 全局配置: ~/.config/feishu-doc-publisher/.env
2. 项目目录: 当前工作目录下的 .env 文件
3. 系统环境变量: 已设置的 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 安装依赖