Chinese Tech Writing

SKILL.md

---
name: chinese-tech-writing
description: >
  中文技术文档写作规范助手。当用户需要撰写、审校、润色或重写中文技术文档（包括
  README、API 文档、产品手册、博客、教程、changelog、UI 文案等）时触发。触发关键词包括：
  "中文文档"、"技术写作"、"文档规范"、"文档审校"、"润色文档"、"rewrite"（针对中文内容）、
  "帮我写文档"、"文案规范"、"排版规范"、"文档检查"、"UI 文案"、"按钮文案"、"错误提示"。
---

# 中文技术文档写作规范 Skill

> **规范来源**：阮一峰《中文技术文档写作规范》（Public Domain）+ 扩展规范
> **适用范围**：技术 README、API 文档、产品手册、博客、教程、Changelog、界面文案等所有中文技术写作场景。

---

## 工作模式

本 Skill 支持两种工作模式，根据用户意图自动判断：

| 模式 | 触发条件 | 行为 |
|------|----------|------|
| **Review（审校）** | 用户提供已有文档，要求检查/审阅/找问题 | 逐项列出违规点，给出修改建议，不直接改写全文 |
| **Rewrite（重写/润色）** | 用户要求改写、润色、优化或生成新文档 | 直接输出符合规范的完整文档 |

---

## 规范速查（核心规则）

以下为最高频违规项，处理任何文档前必须检查：

### 1. 字间距（最易忽略）
- 中文与英文之间加半角空格：`快速启动 Windows 系统` ✓
- 中文与数字之间加半角空格（风格需统一）：`购买了 5 台` ✓
- 英文/数字与全角标点之间**不**留空格：`MacBook Air。` ✓

### 2. 句子长度
- 单句 ≤ 20 字为佳，≤ 29 字可接受，≤ 39 字需语义明确，> 40 字不可接受
- 整段逗号分隔的长句总长 ≤ 100 字

### 3. 写作风格
- 使用主动语态，避免被动语态
- 使用肯定句，避免双重否定
- 不使用感叹号（`！`），不连用感叹号
- 不使用非正式/网络语言

### 4. 人称与语气
- "你"与"您"全文只能用一种，不得混用
- 不使用"我们"代指系统或产品
- 操作步骤使用直接命令句（动词开头）

### 5. 标点符号
- 中文语境全程使用**全角**标点
- 并列词用顿号（`、`），不用逗号
- 省略号用 `⋯⋯`（六点），不用 `...` 或 `。。。`
- 引号使用 `" "` 和 `' '`，不用直引号

### 6. 数值
- 阿拉伯数字使用半角形式
- 千位以上加千分号：`1,258,000`
- 数值范围用 `～` 或 `—`：`132 kg～234 kg`

### 7. 标题层级
- 最多四级标题，谨慎使用四级
- 同级标题不能只有一个（避免孤立编号）
- 下级标题不重复上级名称

### 8. 术语一致性
- 品牌名大小写必须准确：GitHub、JavaScript、Node.js、VS Code
- 同一概念全文只使用一种称呼
- 英文缩写首次出现给出中文全称

### 9. Markdown 格式
- 代码块必须标注语言类型（````bash`、````json` 等）
- 步骤用有序列表，并列项用无序列表
- 链接文本具有描述性，不用"点击这里"

---

## 完整规范参考

详细规则分布在以下 reference 文件中，按需查阅：

| 文件 | 内容 |
|------|------|
| [`references/title.md`](references/title.md) | 标题层级与原则 |
| [`references/text.md`](references/text.md) | 字间距、句子、写作风格、人称语气、英文处理 |
| [`references/paragraph.md`](references/paragraph.md) | 段落结构与引用规范 |
| [`references/number.md`](references/number.md) | 数值、货币、数值范围表示法 |
| [`references/marks.md`](references/marks.md) | 标点符号（句号/逗号/顿号/引号/括号/省略号等） |
| [`references/structure.md`](references/structure.md) | 文档体系结构与文件命名 |
| [`references/markdown.md`](references/markdown.md) | Markdown 格式规范（代码块/列表/链接/强调/表格） |
| [`references/terminology.md`](references/terminology.md) | 术语一致性、品牌名大小写、缩写展开 |
| [`references/ui-copy.md`](references/ui-copy.md) | 界面文案（按钮/提示/空状态/错误信息/表单） |
| [`references/changelog.md`](references/changelog.md) | 版本变更日志（Changelog）写法 |
| [`references/checklist.md`](references/checklist.md) | 场景化审校 Checklist（UI文案/README/完整手册三版） |

---

## 场景识别与 Checklist 选择

| 文档类型 | 使用 Checklist 版本 |
|----------|-------------------|
| UI 文案（按钮、Toast、错误提示等，< 50 字） | 精简版（8 条） |
| README、教程、API 文档（< 2000 字） | 标准版（25 条） |
| 完整产品手册、长篇技术文档（> 2000 字） | 完整版（45+ 条） |

---

## 输出格式规范

### Review 模式输出格式

```
## 文档审校报告

### 问题汇总（共 N 项）

| # | 位置 | 原文 | 问题 | 严重程度 | 建议修改 |
|---|------|------|------|----------|----------|
| 1 | 第2段第1句 | ...原文... | 中英文间缺少空格 | 🔴 | ...修改后... |
| 2 | 标题 H3 | ... | 孤立编号标题 | 🟡 | 合并至上级或改用列表 |

### 严重程度说明
- 🔴 必须修改：违反核心规范，影响阅读
- 🟡 建议修改：不符合最佳实践
- 🟢 可选优化：风格建议
```

### Rewrite 模式输出格式

直接输出润色后的完整文档，在文末附简短说明：

```
---
**改动说明**（仅列主要变化）：
- 修正了 X 处中英文间距
- 将被动语态改为主动语态
- 调整了标题层级结构
```

---

## Few-shot 示例

详见：
- [`examples/review.md`](examples/review.md) — Review 模式完整示例
- [`examples/rewrite.md`](examples/rewrite.md) — Rewrite 模式完整示例

---

## 执行流程

```
1. 判断文档类型（UI文案 / 普通文档 / 长篇手册）
2. 判断模式（Review / Rewrite）
3. 根据文档类型读取 references/checklist.md 对应场景版本
4. 按规范逐项检查或重写文档
5. 按上述输出格式返回结果
6. 若文档超过 500 字，分段处理并在末尾汇总
```