zh-quality

专治 AI 写中文的"机器口音"——乱码 / 假名混入 / 繁简混用 / 半角标点，一键检查并修复

背景 • Before/After • 安装 • 使用 • 规则 • 场景

---

为什么需要 zh-quality

人写中文，错的是错别字和语病；AI 写中文，错的是另一类问题。

大模型（ChatGPT / Claude / Gemini / Doubao / Qwen 等）输出中文时，因训练语料混入、tokenizer 边界、繁简语料混合等原因，会稳定产出只有机器才会犯的结构性错误：

机器错误	AI 输出示例	原因
日文假名混入	产品の说明 / 使用アプリ	日文训练语料污染
乱码字符	采用�优质材料	tokenizer 解码失败
繁简混用	軟體质量很好	港台语料混入大陆文本
港台用词	記憶體 / 網路 / 程式	训练集地区不均
半角标点	你好**,世界!**	英文标点习惯渗透
中英无间距	用Python写	模型不知道排版规范
零宽字符	你​好（含 ZWSP）	复制粘贴携带
Unicode 非规范	NFD 形式的骨	平台差异

这些问题人眼难一眼看出（尤其零宽字符、NFD），但会让你的文章/PPT/产品文案一眼显出"AI 味"。

zh-quality 是一个 Claude Code skill，专攻这 12 类 AI 输出的机器口音，三种载体一站式覆盖：纯文本 / PPT / 图片。

Before / After

❌ AI 生成的原始文本 测试一下,使用Python3.9開發的軟體. 功能包括:1)網路連接 2)記憶體管理！！！ 产品の说明：采用优质材料(进口)

✅ zh-quality 修复后 测试一下，使用 Python3.9 开发的软件。 功能包括：1）网络连接 2）内存管理！ 产品的说明：采用优质材料（进口）

修复内容：半角标点 → 全角 · 繁简混用 → 统一简体 · 港台术语 → 大陆用法 · 日文假名 → 汉字 · 中英间距补全 · 连续标点缩减 · 半角括号 → 全角

┌──────────────────────────────────────────┐
│  12 项文本规则            ████████ 覆盖   │
│  200+ 异体字映射          ████████ 港台全  │
│  纯文本 / PPT / 图片      ████████ 全场景  │
│  URL·代码·品牌名         ████████ 不误报  │
│  一键修复 + diff 对比     ████████ 可操作  │
│  32 个单元测试            ████████ 全通过  │
└──────────────────────────────────────────┘

30 秒看效果（Demo）

git clone https://github.com/Jackychen-12/zh-quality.git
cd zh-quality && bash setup.sh
bash tests/samples/run_demo.sh

输出三段对比：

1. 典型 AI 输出 → 14 行修复 diff，14 行变化覆盖标点/间距/繁简/假名
2. 隐藏问题样本 → 揭出 25 个肉眼难发现的问题（零宽字符 P1、假名混入 P0）
3. 干净文本 → 报告 0 个问题，验证无误报

与已有工具的区别

工具	主战场	不解决
zhlint	通用中文排版（人写）	AI 特有的假名混入 / 零宽字符 / NFD / 港台用词替换
autocorrect	中英间距 + 全半角标点	繁简混用 / 异体字 / 乱码 / PPT 字体 / 图片
zh-quality	AI 输出的"机器口音"	翻译 / 内容创作 / 字体设计 / 错别字

简言之：zhlint / autocorrect 是给人写的中文用的，zh-quality 是给 AI 写的中文用的。两者可叠加使用。

安装

方法一：npx 一键安装（推荐）

npx skills add https://github.com/Jackychen-12/zh-quality.git

方法二：Git 克隆

git clone https://github.com/Jackychen-12/zh-quality.git ~/.claude/skills/zh-quality
cd ~/.claude/skills/zh-quality && bash setup.sh

方法三：手动安装

mkdir -p ~/.claude/skills/zh-quality
# 下载本仓库所有文件到该目录
pip3 install opencc-python-reimplemented python-pptx python-docx Pillow

OpenCode 用户：克隆到 ~/.config/opencode/skills/zh-quality/ 即可，OpenCode 也兼容 ~/.claude/skills/。

使用

在 Claude Code 中

直接用自然语言触发——不需要记命令：

检查中文              → 检查当前文件或指定文件
修复乱码              → 检查并修复
PPT 字体修复          → 检查 .pptx 文件的字体/间距
图片中文乱码          → 检测图片中的乱码文字
中文有问题 / 字体不对  → 自动判断场景并处理

命令行

# 自动判断文件类型，一个命令搞定
python3 scripts/check.py document.md
python3 scripts/check.py presentation.pptx
python3 scripts/check.py report.docx
python3 scripts/check.py image.png

# 修复
python3 scripts/check.py --fix document.md

# 修复前先看 diff
python3 scripts/check.py --diff document.md

# Markdown 报告
python3 scripts/check.py --report document.md

# 批量扫描整个目录
python3 scripts/check.py --report ./my_docs/

管道输入

