| name | gh-lark-tech-doc-writing |
| description | 从零写或大改技术侧飞书文档（技术方案 / PRD / 设计文档 / RFC），并在交付前执行方案 正确性 Review。适用于「帮我写一篇 XX 技术方案」「把这个设计整理成飞书文档」「按规范写份 PRD / RFC」等需求。Review 强制检查现有机制复用、范围边界、对象归属、字段消费者、运行时 感知入口、事实依据、异常分支、接口契约和全文一致性；发现无消费者的新对象、重复事实源、错误 注入层或未验证关键假设时，先修正方案再写入。正文遵循结论优先、概念首次解释、职责分角色、 按关系语义选择拓扑图、时序图、漏斗图、决策流程图或泳道图，并逐张回读线上画板。若已有划词 评论且要求逐条修改并保住锚点，改用 gh-lark-comment-doc-editing skill。 |
飞书技术文档 · 写作
从零写或大改一篇技术侧飞书文档（技术方案 / PRD / 设计文档 / RFC）。目标：产出给决策/评审
看的文档——结论清楚、能扫读、没读过源码的 reviewer 也能看懂。
何时用这个 skill
- 用户要新写一篇技术飞书文档：「帮我写一篇 XX 技术方案」「起草一份 PRD 到飞书」。
- 用户要整篇大改/重组一篇技术文档的正文结构与表达。
不适用：
- 文档已带他人划词评论、要求「按评论逐条改 / 回应 reviewer / 别把评论搞丢」→ 改用
gh-lark-comment-doc-editing skill（那边多一层保锚点 + 回评论的强约束）。
- 非技术评审类的纯撰写、非飞书文档 → 直接用 lark-doc。
核心心法（落笔即照它组织，别写完再返工）
- 先审方案，再写正文：先确认对象、职责、消费者、事实源和运行时链路，不把未经审查的讨论稿
直接组织成正式方案。
- 结论优先：每段第一句就给本方案需要的结论；实现细节能砍就砍。
- 一块一事：一个
<p>/<li> 只讲一件事；多类并列信息拆成带标号或小标题的条目。
- 按角色拆分工：多模块/多端各自负责什么，按角色拆成列表（一角色一条），别串成长句。
- 新概念先交代来源：首次出现内部专有名词 / 机制 / 函数 / 配置项，紧跟一句话括注说明。
- 按语义选图：先判断要表达的是拓扑、交互时序、准入收敛、条件分支还是跨角色流程，再选择
对应图形；多张图不得为了统一风格而套用同一模板。
- 别用问答体：已确认的结论直接陈述，不要保留「问题？→ 答案」的形式。
- 方案对比用紧凑模板：先列候选方案和核心差异，再用只含「方案说明 / 优点 / 缺点」的
三列表格完成选型；优缺点在单元格内使用无序列表。
- 按人的理解过程组织：章节沿着读者理解和系统执行的先后顺序展开；流程优先用图，并列信息
优先用列表，不按模块名堆成彼此割裂的说明书。
展开见下面「可读性原则」。
强制工作流
1. 还原现状与范围
先读取用户提供的 PRD、参考文档、代码和现有配置。对声称“沿用现状”的内容查到真实实现；不要把
本可在现有链路内完成的需求扩成新 Registry、新服务、新协议或新管理后台。
2. 写入前 Review
完整读取并执行
references/technical-review-checklist.md。
对每个新增对象、模块、配置项和协议字段，在内部完成以下审计：
对象 → 负责人 → 消费者 → 事实源 → 生效时机 → 现有机制 → 新增必要性
任一项说不清时，先继续查代码、文档或上游契约。无法从现有材料确认且会改变方案方向时，向用户
澄清；不要用看似合理的默认值补齐。无消费者、重复事实源、放错层或超出范围的设计直接删除。
3. 撰写与落地
按 Review 后的最终设计写正文。接口或数据流是方案核心时，给出足以评审字段消费关系的结构定义或
伪代码；不要只写抽象动作，也不要堆与本次决策无关的源码行号和实现过程。
4. 写入后 Review
重新获取最终文档并再次执行 Review 清单，重点做反例扫描和全文一致性检查。发现问题直接修正文档，
直到没有阻断项。Review 是内部质量门禁，除非用户要求，不在正文新增“Review 过程”章节。
落地手法（用 lark-doc 的 docs 子命令）
新建文档：
bash <lark-doc>/scripts/lark-cli.sh docs +create \
--title '<文档标题>' --content @/abs/path/body.xml --doc-format xml
@ 后用绝对路径（lark-cli wrapper 会 cd 到 SKILL_ROOT，相对路径 FileNotFoundError）。- 正文用 XML 组织：
<h1>/<h2> 章节标题、<p> 段落、<li> 列表项、<b> 小标题、
<code> 行内代码和 <whiteboard> 画板块。
- 章节编号（一、二、三 / §3.1）一次定稿；后续增删内容不要重排编号。
- 大改已存在的文档：先
docs +fetch --api-version v2 --doc-format xml --detail with-ids
拿到 block id，再用 docs +update / +update-batch 的 block_replace 等命令改。
画板工作流
技术文档包含关系、流程、时序或门禁信息时，必须完整读取并执行
references/diagram-workflow.md。核心门槛：
- 先列出每张图要回答的问题，再独立选型；禁止一个视觉模板到处套。
- 使用
lark-whiteboard / lark-whiteboard-cli 生成飞书原生可编辑节点；PNG/JPG 只用于预览
验收，不作为文档最终图形。
- 写回后逐张线上回读，检查空白画板、图层遮挡、文字裁切、连线穿模和画布比例；未回读不得宣称
完成。
- 用户要求“先看一个”时，只更新一张样例，确认后再批量处理。
写完必须回读最终文档，同时执行技术 Review、可读性自检和画板验收，不能只检查正文排版。
可读性原则（唯一权威副本）
技术文档的核心写作规范，详见 references/readability-principles.md。
落笔时照它组织正文，写完对照上面 9 条心法自检。
这份规范是唯一权威副本（single source of truth），姊妹 skill gh-lark-comment-doc-editing
也引用同一份文件。要改原则，只改 references/readability-principles.md 这一处，
不要在本 SKILL.md 里另抄。
技术 Review 清单
方案正确性门禁详见
references/technical-review-checklist.md。每次新写或
整篇大改技术方案都必须完整读取并执行；它负责检查“方案是否成立”，可读性原则负责检查“正文是否
好读”，两者都通过后才能交付。
依赖
- lark-doc skill（同一环境内），提供
docs +create（建文档）、+fetch（拉正文/block id）、
+update / +update-batch（改正文）。本 skill 只是这套命令之上的方法论编排。
- lark-whiteboard 与 lark-whiteboard-cli skills：创建、更新和回读飞书原生画板；格式路由、
dry-run、覆盖确认和渲染规则以这两个 skill 为准。
- 姊妹 skill gh-lark-comment-doc-editing：文档已带划词评论、要按评论逐条就地改并保锚点时用它，
与本 skill 共用
references/readability-principles.md。
