technical-writing git:20261019.0e15234A

Immutable. This exact content never changes and is served at /api/v1/blob/f620d9e035be12b2.

---
name: technical-writing
description: 在起草或重构中文技术设计文档、架构笔记、源码分析、评审稿或工程分享文章，或检查、改写文本的 AI 味、文风、术语和技术文案时使用；先用代码、指标和约束建立论证，再按文档类型或编辑模式加载对应规则。
---

# 技术写作与文体编辑

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

## 选择模式

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

| 交付物 | 参考 |
| --- | --- |
| 设计文档、架构评审、技术决策说明 | [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 味、按文风润色、检测写作模式、改写技术或界面文案 | [references/style-editing.md](references/style-editing.md) |

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

论文、实验报告或技术文章需要组织实验论证、解释不利结果或处理审稿反馈时，另读 [实验与主张](references/experiments-and-claims.md)。普通操作说明和局部润色不加载此参考。

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

## 共同流程

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。