| version | 3 |
| name | chinese-documentation |
| description | 中文文档排版参考——中英文空格、全半角标点、术语保留、链接格式、中文文案排版指北约定。仅在用户显式 /chinese-documentation 时调用,不要根据上下文自动触发。 |
中文技术文档写作规范
Trigger Boundary
这是显式触发型参考技能。仅当用户明确点名 /chinese-documentation,或明确要求中文技术文档排版、文案规范、README / API 文档写法、中英混排检查时使用。
不要让本技能抢占 MoviePilot 媒体、站点、订阅、下载、转移、Agent Git 或系统维护路线。
Core Principle
排版服务阅读体验,规范服务一致性,内容服务读者。中文技术文档应做到:好读、准确、自然、结构清楚,避免机翻味和中英标点混乱。
基础排版规则
空格
- 中文与英文之间加空格:
使用 Git 管理代码。
- 中文与数字之间加空格:
修复 3 个 Bug。
- 数字与单位之间加空格:
5 MB、200 ms。
- 百分比和角度等不加空格:
95%、32°C。
- 链接前后按语句需要留空。
标点
- 中文语境使用全角标点。
- 英文句子和代码上下文使用半角标点。
- 全角标点与英文 / 数字之间一般不额外加空格。
- 中文括注优先用全角括号:
安装完成后(约 3 分钟)继续。
- 纯英文或版本号括注可用半角括号:
Spring Boot (v3.2.0)。
数字与代码
- 技术参数统一使用半角阿拉伯数字:
端口 8080、HTTP 200。
- 命令、路径、变量、字段名使用行内代码:
npm install、/api/v1/orders、user_id。
- 代码块标注语言类型,示例尽量可直接运行。
中英混排与术语
保留英文:
- 专有名词:React、Kubernetes、Redis、MySQL。
- 通用缩写:API、SDK、CLI、CI/CD、ORM。
- 命令、字段、协议:
git commit、HTTP、JSON、REST。
- 无稳定中文译名或中文更别扭的术语。
翻译为中文:
- 公认概念:数据库、服务器、浏览器、缓存、负载均衡。
- 描述性短语:version control -> 版本控制。
- 标题和章节尽量中文,必要技术名词保留英文。
首次出现的重要术语可写中英对照,后文使用同一术语。
常用文档结构
README
# 项目名称
一句话说明项目解决什么问题。
## 特性
## 快速开始
### 环境要求
### 安装
### 基本用法
## 文档
## 示例
## 贡献指南
## 许可证
要点:先让读者跑起来,再给完整说明;不要把内部实现细节堆在开头。
API 文档
## 创建订单 / Create Order
### 基本信息
- 请求方式:POST
- 请求路径:`/api/v1/orders`
- 鉴权方式:Bearer Token
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
### 请求示例
### 响应参数
### 响应示例
### 错误码
金额、时间、枚举必须写清单位和格式。
详细坏例/好例、结构示例和发布前清单见同目录 REFERENCES.md。
Review Rules
- 少用直译和被动语态。
- 长句拆短,一句话只说一件事。
- 中文句子用中文标点,英文句子用英文标点。
- 大段说明优先拆成列表、表格或步骤。
- 示例必须可运行或足够接近真实场景。
- 链接可访问,图片有 alt 文本。
Output Contract
回答时只给与用户请求相关的文档规范或修改建议,不要展开整套手册。若修改了 Agent 能力资产,完成后执行结构验证,并提醒是否需要同步仓库。