---
name: technical-writing
description: 在起草或重构中文技术设计文档、架构笔记、源码分析、评审稿或工程分享文章时使用；先用代码、指标和约束建立论证，再按文档类型加载对应规则。只需润色短文本或调整语气时使用 style-aware-editor。
---

# 中文技术写作

把背景、观察、判断、影响和验证讲清楚，让技术同伴能复核结论并继续工作。不要用流畅措辞掩盖证据缺口，也不要把技术文档写成营销稿。

## 选择模式

先确定交付物，只读取对应参考：

| 交付物 | 参考 |
| --- | --- |
| 设计文档、架构评审、技术决策说明 | [references/design-document.md](references/design-document.md) |
| 源码深挖、调用链、语言或系统机制文章 | [references/source-analysis.md](references/source-analysis.md) |
| 操作手册、API 流程、故障处理、安全说明 | [references/controlled-instructions.md](references/controlled-instructions.md) |
| Hugo 或工程博客文章 | [references/hugo-article.md](references/hugo-article.md) |

短技术说明、评审摘要或架构笔记可直接使用下面的共同流程。只需处理 AI 味、术语或语气而不调整论证结构时，交给 `style-aware-editor`。

规划整套产品手册或文档站时，按读者任务组织入门、配置、接口参考和故障处理；只建立实际需要的栏目，并沿用目标仓库的文件命名约定。

## 共同流程

1. 明确读者、文档类型、要推动的判断和文档覆盖范围。
2. 收集可引用的代码路径、版本、指标、issue/PR、实验和约束。缺失事实能从当前仓库或官方资料确认时先验证，不用想象补齐。
3. 按以下证据链组织内容：

   `观察 / 代码 / 指标 -> 归纳 -> 判断 -> 实现影响 -> 可观测性 / 验证`

4. 先列章节职责，再写正文。每节只承担一个主要问题，删除不能推进事实、论证或操作的段落。
5. 复核数字、日期、版本、状态、链接、术语和确定性。区分源码事实、外部来源、基于证据的推论和个人建议。
6. 最后检查影响面、失败路径、验证方式和未决问题是否缺位。

## 共同写作规则

- 先证据，后判断；证据不足时降低确定性，不反向寻找理由支持预设结论。
- 不新增来源没有提供的日期、数字、SLA、能力或成功结果；保留条件、单位、默认值、兼容性和失败行为。
- 同一对象、状态和动作使用同一首选术语，不为避免重复而轮换技术同义词。
- 一句尽量只表达一个意思；拆开长定语，优先使用肯定句、主动语态和直接动词，避免双重否定。代词指向不清时，重复对象名称；检查“的、地、得”是否用对。
- 每段先说重点；标题不跳级，不为单个子项增加一层标题，也不重复上级标题，末尾不加句号、逗号或冒号。列表只放真正并列的内容，少用加粗。
- 用具体对象、条件、约束和关系替代“赋能、生态、闭环、打通、落地、沉淀”等抽象词。
- 删掉开场和结尾套话、设问自答、硬凑的三项并列及宣传腔形容词；遇到“不仅……而且……”“不是 A，而是 B”等套式，直接写实际关系和结论。
- 默认只写目标、适用范围和会改变判断的约束。不要为了结构对称增加“非目标”“不做什么”或“范围外”章节；确有必要的排除项应写进对应方案、兼容性、安全或验收段落，并说明具体影响。
- 代码、命令、路径、字段、枚举值、配置项和响应原文保持不变。
- 图表只用于复杂控制流、状态变化或三个以上组件关系；图后补充文字解释和证据边界。
- Hugo 元数据、标签和目录规则属于目标仓库约定，优先读取仓库指令和相邻文章，不写死到全局技能。

## 中文排版与数值

- 中文正文的中英文、中文与数字之间留一个半角空格；数字与英文单位之间留空格，百分号和角度符号紧跟数字。中文句子用全角标点，完整英文句子用半角标点；全角标点前后不额外加空格。产品名保持官方写法，项目既有风格优先。
- 数字用半角字符。正文中五位及以上的数量可用千分位分隔；版本号、日期、地址、标识符和代码保持原样。数值范围两端都写单位或百分号，避免让读者猜测单位。
- 区分“增加了”和“增加到”、“降低了”和“降低到”；描述下降时用差值或百分比，避免“降低几倍”的歧义。
- 中文并列词用顿号，必要时用“和”连接最后一项；不要重复堆叠感叹号、问号。中文补充说明用全角括号，引用符号沿用目标仓库风格；中文省略号写作“……”，不与“等”连用。
- 首次使用读者可能不熟悉的缩写时解释全称；专有名词遵循官方大小写，不自造缩写。外部文字、图片和数据注明出处。
- 排版检查只处理正文，保留 Markdown 代码块、行内代码、链接地址、图片地址和公式原样；自动修正后复核差异。

## 输出契约

根据交付物和读者组织内容，不固定套用章节。成稿满足：

1. 读者能从必要上下文理解文档要解决的问题；短说明不重复铺陈目标和范围。
2. 每个关键判断都有前文证据、来源或明确前提。
3. 事实、推论、建议和未验证项可以区分。
4. 影响面、失败路径和验证方式只在与主题相关且会改变读者判断时展开。
5. 不为完整感虚构备选、指标、负责人或已完成验证。

用户要求编辑文件时，复读修改后的完整文档并执行目标仓库适用的格式或构建检查；只要求草稿或审查时，不擅自落盘。

若已有 `autocorrect`，可先用只读检查定位排版问题；仅在用户授权编辑文件时修正，并复核差异。不为排版检查自动安装工具或生成额外报告文件。

本技能的受控技术说明规则基于 [Tech-Doc-Style-Chinese](https://github.com/Fenng/Tech-Doc-Style-Chinese) 提交 `a6f5b6064b92cac113e1277e5fbd266042e20577` 重新整理。上游内容由 Copyright (c) 2026 Fenng 按 MIT License 授权；本技能不声称输出符合 ASD-STE100。