git:20261018.6377c0f to git:20261018.4f1e812

---

name: document-writing

description: 统一技术文档、调研笔记和仓库交付物的中文表达、证据论证、Markdown 格式与伪代码规范；编写或修改正式文档时使用。

---

# 文档写作规范

编写或修改正式文档、调研笔记和仓库交付物时使用本 skill。保持读者定位、术语、证据确定性和文件格式的一致性。

## 清晰与准确

以下原则参考 ASD-STE100[^asd-ste100]，用于保持表达清晰，不要求或宣称符合该标准的受控英语规范。保留用户要求的语言、格式和语气，不把英文词数限制套到其他语言上。

| 检查项 | 要求 |

| ------------ | -------------------------------------------------------------------------------------------------------------- |

| 名称与指代 | 同一对象使用同一名称，保留准确的界面标签。代词有多个指代对象时直接写出对象，不补造缺失事实。 |

| 条件与顺序 | 条件、例外、否定与所约束的动作写在一起。重排内容时保留前置条件、完成条件、先后顺序及必要条件与充分条件的区别。 |

| 义务与确定性 | 区分许可、建议、要求和能力；保留证据确定性，区分拟议、已开始与已完成的动作。 |

| 简洁与完整 | 简洁不能删去理解答案所需的原因和边界。清楚的原句可以保留，不强求短句或固定格式。 |

## 中文表达

适用于所有中文输出。负面清单检查的是表达动作，换词但保留同一种空泛表达仍须修改；例词在语境中自然且有实际含义时按语义判断。明确禁用的词组遵守禁用规则。

### 措辞

1. 平实中文：中文现代、平实、直接，语法地道；句子完整，一句话只说一件事，避免晦涩复杂的长句。

2. 术语一致：首次出现交代中文名与英文全称或缩写，后文固定称呼。

3. 事实与因果：少用“显然”“不难发现”替读者下判断，直接写事实与因果。

4. 领域用语：使用领域已有术语，不生造专业文献中没有的词，不用夸张搭配、修辞与金句。

5. 正面叙述：避免反复用否定句限定边界，使叙述前后反复；必要的技术条件与否定判断写清楚。

6. 正文与标题：正文回避设问句和只强调文章结构的引导句。标题直接表达主题，不写设问句或仅去掉问词的口水话标题。

7. 禁用词组：禁用“相当具体”。

### AI 味与中文模式负面清单

逐段检查下列问题；同类问题合并检查，具体例子、改写要求和例外分别保留。

| 问题类型 | 禁止的表达动作与例子 | 改写要求或例外 |

| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |

| 局部强结构与三段式 | 死板列举，用形式上的次序伪造递进关系，如用“首先……其次……最后……”串联排比段落。 | 按真实内容关系组织；并列内容用列表，有实际顺序的操作步骤用有序列表。 |

| 逻辑缺口与过渡套话 | 用丝滑过渡句掩盖论据、推导或大结构上的缺口；用“从而”“进而”“基于此”“有鉴于此”充当空泛的段落过渡。 | 补齐论据与推导，交代实际因果；没有因果或递进关系时直接进入下一项内容。 |

| 重复观点与段末收尾 | 一个观点换一种说法反复重申，段落没有增加新信息；用“这说明”“可以看出”“到这里”“由此可见”作为无信息的段末收尾。 | 删除重复表述，直接写有证据的结论，保留新增信息。 |

| 对称套话与翻案腔 | 反复使用“不是……而是……”制造无实际对照的转折；先虚构读者的误解再推翻，如“不是 A 而是 B”“你以为 A 其实 B”“A 不重要，重要的是 B”。 | 直接陈述判断；真实的自我修正、技术对照和适用边界照常写，“不只 A 还 B”的递进可以用。 |

| 模糊立场 | 正话反话一起说，把判断打磨得四平八稳，却不按证据作出取舍。 | 按证据作出判断，说明判断依据；证据不足时明确缺少什么，不用模糊立场掩盖不确定性。 |

| 奇怪比喻与升华 | 使用奇怪的比喻，胡乱抬高抽象层级，或把具体观察拔高成普遍真理，如“这体现了工程师精神”“这就是开源的魅力”。 | 保留具体观察、判断维度与依据，省去无依据的抽象评价。 |

| 生造黑话与通稿腔 | 使用生造黑话、“赋能”“开箱即用”“闭环”“抓手”“打法”“深度对齐”等生硬套话。 | 写具体事实与动作，例如能做什么、省去什么配置、哪些步骤已经跑通。 |

| 作者位置 | 缺少有依据的作者判断，或编造矫揉造作的情绪体验。 | 提供有依据的判断；没有材料支持的情绪体验不写。 |

| 读者漂移 | 同一篇文档在专家预设与零基础科普之间漂移。 | 保持全文的读者定位与解释深度一致。 |

