# docx-proofread

**Repository Path**: kavinxu/docx-proofread

## Basic Information

- **Project Name**: docx-proofread
- **Description**: Word(.docx) 中文差错检查 skill：离线规则库 866 条，扫描正文/表格/页眉页脚，以批注、修订痕迹、高亮回写，输出 Markdown 与 HTML 校对报告，可被 Agent 调用。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-07
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# docx-proofread · Word 文档中文差错检查

> 把 WPS/Word 里的人工校对，变成 Agent 可调用的本地能力：扫描 .docx → 找出差错 → 以**批注 / 修订 / 高亮**回写，同时产出校对报告。全程离线，文档不出本地，结果兼容 Microsoft Word 与 WPS 文字。

![icon](icon.png)

---

## 一、能做什么

| 能力 | 说明 |
| --- | --- |
| 错别字 / 成语误用 | 5658 条错词对照：按装→安装、峻工→竣工、一如继往→一如既往、迫不急待→迫不及待 |
| 语义重复 / 语病 | 220 条：大约…左右、凯旋归来、涉及到、之所以…的原因、减少一倍、防止…不再 |
| 标点符号 | 102 条正则 + 9 组配对检查：中英标点混用、重复标点、引号书名号不配对 |
| 格式体例 | 36 条：全角字符、日期/金额写法、连续空格、千分位不统一 |
| 公文规范 | 54 条规则 + 87 条词条（级别为 warn/info，需人工核对）：建国→新中国成立、截止/截至 等 |
| 语义级校对 | 由 Agent（LLM）接入：逻辑矛盾、术语不统一、事实错误、语句不通 |
| 回写形态 | 批注（原文不动）/ 修订痕迹（可逐条接受拒绝）/ 高亮染色，可组合 |
| 报告 | Markdown + HTML（卡片式，含统计与明细表） |

**覆盖范围**：正文、表格单元格、页眉、页脚。

---

## 二、快速开始

```bash
cd skills/docx-proofread/scripts

# 一键：抽取 → 检查 → 回写 → 报告
python3 proofread.py run 我的稿子.docx --out-dir ./校对结果 --mode comment,highlight
```

产物：

```
校对结果/
├── blocks.json                 抽取的文本块（给 Agent 用）
├── blocks.json.txt             便于阅读的文本版
├── issues.json                 问题清单
├── 我的稿子_已校对.docx         带批注+高亮的文档
├── report.md                   校对报告
└── report.html                 网页版报告
```

环境要求：Python 3.8+，`pip install python-docx`（可选 `jieba`、`pypinyin`）。

---

## 三、使用样例

样例文件在 `examples/`，输入文档与产出结果都在，可直接打开对照。

**终端用户怎么在 ima.copilot 里用**：见 [使用样例.md](使用样例.md) —— 8 个真实场景，每句「你可以这样说」都能原样复制，附产出说明与常见问题。

### 样例 1：交稿前查错别字（最常用）

**输入**：`examples/01-交稿前检查/示例-待校对文稿.docx`（467 字，含人为植入的 16 处差错）

**命令**：

```bash
python3 proofread.py check 示例-待校对文稿.docx -o issues.json
```

**检出**（16 条，零误伤）：

| 位置 | 原文 | 建议 | 级别 |
| --- | --- | --- | --- |
| 正文第 4 段 | 按装 | 安装 | 错误 |
| 正文第 4 段 | 峻工 | 竣工 | 错误 |
| 正文第 5 段 | 一如继往 | 一如既往 | 错误 |
| 正文第 6 段 | 再接再励 | 再接再厉 | 错误 |
| 正文第 6 段 | 迫不急待 | 迫不及待 | 错误 |
| 正文第 9 段 | 陷井 | 陷阱 | 错误 |
| 正文第 9 段 | 松驰 | 松弛 | 错误 |
| 正文第 8 段 | 大约有50人左右 | 删去其一 | 疑似 |
| 正文第 10 段 | 之所以…的原因 | 句式杂糅 | 错误 |
| 正文第 13 段 | 建国以来 | 新中国成立以来 | 疑似 |
| 表 1 第2行第2列 | 按装 | 安装 | 错误 |
| 第1节页眉 | 2025/1/1 | 统一日期体例 | 疑似 |

