doc-style

name	doc-style
description	结构化编写、重构、润色和验收 Markdown / MDC 文档。 只要用户要创建、编辑、润色、改写、评审或整理任何 `.md` / `.mdc` 文件， 或需要整理规则文档、普通说明文档、PR review 评论、GitHub 评论、零散草稿，就应使用这个 skill。

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 重新润色。

维度	评估标准	得分
直接性	是否直接陈述事实、决策或动作，删除“下面介绍”“需要说明”等空泛引导	/8
具体性	是否写清主体、动作、对象、条件和结果，避免“相关处理”“进一步优化”等模糊表达	/8
职责边界	每项职责是否归属明确，同一句或同一列表项是否混入多个角色或层级	/8
结构承载	载体是否匹配信息关系，附属表达是否符合对应的载体规则	/8
时间稳定性	稳定正文是否使用当前事实和目标契约，历史过程是否只保留必要的决策影响	/8
清晰度	是否存在黑话、术语堆叠、被动嵌套、长定语或不明确指代	/8
精炼度	是否删除过程叙述、跨节重述、结构复述和无信息量的衔接句	/8
自然度	句式和节奏是否自然，是否避免机械排比、公式结构和过度解释	/8
文档审美	结构、信息层级、行文节奏、留白和对齐是否支持快速阅读	/8
common 规范	按 0x02 的 5 个 common 文件检查。不满足一点扣 2 分，扣分上限为 28 分	/28