Feishu Doc Workflow

---

name: feishu-doc-workflow

description: Feishu 文档写作与排版工作流。处理飞书 docx 的正文改写、分段润色、插图、按块定位插入、补充链接、以及把文档权限改成“互联网获得链接的人可查看”等公开分享设置时使用。也用于排查“能读不能写”“插图位置不对”“文档写入 400/403”这类飞书文档问题。

---

# Feishu Doc Workflow

用这个 skill 处理 **飞书 docx 文档本体** 的写作、排版、插图、公开分享和排障。

这个 skill 能不能给别人用？

能。这个 skill 本质上是一套 **飞书文档工作流说明书**，不是绑定某个私人账号的硬编码脚本。

但它不是“裸技能包到处都能跑”的那种万能包。别人要正常使用，至少要满足：

是否必须安装新版飞书插件？

**不绝对要求“必须是最新版官方插件”**，但要求环境里已经具备等价能力。

更准确地说，这个 skill 依赖的是：

所以：

**最稳妥的发布建议**：默认面向“已接好飞书、且 `feishu_doc` 正常可用”的 OpenClaw 用户发布。

发布给别人前，最好写清楚的飞书权限

按当前这套 skill 的能力，建议至少写清下面这些 **最低测试通过权限**：

如果发布说明要写得更实用，再补两条环境前提：

其中：

建议在发布页附的兼容性说明

可以直接写成：

> 本 skill 面向已完成飞书集成的 OpenClaw 用户。要求环境中 `feishu_doc` 工具可用，且飞书应用至少具备 `docx:document`、`docx:document:readonly`、`docx:document.block:convert`、`drive:drive` 权限。若需将文档开成“互联网获得链接的人可查看”，还需在当前环境允许通过 API 更新 Drive public permission。

推荐 OpenClaw 最低版本

建议写成：

原因不是“这个 skill 只认某个版本号”，而是当前内容已经按我这次实际验证通过的环境来写：

如果别人版本更老，但 `feishu_doc` 与相关权限链路都正常，也可能能用；只是**公开发布时最好写“推荐 2026.3.8+”**，避免踩旧环境坑。

推荐飞书插件形态

公开说明里建议明确：

- 已启用当前内置 / stock `feishu` 扩展，或

- 使用功能等价、已验证可提供 `feishu_doc` 的 Feishu 插件方案

不要把发布文案写成“必须安装某一个特定插件版本”，而应写成：

> 只要你的 OpenClaw 环境已经具备 `feishu_doc` 工具能力，并配置好了飞书 app 凭证，本 skill 就可使用。

安装前检查清单

发布时建议附这个 checklist：

- `docx:document`

- `docx:document:readonly`

- `docx:document.block:convert`

- `drive:drive`

常见报错速查表

1. `400` 写文档失败

先查：

这是最常见根因。没有这个权限时，经常表现为：

2. `403` 能读不能写

先查：

也就是：

3. 图片插入成功但位置不对

先查：

解决原则：

4. 文档已经开了外部访问，但外网还是打不开

先查：

不要只看 PATCH 成功，要再 GET 一次确认最终值。

快速判断

推荐工作流

1. 先读，再改

编辑已有飞书文档时，优先按这个顺序：

1. `feishu_doc(action="read")` 看标题、正文摘要、块类型

2. 如果涉及图片、表格、精确位置插入，再 `feishu_doc(action="list_blocks")`

3. 再决定是：

- 小改几段 → `update_block`

- 在某段后面补内容 → `insert`

- 文档尾部补内容 → `append`

- 整篇重写 → `write`

不要一上来就整篇 `write`，除非你明确要整体重写。

2. 插图规则

插图时优先记住两件事：

常用做法：

1. `list_blocks` 找到当前块顺序

2. 判断图片应插在谁前面/后面

3. `upload_image(file_path=..., parent_block_id=<doc_token 或父块>, index=<位置>)`

4. 如果插错了，不要硬忍，直接 `delete_block`

5. `read` 或 `list_blocks` 复查最终顺序

3. 长文排版规则

当用户说“别一大坨字堆一起”“花一点”“中间加图”时：

公开分享权限：开成“互联网获得链接的人可查看”

当用户明确要求：

目标状态应设为：

API 方式

用 Feishu Drive public permission 接口：

PATCH body 参考：

{
  "external_access_entity": "open",
  "security_entity": "anyone_can_view",
  "comment_entity": "anyone_can_view",
  "share_entity": "anyone",
  "manage_collaborator_entity": "collaborator_can_view",
  "link_share_entity": "anyone_readable",
  "copy_entity": "anyone_can_view"
}

改完后一定再 `GET` 一次确认，不要只看 PATCH 成功。

飞书文档写入排障：先查这两层

这是最该记进 skill、而不是记忆的固定排障套路。

情况 A：写文档时报 400

第一优先检查：

如果缺这个权限，常见表现就是：

情况 B：能读但写时报 403

第二优先检查：

也就是两层要都通：

1. 应用 scope 允许写

2. 这篇文档本身也允许这个应用编辑

只通第一层、不通第二层，仍然会 403。

经验原则