doc-generator

name	doc-generator
description	将用户提供的项目碎片信息整理为结构化中文 Markdown 文档并落盘到 docs。触发于用户提供零散片段并要求成文时；完成后必须调用 doc-optimizer。

Doc Generator（文档生成器）

用于把用户关于本工程的碎片化、未结构化内容，整理为一份能够准确表达作者意图的文档产出（可以是完整文档，也可以是已有文档中的局部片段）。
生成后必须触发 doc-optimizer 进行二次优化，并将最终文档落入 docs/ 目录。

事实来源优先级（强制）

1. 当前工程项目源代码（第一可信来源）
2. 用户提供的片段与补充说明
3. 现有 docs/ 文档（用于风格与历史背景参考，不可覆盖源码事实）

若用户片段与源码现状不一致，必须先定位并解释差异，再按用户意图写“现状 / 计划 / 已完成”的准确表述，禁止把未落地内容写成已实现事实。

触发时机

• 用户给出零散片段、草稿要点、聊天记录式输入，希望整理成正式文档
• 用户明确要求“按我的文档风格写”
• 用户要求将结果直接产出到 docs/ 目录
• 需要先“从无到有”生成文档，再做格式与可读性优化
• 用户要求只补写/改写某一段、某个章节、某个占位符（局部片段生成）

输入

• 用户提供的碎片化内容（观点、结论、日志、问题、方案、背景）
• 目标文档主题（若未给出，需先归纳一个准确主题）
• 目标文件名（若未指定，基于主题生成 kebab/upper-snake 风格文件名）
• 风格参考范围：docs/ 下已有中文文档（如 BOTTLENECK.md、REFACTOR.md）
• 与片段相关的源码上下文（文件、模块、函数、配置、调用链）
• 若是局部片段生成，必须额外读取并理解“该片段所在文档”的上下文（前后段、章节语气、叙述节奏）

表达约束

• 能一句话说清的内容，不要展开成一段。
• 不要为了“完整”重复同一个意思，不写车轱辘话。
• 不刻意套“背景 / 目标 / 方案 / 收益”等这类固定模板；结构服从内容本身。
• 强调“不要 AI 味”，删掉空话、套话和过度过渡句。

执行步骤

1. 收集并归并碎片信息。

   • 把输入拆成“事实、判断、过程、结论、待确认点”。
   • 对冲突信息先标记，不擅自拍板。

2. 先做源码对齐与事实校验。

   • 以当前工程源码为第一可信来源，定位片段对应的模块、文件、函数、配置和调用关系。
   • 区分“已在代码中实现”“仅在讨论中提出”“计划中但未落地”三种状态。
   • 无源码或用户明确证据支撑的内容，不写为既成事实。

3. 建立最小必要工程上下文。

   • 根据片段与源码中出现的模块、术语、变量、流程补齐背景。
   • 目标读者默认为 0 上下文读者，确保文档可独立阅读。

4. 建立风格优先级（局部片段场景强制）。

   • 若是局部片段生成：先对齐整篇文章风格（叙事视角、语速、段落长度、术语习惯），再对齐作者个人文档风格。
   • 若是整篇生成：优先对齐作者个人文档风格，并保持全文风格一致。

5. 提炼“作者真正想表达的主线”。

   • 明确文档主问题与核心结论。
   • 将所有片段挂接到同一条逻辑链，避免信息堆叠。
   • 生成内容必须重点回答：出于什么而设计、为何如此设计、解决了什么问题（及代价/边界）。

6. 按用户既有风格完成初稿。

   • 参考 docs/ 既有文风：第一人称、复盘视角、技术细节具体。
   • 保留用户原有语气强度，不改写成模板化公文。
   • 不引入用户未表达过的业务立场或技术承诺。
   • 避免只罗列“代码怎么实现”，需优先写清设计动机、设计取舍和问题闭环。
   • 若一句话已经足够准确，就停在一句话，不主动补背景废话。

7. 不确定信息先提问确认（强制）。

   • 当“设计动机/取舍依据/问题定义”缺失或存在多种合理解释时，不得自行脑补。
   • 必须先向用户抛出澄清问题，拿到确认后再写入文档。

8. 落盘到 docs/ 目录。

   • 写入目标文件：docs/<name>.md。
   • 若文件已存在，在不丢失既有有效内容前提下做增量更新或替换。

9. 强制触发 doc-optimizer。

   • 对刚生成的 docs/<name>.md 调用 doc-optimizer。
   • 优化目标：结构可读性、Markdown 规范、混排可读性、上下文充分性。

10. 完成后做一致性回检。

• 检查“生成前意图”与“生成后表达”是否一致。
• 检查关键事实是否遗漏、状态是否前后矛盾。

输出 / 质量门槛

• 输出物：docs/<name>.md（已完成 doc-optimizer 二次优化）
• 必须满足：
  • 源码一致：关于实现现状的描述可在当前工程源码中找到对应依据
  • 意图准确：能清晰表达用户真正想表达的含义
  • 信息完整：碎片中的关键事实与结论不丢失
  • 片段一致：若为局部片段，能无缝融入原文，不破坏整篇文章叙事与语气
  • 风格贴合：读起来与 docs/ 既有文档风格一致
  • 可读性强：0 上下文读者可读懂问题、过程与结论
  • 深度到位：明确回答“为何设计、为何这样设计、解决了什么问题”
  • 结构自然：逻辑顺序来自内容本身，不强套固定模板

禁止事项

• 禁止在信息不足时臆造关键事实
• 禁止脱离当前工程源码上下文直接“脑补实现细节”
• 禁止为了“看起来规范”而篡改用户原始立场
• 禁止忽略冲突片段并直接合并为单一结论
• 禁止仅罗列实现步骤而不解释设计动机与问题闭环
• 禁止在关键动机不确定时跳过澄清，直接下结论写入文档
• 禁止为了凑结构刻意套模板，写出明显的 AI 腔
• 禁止同义反复、空洞总结、机械收束
• 禁止跳过 doc-optimizer 直接交付
• 禁止将输出落到 docs/ 以外目录（除非用户明确要求）

后续纠偏原则

• 用户后续若对文档事实或结论纠偏，以最新说明为准。
• 纠偏采用最小改动原则，仅修改受影响段落并保持整体风格一致。
• 若纠偏影响上下文一致性，需同步更新标题、状态描述与结论段。