gh-lark-tech-doc-writing

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。

核心心法（落笔即照它组织，别写完再返工）

1. 先审方案，再写正文：先确认对象、职责、消费者、事实源和运行时链路，不把未经审查的讨论稿 直接组织成正式方案。
2. 结论优先：每段第一句就给本方案需要的结论；实现细节能砍就砍。
3. 一块一事：一个 <p>/<li> 只讲一件事；多类并列信息拆成带标号或小标题的条目。
4. 按角色拆分工：多模块/多端各自负责什么，按角色拆成列表（一角色一条），别串成长句。
5. 新概念先交代来源：首次出现内部专有名词 / 机制 / 函数 / 配置项，紧跟一句话括注说明。
6. 按语义选图：先判断要表达的是拓扑、交互时序、准入收敛、条件分支还是跨角色流程，再选择 对应图形；多张图不得为了统一风格而套用同一模板。
7. 别用问答体：已确认的结论直接陈述，不要保留「问题？→ 答案」的形式。
8. 方案对比用紧凑模板：先列候选方案和核心差异，再用只含「方案说明 / 优点 / 缺点」的 三列表格完成选型；优缺点在单元格内使用无序列表。
9. 按人的理解过程组织：章节沿着读者理解和系统执行的先后顺序展开；流程优先用图，并列信息 优先用列表，不按模块名堆成彼此割裂的说明书。

展开见下面「可读性原则」。

强制工作流

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。核心门槛：

1. 先列出每张图要回答的问题，再独立选型；禁止一个视觉模板到处套。
2. 使用 lark-whiteboard / lark-whiteboard-cli 生成飞书原生可编辑节点；PNG/JPG 只用于预览 验收，不作为文档最终图形。
3. 写回后逐张线上回读，检查空白画板、图层遮挡、文字裁切、连线穿模和画布比例；未回读不得宣称 完成。
4. 用户要求“先看一个”时，只更新一张样例，确认后再批量处理。

写完必须回读最终文档，同时执行技术 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。