---
name: chinese-quotes-fix
description: Check and fix Chinese quote pairing in Markdown files generated by ClaudeCode or other agents, while preserving Markdown syntax and protected blocks.
---

# 中文引号修复技能

用于检查并修复 Markdown 文档里的中文引号问题（双引号 + 单引号），重点处理 ClaudeCode / Agent 生成文档中常见的这类错误：

- 正文里混入英文直双引号 `"`
- 正文里中文语境下的直单引号 `'`（如 `'客户为先'`）未转为中文单引号 `‘’`
- 左右引号方向不配对
- Mermaid、YAML、代码块、HTML 属性等语法区域被误改

核心目标不是“全局轮流替换”，而是只修正文 prose，并尽量准确判断每个直引号应该变成左引号还是右引号。

## 适用场景

- ClaudeCode 输出的教程、博客、知识库文档
- 含有 Mermaid 流程图、HTML 片段、Markdown 链接的 Markdown 文件
- 中文正文为主，夹杂英文术语，例如 `"做 Agent"`、`"微调"`、`"一问一答"`

## 保护区规则

以下区域中的直引号默认不改动：

- YAML front matter
- Fenced code blocks，包括 ``` 和 ~~~
- Inline code
- Mermaid HTML 块，例如 `<div class="mermaid">...</div>`
- Markdown 链接与引用式链接定义
- HTML tag / attribute / comment
- 常见非正文 HTML block，例如 `details`、`table`、`svg`、`pre`

这条规则是为了避免把语法中的合法直引号误改成中文弯引号，导致 Markdown、HTML 或 Mermaid 失效。

## 标准工作流

### 1. 先检查

```bash
python .claude/skills/chinese-quotes-fix/check_quotes.py "path/to/file.md"
```

批量检查：

```bash
python .claude/skills/chinese-quotes-fix/check_quotes.py "docs/**/*.md"
```

检查输出会区分：

- 文件里一共有多少个直双引号 / 直单引号
- 有多少个在正文里，属于可修复目标（单引号仅检测 CJK 语境）
- 哪些行仍有正文直引号
- 当前正文里的弯引号是否存在配对问题（双引号和单引号分别报告）
- 只要存在正文直引号或配对问题，命令就返回非零退出码，便于 CI 和自动化校验阻止错误内容发布

### 2. 预览修复

```bash
python .claude/skills/chinese-quotes-fix/fix_quotes.py --dry-run "path/to/file.md"
```

### 3. 正式修复

```bash
python .claude/skills/chinese-quotes-fix/fix_quotes.py "path/to/file.md"
```

### 4. 修复配对问题（弯引号方向错误）

当 check 报告 `pairing issues`（如 `”Context Engineering”` 应为 `“Context Engineering”`）时，使用 `--fix-pairing`：

```bash
python .claude/skills/chinese-quotes-fix/fix_quotes.py --fix-pairing --dry-run "path/to/file.md"
python .claude/skills/chinese-quotes-fix/fix_quotes.py --fix-pairing "path/to/file.md"
```

此模式会分析上下文判断每个弯引号的正确方向，将误用为开引号的 `”` 修正为 `“`，反之亦然。

## 配对策略

### 双引号

脚本不会简单按“第 1 个左引号、第 2 个右引号”做全局替换，而是结合上下文判断：

- 行首、冒号、左括号等之后的直引号，优先判为开引号 `“`
- 标点、句末、右括号之前的直引号，优先判为闭引号 `”`
- 如果一行里已经出现现成的 `“` / `”`，会把它们纳入状态判断，尽量修复混用场景
- 状态按行重置，避免上一段的未闭合引号污染下一段

### 单引号

单引号使用同样的上下文判断逻辑，但额外增加 **CJK 语境检测**：

- 只有当直单引号 `'` 的前后邻近字符包含 CJK 文字或中文标点时，才判定为中文单引号并进行转换
- 英文语境中的撇号（如 `don't`、`it's`）不会被误改
- 转换目标：`'` → `‘`（U+2018）或 `’`（U+2019）

常见修复场景：

- `“客户为先”` 中的 `'客户为先'` → `‘客户为先’`
- `京东的'多快好省'理念` → `京东的‘多快好省’理念`

## 推荐使用方式

当你刚完成一篇 agent 生成的中文文档时，建议顺序如下：

1. 先完成正文生成或格式整理
2. 再跑 `check_quotes.py`
3. 如果存在正文直引号，再用 `fix_quotes.py --dry-run`
4. 预览无误后正式执行修复
5. 最后抽查 Mermaid、YAML、链接和 HTML 片段

## 验收清单

修复完成后至少确认这几项：

- 正文里的 `"` 已替换成配对的 `“”`
- CJK 语境中的 `'` 已替换成配对的 `‘’`
- 英文撇号（`don't`、`it's`）保持原样
- Mermaid 中的 `[“text”]` 保持原样
- YAML 里的 `title: “...”` 保持原样
- Markdown 链接没有被破坏
- `check_quotes.py` 不再报 `Needs fix`
- `check_quotes.py` 的双引号和单引号 `Pairing issues` 均为 0

## 注意事项

- 单引号仅在 CJK 语境下修复（前后邻近字符为中文字或中文标点），英文撇号不受影响
- 如果某些 HTML block 内部本身就是正文，但你不希望保护它们，需要按具体场景再调规则
- 如果文档里故意保留英文学术用法的直引号，修复前请先用 `--dry-run` 确认
- Windows 控制台可能不是 UTF-8，脚本已经做了安全输出处理，但最终内容仍建议以文件实际渲染结果为准