Run any Skill in Manus with one click

zh-doc-style

Stars27

Forks37

UpdatedJuly 2, 2026 at 08:06

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

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

UCloudDoc-Team

UCloudDoc-Team/uk8s

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Technical WritersArts, Design, Entertainment, Sports, and Media Occupations·SOC 27-3042

File Explorer

7 files

SKILL.md

readonly

Run any Skill with one click

name

zh-doc-style

description

中文技术文档排版规范

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

工作流程

第 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:英文缩写全大写,技术/产品名词首字母大写

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

缩写词 → 全大写: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 不可改":

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

输出:变更汇总

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

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

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

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

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

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

name

zh-doc-style

description

中文技术文档排版规范

工作流程

第 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 步:脚本前置——先处理规则 2、4

开工第一件事就是跑脚本,哪怕原文看着还挺乱。对所有要处理的文件依次运行(脚本在本 skill 的 scripts/ 目录下,用绝对路径):

# 自动修正:数字与中文去空格 + 含中文句子的半角标点转全角
python3 /Users/bobshi/.claude/skills/zh-doc-style/scripts/fix_style.py <文件1> <文件2> ...

脚本整块跳过代码块以免误伤键值,因此 YAML/代码块里的中文注释标点不在自动处理范围内。若代码块含中文注释,稍后按规则 4 亲自过目一遍即可。

第 3 步:手动改规则 1、3、5

这一步专心做规则1/3/5,数字空格和标点全角已由脚本处理,不用再动它们。

第 4 步:全文自检验证

手动改完后,对所有文件跑一遍自检脚本,确认五条规则都已到位、没有遗漏:

python3 /Users/bobshi/.claude/skills/zh-doc-style/scripts/check_style.py <文件1> <文件2> ...

这一步是阻塞的交付前硬性检查,必须跑。 不跑 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处理 → 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 不可改":

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

输出:变更汇总

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

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

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

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

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

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