zh-doc-style

name	zh-doc-style
description	审核并规范化中文技术文档的排版风格,包括中英文之间加空格、数字与中文不加空格(数字与英文之间加空格)、英文缩写全大写、技术/产品名词首字母大写、含中文的句子使用全角标点,并顺带修复语义与错别字。当用户要求"审核/优化/规范/排版/润色/校对/格式化"中文 Markdown 文档,或提到"中英文空格""全角标点""文档风格""格式规范""排版检查",或让你处理当前 git 分支改动过的 .md 文档时,务必使用本 skill。适用于 UCloud / UK8S 等中文技术文档;即使用户没有明确说"排版"二字,只要意图是统一中文文档的书写格式,也应触发。

中文技术文档排版规范

把中文技术文档整理成一致、专业的书写风格,并顺手修掉明显的语义与错别字问题。这些规则的共同目标只有一个:让中文读者读得顺、看得清,同时不破坏任何代码、命令和链接的正确性。

工作流程

第 1 步:确定处理范围

情形 A — 当前分支改动的文件(用户说"当前分支""改过的文件""这次改动"等):

# 找基准分支:优先 origin/HEAD 指向的默认分支,回退到 master、再回退 main
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:英文缩写全大写,技术/产品名词首字母大写

散落在中文里的英文技术名词,统一成规范大小写,读起来更专业、更一致。分三类处理,拿不准时查「术语表」;表里没有的,按同样原则判断。

1. 缩写词 → 全大写:svc→SVC、json→JSON、http→HTTP、ssl→SSL、ns→NS、lb→LB、eip→EIP
2. 技术/产品专有名词 → 首字母大写:kubernetes→Kubernetes、k8s→K8s、pod→Pod、ingress→Ingress、secret→Secret、nginx→Nginx
3. 命令名 / 二进制名 / 代码标识符 → 保持其规范原样: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 不可改":

# LB 类型,outer 公网,inner 内网    ← 中文注释:按规则规范化(全角逗号、LB 大写、中英空格)
alb.ingress.kubernetes.io/load-balancer-type: 'outer'   ← 键和值:一个字符都不动

---

输出:变更汇总

改完后向用户报告,让改动一目了然、便于核对。建议结构:

已处理 N 个文件:<文件列表>

按规则分类的改动:
- 中英文空格:<举 2-3 个代表性例子>
- 数字与中文去空格:<例子>
- 英文大小写规范:<例子>
- 全角标点:<例子>

语义/错别字修复(请重点核对,这些改变了原文):
- <文件:原 → 新,附一句原因>

按规则特意保留的边界情形(供参考):
- 如 base64 / 10Mbps 视为英文词,与中文间保留空格
- 配置枚举值 outer/inner/month 等未大写(它们是代码取值)

报告聚焦"改了什么、为什么",不要逐行复述整个 diff——用户可以自己看 git diff。