echo "测试,hello世界" | python3 scripts/check_text.py --stdin

12 项检查规则

#	规则	严重度	Before	After
1	日文假名混入	P0	产品の说明	产品的说明
2	乱码字符	P0	采用�材料	标记需重新生成
3	繁简混用	P1	產品质量	产品质量
4	中英文间距	P2	用Python写	用 Python 写
5	标点全半角	P2	你好,世界	你好，世界
6	连续标点	P3	太好了！！！	太好了！
7	段首多余空格	P3	段落文字	段落文字
8	空行过多	P3	4+ 连续空行	缩减为 2 行
9	括号全半角	P2	中文(注释)	中文（注释）
10	异体字（200+）	P2	軟體/記憶體	软件/内存
11	零宽字符	P1	不可见字符	删除
12	Unicode 规范化	P1	NFD 编码	统一 NFC

严重度：P0 = 不可读，必须修 · P1 = 影响专业性 · P2 = 影响阅读 · P3 = 风格建议

智能跳过（不误报）

规则不是无脑正则——有上下文感知，这些场景不会被误报：

场景	示例	处理
URL	访问 https://github.com/user/repo 查看	跳过 URL 内标点
inline code	用 `print("hello")` 打印	跳过反引号内标点
品牌名	我的iPhone很好用	不强制加空格
email	联系 test@email.com	跳过 email 内标点
代码块	``` 包裹的内容	整块跳过

品牌白名单内置 20+（iPhone/iPad/macOS/GitHub/YouTube/WiFi...），可在 BRAND_NO_SPACE 中扩展。

覆盖场景

纯文本（.md / .txt / .json / .yml）

12 项规则全覆盖，支持 --fix 自动修复 + --diff 对比 + --report 报告。

PPT（.pptx）

检查项	说明
EA 字体缺失/错误	东亚字体为空或设为 Arial → 替换为 PingFang SC
字间距异常	> 300 或 < -100 centi-pt → 重置
行间距异常	> 300% 或 < 80% → 重置 120%
编码损坏	含 � → 标记人工处理
文本内容	对每个文本框跑 12 项文本规则

修复前自动创建 *_backup.pptx，不动布局/样式/结构。

Word（.docx）

与 PPT 同等检查能力，同样保留原文件备份。

图片（.png / .jpg）

AI 图片模型渲染中文本质上不可靠，提供三种路径：

路径	做什么	适合
方案 A：修复 prompt	输出保留原图构图的新 prompt，仅替换文字	无多模态能力的模型
方案 B：程序修复	Pillow 擦除乱码 + 正确字体重绘	有图片文件路径
方案 C：底图 + overlay	生成无字底图 → 程序叠加文字	新生成图片

图片 OCR 检测需要 Tesseract（可选），未安装时自动降级为预防提醒模式。

配置

编辑 config.json 按需开关规则：

{
  "rules": {
    "bracket_style": false,
    "leading_spaces": false,
    "repeated_punctuation": false
  },
  "skip_extensions": [".min.js", ".min.css"],
  "max_file_size_kb": 500
}

设为 false 的规则全局禁用。

目录结构

zh-quality/
├── SKILL.md              # Claude Code skill 入口
├── README.md             # 本文件
├── config.json           # 规则配置（可自定义）
├── setup.sh              # 一键安装依赖
├── pyproject.toml        # pip install 支持
├── scripts/
│   ├── check.py          # 统一入口（自动识别文件类型）
│   ├── check_text.py     # 文本 12 项规则
│   ├── check_pptx.py     # PPT 检查+修复
│   ├── check_docx.py     # Word 检查+修复
│   ├── check_image.py    # 图片 OCR 检测
│   └── overlay_fix.py    # 图片文字修复
├── references/
│   ├── chinese-text-rules.md      # 规则的学术依据
│   └── common-errors-catalog.md   # 错误类型目录
├── fonts/README.md       # 字体安装指南
└── tests/
    ├── test_text.py      # 32 个单元测试
    ├── samples/          # 3 个 demo 样本 + run_demo.sh
    └── expected/         # 修复后的期望输出

依赖

必要（setup.sh 自动安装）：

包	用途
opencc-python-reimplemented	繁简转换
python-pptx	PPT 操作
python-docx	Word 操作
Pillow	图片处理

可选：

包	用途	安装
pytesseract + Tesseract	图片 OCR	brew install tesseract tesseract-lang && pip3 install pytesseract

贡献

欢迎 PR，特别是：

• 新增规则：在 check_text.py 中添加 check_* / fix_* 函数对
• 扩充映射表：VARIANT_MAP（异体字）、BRAND_NO_SPACE（品牌白名单）
• 新文件格式：参照 check_pptx.py 的模式添加新格式支持
• Bug 报告：提 Issue 附上触发误报/漏报的文本样本

开发流程：

git clone https://github.com/Jackychen-12/zh-quality.git
cd zh-quality
bash setup.sh
python3 tests/test_text.py  # 32 个测试应全部通过

License

MIT