Docx batch variable replacement

docx-batch-variable-replacement

技能用途

本技能用于基于一个 Word 模板文档，批量复制生成多个差异化 Word 文件。

适用场景包括但不限于：

• 同一合同模板生成多家公司版本；
• 同一技术方案生成多个单位版本；
• 同一报价文件生成多个客户版本；
• 同一验收资料生成多个项目版本；
• 同一投标/应答文件按不同公司、项目、联系人等信息生成版本。

本技能只处理：

1. 复制 Word 文件；
2. 按用户本次提供的映射关系进行机械替换；
3. 检查旧信息和占位符残留；
4. 输出检查报告。

不得进行文档写作、润色、扩写、删减、重排版或自行补充信息。

---

核心原则

1. Skill 只固定流程和边界，不固定具体公司清单。
2. 替换数据必须由用户本次提供。
3. 不得自行猜测公司名称、联系人、电话、地址、项目名称、金额、日期等信息。
4. 未列入用户本次映射关系的内容，一律不得修改。
5. 本任务不是写文档，而是批量复制和字段替换。
6. 默认采用严格匹配，不进行模糊匹配。
7. 默认区分大小写，并严格区分全角、半角字符。
8. 如需模糊匹配、大小写忽略、全半角归一化，必须由用户明确授权。

---

用户每次需要提供的信息

执行任务前，应确认用户是否提供了以下信息：

1. 原始 Word 文件路径；
2. 输出目录；
3. 每个输出文件名；
4. 每个文件对应的替换映射关系；
5. 需要重点检查残留的旧字段。

替换映射关系可以来自：

• CSV 文件；
• Excel 文件；
• Markdown 表格；
• JSON；
• 用户直接粘贴的文本清单。

不得要求用户固定使用某一种格式。

---

推荐输入格式

用户可以提供类似以下格式：

原始文件：template.docx
输出目录：output/

文件：01-目标公司A.docx
甲公司 → 目标公司A
张三 → 李四
13800000000 → 13900000000
甲方地址 → 目标地址A

文件：02-目标公司B.docx
甲公司 → 目标公司B
张三 → 王五
13800000000 → 13700000000
甲方地址 → 目标地址B

也可以提供表格：

output_filename	old_company	new_company	old_contact	new_contact	old_phone	new_phone
01-目标公司A.docx	甲公司	目标公司A	张三	李四	13800000000	13900000000
02-目标公司B.docx	甲公司	目标公司B	张三	王五	13800000000	13700000000

---

内部处理逻辑

无论用户提供 CSV、Excel、Markdown 表格、JSON 还是纯文本清单，都应转换为以下内部结构理解：

[
  {
    "output_filename": "01-目标公司A.docx",
    "replacements": [
      {
        "old": "甲公司",
        "new": "目标公司A"
      },
      {
        "old": "张三",
        "new": "李四"
      }
    ]
  }
]

该结构仅用于内部执行理解，不要求用户必须提供 JSON。

---

替换冲突预防

执行替换前，必须检查映射关系是否存在冲突。

重点检查：

1. 是否存在重复的 old 字段；
2. 是否存在相同 old 对应不同 new 的情况；
3. 是否存在替换链条，例如 A → B，同时又有 B → C；
4. 是否存在包含关系，例如“目标公司”和“目标公司集团”；
5. 是否存在空值替换；
6. 是否存在输出文件名重复。

处理原则：

1. 如存在明显冲突，不得自行决定，应写入检查报告。
2. 如存在包含关系，应优先替换长字符串，防止短字符串提前替换造成错误。
3. 如存在 A → B、B → C 这类链式关系，应避免多轮替换导致结果被二次替换。
4. 优先采用一次性扫描替换策略，避免前一项替换结果被后一项继续替换。
5. 如无法保证替换顺序安全，应停止对应文件处理，并写入检查报告。

---

执行流程

1. 读取用户输入

读取原始 Word 文件和用户提供的替换映射关系。

检查内容包括：

1. 是否给出原始 Word 文件；
2. 是否给出输出目录；
3. 是否给出输出文件名；
4. 是否给出每个文件对应的替换关系；
5. 是否存在空字段；
6. 是否存在重复输出文件名；
7. 是否存在明显冲突的替换关系；
8. 是否存在链式替换风险；
9. 是否存在长短字段包含关系；
10. 是否存在 .docm、数字签名、受保护文档、复杂动态域等高风险文档特征。

如发现异常，不得自行修正，应写入检查报告。

---

2. 复制 Word 文件

根据用户提供的输出文件名，将原始 Word 文件复制到输出目录。

要求：

1. 输出文件数量必须与用户清单一致；
2. 输出文件名必须严格等于用户提供的名称；
3. 不得自行改名；
4. 不得自行新增文件；
5. 不得遗漏文件。

