| name | feishu-doc-style |
| description | 写飞书文档（技术方案、PRD、复盘、说明等）时遵守的写作规范，目标是让人读一遍就懂。当用户要写、改、审阅或润色一篇飞书 / 技术文档，问"这么写清不清楚""怎么把流程讲明白"，或显式输入 /feishu-doc-style 时使用。核心：只留结论不写推理、段落两三行、流程用图不用文字、不用黑话、格式克制、标题写内容不写结构。 |
| license | MIT |
| metadata | {"trigger":"写 / 改 / 审 / 润色飞书或技术文档（技术方案、PRD、复盘、说明）时，默认按本规范执行。","source":"2026-06-15 与 Daniel 打磨 Agora 技术方案、PRD 时定下、并持续补充。","self_compliance":"这份 skill 的所有文件本身也按这些规则写——改它时先用「交稿前自查」过一遍。"} |
feishu-doc-style
写飞书文档时遵守的规范，技术方案、PRD、复盘、说明这些都适用。目标只有一个：让人读一遍就懂。
何时使用
只要在写、改、审阅或润色一篇飞书文档或技术文档，就默认按本规范执行，不用等用户点名。
用户显式输入 /feishu-doc-style，或问"这么写清不清楚""怎么把这段讲明白"时，对着「核心原则」和「交稿前自查」给出修改。
帮人改稿时，先按自查清单逐条扫一遍，把违规的地方挑出来、给出改后的写法，再说明改了什么。
核心原则
-
只留结论，不写推理。 「为什么这样选、当时怎么权衡」这类推导过程删掉，直接给结论。读者要的是答案，不是你的思考过程。
-
段落两三行就够。 一段不超过两三行，不要把很多句话堆成一大段。长段落让人读着累。
-
流程类的内容用图，不用文字。 谁先谁后、数据怎么流、状态怎么变，这些用图表达，不要用一长串文字描述。一张时序图顶一大段文字。
-
箭头只能出现在图里。 正文和表格里禁止写「A → B；C → D」这种箭头速记链。它逼着读者在脑子里反查，等于把翻译成本丢给读者。
-
说人话，不用黑话。 内部术语读者看不懂。要么换成大白话，要么第一次出现时用一句话讲清楚。常见黑话对照见 references/jargon.md。
-
表格单元格写完整短句。 不要在格子里堆术语缩写，写「谁做了什么、结果是什么」。
-
不用装饰性 emoji 和高亮框。 📌 ⭐ 🔒 💡 ✅ 🚧 这类 emoji，还有彩色 callout 高亮框，都让页面显得乱、显得脏。要强调就用「加粗小标题。 接正文」的普通段落；文档级备注、状态提示用 > 引用块。一整篇下来，一个装饰 emoji、一个高亮框都不该有。
-
加粗要克制。 每节至多一两处，只加在真正的全局结论或原则领头上。名词清单、字段名、方位词（左 / 中 / 右）一律不加粗——层级靠句子和表格结构表达，不是靠满屏加粗。
-
不用键盘打不出来的字符。 圈码 ①②③④⑤、状态颜文字 ✓ ◐ ◑ ● ○、当图标用的 !、功能图标 ⚡ ⌘——这些都不是人正常会手打的东西，看着像「把界面文案原样誊上来」。列举用正常的「1. 2. 3.」有序列表或「第一、第二」；状态直接写「已完成 / 进行中」；步骤编号用普通数字（第 1 步 / STEP 1）。
-
标题写内容，不写结构。 标题直接说这节讲什么（「今年的目标和主要手段」「在做的事和进展」），不要把组织逻辑或写作脚手架塞进去。不写「总：」「分：」「第一部分：」这类结构前缀——总分、并列、先后靠内容顺序和标题层级自然体现。也不在标题里加元说明（解释机制的「（AI 每天追加）」这种话放正文或 > 引用块）。还要避免给内容套一个不匹配的框——比如把「按方向在做的几件事」硬塞进「上半年进展」这种时间壳里；先想清楚这块内容真正的组织维度（当前状态按方向，流水才按时间）。自查：把标题念出来，像不像一个人正常会起的名字——「总：今年的目标」就不像，「今年的目标」才像。
表格怎么写
列名用人话，最好是问句式。比如「用户做什么 / 系统在背后做什么 / 要不要在线等」，不要用「同步入口 / 异步链路与落库」这种内部黑话。
单元格是完整短句，一句话讲清楚谁做了什么、结果是什么。
技术细节放正文，表格只负责让人看懂。完整的建表语句、接口定义这些放正文专门章节，表格里不堆。
配图：什么时候用什么图
能画成图的流程就不要用文字堆。按要表达的东西选图：
| 要表达什么 | 用哪种图 |
|---|
| 逻辑流程、谁先谁后、数据怎么一步步流过去 | 时序图（mermaid sequenceDiagram），按角色分泳道 |
| 模块怎么分层、谁依赖谁 | 架构图（卡片式节点：图标加标题加一句说明，按层配色） |
| 状态怎么流转（比如草稿到发布到下架） | 流程图或状态图（mermaid flowchart） |
怎么把这些图真正放进飞书（mermaid 画板、lark-whiteboard、lark-cli 的用法）见 references/feishu-tooling.md。
交稿前自查
交稿前对着这份清单逐条过，有一条没过就回去改：
配套参考
这个 skill 自己也守这些规则
本 skill 的 SKILL.md、README、references 全按上面的规范写。改它时，先把「交稿前自查」当成对自己的检查：没有装饰 emoji、没有箭头链、段落短、标题写内容。规则变了就同步改 SKILL.md 和 README，别让两边对不上。
