Chinese Tech Writing

中文技术文档写作规范助手。当用户需要撰写、审校、润色或重写中文技术文档（包括 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/text.md	字间距、句子、写作风格、人称语气、英文处理
references/paragraph.md	段落结构与引用规范
references/number.md	数值、货币、数值范围表示法
references/marks.md	标点符号（句号/逗号/顿号/引号/括号/省略号等）
references/structure.md	文档体系结构与文件命名
references/markdown.md	Markdown 格式规范（代码块/列表/链接/强调/表格）
references/terminology.md	术语一致性、品牌名大小写、缩写展开
references/ui-copy.md	界面文案（按钮/提示/空状态/错误信息/表单）
references/changelog.md	版本变更日志（Changelog）写法
references/checklist.md	场景化审校 Checklist（UI文案/README/完整手册三版）

---

场景识别与 Checklist 选择

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

---

输出格式规范

Review 模式输出格式

text

## 文档审校报告

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

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

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

Rewrite 模式输出格式

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

text

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

---

Few-shot 示例

详见：

• examples/review.md — Review 模式完整示例
• examples/rewrite.md — Rewrite 模式完整示例

---

执行流程

text

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