| 提示语引导 | 使用“值得注意的是”“需要指出的是”“有一点很重要”等无信息提示。 | 直接写事实或因果。 |

| 报告与巡检腔 | 使用“本次”“整体而言”“综上所述”“具体来说”“随着……的发展”等套话；给客观状态套“发现 N 个……”“检测到 N 项……”“未发现关联……”等多余动作壳。 | 直接写“N 个失效项”“无关联残留”等状态。 |

## 技术文档写作

### 论断与证据

1. 核实事实：只把核实后的信息写成事实。API 失败、限流和空结果不代表信息不存在，继续查询官方网页、搜索引擎和可用浏览器；查询过程与无关工具错误不进入成品正文。

2. 直接判断：证据充分时敢于表述、敢于评价，不用“可能”“未必”“我觉得”作无依据的自我弱化，不用正反观点并列代替取舍。

3. 不确定性：证据不足时明确区分事实、推断与待验证问题，说明缺少什么证据，保持原有确定性。

4. 判断依据：“更好”“更强”“更自然”等评价必须带比较维度和理由，例如步骤更短、假设更少、准确率更高或图像更直观。

5. 论证支撑：使用例子、反例、小推导与直观解释，不能只给抽象结论，也不能用自然语言替代数学推导。

6. 推导完整：定理、证明和核心推导达到论文级别的完整性。每步写清符号、条件、变形和依据，禁止为压缩篇幅几笔带过。

7. 资料关系：用自然语言说明资料之间的关系、差异与依据，避免堆叠链接。stars、citation 等传播指标不能替代对方法与内容本身的核实。

### 结构

1. 正文与标题：正文优先使用连贯段落，用 `##`、`###` 等标题语法划分层级，不用加粗伪装标题。

2. 分类与并列：分类讨论和并列项用有序列表、无序列表或表格等对应语法，不挤在同一段里。

3. 单段单义：单段只讲一件事。多个点、论断、定义或公式分别展开，避免堆积。

4. 公式布局：定义式、多步等号链和核心恒等式放行间，行内只放短符号；公式规则见“数学与 LaTeX”。

5. 表格边界：表格只承载并列事实和比较，长篇论证使用段落。

6. 格式用途：充分使用引用、伪代码、图片等对应语法，选择能清楚表达内容的形式。

7. 读者一致：默认写给认真自学的同行，全文保持读者定位一致；用户指定读者时据此调整全文。

## 文档格式与文件组织

### Markdown、引用与链接

1. 段落换行：Markdown 段落写在一行内，不手工折行（hard wrap）；换行交给渲染器。表格行、列表项、代码块与 blockquote 按各自结构分行。

2. 外部引用：正式文档的外部来源使用脚注，正文在来源名后紧跟 `[^key]`，键为小写 ASCII 与连字符，如 `[^zhang20]`；同一来源复用同一键，正文行内不放外部来源链接。

3. 参考文献：文末设“### 参考文献”，逐行写 `[^key]: 作者. 标题. 来源 年份. [标题或域名](链接)`。

4. 回复引用：日常回复的引用遵循用户与平台要求。

### 数学与 LaTeX

1. 公式分隔：Markdown 行内公式用 `$`，行间公式用 `$$`；LaTeX 文档使用相应数学环境。

2. 公式解释：解释符号、条件、变形和直觉。定义式、多步等号链与核心恒等式独立展示。

3. 表格公式：使用 `\mid`、`\Vert` 等命令，避免裸 `|` 破坏 Markdown 表格结构。

### 命名与拆分

1. 日期命名：独立研究笔记、报告与成品文档按 `YYYY-MM-DD-<topic>.<扩展名>` 命名，日期取最后更新时间。正文更新后同步改文件名与引用。

2. 主题语言：topic 与正文语言一致；中文文档用中文名，英文文档用小写 ASCII 加连字符。

3. 稳定入口：固定入口、长期维护文档和工具要求的文件名保持稳定；仓库已有命名规范时遵循仓库规范。

4. 文件长度：单文件控制在 1000 行以内，超出按章或节拆分。LaTeX 用 `\input` 组装，分文件放在 `sections/` 等子目录。

5. 成品主文件：新建成品主文件使用有意义的日期与主题名，避免 `main.tex`、`main.md` 等泛名；固定入口和工具要求按前述例外处理。

## 伪代码校验与配套工具

- 提交 Markdown 前运行 `.crossnote/scripts/check-pseudocode.cjs --staged`；解析失败为 error，缺少 `Semantics:`、info 拼写错误和无效值为 warning。

- 手动全库检查运行 `node .crossnote/scripts/check-pseudocode.cjs`。预览、导出和打印由 `parser.js` 预渲染为 `<figure>`；`pseudocode-runtime.js` 只作客户端兜底；pandoc 导出保留原始围栏源码。

- 需要绘图时使用 `figure-viz` skill，或从原始论文取得图片，并在正文中注明来源和处理方式。