AI 辅助检查 Word 文档（docx / .doc）中的错别字，在修订模式下自动修正并添加批注说明。修正后的文档以 Word 原生修订追踪（tracked changes）标记所有修改，每处修改附有批注说明错误原因，原文档格式和排版完整保留。
> ⚠️ .doc 格式支持：本 skill 支持输入 .doc 格式文件。处理时会自动使用 pywin32（COM 自动化）调用 Microsoft Word 将 .doc 转换为 .docx，然后按标准流程处理。要求：Windows 系统 + 已安装 Microsoft Word + 已安装 pywin32 库。
D:\docs\测试文件.docx）原文件名_CheckOut_.docx ，位于输入文件同目录。typos_found: listverification_passed: boolean # 内容完整性验证是否通过> 以下行为会导致输出文档内容丢失或损坏，严格禁止：
typo_fixer.py 进行修正（见第四步）。自行编写脚本调用 Document 类的 get_node + replace_node 会导致 严重内容丢失——replace_node 会替换整个 w:r 节点，如果该节点包含除错别字外的其他文本，这些文本将全部丢失。typo_fixer.py（含 --extract-only 文本提取功能）和 verify.py（验证功能）。必须直接调用这些脚本，禁止将多行 Python 代码粘贴到终端执行。多行 Python 代码在 PowerShell 的 python -c 中极易因引号嵌套、分号分隔、for/if 语句等导致语法错误。Document 类的 get_node + replace_node 修正错别字：replace_node 会替换整个 w:r 节点，如果该节点包含除错别字外的其他文本，这些文本将全部丢失。必须使用 typo_fixer.py（见第四步），其内部已正确处理文本拆分逻辑。.trae/skills/checking-doc-typos/ 目录内创建。所有路径 必须 使用绝对路径 本工作流程使用以下路径变量，请在开始前明确它们的值：
| 变量 | 含义 | 示例 |
|---|---|---|
| :-------------- | :------------------------------------------ | :------------------------------------------- |
| 本 skill 的名称，同时也是输出 docx 文件中批注的作者名 | checking-doc-typos |
| 本 skill 的根目录（包含 scripts/ 和 ooxml/ 的目录） | D:\path\to\.trae\skills\checking-doc-typos |
| 输入文件的 绝对路径（docx 或 .doc） | D:\docs\测试文件.docx |
| 输入 docx 文件所在目录的绝对路径 | D:\docs |
| 第一步获取的本地时间戳 | 20260424_153025 |
| 工作文件夹的绝对路径 | D:\docs\checking-doc-typos_20260424_153025 |
> ⚠️ 所有路径必须使用绝对路径。Windows 路径中的反斜杠 \ 在 Python 中是转义字符，在命令行参数中直接使用原始路径即可（如 D:\docs\file.docx），不要手动添加额外转义。
在开始任何操作之前，必须先执行以下命令获取当前本地时间戳：
python -c "from datetime import datetime; print(datetime.now().astimezone().strftime('%Y%m%d_%H%M%S'))"
将输出的时间戳记为 20260424_153025，则 20260424_153025）。
> ⚠️ 必须实际执行此命令，不得自行编造或猜测时间戳。禁止使用 20260424_120000 等占位时间戳。
然后定义工作文件夹路径。工作文件夹必须创建在输出 docx 文件所在的目录下，使用绝对路径：
\_ D:\docs\checking-doc-typos_20260424_153025）> ⚠️ 工作文件夹位置禁止事项：
> - 禁止在 skill 目录（.trae/skills/checking-doc-typos/）内创建工作文件夹
> - 禁止使用相对路径（如
> - 后续所有步骤中的路径 必须 使用
创建工作文件夹：
mkdir "<work_dir>"
后续步骤中除最终修正版 docx 外的所有中间产物都放在
如果输入文件为 .doc 格式，typo_fixer.py 和 verify.py 会自动调用 doc_converter.py（基于 pywin32 COM 自动化）将 .doc 转换为临时 .docx 文件，处理完成后自动清理临时文件。无需手动执行转换操作。
> ⚠️ .doc 转换前提条件：
> - 必须在 Windows 系统上运行
> - 必须已安装 Microsoft Word（COM 组件）
> - 必须已安装 pywin32 库（pip install pywin32）
如果需要手动转换 .doc 文件，也可以直接调用：
python "<skill_root>\scripts\doc_converter.py" "<input_doc>" --output "<output_docx>"
使用本 skill 提供的 typo_fixer.py 脚本提取 docx 文件的文本内容：
python "<skill_root>\scripts\typo_fixer.py" "<input_docx>" --extract-only > "<work_dir>\extracted_text.txt"
> ⚠️ 禁止使用 python -c 执行多行 Python 代码来提取文本，也 禁止 将提取代码保存为独立的 .py 文件。typo_fixer.py 已内置 --extract-only 参数，直接调用即可。
> ⚠️ 文本提取覆盖范围：文本提取已覆盖正文段落、表格、页眉页脚和文本框（包括传统文本框 w:txbxContent 和现代形状文本框 wps:txbx）。脚注、尾注中的文字仍无法提取，如果文档包含这些元素，应提醒用户可能存在未检查到的区域。
仔细阅读提取的文本，逐段检查以下类型的错误：
校对时可查阅同目录下的 references/ 文件夹：
references/common-typos.md — 常见错别字速查表（同音字、形近字、易错词组）references/common-sentence-errors.md — 常见病句类型（语序不当、搭配不当、成分残缺或赘余、结构混乱、表意不明、不合逻辑）将发现的错别字整理为 JSON 格式，并保存为文件：
[
{
"wrong": "按装",
"correct": "安装",
"reason": "同音错别字，'安'为正确写法",
"context": "设备按装完毕"
},
{
"wrong": "己经",
"correct": "已经",
"reason": "形近错别字，'已'为正确写法",
"context": "己经完成验收"
}
]
当同一错别字在文档中出现多次，但只需修正其中特定位置时，可使用 context 和 occurrence 字段实现精准定位。不指定这两个字段时，typo_fixer.py 会修正文档中所有匹配处（默认行为）。
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
| :----- | :----- | :----- | :----- |
context | string | 上下文匹配：只有当错别字所在段落的完整文本包含此字符串时，才执行修正。用于通过上下文唯一确定需要修正的位置 | "降低安装成本" |
occurrence | integer | 第 N 次出现：只修正文档中第 N 次出现的错别字（从 1 开始计数，按 XML 文档顺序）。用于同一错别字出现多次但只需修正特定位置的场景 | 2 |
使用示例：
[
{
"wrong": "压榨",
"correct": "榨取",
"reason": "用词不当",
"context": "降低安装工作量和安装成本"
},
{
"wrong": "压榨",
"correct": "榨取",
"reason": "用词不当",
"occurrence": 2
}
]
> ⚠️ context 和 occurrence 可同时使用：同时指定时，先用 context 过滤出匹配的段落，再在这些段落中按 occurrence 定位。大多数情况下只需使用其中一个即可。
> ⚠️ context 应足够具体以唯一标识目标段落。如果 context 匹配到多个段落且未指定 occurrence，这些段落中的错别字都会被修正。
> ⚠️ occurrence 的计数基于 XML 文档顺序（getElementsByTagName("w:p") 的遍历顺序），涵盖正文、表格、页眉页脚、文本框等所有区域，与 python-docx 的 doc.paragraphs 顺序不同。禁止使用 python-docx 的段落索引来推算 occurrence。
> ⚠️ 文件命名规则（必须严格遵守）：将错别字列表保存为 JSON 文件时，文件必须放在工作文件夹 typos_，其中 typos.json、typos_to_fix.json 等无时间戳的文件名。
使用本 skill 提供的 typo_fixer.py 脚本进行修正。该脚本会自动处理文本拆分、修订追踪标记和批注添加，不会丢失任何内容。
> ⚠️ 再次强调：必须使用 typo_fixer.py，禁止自行编写修正脚本。 自行编写脚本调用 Document 类的 get_node + replace_node 会导致严重内容丢失，因为 replace_node 会替换整个 w:r 节点，而一个 w:r 节点可能包含除错别字外的其他文本，这些文本会随节点替换而丢失。typo_fixer.py 内部已正确处理了文本拆分逻辑（将 w:r 中的文本拆分为"错别字前文本 + 删除标记 + 插入标记 + 错别字后文本"），不会丢失任何内容。
方式一：通过 JSON 文件传入错别字列表（推荐）
python "<skill_root>\scripts\typo_fixer.py" "<input_docx>" "<input_dir>\原文件名_CheckOut_<timestamp>.docx" --typos-file "<work_dir>\typos_<timestamp>.json"
方式二：通过命令行参数传入错别字 JSON 字符串
python "<skill_root>\scripts\typo_fixer.py" "<input_docx>" "<input_dir>\原文件名_CheckOut_<timestamp>.docx" --typos '[{"wrong":"按装","correct":"安装","reason":"同音错别字"}]'
> ⚠️ Windows PowerShell 环境注意事项：
> - ❌ 禁止使用 PYTHONPATH= 等 bash 语法设置环境变量，PowerShell 不支持此语法
> - 必须使用 python " 直接调用脚本，脚本内部已自动处理 sys.path
> - 如果必须设置 PYTHONPATH，PowerShell 语法为 $env:PYTHONPATH="
脚本执行后会输出处理统计信息，包括成功和失败的修正数量。请关注输出中的 ⚠️ 未找到文本 条目，这些表示在文档中未找到对应的错别字文本。
> ⚠️ 如果修正失败数量大于 0，需要检查原因：可能是错别字文本在文档中不存在（AI 误判），或文本跨越了多个 w:r 元素。对于后一种情况，typo_fixer.py 已内置处理逻辑，通常不会出现此问题。
> ⚠️ 文件命名规则（必须严格遵守）：输出 docx 文件名必须为 原文件名_CheckOut_，其中 原文件名_CheckOut.docx 等无时间戳的文件名。
> ⚠️ 本步骤为强制性步骤，不得跳过。 未通过验证的文档 禁止 输出给用户。如果验证失败，必须排查原因并修正后重新执行第四步和第五步（见下方反馈闭环）。
使用本 skill 提供的 verify.py 脚本进行验证。
python "<skill_root>\scripts\verify.py" "<input_docx>" "<input_dir>\原文件名_CheckOut_<timestamp>.docx" "<work_dir>"
该脚本会自动执行以下三项验证：
> ⚠️ 禁止使用 python -c 执行多行 Python 代码来验证，也 禁止 将验证代码保存为独立的 .py 文件。verify.py 已封装全部验证逻辑，直接调用即可。
> ⚠️ 如果任何验证项未通过（输出 ❌），必须排查原因并修正后再继续，不得向用户输出有内容缺失的文档。常见原因：使用了自行编写的修正脚本而非 typo_fixer.py，导致 w:r 节点被整体替换而丢失非错别字文本。
验证失败 → 排查原因 → 修正 typos JSON → 重新执行第四步 → 重新执行第五步
| |
+--- 最多重试 3 次---+
|
3 次仍失败 → 向用户报告详情，建议人工检查
typo_fixer.py（而非自行编写脚本）wrong 字段是否与文档中的实际文本完全匹配向用户报告检查结果：
📋 错别字检查完成
检查文件：xxx.docx
发现问题数：N
【修正清单】
1. "按装" → "安装"（同音错别字）
2. "己经" → "已经"（形近错别字）
3. "按步就班" → "按部就班"（成语错字）
4. "帐号" → "账号"（常见别字）
5. "拔涉" → "跋涉"（形近错别字）
已生成修订版文档：xxx_CheckOut_<timestamp>.docx
- 所有修改均以修订模式标记，可在 Word 中逐一接受/拒绝
- 每处修改附有批注说明
- 中间文件保存在：<work_dir>
00AB1234）python -c "from datetime import datetime; print(datetime.now().astimezone().strftime('%Y%m%d_%H%M%S'))" 获取真实本地时间戳，记为 _ checking-doc-typos_20260424_153025），创建在输出 docx 文件所在目录下，使用绝对路径 typos_.json 。禁止自行编造时间戳。禁止使用 typos.json、typos_to_fix.json 等无时间戳的文件。原文件名_CheckOut_.docx ，放在输入文件同目录下，不放在工作文件夹。禁止自行编造时间戳。禁止使用 原文件名_CheckOut.docx 等无时间戳的文件。.trae/skills/checking-doc-typos/）内创建工作文件夹_/unpacked typo_fixer.py 已正确处理文本拆分逻辑，不会丢失内容Document 类的 get_node + replace_node，这会导致整个 w:r 节点被替换，丢失节点中除错别字外的所有文本typo_fixer.py（含 --extract-only 文本提取功能）和 verify.py（验证功能）。必须直接调用这些脚本python -c 执行多行 Python 代码（含 for 循环、if 语句、函数定义等），PowerShell 的引号嵌套和语句分隔规则与 bash 不同，极易导致语法错误.py 文件放在项目目录中verify.py 脚本执行第五步的三项验证（段落数量、模拟接受修订、文件结构）PYTHONPATH=xxx python -m ... 设置环境变量，PowerShell 不支持此语法python "\scripts\脚本名.py" 直接调用脚本，脚本内部已自动处理 sys.path\ 在命令行参数中直接使用即可，不要手动添加额外转义checking-doc-typos/
├── SKILL.md # 本文档
├── references/ # 参考资料
│ ├── common-typos.md # 常见错别字速查表
│ └── common-sentence-errors.md # 常见病句类型
├── scripts/
│ ├── __init__.py
│ ├── document.py # Document 类（OOXML 编辑器）
│ ├── utilities.py # XMLEditor 基类
│ ├── doc_converter.py # .doc 转 .docx 转换（pywin32 COM 自动化）
│ ├── typo_fixer.py # 错别字修正主脚本（必须使用此脚本）
│ │ # --extract-only: 提取文本（第二步）
│ │ # --typos-file: 通过 JSON 文件修正（第四步）
│ │ # --typos: 通过命令行 JSON 修正（第四步）
│ │ # context 字段: 上下文匹配精准定位
│ │ # occurrence 字段: 指定第 N 次出现
│ ├── verify.py # 内容完整性验证脚本（第五步）
│ └── templates/ # 批注相关 XML 模板
│ ├── comments.xml
│ ├── commentsExtended.xml
│ ├── commentsIds.xml
│ ├── commentsExtensible.xml
│ └── people.xml
├── ooxml/
│ └── scripts/
│ ├── unpack.py # docx 解压
│ ├── pack.py # docx 打包
│ └── validation/ # 验证工具
│ ├── __init__.py
│ ├── base.py
│ ├── docx.py
│ └── redlining.py
└── requirements.txt
共 1 个版本