Feishu Docs Skill

飞书文档读写工具。支持在用户的个人云盘内创建、读取、写入文档，自动管理 OAuth 续期。

🚀 快速开始（5 分钟）

跟着这 7 步走，小白也能配置好。

第 1 步：创建飞书应用

1. 打开 https://open.feishu.cn → 点击 创建企业自建应用
2. 取个名字，比如 My Notes，点确定
3. 创建成功后，在 凭证与基础信息 里找到 App ID 和 App Secret，复制下来

第 2 步：开通权限

左侧菜单 → 权限管理 → 搜索并添加 2 个权限：

勾选后点 批量开通。

第 3 步：设置重定向 URL

左侧菜单 → 安全设置 → 重定向 URL → 添加：

https://open.feishu.cn/cli/callback

第 4 步：保存凭证到本地

打开终端，执行以下命令（换成你自己的 App ID 和 Secret）：

echo 'FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxxxxx' >> ~/.openclaw/.feishu_env
echo 'FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.openclaw/.feishu_env
chmod 600 ~/.openclaw/.feishu_env

第 5 步：修改文件夹 ID（可选）

如果你想把笔记归纳到指定文件夹：

1. 打开飞书云盘 → 新建一个文件夹（比如 Ace笔记）
2. 进入文件夹 → 复制浏览器地址栏末尾的那串 ID（类似 xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx）
3. 编辑 scripts/feishu_docs.py，找到 ACE_FOLDER_TOKEN 换成你的文件夹 ID

不改也没关系，文档会默认创建在云盘根目录。

第 6 步：发布应用并授权

1. 回到飞书开发者后台 → 版本管理与发布 → 创建版本（版本号写 1.0.0）→ 提交审核
2. 审核通过后，打开飞书 → 工作台 → 搜索你的应用 → 点击 安装

第 7 步：授权你的账号

先加载凭证，然后运行授权命令：

source ~/.openclaw/.feishu_env
cd ~/.openclaw/workspace
python3 scripts/feishu_docs.py token

终端会输出一个链接 → 浏览器打开它 → 扫码登录飞书 → 授权后会跳转 → 地址栏 ?code=xxx 那串复制下来 → 粘贴到终端回车。

看到 Token 刷新成功！ 就搞定了。

✅ 测试

source ~/.openclaw/.feishu_env
cd ~/.openclaw/workspace
python3 scripts/feishu_docs.py create "Hello World"

返回一个飞书链接，点开能看到文档 → 配置成功 🎉

使用方式

支持的脚本操作

python3 scripts/feishu_docs.py list                    # 列出云盘最近文档
python3 scripts/feishu_docs.py read \x3Cdoc_id>           # 读取文档内容
python3 scripts/feishu_docs.py create \x3Ctitle>          # 创建文档
python3 scripts/feishu_docs.py write \x3Cdoc_id> \x3Ctext>        # 追加文本段落
python3 scripts/feishu_docs.py bold \x3Cdoc_id> \x3Ctext>         # 追加加粗文本
python3 scripts/feishu_docs.py heading \x3Cdoc_id> \x3Ctext> [level=2]  # 追加标题（level=2为H2，3为H3）
python3 scripts/feishu_docs.py token                   # 查看/刷新 token 状态
python3 scripts/feishu_docs.py code \x3Cdoc_id> \x3Ctext>    # 追加代码块（纯文本，不带 style 字段）
python3 scripts/feishu_docs.py image \x3Cdoc_id> \x3Curl>    # 从网址插入图片

通过 Agent 使用

安装此 Skill 后，你的 Agent 可以理解这些指令：

"记到飞书：今天的会议纪要写了xxx"
"把上周的分析报告追加到笔记里"
"帮我创建一篇周报笔记"
"读取笔记内容给我看看"
"把这张截图插进文档"

Agent 会自动完成创建文档、格式化内容、插入图片等操作。

前置条件（详细版）

飞书应用配置

使用前需要完成一次性的飞书开放平台配置：

1. 创建应用：访问 https://open.feishu.cn → 创建企业自建应用
2. 获取凭证：应用详情 → 凭证与基础信息 → 记录 App ID 和 App Secret
3. 开通权限（应用身份权限 + 用户身份权限）：
   • drive:drive — 云盘完全读写
   • docx:document — 文档读写
4. 配置安全设置：重定向 URL 添加 https://open.feishu.cn/cli/callback
5. 发布版本：创建版本号（如 1.0.0）并提交审批
6. 企业授权：飞书管理后台 → 工作台 → 应用管理 → 安装并授权

凭证配置

将 App ID 和 App Secret 存入环境变量或配置文件：

# 方式一：环境变量
export FEISHU_APP_ID="your_app_id"
export FEISHU_APP_SECRET="your_app_secret"

# 方式二：配置文件（推荐，chmod 600）
echo 'FEISHU_APP_ID=your_app_id' >> ~/.openclaw/.feishu_env
echo 'FEISHU_APP_SECRET=your_app_secret' >> ~/.openclaw/.feishu_env
chmod 600 ~/.openclaw/.feishu_env

OAuth 授权

用户需通过 OAuth 授权获取 user_access_token，使文档创建在个人云盘：

1. 生成授权链接（由工具自动生成或手动拼接）
2. 用户点击链接 → 飞书登录授权
3. 授权成功后复制跳转链接中的 code 参数
4. 工具自动换取 access_token + refresh_token

权限与安全规则

• 文件夹范围：仅限指定的文件夹内操作（通过 FEISHU_FOLDER_TOKEN 环境变量配置）
• 禁止操作：不可查看/编辑/移动/删除指定文件夹以外的文档
• 删除保护：删除文档需获得用户明确确认
• 多笔记：不同题材可在文件夹下创建多篇笔记

涉及的飞书 API

文档格式化规范

标题体系

H1 = 日期（当天笔记标题）
H2 = 数字序号 + 独立内容标题
H3 = 内容内短标题

内容格式

• CLI 命令/代码 → 飞书代码块（block_type=14），注意不要加 style 字段，API 会拒绝

• 步骤流程 → 编号列表（1. 2. 3.）

• Emoji 仅用于以下场景：

  Emoji	场景
  ⚠️	注意事项、警告
  💡	重点提示、诀窍
  ✅	完成状态
  🔒	安全相关
  🚀 / ✨	标题或里程碑

• 加粗：关键术语、重要结论、核心数字 — 使用 text_element_style.bold: true

• 🔴 颜色标签：H3 标题前可用颜色 emoji 区分模块，正文中红色/橙色用于警示性重点

• 行内代码：文件名、命令、参数、API 端点 — 使用 text_element_style.inline_code: true

表格规范

• 首行表头自动加粗（bold=True）
• 每格仅含一个文本块，无多余空行
• 行数列数无限制，超大表格（50行+）创建前会警示
• 创建方式：block_type=31，使用 PATCH 更新单元格内容

图片插入（3 步流程）

飞书 Docx API 不支持一步创建带图的图片块，需分三步：

1. 创建空图片块 — POST children，image: {} 必须为空对象
2. 上传图片 — upload_all，parent_node 设为图片块 ID
3. PATCH 绑定 — replace_image 传入原始 file_token

注意事项：

• 不需要 image/ 前缀，用原始 file_token 即可
• upload 的 parent_node 是图片块 ID，不是文档 ID
• file_token 字段在 create 时 API 接受但不存储
• token 字段在 create 时直接报 invalid param