📦 feishu-doc-publisher — 飞书文档发布器

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

前置条件 用户需在飞书开放平台创建应用并获取 FEISHU_APP_ID 与 FEISHU_APP_SECRET。 应用需具备以下权限：

• docx:document — 读写新版文档
• docx:document:readonly — 只读新版文档（可选）

安装 运行安装脚本（交互式配置凭证 + 安装依赖 + 注册到 OpenClaw）： bash {baseDir}/install.sh

也可通过命令行参数直接传入凭证（非交互模式）： bash {baseDir}/install.sh --app-id --app-secret

使用方式 发布 Markdown 文件到飞书 执行以下命令： node {baseDir}/scripts/publish.js ""

参数说明： ：待发布的 Markdown 文件路径（必填）

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

发布并指定自定义标题 node {baseDir}/scripts/publish.js "" --title "自定义文档标题"

发布到指定目录 node {baseDir}/scripts/publish.js "" --folder "" folder_token 可从飞书文件夹 URL 获取。

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

技术实现

• 调用飞书 blocks/convert API 将 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 安装依赖