# Chinese Document Style

> 中文写作规范，包含基础规则、类型判断、格式修正流程及检查工具。

- Skill: `zjc0230-code/chinese-document-style` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add zjc0230-code/chinese-document-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zjc0230-code/chinese-document-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zjc0230-code (https://skillmd.com/u/zjc0230-code)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zjc0230-code/chinese-document-style

---


# 中文写作基础规范

## 适用范围

编写中文内容时使用本规范。

## 写作类型判断

### 判断流程

**1. 阅读目标**
- 阅读/理解 → 文章风格
- 参考/查阅 → 文档风格
- 运行/调试 → 代码风格

**2. 内容性质**
- 业务/场景/故事 → 文章风格
- 规范/手册/说明 → 文档风格
- 实现/算法/逻辑 → 代码风格

**3. 典型场景**

| 类型 | 典型场景 | 写作风格 | 特征 |
|------|---------|---------|------|
| **代码** | 技术方案、API 说明、算法实现 | 代码+注释 | 大量代码块、分块结构、技术细节 |
| **文档** | 手册、规范、说明文档 | 清晰+结构化 | 分块列表、标题层级、信息密度高 |
| **文章** | 技术介绍、案例分享、业务方案 | 连贯+叙述性 | 完整段落、流畅叙述、业务价值导向 |

### 针对代码模型的提示

使用代码模型写作时注意：
- 先判断类型，再开始写作
- 避免代码化表达（代码块和分块结构）
- 控制代码示例，优先用文字说明
- 关注业务价值（为什么、做什么）
- 段落完整性，避免过度拆分

## 格式修正工作流程

### 1. 快速参考

使用 `references/quick-reference.md` 快速查阅规则。

### 2. 专门规范

根据文档类型查阅专门规范：
- 技术文档 → `references/technical-doc.md`
- 技术文章 → `references/technical-article.md`
- 项目文档 → `references/project-doc.md`
- 简历文档 → `references/resume.md`

### 3. 自动检查

使用脚本检查通用格式问题（适用于所有类型）：

```bash
python scripts/check_format.py <file.md>

# 选项
--skip-tables     跳过表格行（适用于文档类型）
--warnings-only   只显示警告，不返回错误退出码
```

**检查项**：空格、标点、引号、省略号、破折号、时间格式、括号空格、千位分隔符

**检查策略**：
- 文章：默认检查
- 文档：`--skip-tables`
- 代码文件：手动审核（代码块已自动跳过）

**注意**：脚本检查基础格式，不检查写作风格；写作类型判断在写作阶段完成。

### 4. 手动修正

按顺序检查：空格 → 标点 → 数字 → 日期时间，保持最小化原则。

### 核心原则

只修正格式和排版，不改变内容和语义；保持原文风格；保持同一文档内格式一致。

## 中文规范

### 汉字与用语

- 使用简体字和中国大陆地区词汇
- 不使用网络语言、流行语、歧视性/不雅语言
- 避免错别字（登录、阈值、重启）

### 翻译

- 使用中国大陆地区译法
- 广为接受的英文缩写可直接使用
- 未广为接受的词汇首次出现时在括号中注明原文

### 排版

- 不使用段首缩进

### 空格

- 汉字与英文、汉字与阿拉伯数字之间添加空格
- 汉字标点与英文、汉字标点与阿拉伯数字之间不添加空格
- 汉字与半角标点之间不添加空格
- 格式化内容与汉字之间不添加空格

### 标点符号

| 符号 | 形式 |
|------|------|
| 句号 | 。 |
| 逗号 | ， |
| 顿号 | 、 |
| 感叹号 | ！ |
| 问号 | ？ |
| 冒号 | ： |
| 分号 | ； |
| 引号 | " " |
| 书名号 | 《 》 |
| 括号 | （ ） |
| 破折号 | —— |
| 省略号 | …… |
| 分隔号 | / |

**使用原则**：
- 中文句子使用汉字标点
- 并列词语使用顿号，最后两个用"和"/"或"连接时不使用
- 使用弯引号，不使用直角引号「」
- 中文句子使用全角括号，括号内容都是英文时用半角括号
- 出版物名称使用书名号
- 区间和范围使用一字线"—"或波浪号"～"
- 分行列举中，非完整句子用分号，完整句子用句号

### 数字

- 不超过 10 的数字推荐中文，10 及以上推荐阿拉伯数字
- "万""亿"可用阿拉伯数字：300 万
- 四位及以上数字用千位分隔符：3,000,000

### 电话号码

- 座机：6123-4567 或 123 4567
- 含区号座机：010 6123-4567 或 (010) 6123-4567
- 手机：139-1234-5678（3-4-4 分组）
- 400/800：400-123-4567（3-3-4 分组）
- 国际：+86 10 6123-4567

### 日期时间

- 日期：2020 年 3 月 31 日或 2020-03-31
- 年份用 4 位数
- 时间用半角冒号：9:05

### 量和单位

- 量和单位遵守 GB 3100、GB 3101 和 GB 3102（全部）

## 标题规范

### 标题层级

- 一级标题：文章标题
- 二级标题：主要部分大标题
- 三级标题：二级标题下的小标题
- 四级标题：三级标题下某一方面的小标题

### 使用原则

- 层级连续：一级标题下不能直接出现三级标题
- 避免孤立编号：同级标题不止一个
- 名称不重复：下级标题不重复上级标题名字
- 限制四级标题：尽量避免，保持层级简单

## 句子结构

### 句子长度

- 不含标点的单个句子或逗号分隔的句子构件尽量 20 字以内
- 20～29 字可接受；30～39 字需语义明确；40 字以上不接受
- 逗号分割的长句不超过 100 字或正文 3 行

### 句式和语气

- 优先使用简单句和并列句
- 使用肯定句优于否定句
- 避免双重否定

### 写作风格

- 优先主动语态
- 使用正式语言
- 使用现代汉语
- 正确使用"的""地""得"
- 代词指代明确
- 避免形容词堆砌

## 英文规范

### 基本规则

英文部分遵循《Chicago Manual of Style》。

### 拼写

- 使用美式英语：Color, grey, center, canceled
- 商标和品牌名遵循官方拼写：iPhone, App Store

### 大小写

- 文章标题、出版物名称使用标题大小写
- 章节标题、表格标题使用句子大小写

### 空格

- 数字和单位通常用空格，百分号、温度、角度单位除外：5.0 cm, 32°C, 50%, 45°
- 数字和倍数符号、倍数符号和单位之间不用空格：128GB, 5GHz

### 标点符号

| 符号 | 形式 |
|------|------|
| 撇号 | ' |
| 引号 | " " |
| 省略号 | ... |
| 连字符 | - |
| En dash | – |
| Em dash | — |

**使用原则**：
- 英文句子末尾单词以点"."结尾时不再使用句号
- 括号外侧留空格
- 三个及以上并列词组在连词前使用牛津逗号
- 破折号使用 em dash，左右不留空格
- 区间推荐使用 en dash

### 货币

- 货币前缀和数字间不用空格：$12.34
- 财务语境负数用括号表示：$(12.34)

### 数字

- 四位及以上数字用逗号千位分隔：3,000,000
- 序数字母不上角标：1st, 2nd, 3rd

### 电话号码

- 区号用括号或连字符：(212) 123-4567 或 212-123-4567
- 国际号码用加号"+"作为国际冠码：+1 (212) 123-4567

### 日期时间

- 美式日期：Sunday, January 31, 2021
- 日期日不用序数：January 31
- 12 小时制：9:30 a.m. 或 9:30 am
- 午夜和正午：12:00 midnight, 12:00 noon

### 中英混排处理

- 单复数还原：英文原文用复数形式时，翻译成中文还原为单数
- 缩写：外文缩写用半角圆点表示：U.S.A., Apple, Inc.
- 省略号转换：表示中文时，英文省略号改为中文省略号
- 书名号转换：英文书名或电影名改用中文表达时，双引号改为书名号
- 术语首次出现：第一次出现英文词汇时，在括号中给中文标注
- 大小写：专有名词中每个词第一个字母大写，非专有名词不需要大写

## 数值规范

### 半角数字

阿拉伯数字使用半角形式。

### 千分号

- 四位及以上数值添加千位分隔符：1,258,000
- 四位数值千分号可选用：1000 或 1,000

### 货币

使用阿拉伯数字，货币符号在前或货币中文名在后：$1,000 或 1,000 美元

### 数值范围

用波浪线（`～`）或一字线（`—`）连接：132 kg～234 kg

带单位或百分号时，两个数字都添加单位：132 kg～234 kg, 67%～89%

### 变化程度

- **增加**：用"增加了""增加到"。"了"表增量，"到"表定量
- **减少**：用"降低了""降低到"
- **禁止**：不能用"降低 N 倍"或"减少 N 倍"

## 段落规范

### 组织原则

- 一个段落只有一个主题或中心句子
- 段落的中心句子放在段首
- 段落长度不超过七行，最佳小于等于四行
- 段落用陈述和肯定语气，避免感叹语气
- 段落之间用一个空行隔开
- 段落开头不留空白字符

### 引用与转载

- 引用第三方内容注明出处
- 全篇转载在全文开头显著位置注明作者和出处
- 使用外部图片在图片下方或文末标明来源

## 代码规范

### 格式化

- 变量类型、数据库字段类型、类、方法、函数、变量的名字、字面量格式化为代码
- 字符串字面量格式化为代码时，在句中不引起歧义可不加引号

## 参考资料来源

- **技术文档部分**：阮一峰《中文技术文档的写作规范》
  - GitHub：https://github.com/ruanyf/document-style-guide.git
  - 许可证：公共领域（public domain）
- **其他类型规范**：根据实际需要和行业最佳实践整理