---

name: feishu-writer category: discoverable trigger: "飞书文档|飞文档|写文档到飞书|生成研报|写研报|画架构图|mermaid|plantuml|飞书长文|飞书富文本|技术方案|设计文档|feishu writer|write feishu doc" description: > TRIGGER WHEN: 用户要求写/创建/整理飞书文档、"生成研报"、"画架构图(Mermaid/PlantUML)"且明确指定输出到飞书时。 专业的飞书文档生成与富文本写入，支持高质感排版、Mermaid 净化及分块长文写入。 本技能是 lark-doc / lark-wiki 的"长文创作 + 富文本写入"补充，不重复 lark-doc 已有的通用文档操作。 metadata: requires: bins: ["python3"] secrets: - path: "~/.ethan/.secrets/my_feishu.json" fields: ["app_id", "app_secret"] description: "飞书自建应用凭证。文件格式：{"app_id":"cli_xxx","app_secret":"xxx"}。缺省时脚本会以明确错误退出，绝不回退到硬编码。" relates: - skill: lark-doc scope: "通用文档 CRUD（fetch/create/update/media）。feishu-writer 不重复这些能力，只在需要 add_ons Mermaid 块、按文本定位移动图、转移所有权时介入。" - skill: lark-wiki scope: "知识空间节点管理。feishu-writer 写入完成后，若需挂到 Wiki 节点，转交 lark-wiki。" - skill: lark-shared scope: "认证与权限处理。当本技能脚本报权限错误时，转交 lark-shared 走 split-flow 授权。" - skill: lark-base scope: "多维表格（Bitable）创建与字段配置。需要在飞书文档中内嵌项目追踪/接口字段表/风险登记册时转交。" - skill: lark-whiteboard scope: "复杂自由排版架构图（SVG/JSON DSL）。本技能 add_mermaid.py 仅用于原生 add_ons Mermaid 块这种轻量场景。" license: MIT version: 2.2.0 source: internal (hermes agent, upgraded with Aime spec)

飞书高级写作助手 (Feishu Writer)

本技能用于生成极致专业、具有"人味"的飞书文档。写作规范依据 Aime 完整调研（2026-07-25）。

🧭 与 lark-doc / lark-wiki 的协作分工

场景	用谁
创建 / 读取 / 局部编辑普通文档	lark-doc（lark-cli docs +create/+fetch/+update）
知识空间节点管理、挂文档到 Wiki	lark-wiki
多维表格（项目追踪/字段表/风险登记册）	lark-base
复杂架构图（自由排版、SVG）	lark-whiteboard（whiteboard +update）
原生 Mermaid add_ons 块注入（block_type=40）	本技能 add_mermaid.py
按正文文本定位 → 删除旧块 → 在锚点后插入新 Mermaid	本技能 move_chart.py
把文档所有权从 bot 转给用户	本技能 transfer_owner.py
长文方略、去 AI 味排版、视觉节奏	本技能（写作规范）

铁律：本技能脚本是 lark-doc 的补充，不重新实现 docs +create/+fetch/+update。当用户的需求落在 lark-doc 已覆盖的通用操作上时，优先走 lark-doc；只有需要 add_ons Mermaid 块、按文本移动图、转移所有权时才用本技能脚本。

🛡️ 核心铁律 (Hardlines)

1. 去 AI 味排版：
   • 严禁署名（如 "by AI"）。
   • 禁止在正文写进度信息。
   • 标题要么纯中文，要么纯英文，禁止中英混杂（机翻感）。
   • 严禁使用"1. 执行摘要"、"总结"等 AI 惯用语，必须严格遵守"黄金开局"（# 概述 → ## 背景 → ## 目标）；去掉所有章节数字编号（如 ## 1.），保持专业感。