---

3. 执行机械替换

只允许执行用户本次明确提供的替换关系。

要求：

1. 替换前字段必须来自用户输入；
2. 替换后字段必须来自用户输入；
3. 不允许新增替换项；
4. 不允许推断公司简称；
5. 不允许推断联系人；
6. 不允许推断地址、电话、日期、金额、项目编号；
7. 不允许改写正文；
8. 不允许润色正文；
9. 不允许删除正文；
10. 不允许调整格式；
11. 默认严格匹配原字符；
12. 默认区分大小写；
13. 默认区分全角、半角字符。

---

Word XML 与 run 断裂处理要求

Word 文档中的可见文本可能在底层 XML 中被拆分为多个 run。

例如，可见文本：

甲公司

在 Word XML 中可能被拆分为：

甲
公司

因此，禁止只使用简单的 paragraph.text.replace() 或单个 run 内替换作为唯一方案。

实现时必须考虑以下情况：

1. 同一字段被拆分到多个 run；
2. 同一字段中间存在不同字体、加粗、下划线或颜色；
3. 同一字段位于表格、页眉、页脚、文本框中；
4. 同一字段被 Word 拼写检查、修订或历史编辑拆开；
5. 同一字段出现在复杂 XML 节点中。

建议实现方式：

1. 优先采用能够处理跨 runs 文本替换的算法；
2. 可在同一段落或同一 XML 容器范围内重建文本索引，再映射回 run；
3. 可优先处理同格式 run 的合并；
4. 可在必要时采用 XML 级替换策略；
5. 替换后不得破坏原有文档结构、样式、图片、表格、页眉页脚和字段代码。

如果工具无法可靠处理跨 runs 替换，必须在检查报告中明确说明风险，不得假装替换成功。

---

替换范围

应尽可能覆盖 Word 文档中的以下位置：

1. 正文段落；
2. 表格；
3. 页眉；
4. 页脚；
5. 脚注；
6. 尾注；
7. 批注；
8. 文本框；
9. 目录中的文本；
10. 文档属性中可处理的文本。

如果某些位置因工具限制无法处理，必须在检查报告中说明。

---

高风险 Word 文档处理限制

如果原始文件存在以下情况，必须在检查报告中提示风险：

1. .docm 宏文档；
2. 数字签名；
3. 受保护文档；
4. 启用了修订模式；
5. 复杂动态域；
6. 自动目录、交叉引用或自动编号较多；
7. 水印；
8. 嵌入对象；
9. 复杂页眉页脚；
10. 文本框、形状、SmartArt 中包含待替换字段；
11. 图片、扫描件或签章中包含文字。

处理原则：

1. 不得删除宏；
2. 不得破坏数字签名；
3. 不得强行修改受保护内容；
4. 不得改动签章；
5. 不得改动图片；
6. 不得将 Word 内容整体转写后重新生成新文档，除非用户明确允许。

---

空值处理规则

如果替换后的值为空，应重点标记。

例如：

张三 →

处理原则：

1. 不得默认认为用户想删除该字段；
2. 应在检查报告中标记为空值替换；
3. 如用户明确要求空值替换，可以执行；
4. 执行后必须检查是否出现空括号、空冒号、空表格单元格等异常格式；
5. 如无法判断，应停止该项替换并列为待确认项。

---

严禁行为

执行本技能时，严禁：

1. 重写正文；
2. 润色表达；
3. 扩写内容；
4. 删除内容；
5. 调整章节结构；
6. 调整标题层级；
7. 调整编号；
8. 调整表格结构；
9. 调整目录；
10. 调整页眉页脚格式；
11. 改动图片；
12. 改动签章；
13. 改动附件；
14. 自行补充公司信息；
15. 自行补全简称；
16. 自行生成联系人、电话、地址；
17. 自行推断金额、日期、项目编号；
18. 将 Word 内容整体转写后重新生成新文档，除非用户明确允许；
19. 使用简单替换后不做残留检查；
20. 未确认替换成功却在报告中写“全部完成”。

---

残留检查

每份文件生成后，必须检查旧信息是否残留。

重点检查：

1. 原公司名称；
2. 原联系人；
3. 原电话；
4. 原地址；
5. 原项目名称；
6. 用户指定的其他旧字段；
7. 疑似旧公司简称；
8. 疑似模板残留内容。

---

通用占位符检查

除用户指定旧字段外，还应检查常见占位符和模板残留。

包括但不限于：

XXX
XX公司
某某公司
某地区某公司
待补充
待填写
待完善
填写
【】
[]
[ ]
{{ }}
{{...}}
${...}
__
____
202X年
20XX年
xxxx
xxxxx
TBD
TODO

