# Chinese Technical Writing

> 为中文技术文档提供受控语言写作、改写和审校。当用户要求起草、重写、简化或审校操作步骤、规范、接口说明、错误消息、架构文档、README、含中文的 Mermaid 图或面向机器处理的中文时使用；也适用于消除歧义、统一术语、检查规范词和步骤可执行性。不用于文学创作、营销文案、技术事实验证或 ASD-STE100 合规认证。

- Skill: `dannyge/chinese-technical-writing` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add dannyge/chinese-technical-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dannyge/chinese-technical-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: dannyge (https://skillmd.com/u/dannyge)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dannyge/chinese-technical-writing

---


# 中文技术写作

借鉴 ASD-STE100 的受控语言思想，为中文技术内容建立可执行的写作约束。目标是让读者准确理解并正确执行，而不是机械缩短文本或把中文改成翻译腔。

## 默认行为

根据用户请求决定操作，不要求用户选择模式：

- 用户要求写作时，根据已知事实和受众起草内容。
- 用户要求改写时，保留原意并提高可执行性；默认只返回可直接使用的成稿。
- 用户要求审校时，定位问题并说明风险；除非用户要求修改，否则不改文件或替用户决定存在歧义的技术含义。

默认使用**通用模式**。遇到操作步骤、安全提示、规则和要求、API 契约、错误消息、工具说明、提示词或机器解析文本时，自动改用**严格模式**。只有用户询问或要求审校依据时才说明模式。

严格模式执行全部结构约束。通用模式保留必要的行文节奏，但仍执行术语、指代、逻辑和语义保持规则。

## 工作流程

1. **读取局部规范。** 处理仓库文件时，先读取适用的 `AGENTS.md`、贡献指南、模板和邻近文档。局部规范优先于默认样式阈值，但不能削弱语义准确性。
2. **确定文本契约。** 明确受众、阅读后的任务，以及文本是规范性、程序性还是说明性内容。只有缺失信息会改变技术含义时才标为待确认。
3. **保护字面量。** 原样保留代码块、命令、路径、URL、标识符、API 名称、配置键、占位符、版本号、数值、单位和界面标签，除非用户明确要求修改。新建或修改含中文的 Mermaid 图时，执行本 Skill 的 Mermaid 兼容规则。
4. **建立语义账本。** 记录主体、动作、对象、条件、范围、时间、例外、否定、数量和要求强度。写作时以用户事实为账本；改写时以原文为账本。
5. **应用规则。** 优先修复会改变执行结果或产生多种解释的问题，再处理可读性。需要完整规则编号和阈值时，读取 [references/chinese-writing-rules.md](references/chinese-writing-rules.md)；需要排版、数字、标题、列表、链接或无障碍约定时，读取 [references/chinese-style-conventions.md](references/chinese-style-conventions.md)；需要文体示例时，读取 [references/examples.md](references/examples.md)。
6. **处理歧义。** 不推测缺失的主体、因果、布尔作用域或参数。无法安全改写时保留相关内容，并使用 `[待确认：具体问题]`。
7. **验证并迭代。** 对长文本或文件运行静态检查器。随后核对语义账本、字面量、Markdown/MDX 结构、链接和项目要求。修复问题后重新检查，直到没有未解释的 hard finding。零发现不表示事实正确或完全无歧义。

## 核心规则

- 一个术语只表示一个概念；一个概念只使用一个首选术语。首次出现的缩略语给出全称，通用或已定义缩略语除外。
- 明确动作主体。程序步骤已明确由读者执行时，可以省略“用户”；系统行为、权限判断和自动化动作必须写明组件或角色。
- 严格模式中，一个步骤只包含一个主要动作。前置条件写在动作之前，结果和验证写在动作之后。
- 代词和指示词必须有唯一、就近的先行词。能写实体名时，不写含糊的“它”“其”“该内容”“相关配置”“上述方式”。
- 保留要求强度：`必须/不得`、`应/不应`、`可以`、`建议`、`可能`不能互换。规范文档需要定义这些词时，以该文档的定义为准。
- 优先使用肯定句和单层否定。遇到“双重否定”“除非……否则不……”或多层例外时，拆成条件和结果。
- 优先使用直接动词，如“配置”“检查”“删除”；避免“进行配置操作”“实现对日志的查看”等空泛结构。
- 句子只表达一个中心关系。严格模式的默认句长上限为 40 个计数单元，通用模式为 60 个；超过阈值先拆分，若拆分会损失精度则保留并说明原因。
- 三项及以上的步骤、条件或并列项使用列表。并列项保持相同语法结构，不在列表项末尾悬置“和”“或”“以及”。
- 错误消息至少说明：发生了什么、影响什么；如果已知恢复动作，再说明如何处理。不要虚构原因或保证恢复成功。
- 安全提示先写危险或适用条件，再写必须执行的动作，最后写不执行的后果。不要把安全条件埋在段落中。
- 用事实、阈值和观察结果替代“高效”“稳定”“灵活”“显著”等无证据评价。

## 中文规范词与 RFC 2119

中文没有 RFC 2119 大写关键词那样的强度标记，“必须”“应”“建议”同时是日常词汇，生成和改写时容易发生强度漂移。因此：

- 中文输出只使用 ZH-04 档位表收录的强度词，不使用“务必”“记得”“千万”等表外词承担要求强度。
- 改写时逐句把原文强度记入语义账本，只做同档替换，不升格也不降格。
- 目标文档声明了关键词约定（RFC 2119、GB/T 1.1 助动词或团队规范）时，改按声明的映射执行。
- 中英混排的规范性文本可以直接使用大写 MUST/SHOULD/MAY 标记强度。

映射表、重映射规则和选词约束见 [references/rfc2119-chinese.md](references/rfc2119-chinese.md)。

## 静态检查器

### 运行要求

- 核心写作和审校规则不依赖 Python。
- 推荐使用 uv 0.11 或更高版本运行可选静态检查器。脚本声明 Python `>=3.11,<4`。
- 检查器仅使用 Python 标准库，不需要安装第三方包。
- 输入文件必须使用 UTF-8 编码。
- 如果没有 uv，可直接使用已安装的兼容 `python3`。如果两者都不可用，跳过静态检查并执行人工审校。不要擅自安装、升级或下载运行时。

默认使用隔离、离线且禁止自动下载 Python 的命令：

```bash
uv run --offline --no-python-downloads scripts/zh-tech-lint.py --mode strict path/to/doc.md
uv run --offline --no-python-downloads scripts/zh-tech-lint.py --mode general --format json path/to/doc.md
```

项目有术语表时，可提供 TSV 文件：第一列为首选术语，第二列为用英文逗号分隔的禁用别名。

```text
用户	客户,使用者
删除	移除,清除
```

```bash
uv run --offline --no-python-downloads scripts/zh-tech-lint.py --terms terms.tsv path/to/doc.md
```

回退命令：

```bash
python3 scripts/zh-tech-lint.py --mode strict path/to/doc.md
```

不要使用 `uvx` 或 `pipx` 运行当前脚本；它们适合已打包并提供命令入口的 Python 工具。检查器会跳过围栏代码块，并尽量忽略行内代码、URL 和 Markdown 链接目标。它不能判断事实、唯一指代、因果关系或要求强度是否在改写中保持不变。

## 输出约定

- **写作或改写**：默认只给可直接使用的成稿。只有存在无法消解的技术歧义时，附最少量待确认项。
- **审校**：使用下表，按风险排序。位置应精确到文件和行号，或原文片段；不把纯风格偏好写成缺陷。
- **用户要求对照**：给出原文、改写、规则编号和语义保持说明。
- **编辑仓库文件**：完成修改后报告改动范围和验证结果；遵守仓库自身的提交和构建要求。

```markdown
| 优先级 | 位置 | 规则 | 问题与风险 | 建议 |
|---|---|---|---|---|
| P1 | 文件或原文位置 | ZH-xx | 可验证的问题及后果 | 最小修改建议 |
```

## 关键陷阱

- 不要为了缩短句子删除条件、例外、数值、否定、范围或不确定性。
- 不要把“可能”改成事实，不要把“建议”升级为“必须”，也不要反向弱化要求。
- 不要用表外词（如“务必”“记得”）承担要求强度。文档声明了关键词体系时，按声明词表执行。
- 程序步骤已明确由读者执行时，省略“用户”不一定构成主体缺失；系统行为仍须写明组件。
- 不要把静态检查结果当成语义证明、事实验证或合规证书。
- 不要为了让错误消息显得完整而虚构原因、恢复动作或成功保证。
- 不要机械套用空格、括号或标点偏好。项目格式规范优先；没有项目规范时，才使用本 Skill 的默认中文排版约定。
- 不要把中文展示文本直接作为 Mermaid 内部 ID，也不要为了显示中文而把中文写入样式选择器。

## 边界

- 本 skill 借鉴 ASD-STE100 的“受控词汇、单一含义、简单结构和一致术语”等方法，但规则是为中文技术写作重新设计的。不得声称输出“符合 ASD-STE100”。
- 语言清晰不等于技术正确。涉及库、框架、协议、产品或云服务的事实时，应另行对照当前权威文档。
- 不复制 ASD-STE100 的受控词典或受版权保护的规则正文。需要认证或行业合规时，使用官方标准并由合格人员复核。
- 清晰优先于短。规则之间冲突时，先保留技术含义，再说明未采用某项样式建议的原因。

## 按需资源

- 需要完整规则、严重级别和阈值说明时，读取 [references/chinese-writing-rules.md](references/chinese-writing-rules.md)。
- 需要处理数字、单位、标点、空格、标题、列表、链接、表格或图片时，读取 [references/chinese-style-conventions.md](references/chinese-style-conventions.md)。
- 需要新建、改写或审校含中文的 Mermaid 图时，读取 [references/mermaid-chinese.md](references/mermaid-chinese.md)。
- 需要处理中文规范词与 RFC 2119、GB/T 1.1 助动词的对应，或审校声明了关键词体系的文档时，读取 [references/rfc2119-chinese.md](references/rfc2119-chinese.md)。
- 需要查看常见中文技术文档的改写方式时，读取 [references/examples.md](references/examples.md)。