2. 黄金开局：必须采用「封面+元信息+背景摘要 Callout」起手式（详见 文档结构）。
3. 视觉纵深（每篇必有图）：
   • 每篇文档至少 1 张全景流程图/架构图；核心 H2 章节尽量各配 1 张图（流程图/架构图/时序图/数据图表）。
   • 素材配图：若文档基于外部资料（论文/报告/网页）撰写，必须从资料中提取有价值的图（架构图、实验结果图、流程图等）插入正文，不要只有文字。详见工作流「写入阶段 · 章节配图」。
   • 严禁扁平架构图。
   • Mermaid 优先：流程图/时序图/ER 图优先使用 Mermaid（飞书原生渲染）。
   • 架构图：复杂架构图优先 Draw.io 导出 SVG；条件不允许时用 Mermaid 三层架构图模板（见 references/diagram-templates.md）。
   • Mermaid 净化：节点必须用双引号包裹 A["节点名"]，严禁包含斜杠或括号以防客户端崩溃。注入前必须剔除节点名中的 Emoji 和特殊符号。

---

📐 写作规范（Aime 完整调研落地）

1. 文档结构设计

1.1 开头（封面 + 元信息 + 背景摘要）

[封面区域]
文档标题（H1，全文唯一，名词短语《XXX 方案设计》）
副标题/一句话摘要（正文色弱化，斜体）

[元信息区域] — 用表格或信息列表
- 作者 / 创建时间 / 最后更新
- 状态：🟡 草稿 / 🟢 已发布 / 🔴 已废弃
- 阅读对象：[目标读者]
- 预计阅读时长：X 分钟

[背景摘要区域] — 用蓝色 Callout
📌 本文要解决的问题是 XXX，读完你将了解 A、B、C。

规则：

• 标题必须回答"这篇文档是关于什么的"，避免"XXX方案v2"这种版本化标题
• 摘要 Callout 限制在 3 句以内，点明问题、解法、收益
• 元信息一定要有，方便追溯

1.2 主体段落结构（"总-分-收"三段式）

H2 章节标题（说明这一节要回答什么问题）
  └─ 一句引导句：解释本节的核心结论或主旨（1句，加粗）
  └─ H3 子节 A → 正文内容 + 代码块/表格/图片
  └─ H3 子节 B → 正文内容
  └─ 小结句（1-2句，用斜体或引用块收尾）

章节命名策略：

• H1：文档总标题，全文唯一，用名词短语（《XXX 方案设计》）
• H2：主功能模块，用动宾或疑问句（"为什么要做 XXX"、"如何配置 XXX"）
• H3：具体子话题，用名词或短句（"配置参数说明"）
• H4：不推荐常规使用

1.3 结尾收束

H2 总结 / 下一步

[总结 Callout — 绿色 ✅]
✅ 本文核心结论：
- 结论 A / 结论 B / 结论 C

[下一步 / 待办] — 表格
| 行动项 | 负责人 | 截止时间 | 状态 |

[相关链接]
- 🔗 上游依赖：相关文档 A
- 🔗 下游影响：相关文档 B
- 🔗 参考资料：相关文档 C

2. 排版样式

2.1 字体与字号

层级	飞书对应	使用场景
H1	标题1	文档主标题，全文唯一
H2	标题2	主要章节分割
H3	标题3	子话题
正文	正文	所有正文内容
说明文字	正文+斜体	注释、补充说明

• 不推荐在正文中手动放大字号，破坏层级一致性
• 例外：封面大标题可手动加大到 H1 以上

2.2 加粗 / 斜体 / 颜色

加粗（Bold） — 每段不超过 3 处：

• ✅ 用于：核心结论句、重要名词、警告性内容、数字指标
• ❌ 不用于：整段加粗、标题

斜体（Italic） — 语气弱化/引用/补充：

• ✅ 用于：术语初次出现、引用文献、补充注释
• ❌ 不用于：中文长段（可读性差）

颜色标注 — 全文不超过 3 种，每页不超过 5 处：

颜色	用途
🔴 红色	错误、危险、禁止做的事
🟡 橙/黄色	警告、注意事项、待确认
🔵 蓝色	链接（系统默认）
🟢 绿色	正确做法、已完成状态
⚫ 灰色	已废弃、低优先级

2.3 列表使用规则

• 无序列表：并列关系，每条不超过 2 行，嵌套不超过 2 层
• 有序列表：有执行顺序的步骤，每条末尾不加句号
• 引用块：仅用于引用他人原话/文档，不用于自己的观点（用 Callout 代替）

3. 布局组件

3.1 高亮块（Callout Block）— 飞书最核心的视觉组件