发现后不得自行替换，应写入检查报告。

---

检查报告要求

任务完成后，必须生成 check.md。

报告格式如下：

# 批量 Word 替换检查报告

## 一、输入信息

- 原始文件：
- 输出目录：
- 输出文件数量：
- 替换映射来源：
- 执行时间：

## 二、文件生成结果

| 序号 | 输出文件名 | 是否生成 | 备注 |
|---|---|---|---|

## 三、替换统计

| 输出文件名 | 替换前 | 替换后 | 替换次数 | 备注 |
|---|---|---|---:|---|

## 四、旧信息残留检查

| 输出文件名 | 残留字段 | 出现位置 | 说明 |
|---|---|---|---|

## 五、通用占位符检查

| 输出文件名 | 疑似占位符 | 出现位置 | 说明 |
|---|---|---|---|

## 六、替换实例预览

| 输出文件名 | 字段 | 替换前上下文 | 替换后上下文 |
|---|---|---|---|

## 七、高风险文档提示

| 输出文件名 | 风险项 | 说明 |
|---|---|---|

## 八、异常与待确认项

| 输出文件名 | 问题 | 建议处理 |
|---|---|---|

---

替换实例预览要求

为方便用户快速核对，每个输出文件应尽量抽取 1-2 处替换实例。

示例：

替换前：……甲公司同意按照合同约定……
替换后：……目标公司A同意按照合同约定……

要求：

1. 仅展示短上下文；
2. 不需要大段复制原文；
3. 不得泄露不相关正文；
4. 如未找到替换实例，应在报告中说明。

---

质量验收标准

任务完成后，应满足：

1. 输出文件数量正确；
2. 输出文件名与用户清单完全一致；
3. 用户提供的替换项已执行；
4. 未列入映射关系的内容未被修改；
5. 文档主体结构未变化；
6. 文档格式未明显变化；
7. 已检查旧字段残留；
8. 已检查通用占位符残留；
9. 已生成 check.md；
10. 异常和待确认项已明确列出；
11. 跨 runs 替换风险已处理或已明确提示；
12. 高风险 Word 特征已明确提示。

---

推荐执行口径

当用户要求执行批量 Word 替换时，按以下口径执行：

本次任务按 docx-batch-variable-replacement 技能执行。

只进行：
1. 复制原始 Word 文件；
2. 按用户本次提供的映射关系机械替换；
3. 检查旧信息残留；
4. 检查通用占位符残留；
5. 输出 check.md 检查报告。

不进行：
1. 正文重写；
2. 表达润色；
3. 内容扩写；
4. 内容删减；
5. 格式调整；
6. 结构调整；
7. 自行推断任何替换内容；
8. 改动图片、签章、附件；
9. 将 Word 内容整体转写后重新生成新文档。

所有未列入本次映射关系的内容，均视为禁止修改。

---

建议实现方式

优先使用脚本处理 .docx 文件，避免人工编辑。

实现时应注意：

1. 不得破坏原文档结构；
2. 不得重建整个文档；
3. 不得丢失样式、图片、页眉页脚、表格；
4. 替换完成后必须另存为新文件；
5. 当前 scripts/replace_docx.py 更适合作为单文件替换底层工具，默认覆盖正文、表格和页眉页脚；
6. 脚注、尾注、批注、文本框、文档属性、占位符残留汇总和 check.md 生成需要额外补充逻辑或单独复核；
7. 必须输出替换次数和残留检查结果；
8. 必须考虑 Word XML 中的 run 断裂问题；
9. 必须考虑替换链条和长短字段包含关系；
10. 必须检查通用占位符残留；
11. 必须对 .docm、数字签名、受保护文档、复杂动态域等情况提示风险。

如果工具无法安全处理复杂 Word 内容，应停止并提示用户改用更稳妥的方式，不得强行生成可能损坏格式的文件。 当用户要求批量替换 docx 变量、项目名称、单位名称、占位符时，可将 scripts/replace_docx.py 作为单文件替换组件，在外层补充批量调度、残留检查和 check.md 生成逻辑。

---

脚本调用建议

当前内置脚本 scripts/replace_docx.py 已支持两种方式：

1. 单文件替换：

python scripts/replace_docx.py input.docx output.docx 甲公司=目标公司A 张三=李四

2. 批量替换并生成 check.md：

python scripts/replace_docx.py --batch batch.json

推荐批量清单使用 JSON，对应结构示例：

{
  "template": "template.docx",
  "output_dir": "output",
  "check_fields": ["甲公司", "张三"],
  "files": [
    {
      "output_filename": "01-目标公司A.docx",
      "replacements": [
        {"old": "甲公司", "new": "目标公司A"},
        {"old": "张三", "new": "李四"}
      ]
    }
  ]
}