**产出**：`示例-待校对文稿_已校对.docx`（16 条批注 + 高亮，原文一字未改）、`report.html`（见 `examples/01-交稿前检查/report.html`）。

### 样例 2：直接出修订稿

```bash
python3 proofread.py apply 示例-待校对文稿.docx -i issues.json -o 修订稿.docx --mode revise
```

生成的是**真正的 Word 修订痕迹**：错词被标为删除、正确写法标为插入，对方在 Word/WPS 里可逐条「接受/拒绝」。样例产出见 `examples/02-出修订稿/`。

### 样例 3：让 Agent 做语义级校对

规则引擎抓不到「逻辑矛盾、术语不统一、事实错误」，交给 Agent：

```bash
python3 proofread.py extract 我的稿子.docx -o blocks.json --as-text
# Agent 阅读 blocks.json.txt，按协议产出 issues.json
python3 proofread.py apply 我的稿子.docx -i issues.json -o 已校对.docx --mode comment
```

Agent 的提示词模板与 JSON 规范见 `examples/03-Agent语义校对/` 与 `references/agent-protocol.md`。

### 样例 4：挂企业词库

```bash
python3 proofread.py check 合同.docx -o issues.json --lexicon 我司词库.json
```

词库支持正词白名单、必改错词、术语统一表、自定义正则，格式见 `assets/lexicon.example.json`。

---

## 四、命令参考

```bash
python3 proofread.py extract a.docx -o blocks.json --as-text          # 抽取文本块
python3 proofread.py check   a.docx -o issues.json                    # 规则检查
python3 proofread.py check   a.docx -o issues.json --min-severity info # 连提示级也要
python3 proofread.py check   a.docx -o issues.json --exclude 格式,标点 # 按类型排除
python3 proofread.py apply   a.docx -i issues.json -o 稿.docx --mode comment,highlight
python3 proofread.py report  -i issues.json -o report.html --format html
python3 proofread.py run     a.docx --out-dir ./校对结果
```

`--mode` 可选：`comment`（批注，默认）、`highlight`（高亮）、`revise`（修订），可逗号组合。

---

## 五、质量与边界

- **默认阈值 `--min-severity warn`**：中英/数字间空格这类排版风格问题已降为 info，默认不打扰。
- **不要盲信一键修正**：规则引擎有误报，尤其公文规范类只做提示，交付前请人工过一遍批注。
- **政治性/敏感表述**：仅内置 60 条通用规范提示，不能替代专业审校（WPS 黑马校对有 30 万条规则库，需商务授权）。
- **仅支持 .docx**：.doc 需先转换，PDF 不适用。
- 扫描范围可用 `--no-tables` / `--no-headers` 调整。

---

## 六、目录结构

```
docx-proofread/
├── SKILL.md                    Skill 定义（Agent 读取）
├── README.md                   本文件
├── CHANGELOG.md                版本记录
├── LICENSE                     MIT
├── icon.png / icon_256.png     图标
├── scripts/
│   ├── proofread.py            CLI 入口
│   ├── docx_io.py              docx 解析、字符级定位、批注/修订/高亮回写
│   ├── rules.py                规则引擎
│   └── rules_data/*.json       五类规则库（6157 条）
├── references/
│   ├── wps-ai-proofread-research.md   WPS AI 校对能力调研与选型
│   └── agent-protocol.md              Agent 协作协议与提示词模板
├── assets/
│   ├── lexicon.example.json    自定义词库示例
│   └── sample_待校对.docx      测试样例
└── examples/                   四个使用样例（含输入与产出）
```

---

## 七、版本

当前 **v1.2.0**，见 [CHANGELOG.md](CHANGELOG.md)。