颜色/图标	使用语义	示例
💡 黄色	提示、技巧、推荐做法	💡 这里有个更快的方法…
⚠️ 橙色	警告、注意事项	⚠️ 此操作不可逆
🚫 红色	错误、禁止、高风险	🚫 不要在生产环境执行
✅ 绿色	总结、已确认结论	✅ 本节核心结论
📌 蓝色	背景说明、前提条件	📌 阅读本节前，请先了解…
📝 灰色	编辑备注、草稿注释	📝 TODO：此处待补充数据

规则：

• 每个 H2 章节 Callout 不超过 2 个
• 连续 Callout 之间必须有正文间隔
• 不要用 Callout 包裹超过 5 行的大段正文

3.2 折叠块

适合折叠：详细参数说明、历史版本、FAQ、长代码、附录 不适合折叠：核心结论、重要警告、关键步骤

命名规则：▶ 展开：完整配置参数说明，不要写"详情"、"更多"

3.3 分栏

场景	推荐分栏
对比两个方案	2 栏
并排展示图片	2-3 栏
参数说明	不分栏，用表格
移动端阅读	不分栏

规则：每栏正文不超过 200 字；不在分栏内再嵌套分栏；用于"视觉并排展示"，不用于"节省空间"。

3.4 表格排版

• 表头加粗 + 浅灰底色（#F5F5F5）
• 每列宽度按内容比例，不要全部等宽
• 状态列用颜色编码（🔴🟡🟢）
• 超过 10 行加说明"共 X 项，按 XXX 排序"
• 最多 6-7 列，超过请拆分

4. 视觉层次与阅读节奏

创造视觉纵深的 5 个手法：

1. 留白节奏：H2 前后各空一行，每 3-4 段插入视觉元素打断
2. 层级递进：H1→H2→H3 不跳级
3. 对齐一致：列表缩进方式统一
4. 视觉锚点：每 500 字左右设置一个"小地标"（Callout/图/表/分割线）
5. 段落长度控制：单段不超过 5 行

标准 H2 章节节奏模板：

H2 标题（锚点）
  ↓
引导句（1句，加粗核心观点）  ← 快速扫读者决定要不要继续读
  ↓
正文段落 A（3-4行）
  ↓
视觉元素（表格/代码块/Callout）← 阅读减速带
  ↓
正文段落 B（3-4行）
  ↓
小结/结论句（1-2句，斜体或 Callout）← 快速扫读者获得结论

5. 内容充实策略

5.0 篇幅底线（反偷懒硬约束）

写少了就是没做完。 一份正经文档不是"把要点列出来"就交差，读者要的是能读懂、能落地的深度内容。

文档类型	正文字数底线	H2 章节数
论文/技术方案解读	≥ 3000 字	≥ 5
设计文档/研报	≥ 2500 字	≥ 4
普通整理/纪要	≥ 1500 字	≥ 3

• 每个 H2 章节正文不少于 300 字，不能只有一句话 + 一张表就结束。
• 每个核心论点展开三层：是什么 → 为什么/怎么做 → 举例/数据佐证。只写第一层就是偷懒。
• 表格/图不能代替正文：图表是"减速带"，前后都要有文字讲清楚它说明了什么、边界在哪。见 gotchas「图多文少」。
• 如果自我感觉"好像写得有点短"，那就是真的短了 —— 回到每个章节按"所以呢？"再扩一轮。

5.1 核心原则："所以呢？"

每句话都要回答"所以呢？" — 每个论断后面必须跟 数据/案例/原因/对比 中的至少一个。

• ❌ 空洞写法：「我们采用了微服务架构。」
• ✅ 充实写法：「我们采用微服务架构，将用户服务、订单服务、支付服务解耦，单个服务故障不影响全局可用性，上线频率从每月 2 次提升到每天 10+ 次。」

5.2 章节内容清单

章节类型	必须包含	加分项
背景/问题定义	现状、痛点量化、为什么现在解决	历史背景、失败尝试
方案设计	核心思路、方案对比、选型理由	架构图、伪代码、决策矩阵
实施步骤	有序步骤、前置条件、预期结果	截图、示例输出、常见错误
结论/总结	核心结论列表、量化收益、后续计划	风险与局限、Q&A

5.3 数据嵌入策略

数据规模	呈现方式
1-2 个指标	行内数据，加粗：延迟从 800ms 降至 120ms，降幅 85%
2-4 个维度	2 栏布局或 before/after 表格
5 个以上指标	嵌入多维表格图表（转交 lark-base）

