feishu-doc-publisher

by happyphper

Install this Skill

curl -fsSL -o feishu-doc-publisher.zip https://skill.seembox.com/api/v1/skills/feishu-doc-publisher/download && unzip feishu-doc-publisher.zip

Download feishu-doc-publisher.zip

SKILL.md About

---
name: feishu-doc-publisher
version: 1.1.2
description: >-
  将 Markdown 文件发布为飞书（Feishu/Lark）在线文档。
  支持完整的 Markdown 语法，包括标题、段落、表格、有序/无序列表、
  待办事项、分隔线、加粗/斜体等富文本样式。
  当用户需要将本地 Markdown 文件同步或发布到飞书文档时使用。
metadata:
  openclaw:
    requires:
      bins:
        - node
      env:
        - FEISHU_APP_ID
        - FEISHU_APP_SECRET
    primaryEnv: FEISHU_APP_SECRET
---

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

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

## 前置条件

1. 用户需要在飞书开放平台创建应用并获取 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`。
2. 应用需要具备以下权限：
   - `docx:document` — 读写新版文档
   - `docx:document:readonly` — 只读新版文档（可选）
3. **安全建议**：
   - 建议创建专用的飞书应用，仅授予文档读写权限（最小权限原则）。
   - 妥善保管 App Secret，避免泄露；如疑似泄露请立即轮换凭证。
   - 仅发布你确实需要上传到飞书的 Markdown 文件，避免发布包含敏感信息的文件。

## 安装

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

```bash
bash {baseDir}/install.sh
```

> 安装脚本会以交互方式提示输入凭证（Secret 输入时不回显），并安全写入 `~/.config/feishu-doc-publisher/.env`。

## 使用方式

### 发布 Markdown 文件到飞书

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

```bash
node {baseDir}/scripts/publish.js "<markdown_file_path>"
```

**参数说明：**
- `<markdown_file_path>`：待发布的 Markdown 文件路径（必填）

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

### 发布并指定自定义标题

```bash
node {baseDir}/scripts/publish.js "<markdown_file_path>" --title "自定义文档标题"
```

### 发布到指定目录

```bash
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` 安装依赖

_meta.json Metadata

{
  "ownerId": "kn765wb3ahj97r76jfkt0db3rn859kbx",
  "publishedAt": 1777730503978,
  "slug": "feishu-doc-publisher",
  "version": "1.1.2"
}