Doc Style

Doc Style

0x01 定位

doc-style 负责 Markdown / MDC 文档的结构设计、表达压缩与交付前润色。

适用范围：

• 文件范围：所有 .md / .mdc 文档编辑、重构、润色与验收。
• 其他文档类型：规则文档、普通说明文档。
• 短交付：PR review 评论、GitHub 评论、零散草稿的结构化压缩。

职责边界：

• 只处理文档内容、结构和表达。
• 不负责外部资产定位、元数据治理或发布流程。

0x02 通用必读

【CRITICAL（必须执行，不可协商）】无论文档类型是什么，都必须先读 references/common/ 下全部 5 个文件：

• Title
• Text
• Paragraph
• Number
• Marks

0x03 第一性原理

文档的价值是让读者准确复原事实、决策、关系和边界。不能改变读者理解或行动的信息不应保留。

1. 信息必须有增量：每句话至少补充事实、结论、原因、边界、例外或动作中的一项。
2. 关系优先交给结构：表格、图、协议示例和核心伪代码负责表达字段、映射、层级、流程和协作关系。
3. 文字只补结构的语义缺口：说明结构无法直接表达的原因、约束、兼容策略、异常语义和决策后果。
4. 职责必须可定位：句子应能识别谁在什么条件下对什么对象执行什么动作，不把多个角色或层级的职责写在一起。
5. 稳定文档使用现在时：正文描述当前事实和目标契约。历史过程只在影响决策、兼容性或迁移方式时保留。

结构已经表达某项信息时，删除复述性文字。不要用一段话解释读者可以直接从类图、字段表或伪代码中读出的内容。

0x04 写作流程

1. 判定目标：明确目标读者、交付形态和读者需要拿到的结论。
2. 读取规范：完整阅读 common/ 全部 5 个文件。
3. 拆分信息：列出事实、决策、关系、边界和动作，删除没有信息增量的内容。
4. 选择载体：先用结构承载关系，再为结构无法表达的信息补充文字。
5. 完成初稿：句子使用明确主语，不混写职责，不把过程状态写成稳定规则。
6. 润色与自检：按 0x05 检查并交付修订后的版本。

0x05 润色与自检

a. 润色

1. 读取规范：完整阅读 0x02 提及的全部文档和 Humanizer。
2. 检查载体：确认表格、图、协议示例和伪代码已经承载的关系，删除文字复述，按载体规则组织补充语义。
3. 逐句检查：识别空泛引导、历史语气、模糊主语、职责混写和抽象结论。
4. 重写违例：保留原意和必要上下文，用明确的主体、动作、对象和条件重写。
5. 呈现版本：交付修订后的完整版本，不只列问题清单。

修订后的文本必须满足：

• 大声朗读时听起来自然
• 自然地改变句子结构
• 使用具体主体、动作、对象和条件，不用模糊主张
• 为上下文保持适当的语气
• 适当时使用简单的结构（是/有）
• 结构负责表达关系，文字只补充结构未表达的语义

b. 输出闸门

【CRITICAL（必须执行，不可协商）】审稿自检不能用自动检查替代，低于 90 分时，回到 0x05.a 重新润色。