规则：数据必须注明来源；不要写没有对比基准的数据；估算数据用"约"、"~"标注。

5.4 案例嵌入（STAR 简化版）

📌 案例：[案例名称]
- 背景：XXX 场景下，遇到了 YYY 问题
- 做法：我们采用了 ZZZ 方案
- 结果：最终达成 AAA 效果（量化）

案例用 Callout（灰色/蓝色）包裹，多个案例用折叠块收纳。

6. 飞书高阶特性

特性	触发场景	实现路径
多维表格（Bitable）	项目追踪/甘特图、风险登记册、接口字段表、问题 Backlog	转交 lark-base；状态字段用"单选"🟢🟡🔴⚫，责任人用"人员"类型，截止日期开"到期提醒"
内嵌图表	指标趋势、资源分配饼图、任务进度条	多维表格录入数据 → 新建图表视图 → 嵌入正文
公式块（LaTeX）	算法复杂度、统计公式、ML 模型公式	行内 $...$；块级用公式块
目录块	长文档（超过 5 个 H2）必须插入	放在元信息表格之后、第一个 H2 之前，上方加分割线
任务列表（To-do）	文档的"合同"，责任人必须填写	[动词+对象+验收标准]，如"完成用户服务接口联调，通过压测报告"
代码块头部注释	所有独立代码段	# 文件：xxx.py / 作者 / 最后更新 / 用途
关联文档	上游依赖/下游影响/参考资料	@文档名 创建关联，不用粘贴 URL
版本与评论	里程碑评审	重要节点手动加版本备注；评审意见用"选中文字→评论"，不在正文写"【待确认】"

7. 架构图与流程图

按内容选图种（严禁一篇全是同款流程图，见铁律 3）：

要表达的内容	用哪种图	Mermaid 语法
系统由哪些模块组成、如何分层	架构图	flowchart + subgraph 分层
全局视角、整体链路一图看全	全景架构/全景流程图（每篇必有 1 张）	flowchart LR/TD + 多 subgraph
多角色/多系统按时间交互	时序图	sequenceDiagram
跨部门/跨角色的流程流转	泳道图	flowchart + 泳道 subgraph（模板库 #8）
有分支判断的处理逻辑	流程图	flowchart + 菱形 {}
数据实体关系	ER 图	erDiagram
对象在生命周期里的状态流转	状态图	stateDiagram-v2（模板库 #9）

工具选型优先级：

1. 流程图/时序图/ER图/状态图/泳道图 → Mermaid（飞书原生渲染，首选）
2. 系统架构图 → Draw.io 导出 SVG（保持矢量清晰度）
3. 快速草图/讨论稿 → 飞书白板直接嵌入

配色方案（字节/现代科技风）：

用途	色号	说明
主色（核心服务）	#4A90D9	标准蓝，核心/主链路
辅色（外部依赖）	#7B68EE	中紫，第三方/外部系统
成功/数据存储	#52C41A	绿色，数据库/缓存/存储
警告/异步流程	#F5A623	橙色，消息队列/异步任务
危险/失败路径	#FF4D4F	红色，错误处理/降级
背景/分组区域	#F0F5FF	浅蓝，框定服务组
文字（深色节点）	#FFFFFF	白色
文字（浅色节点）	#262626	深灰

节点形状语义、流程图/时序图/ER 图/三层架构图完整模板：见 references/diagram-templates.md

图表嵌入最佳实践：

1. Mermaid 直接嵌入：代码块 → 语言选 mermaid → 飞书自动渲染（首选）
2. SVG 优先于 PNG：Draw.io 导出 SVG，放大不失真
3. 图片必须加图注：图 X：[图表标题]（[数据来源/创建时间]），用斜体正文
4. 大图用折叠块包裹：避免撑开页面
5. 不要截图代替矢量图：高 DPI 屏幕模糊

8. 发布前 Checklist

发布前必须逐项检查 references/writing-checklist.md。

---

🛡️ 核心工作流 (Workflow)

1. 规划阶段 (Planning)

• 超过 5000 字长文必须"分而治之"：先出提纲 → 标注章节字数 → 报备给用户。
• 任何文档先确定：① 目标读者 ② 状态（草稿/已发布）③ 预计阅读时长。

