| name | chinese-tech-writing |
| description | 中文技术文档写作规范。当用户需要撰写、审阅或改进中文技术文档、博客文章、README、产品说明、API 文档或任何中文技术内容时使用此 skill。涵盖中英文混排、标点符号、数值格式、段落结构、标题层级和文档体系。不适用于营销文案、小说、诗歌等非技术性中文写作。 |
| license | MIT |
| metadata | {"version":"1.1.0","source":"https://github.com/fwqaaq/chinese-tech-writing","authors":"fwqaaq","language":"zh-CN"} |
| allowed-tools | ["Read","Write","Edit"] |
本 skill 指导创作符合中文技术文档规范的内容，基于业界公认的中文技术写作标准（参考 GB/T 15834《标点符号用法》及中文文案排版指北）。
适用场景：用户提供需要撰写或审阅的中文技术内容，包括文档、博客、README、产品说明、API 参考等。
写作前的判断
撰写或审阅前，先明确：
- 内容类型：教程、参考文档、概念说明、操作指南？
- 目标读者：开发者、运维、普通用户？
- 中英文混排情况：是否有大量英文术语、代码、命令？
一、标题规范
标题分为四级，使用 Markdown #、##、###、#### 表示。
层级原则
（1）一级标题下不能直接出现三级标题，必须有二级标题过渡。
# 错误示例
### 三级标题
# 正确示例
## 二级标题
### 三级标题
（2）同级标题不能只有一个（孤立编号），应合并到上级或省略该层级。
# 错误示例
## 二级标题 A
### 三级标题 A ← 孤立，唯一的三级标题
## 二级标题 B
# 正确示例
## 二级标题 A ← 直接在此处展开内容，省略孤立的三级标题
## 二级标题 B
（3）下级标题不能与上级标题同名。
# 错误示例
## 概述
### 概述 ← 与上级标题重名
# 正确示例
## 概述
### 背景 ← 使用不同名称
（4）谨慎使用四级标题；三级标题下的并列内容，优先用列表代替四级标题。
# 结构一（不推荐，仅适合篇幅较长的内容）
### 三级标题
#### 四级标题 A
#### 四级标题 B
#### 四级标题 C
# 结构二（推荐）
### 三级标题
**（1）A**
**（2）B**
**（3）C**
二、文本与字间距
中英文混排空格规则
- 全角中文字符与半角英文字符之间加一个半角空格
- 全角中文字符与半角数字之间可加可不加空格，但全文必须统一风格
- 数字与单位之间保留一个半角空格（百分号
% 例外，紧贴数字）
- 半角英文/数字与全角标点之间不加空格
错误：本文介绍如何快速启动Windows系统。
正确：本文介绍如何快速启动 Windows 系统。
错误：他的电脑是 MacBook Air 。
正确：他的电脑是 MacBook Air。
正确：今年我国经济增长率是 6.5%。
正确：今年我国经济增长率是6.5%。（两种均可，全文风格须统一）
正确：1 h = 60 min = 3600 s
正确：一部容量为 16 GB 的智能手机
句子长度控制
- 单句（不含标点）一般控制在 20 字以内；20
29 字可接受；3039 字需语义绝对清晰；超过 40 字应拆分
- 一句话内逗号分隔的总长度不超过 100 字或正文 3 行
- 优先使用简单句和并列句，避免嵌套复杂的复合句
错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。
正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。
错误（含定语从句的复合句）：那个昨天生病的人没有参加会议。
正确（并列句）：他昨天生病了，没有参加会议。
写作风格
优先主动语态（中文不必模仿英文被动语态）
错误：假如此软件尚未被安装，
正确：假如尚未安装这个软件，
注：受事更重要或施事不明时，被动语态是合理的（例如「该漏洞已在 v2.3 中修复」），并非一律禁用。
优先肯定句
错误：请确认没有接通装置的电源。
正确：请确认装置的电源已关闭。
避免双重否定
错误：没有删除权限的用户，不能删除此文件。
正确：用户必须拥有删除权限，才能删除此文件。
不使用非正式语言
错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！
正确：无法参加本次活动，我深感遗憾。
不使用生造的文言式表达
错误：这是唯二的快速启动的方法。
正确：这是仅有的两种快速启动的方法。
「的/地/得」用法
她露出了开心的笑容。 → 形容词＋的＋名词
她开心地笑了。 → 副词＋地＋动词
她笑得很开心。 → 动词＋得＋补语
代词指代必须明确
错误：从管理系统可以监视中继系统和受其直接控制的分配系统。
（「其」可能指管理系统，也可能指中继系统，含义不清）
正确：从管理系统可以监视两个系统：中继系统，以及受中继系统直接控制的分配系统。
名词前的形容词修饰不超过两层
错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。
正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。
英文词汇处理
英文缩写首次出现时，括号内给出英文全称和中文译名；后文直接使用缩写
IOC（International Olympic Committee，国际奥林匹克委员会）成立于 1894 年。此后,IOC 总部设在瑞士洛桑。
英文缩写翻译为中文时，复数形式还原为单数
英文：...information stored in random access memories (RAMs)...
中文：……存储在随机存取存储器（RAM）中的信息……
中文正文中的英文省略号改写为中文省略号
英文：5 minutes later...
中文：5 分钟过去了……
英文书名/电影名/文章名翻译为中文时，双引号改为书名号
英文：He published an article entitled "The Future of the Aviation".
中文：他发表了一篇名为《航空业的未来》的文章。
英文专有名词每个实词首字母大写；非专有名词不大写
专有名词：American Association of Physicists in Medicine（美国医学物理学家协会）
非专有名词：online transaction processing（在线事务处理）
三、段落规范
- 每段只有一个主题；中心句放段首，后续句子为中心句服务
- 段落不超过七行，最佳四行以内
- 段落之间用一个空行隔开
- 段落开头不留空白字符（即不缩进，Markdown 习惯）
引用规范
引用第三方内容时，注明作者和出处：
One man's constant is another man's variable. —— Alan Perlis
全文转载时，在开头显著位置注明作者和出处，并链接至原文：
本文转载自 WikiQuote（链接）
使用外部图片时，在图片下方或文末标明来源：
本文部分图片来自 Wikipedia
四、数值规范
半角数字
阿拉伯数字一律使用半角形式，不得使用全角。
错误：这件商品的价格是１０００元。
正确：这件商品的价格是 1000 元。
千分号
千分号即半角逗号。四位数可加可不加（建议不加，例如年份 2025）；五位及以上必须添加。
4 位（可选）：1000 元 / 1,000 元
5 位以上（必须）：125,800 元、1,258,000 元
注：年份、编号、电话号码、版本号等不视为数值，不加千分号。
货币
技术文档正文中，优先使用「数字 + 中文货币名」的写法，可读性更好；表格、价目列示、代码示例中可使用货币符号紧贴数字的写法。
正文：用户每月需支付 1,000 美元的订阅费用。
表格/列示：$1,000 / ￥6,800 / €920
数值范围
数值范围使用波浪线 ~（半角波浪号，技术文档常用）或一字线 —（占一个全角字符）连接。前后必须保持单位一致：
132 kg~234 kg
67%~89%
2009 年~2011 年
增减表达
「了」表示增量，「到」表示定量。
增加到过去的两倍 → 过去为一，现在为二
增加了两倍 → 过去为一，现在为三
降低到百分之八十 → 定额是一百，现在是八十
降低了百分之八十 → 原来是一百，现在是二十
不要使用「降低 N 倍」或「减少 N 倍」，改用「降低百分之几」。因为「减少一倍」逻辑上意味着数值变为零，超过一倍则成为负数，不合常理。
五、标点符号规范
基本原则
- 中文语句全部使用全角标点
- 整句为英文（包括纯英文的并列项）时使用半角标点
- 句号、问号、叹号、逗号、顿号、分号、冒号不得出现在行首
- 句号等点号不得出现在标题末尾（标号如引号、括号、问号可以）
句号
中文语句结尾用全角句号（。）。括号注释时，句号在括号外：
错误：关于文件的输出，请参照第 1.3 节（见第 26 页。）
正确：关于文件的输出，请参照第 1.3 节（见第 26 页）。
逗号
逗号（，）表示句子内部的一般性停顿。避免「一逗到底」——整段除结尾外全部用逗号，应适当改用句号、分号或拆分为多句。
顿号
中文句子内部的并列词（含夹杂的英文词）用全角顿号（、）分隔，不用逗号：
错误：我最欣赏的科技公司有 Google, Facebook, 腾讯, 阿里和百度等。
正确：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。
最后一项用「和」连接，比只用顿号更连贯：
可以：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里，以及百度等。
更优：我最欣赏的科技公司有 Google、Facebook、腾讯、阿里和百度等。
整句为英文时，并列词使用半角逗号（参见前述「基本原则」）：
Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.
引号
引用时使用全角双引号（“”），注意前后引号字符不同。引号内再次引用时，外层用双引号，内层用单引号（‘’）：
许多人都认为客户服务的核心是“友好”和“专业”。
鲍勃解释道：“我要放音乐，可萨利说：‘不行！’”
括号
补充说明时使用全角圆括号（（）），括号前后不加空格：
请确认所有的连接（电缆和接插件）均安装牢固。
代码、命令、文件路径、参数说明等技术内容内部使用半角括号，遵循该语言/工具的语法。
冒号
全角冒号（：）引出解释和说明：
请确认以下几项内容：时间、地点、活动名称和来宾数量。
表示时间、比例、版本号等技术含义时使用半角冒号（:）：
早上 8:00
长宽比 16:9
省略号
中文省略号为 ……（U+2026 ×2），占两个汉字空间、包含六个省略点。不得使用 ... 或 。。。。
省略号与「等」、「等等」不重复使用——两者都表示列举未尽，二选一即可：
错误（省略号和「等」重复）：
我们为会餐准备了香蕉、苹果、梨……等各色水果。
正确（仅用省略号）：
我们为会餐准备了香蕉、苹果、梨……
正确（仅用「等」）：
我们为会餐准备了香蕉、苹果、梨等各色水果。
感叹号
技术文档语气应平实，避免感叹号（！）。即便使用，也不得多个连用：
错误：这个功能真是太好用了！！！
正确：此功能易于使用。
破折号
破折号用于进一步解释，占两个汉字位置。推荐写法是两个「破折号」加前后空格，在更多字体下显示稳定：
可以：直觉————尽管它并不总是可靠的————告诉我，这事可能出了些问题。
更优：直觉 —— 尽管它并不总是可靠的 —— 告诉我，这事可能出了些问题。
避免使用四个「破折号」连写（在某些字体中会断开显示）。
连接号
两个名词的复合，或图表编号，使用直线连接号（-，半角）：
氧化-还原反应
图 1-1
数值范围使用波浪连接号（～）或一字号（—），占一个全角字符，注意两端加单位：
2009 年～2011 年
波浪连接号也可以用汉字“至”代替。
例句：周围温度：-20 °C 至 -10 °C
六、文档体系
软件文档推荐结构
| 章节 | 必要性 | 说明 |
|---|
| 简介（Introduction） | 必备 | 产品和文档的总体说明 |
| 快速上手（Getting Started） | 可选 | 最快速使用路径 |
| 入门篇（Basics） | 必备 | 环境准备、安装、配置 |
| 进阶篇（Advanced） | 可选 | 中高级开发教程 |
| API 参考（Reference） | 可选 | API 逐一说明 |
| FAQ | 可选 | 常见问题 |
| 附录（Appendix） | 可选 | 术语表、最佳实践、故障排查、更新日志、反馈 |
参考范例：Redux 手册、Atom 手册
文件命名规范
- 文件名不含空格，只使用半角字符，不使用中文
- 只使用小写字母（README、LICENSE、CHANGELOG 等约定俗成的说明文件除外）
- 多单词用半角连词线（
-）分隔，不用下划线
错误：名词解释.md
正确：glossary.md
错误：TroubleShooting.md
正确：troubleshooting.md
错误：advanced_usage.md
正确：advanced-usage.md
审阅清单
审阅中文技术文档时，逐项检查：
