| name | zh-doc-style |
| description | 审核并规范化中文技术文档的排版风格,包括中英文之间加空格、数字与中文不加空格(数字与英文之间加空格)、英文缩写全大写、技术/产品名词首字母大写、含中文的句子使用全角标点,并顺带修复语义与错别字。当用户要求"审核/优化/规范/排版/润色/校对/格式化"中文 Markdown 文档,或提到"中英文空格""全角标点""文档风格""格式规范""排版检查",或让你处理当前 git 分支改动过的 .md 文档时,务必使用本 skill。适用于 UCloud / UK8S 等中文技术文档;即使用户没有明确说"排版"二字,只要意图是统一中文文档的书写格式,也应触发。 |
中文技术文档排版规范
把中文技术文档整理成一致、专业的书写风格,并顺手修掉明显的语义与错别字问题。这些规则的共同目标只有一个:让中文读者读得顺、看得清,同时不破坏任何代码、命令和链接的正确性。
工作流程
第 1 步:确定处理范围
情形 A — 当前分支改动的文件(用户说"当前分支""改过的文件""这次改动"等):
base=$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')
base=${base:-master}
git diff --name-only "$base"...HEAD
git diff --name-only
对每个文件都要审核整份内容,而不只是 diff 的那几行——因为风格要在整篇里保持一致,原有内容里同样可能存在不规范之处。
情形 B — 用户点名的文件或目录:直接处理用户给的路径。
如果范围不明确,先问一句再动手,别猜。
规则分两类处理,分工明确——这是本 skill 最关键的一点,请务必照做:
| 类别 | 规则 | 谁来做 |
|---|
| 纯机械 | 规则 2(数字不贴空格)、规则 4(全角标点) | 交脚本(先跑 fix_style.py) |
| 需要判断 | 规则 1(中英空格)、规则 3(术语大小写)、规则 5(语义/错字) | 你手动改(用 Edit,在脚本之后) |
为什么这样分:规则 2 和规则 4 是确定性的字符替换,不需要理解语义。而反复的实测表明,人(和模型)手动处理这两条时极易出错——尤其规则 2 反直觉(本能会给数字加空格,但本规范要求不加),规则 4 又容易在只顾着改大小写时被整段忘掉。脚本不会累、不会漏、不会被 prompt 的侧重带偏,所以把它们完全交给脚本,你专注在真正需要判断的规则 1/3/5 上。
为什么脚本先跑:让脚本先把标点和数字空格处理干净,你看到的已经是规则2/4 都对的版本,只需专心补术语大小写和中英空格,注意力更集中、不会漏。
第 2 步:脚本前置——先处理规则 2、4
开工第一件事就是跑脚本,哪怕原文看着还挺乱。对所有要处理的文件依次运行(脚本在本 skill 的 scripts/ 目录下,用绝对路径):
python3 /Users/bobshi/.claude/skills/zh-doc-style/scripts/fix_style.py <文件1> <文件2> ...
fix_style.py 直接覆盖原文件,会整块跳过代码块、行内代码、URL、链接目标,并正确区分纯数字(2个)和英文词元(10Mbps 包月、base64 编码 保留空格)。脚本还会清理全角标点邻近的多余空格(如 超时： 检查 → 超时：检查)。
脚本整块跳过代码块以免误伤键值,因此 YAML/代码块里的中文注释标点不在自动处理范围内。若代码块含中文注释,稍后按规则 4 亲自过目一遍即可。
第 3 步:手动改规则 1、3、5
脚本跑完后,用 Read 读一遍刚才处理过的文件(现在标点和数字空格已经对了),然后按文末「排版规则」里的规则 1(中英空格)、规则 3(术语大小写)、规则 5(语义/错字)逐条修正。优先用精确的 Edit 定点替换;同一模式大量重复时可用 perl -i -Mutf8 -CSD -pe '...' 批量处理,批量后抽查确认没误伤代码或链接。
这一步专心做规则1/3/5,数字空格和标点全角已由脚本处理,不用再动它们。
第 4 步:全文自检验证
手动改完后,对所有文件跑一遍自检脚本,确认五条规则都已到位、没有遗漏:
python3 /Users/bobshi/.claude/skills/zh-doc-style/scripts/check_style.py <文件1> <文件2> ...
check_style.py 只报告不改动;若它输出"干净,无机械性问题",说明规则2/4 完全符合。若仍列出 [NUM]/[PUNC] 条目,逐条看一眼——正常情况下 fix_style 已全部处理,剩下的极可能是边界情形(代码/链接/版本号 1.19 ~ 1.34 内部空格等),核对无误即可。
这一步是阻塞的交付前硬性检查,必须跑。 不跑 check 就交卷,等于没做完。
第 5 步:汇总报告
改完后给用户一份分类清单(见文末「输出:变更汇总」),把语义/错别字类的改动单独列出来,方便用户核对——这类改动改变了原意,用户最需要确认。
排版规则
规则 1:中文与英文之间加一个空格
中文方块字和拉丁字母紧贴时视觉上会"糊"在一起,加一个半角空格能显著提升可读性。这是整套规范里最基础、出现频率最高的一条。
选择ALB → 选择 ALB使用yaml部署 → 使用 YAML 部署绑定的LB的ID → 绑定的 LB 的 ID
边界:英文词一侧若紧挨的是标点、括号或行尾,不需要再补空格。
规则 2:数字与中文之间不加空格;数字与英文之间加空格
这是本规范一个刻意区别于常见排版工具的地方,请特别注意。纯数字直接贴着中文写更符合中文习惯,但数字和英文单词之间仍要空格。
- 数字 + 中文 → 无空格:
7 层 → 7层、部署 2 个 → 部署2个、2026 年 3 月 → 2026年3月、北京 2） → 北京2）、80 和 → 80和
- 数字 + 英文 → 有空格:
HTTP 80、UK8S 1.19、Kubernetes 1.30(保持空格不动)
- 版本号范围内部的空格保留:
1.13 - 1.25、1.19 ~ 1.25 不要动内部,只处理它与两侧中文的边界(版本在 1.13 → 版本在1.13,1.25 并且 → 1.25并且)
关键陷阱——"英文+数字"构成的单一词元当作英文处理:像 base64、10Mbps、300Mbps、v11、IPv4、x86 这类整体是一个英文标识符/单位,末尾虽是数字但不算"数字"。它们与中文之间按规则 1 加空格,内部绝不拆分:
base64处理 → base64 处理(不是 base64处理,也不是 base 64)10Mbps包月 → 10Mbps 包月
判断口径:看紧挨中文的那一侧——若是字母(Mbps、GB、ms),按英文加空格;若是纯数字或数字带符号单位(50%、3℃),按数字不加空格(50%的CPU)。
规则 3:英文缩写全大写,技术/产品名词首字母大写
散落在中文里的英文技术名词,统一成规范大小写,读起来更专业、更一致。分三类处理,拿不准时查「术语表」;表里没有的,按同样原则判断。
- 缩写词 → 全大写:
svc→SVC、json→JSON、http→HTTP、ssl→SSL、ns→NS、lb→LB、eip→EIP
- 技术/产品专有名词 → 首字母大写:
kubernetes→Kubernetes、k8s→K8s、pod→Pod、ingress→Ingress、secret→Secret、nginx→Nginx
- 命令名 / 二进制名 / 代码标识符 → 保持其规范原样:
kubectl、kubelet、kube-proxy、containerd、etcd、npd 这些天生小写,是可执行文件或字段名,不要大写它们。
同样关键——不要过度大写。以下一律保持原样,不当作"名词"去大写:
- 通用英文单词:
web、latest、outer、inner
- 配置枚举值 / 命令行取值:
month、year、dynamic、traffic、bandwidth、outer、inner(它们是代码里要原样填写的值,大写会导致配置失效)
- 任何代码、命令、注解键、URL、文件路径里的字符
链接的显示文字要改,链接目标(URL/路径)不要改:[kubernetes 安装](/uk8s/xxx/nginx_1.26) → [Kubernetes 安装](/uk8s/xxx/nginx_1.26)(方括号内改,圆括号内不动)。
规则 4:含中文的句子使用全角标点
一个句子/短语里只要有中文,其中的中文式标点就用全角,视觉上和方块字更协调:,→, .→。 :→: ;→; ?→? !→! ()→()。
注意: 官方已停止维护. → 注意:官方已停止维护。默认:month → 默认:month(冒号属于中文句子,用全角;后面的 month 是英文值,保持不动)- 全角标点自带间距,前后不再加空格:
维护,如果 不是 维护, 如果
不要转成全角的情形(否则会改坏内容):
- 行内代码、代码块、YAML 键值、命令里的标点
- URL、文件路径、链接目标里的标点
- Markdown 结构字符本身:
#、*、-、|、>、反引号、[]() 不是句子标点,永远不动
- 纯英文/纯代码的括号内容,习惯上保留半角并在前面留一个空格:
LB 的类型 (outer/inner)、(month/year/dynamic) 保持半角
规则 5:修复语义与错别字
在排版之外,发现明显的笔误、错字、重复字、语法小病时一并修掉,让文档更可靠。但只改明显错误,不重写、不改变原意;凡是可能改变技术含义、或你不确定作者意图的,不要擅自改,放进汇总报告里请用户确认。
实战中遇到过的例子:
带宽上线 → 带宽上限(形近错字,语义相反)innger → inner(拼写错误)Pod Readines Gate → Pod Readiness Gate(拼写错误)健康检查的的路径 → 健康检查的路径(重复字)- 段落结尾漏掉的句号补上
术语表
紧挨中文出现时套用下列规范写法。这是一份可扩展的清单,不是封闭集——遇到表里没有的,按规则 3 的三类原则判断。
缩写词(全大写)
| 规范写法 | 常见误写 |
|---|
| YAML / JSON / HTML | yaml / json / html |
| HTTP / HTTPS / TCP / UDP / IP | http / https / tcp / ip |
| TLS / SSL / DNS / API | tls / ssl / dns / api |
| K8s | k8s / K8S / k8S |
| SVC / NS / LB / ALB / ULB | svc / ns / lb / alb / ulb |
| EIP / VPC / UVPC / CNI / CSI | eip / vpc / cni / csi |
| PV / PVC / RBAC / IAM / GPU | pv / pvc / rbac / iam / gpu |
| HPA / VPA / CronHPA / CA | hpa / vpa / cronhpa / ca |
| BGP / RSSD | bgp / rssd |
技术专有名词(首字母大写)
| 规范写法 | 常见误写 |
|---|
| Kubernetes | kubernetes |
| Pod / Node / Service | pod / node / service |
| Deployment / StatefulSet | deployment / statefulset |
| Ingress / IngressClass | ingress / ingressclass |
| Secret / ConfigMap / Namespace | secret / configmap / namespace |
| Label / Annotation / Listener | label / annotation / listener |
| Nginx / Docker / Traefik | nginx / docker / traefik |
| Prometheus / CoreDNS / Containerd | prometheus / coredns / containerd |
| Readiness Gate | readiness gate / readines gate |
产品/品牌名(按品牌写法)
| 规范写法 | 常见误写 |
|---|
| UCloud / UK8S | ucloud / uk8s |
| UDisk / RSSD UDisk | udisk |
| UFS / UPFS / US3 / UHub | ufs / us3 / uhub |
命令 / 二进制名(保持小写,勿大写)
kubectl、kubelet、kube-proxy、containerd、etcd、npd、node-problem-detector
注:Etcd / ETCD、Containerd 这类词在"作为组件/章节名"时项目里可能已有既定写法。若同一文档内已有一致惯例,尊重既有惯例,不必强行统一成某一种。
不可改动区(边界)
规范化只作用于中文正文和中文注释。以下内容一律原样保留,这是本 skill 的安全底线——改坏一个 YAML 值或链接,损失远大于排版收益:
- 代码块(
```)里的代码本身:键名、值、命令、字段。只有其中的中文注释可以按规则处理。
- 行内代码(
`...`)整体不动。
- URL、文件路径、Markdown 链接目标(圆括号内)。
- 注解/字段标识符,如
alb.ingress.kubernetes.io/load-balancer-type。
- Markdown 结构与语法字符。
代码块内典型的"可改 vs 不可改":
alb.ingress.kubernetes.io/load-balancer-type: 'outer' ← 键和值:一个字符都不动
输出:变更汇总
改完后向用户报告,让改动一目了然、便于核对。建议结构:
已处理 N 个文件:<文件列表>
按规则分类的改动:
- 中英文空格:<举 2-3 个代表性例子>
- 数字与中文去空格:<例子>
- 英文大小写规范:<例子>
- 全角标点:<例子>
语义/错别字修复(请重点核对,这些改变了原文):
- <文件:原 → 新,附一句原因>
按规则特意保留的边界情形(供参考):
- 如 base64 / 10Mbps 视为英文词,与中文间保留空格
- 配置枚举值 outer/inner/month 等未大写(它们是代码取值)
报告聚焦"改了什么、为什么",不要逐行复述整个 diff——用户可以自己看 git diff。