2. 写入阶段 (Execution)

• 分片注入：每 20 个 Block 切割一次进行插入（单次上限 50）。

• 章节配图（关键，边写边配）：每写完一个 H2 章节就立即检查是否需要配图，不要等全文写完再补——趁该章节上下文还在，当场画图或插图。图种速选：

  要表达的内容	用哪种图	Mermaid 语法
  全局链路/整体流程一图看全	全景流程图（每篇必有 1 张）	flowchart LR/TD + 多 subgraph
  系统模块组成、如何分层	架构图	flowchart + subgraph 分层
  多角色/多系统按时间交互	时序图	sequenceDiagram
  有分支判断的处理逻辑	流程图	flowchart + 菱形 {}
  数据实体关系	ER 图	erDiagram
  对象生命周期状态流转	状态图	stateDiagram-v2

  配图来源：① 自己画 Mermaid（首选）；② 从外部资料提取的图片（论文 Figure、报告截图等，用 docs +media-insert 插入）；③ Draw.io 导出 SVG。每张图后必须配一段文字拆解（见 gotchas「图多文少」）。

• 原生表格：必须采用"原地 PATCH"法（读取 cell 内默认 block 并替换），严禁产生空行。

• 图片搬运：严禁复制旧文档的 Token。必须先 download 到本地再 insert。

• 目录块：长文档（>5 个 H2）必须在元信息表格后插入目录块。

3. 发布前 (Review)

• 按 references/writing-checklist.md 逐项核对。
• 评审意见用"选中文字 → 评论"，不在正文写"【待确认】"。
• 评审通过后手动加版本备注（"v1.0 评审通过版"）。

---

🧰 脚本工具箱

所有脚本均从 ~/.ethan/.secrets/my_feishu.json 读取飞书自建应用凭证（app_id / app_secret），绝不硬编码。文件格式：

{ "app_id": "cli_xxxxxxxxxx", "app_secret": "xxxxxxxxxxxxxxxxxx" }

如果该文件缺失或字段不全，脚本会以非零退出码报错，不会回退到任何内置默认值。

scripts/add_mermaid.py — 注入原生 Mermaid add_ons 块

将一段 Mermaid 代码作为 block_type=40 的 add_ons 块追加到指定文档末尾（或指定 index）。适合需要"原生 Mermaid 渲染"而非 SVG 画板的场景。

# 从 stdin 读 Mermaid，追加到文档末尾
python ~/.ethan/skills/feishu-writer/scripts/add_mermaid.py <doc_token> < mermaid.txt

# 或直接传字符串
python ~/.ethan/skills/feishu-writer/scripts/add_mermaid.py <doc_token> --mermaid 'graph TD\n  A["x"] --> B["y"]'

# 指定插入位置（默认 -1 末尾）
python ~/.ethan/skills/feishu-writer/scripts/add_mermaid.py <doc_token> --index 5 -m 'graph TD...'

净化规则：脚本不会替你净化 Mermaid。调用方必须保证节点名用双引号包裹、无斜杠/括号/Emoji。

scripts/move_chart.py — 按文本定位移动图

按"正文片段"在文档中找到包含该文本的 block，记下其 index+1 作为插入点；删除指定的旧 block_id；在该位置插入新的 Mermaid add_ons 块。常用于"把底部的图挪到对应章节后面"。

python ~/.ethan/skills/feishu-writer/scripts/move_chart.py <doc_token> \
  --delete-block-id <block_id_to_remove> \
  --anchor-text "章节正文中的一段唯一文本" \
  --mermaid-file mermaid.txt

--mermaid-file 优先于 --mermaid；两者缺一回退到 stdin。

scripts/transfer_owner.py — 转移文档所有权

把文档 owner 从当前持有者（通常是 bot）转给指定用户。先尝试 v1 接口，失败再尝试 v2。

python ~/.ethan/skills/feishu-writer/scripts/transfer_owner.py <doc_token> \
  --member-id <ou_xxxxx> --member-type openid

--member-type 默认 openid，可传 userid / departmentid 等。

---

避坑指南 (Gotchas)

