chinese-documentation

name	chinese-documentation
description	中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用，不要根据上下文自动触发。

中文技术文档写作规范

概述

中文技术文档最常见的问题不是内容不够，而是读起来别扭——中英文挤在一起没有空格、全角半角混用。本技能提供一套完整的中文技术文档写作规范。

核心原则： 排版服务于阅读体验，规范服务于一致性，内容服务于读者。

参考标准： 中文文案排版指北

中文排版规范

空格

场景	好	坏
中英文之间	使用 Git 进行版本管理	使用Git进行版本管理
中文与数字之间	包含 3 个新功能	包含3个新功能
数字与单位之间	文件大小不超过 5 MB	文件大小不超过5MB
链接前后	请参考 官方文档 获取信息	请参考官方文档获取信息

例外： 度数、百分比不加空格：32°C、95%

标点符号

• 中文语境使用全角标点：注意：该接口需要鉴权，请先获取 Token。
• 全角标点与英文/数字之间不加空格：项目使用 MIT 协议，详见 LICENSE 文件。
• 括号使用：
  • 中文语境用全角括号：（详见下方说明）
  • 括号内有英文/数字用半角括号：基于 Spring Boot (v3.2.0) 开发
  • 纯英文内容用半角括号：See the documentation (README.md) for details.
• 引号使用：中文推荐直角引号：「确定」按钮，嵌套时用 『』

数字

技术文档统一使用半角阿拉伯数字：支持最多 100 个并发连接，版本号 v2.1.0，端口号 8080。

中英混排最佳实践

术语处理原则

保留英文： 专有名词（React、Kubernetes）、行业缩写（API、SDK、CI/CD）、命令和代码（npm install）、协议标准（HTTP、TCP/IP）、无公认中文翻译的术语（debounce、middleware）。

翻译为中文： 有公认翻译的通用概念（数据库、服务器、负载均衡）、文档标题和章节名。

首次出现标注翻译：

本系统采用消息队列（Message Queue）实现异步通信。
# 后续直接使用：消息队列的消费者需要实现幂等性……

避免过度翻译：

# 好
在 Controller 层做参数校验，Service 层处理业务逻辑。
使用 Redis 做 Session 缓存。

# 坏
在控制器层做参数校验，服务层处理业务逻辑。
使用"远程字典服务"做"会话"缓存。

API 文档格式

接口文档模板

## 创建订单 / Create Order

### 基本信息

- **请求方式 (Method):** POST
- **请求路径 (Path):** `/api/v1/orders`
- **鉴权方式 (Auth):** Bearer Token
- **Content-Type:** application/json

### 请求参数 (Request Parameters)

| 参数名 (Field) | 类型 (Type) | 必填 (Required) | 说明 (Description) |
|----------------|-------------|-----------------|-------------------|
| product_id | string | 是 | 商品 ID |
| quantity | integer | 是 | 购买数量，最小值为 1 |
| address_id | string | 是 | 收货地址 ID |
| coupon_code | string | 否 | 优惠券码 |

### 请求示例 (Request Example)

```json
{
  "product_id": "prod_abc123",
  "quantity": 2,
  "address_id": "addr_xyz789",
  "coupon_code": "SUMMER2024"
}

响应参数 (Response Parameters)

参数名 (Field)	类型 (Type)	说明 (Description)
order_id	string	订单 ID
status	string	订单状态: pending / paid / shipped
total_amount	integer	订单总金额，单位：分
created_at	string	创建时间，ISO 8601 格式

错误码 (Error Codes)

错误码 (Code)	说明 (Description)	处理建议 (Suggestion)
40001	商品不存在	检查 product_id 是否正确
40002	库存不足	减少购买数量或稍后重试

### 金额表示约定

好：明确说明单位

total_amount: 9900 // 单位：分（即 99.00 元）

坏：不说明单位，造成歧义

total_amount: 99.00 // 是元还是分？浮点数会有精度问题

## README.md 中文模板

````markdown
# 项目名称

简短一句话介绍项目是什么、解决什么问题。

## 特性

- 特性一：简要描述
- 特性二：简要描述

## 快速开始

### 环境要求

- Node.js >= 20
- MySQL >= 8.0

### 安装

```bash
npm install your-package

基本用法

import { YourPackage } from 'your-package';
const result = await client.doSomething();

文档

• 使用指南
• API 参考
• 更新日志

贡献指南

欢迎提交 Issue 和 Pull Request。请先阅读 贡献指南。

本地开发

git clone https://gitee.com/your-org/your-project.git
npm install
npm run dev
npm test

许可证

MIT

## 常见问题与避坑指南

### 机翻味

**特征：** 句式生硬、不符合中文表达习惯。

```
# 机翻味
这个函数被用来计算用户的折扣。如果你想要获取更多信息，请参考文档。

# 自然中文
这个函数用于计算用户折扣。更多信息请参考文档。
```

**要点：** 避免被动语态（"被用来" → "用于"）、避免冗余代词、避免直译英文句式。

### 句式欧化

**特征：** 长定语、多重从句。

```
# 欧化句式
这是一个可以帮助开发者在不需要手动配置复杂的构建工具链的情况下快速搭建现代化前端项目的脚手架工具。

# 正常中文
这是一个前端脚手架工具，帮助开发者快速搭建项目，免去手动配置构建工具链的麻烦。
```

**要点：** 长句拆成短句，把定语从句改成并列句，一句话只说一件事。

### 过度翻译与中英标点混用

```
# 过度翻译
请打开您的"终端模拟器"，运行"节点包管理器"的安装命令。

# 正常写法
请打开终端，运行 npm install。

# 坏：中文句子用了英文逗号和句号
请先安装依赖,然后运行测试.

# 好
请先安装依赖，然后运行测试。
```

### 缺乏结构化

```
# 坏：一大段文字没有分段
本系统使用 Redis 做缓存提高查询性能同时使用 MySQL 做持久化存储数据写入时先写 MySQL 再异步更新 Redis……

# 好：用列表和分段组织信息
本系统的缓存策略如下：

- **存储层：** MySQL（持久化）+ Redis（缓存）
- **写入流程：** 先写 MySQL，再异步更新 Redis
- **读取流程：** 先查 Redis → 未命中则查 MySQL → 回写 Redis
- **缓存过期：** TTL 设为 30 分钟
```

## 写作检查清单

### 排版

- [ ] 中英文之间有空格
- [ ] 中文与数字之间有空格
- [ ] 中文语境使用全角标点
- [ ] 英文/代码部分使用半角标点
- [ ] 没有全角半角标点混用

### 术语

- [ ] 专有名词保留英文原文
- [ ] 首次出现的术语标注了中英对照
- [ ] 没有过度翻译业界通用术语
- [ ] 术语使用前后一致

### 内容

- [ ] 句子简短，没有欧化长句
- [ ] 没有不必要的被动语态
- [ ] 用列表和表格组织结构化信息
- [ ] 代码示例可以直接运行
- [ ] 没有"机翻味"

### 格式

- [ ] 标题层级正确（不跳级）
- [ ] 代码块标注了语言类型
- [ ] 链接可以正常访问
- [ ] 图片有 alt 文本