• 字数幻觉 (Word Count Illusion)：AI 一次性输出极难突破 3000 字（往往把 Token 数当成字数）。如果是 5000+ 字深度长文，必须采用"多轮迭代注入 (Multi-pass Expansion)"策略：先生成骨架，再逐个章节进行深度扩写代码和逻辑细节。
• 画板协议匹配 (Whiteboard API Integration)：当需要画出更复杂和自由排版的架构图时，强烈推荐使用 lark-whiteboard 技能（whiteboard +update），通过 JSON DSL 或 Mermaid 代码导出 OpenAPI 格式后渲染，不要直接手写底层 OpenAPI。本技能的 add_mermaid.py 只用于"原生 add_ons Mermaid 块"这种轻量场景。
• 文档防碎裂 (Document Fragmentation)：多次向同文档注入时，必须用 lark-cli docs +update --command overwrite 全量覆盖或基于 Block ID 原地替换，严禁一味 append 导致结构崩塌。
• AI 结构化废话：严禁使用"1. 执行摘要"、"总结"等 AI 惯用语；起手式严格遵循铁律 2 的「封面+元信息+背景摘要 Callout」；去掉所有章节数字编号（如 ## 1.），保持专业感。
• 429 频率：批量填表时必须 time.sleep(0.5)。
• 身份切换：必须强制使用 User Token 创建（lark-cli docs +create --as user），确保文档 Owner 是用户而非机器人。如果文档已被 bot 创建，用本技能 transfer_owner.py 转给用户。
• Mermaid 崩溃：不要相信 API 返回的 Success，必须在注入前手动剔除节点名中的 Emoji 和特殊符号。
• 凭据安全：严禁把 app_secret 写进脚本或日志。所有脚本只从 ~/.ethan/.secrets/my_feishu.json 读取，且打印日志时禁止输出 Authorization header 或 token 明文。
• Callout 滥用：每章节 Callout 不超过 2 个；连续 Callout 必须有正文间隔；不要用 Callout 包裹超过 5 行的大段正文。
• 颜色滥用：全文颜色不超过 3 种，每页不超过 5 处；状态列用 🔴🟡🟢 编码即可，不要全文彩虹化。
• 图多文少 (All Charts, No Prose)：图多不代表深度够。每张关键图后面必须配一段有深度的文字拆解，讲清机制细节、阈值取舍、边界条件和背后的工程动机——否则读者只能看个大概，理解不了"为什么这么设计"。图的密度要够（每个关键流程都配图），但文字的密度也要跟上。
• 表格宽度 (Narrow Table)：飞书文档创建时如果不指定 <colgroup>，表格会默认很窄、文字被挤到换行。所有表格必须显式指定 <colgroup><col width="..."/> 并让总宽度接近 780（2 列用 220+560，3 列用 220+280+280，4 列用 180+200+200+200）。已创建的窄表格用 block_replace 整体替换 table block 来加宽，str_replace 对 colgroup 不生效。
• 大段文字未分点 (Wall of Text)：当一段文字出现明显的"其一/其二"、"三个原因"、"四种情况"等并列结构时，必须拆成 list（<ul> 无序或 <ol> 有序），而不是一整段连续文字。判断标准：如果能在文字里找到 2 个以上同层级的并列点，就值得拆。但不要滥用——连贯的论述性文字（讲一个完整因果链）保持段落，强行拆 list 反而碎片化。用 block_replace 把单个 <p> 替换为 <p>引导句</p> + <ul>分点</ul>。
• 左右布局未利用 (Missing Grid)：当出现"左 vs 右"、"A 的定位 vs B 的定位"这种对比性论述时，用 <grid><column width-ratio="0.5"> 左右布局比一整段文字更有视觉冲击力。典型场景：两个概念并排解释、两种方案对比定位。每栏正文不超过 200 字，不在分栏内再嵌套分栏。注意：column 里放 <p> 即可，不要放 table 或 whiteboard。

---

渐进式参考 (References)

按需加载，避免主 SKILL.md 膨胀：

• references/diagram-templates.md — Mermaid 节点形状语义表、流程图/时序图/ER 图/三层架构图完整模板、字节现代科技风配色应用示例。
• references/writing-checklist.md — 发布前逐项检查清单（12 项）。
• references/writing-prompt.md — Aime 给出的写作 System Prompt 模板，可直接内嵌到 agent 上下文。