简体中文 | English
一个 Codex skill 及辅助脚本，用于复制 .docx 模板并按用户提供的替换映射进行批量文本替换。
方式 1：在 Codex 对话中直接安装本 skill：
$skill-installer https://github.com/kuliantnt/docx-batch-variable-replacement
方式 2：通过 npx skills 安装到 Codex：
npx skills add kuliantnt/docx-batch-variable-replacement -a codex全局安装：
npx skills add kuliantnt/docx-batch-variable-replacement -g -a codex查看仓库中可安装的 skill：
npx skills add kuliantnt/docx-batch-variable-replacement --list安装完成后，重启 Codex 以加载新 skill。
在 Codex 对话中，直接点名使用本 skill，并提供原始 Word 文件、输出目录、输出文件名和替换映射即可。
示例：
使用 docx-batch-variable-replacement skill 处理这批文件。
原始文件：template.docx
输出目录：output/
文件：01-目标公司A.docx
甲公司 → 目标公司A
张三 → 李四
13800000000 → 13900000000
文件：02-目标公司B.docx
甲公司 → 目标公司B
张三 → 王五
13800000000 → 13700000000
每次任务建议至少提供：
- 原始 Word 文件路径
- 输出目录
- 每个输出文件名
- 每个文件对应的替换映射
- 需要重点检查残留的旧字段
替换清单不必固定为一种格式，文本、Markdown 表格、JSON、CSV、Excel 都可以。
本项目适用于重复性文档定制场景，例如：
- 为多家公司生成同一份合同
- 为多个客户创建项目专属版本的提案
- 批量生成多个客户专属的报价文件
- 批量替换多个 Word 文件中的占位符、公司名称、联系人、电话、地址和项目名称
该工具设计范围较为聚焦，仅做以下事情：
- 复制 Word 模板
- 应用用户提供的明确替换映射
- 扫描残留的旧值和常见占位符
- 生成检查报告
不做内容的撰写、改写、润色、扩展、精简或重组。
SKILL.md：Codex skill 定义及运行规则scripts/replace_docx.py：用于单文件和批量替换的 Python CLI
- Python 3
python-docx
安装示例：
pip install python-docx- 默认严格替换
- 默认区分大小写
- 全角与半角字符视为不同字符
- 仅处理当前任务中明确提供的字段
- 优先处理较长的源字符串，以减少子串冲突
- 执行前检查重复、冲突、链式和重叠的替换规则
脚本还会处理跨多个 Word run 的文本片段，不仅依赖简单的 paragraph.text.replace(...)。
当需要从一个模板生成一个输出文档时使用单文件模式。
python scripts/replace_docx.py input.docx output.docx "Old Company=New Company" "Alice=Bob"可选参数：
python scripts/replace_docx.py input.docx output.docx "Old=New" --no-backup
python scripts/replace_docx.py input.docx output.docx "Old=New" --backup-dir backups/行为说明：
- 默认创建备份
- 输出替换命中次数
- 报告未命中的替换键
- 输出对不支持的 Word 结构的已知风险提醒
当需要从一个模板生成多个输出文件时使用批量模式。
python scripts/replace_docx.py --batch manifest.json可选覆盖参数：
python scripts/replace_docx.py --batch manifest.json --template template.docx --output-dir output/
python scripts/replace_docx.py --batch manifest.json --backup --backup-dir backups/支持的清单格式：
.json.txt.md.csv.tsv
原始文件：template.docx
输出目录：output/
文件：01-Company-A.docx
Old Company -> Company A
Alice -> Bob
13800000000 -> 13900000000
文件：02-Company-B.docx
Old Company -> Company B
Alice -> Carol
13800000000 -> 13700000000
注意：纯文本清单目前使用 replace_docx.py 中实现的中文字段标签，即使替换对本身是英文的。
{
"template": "template.docx",
"output_dir": "output",
"check_fields": ["Old Company", "Alice"],
"files": [
{
"output_filename": "01-Company-A.docx",
"replacements": [
{ "old": "Old Company", "new": "Company A" },
{ "old": "Alice", "new": "Bob" }
]
},
{
"output_filename": "02-Company-B.docx",
"replacements": [
{ "old": "Old Company", "new": "Company B" },
{ "old": "Alice", "new": "Carol" }
]
}
]
}| output_filename | old_company | new_company | old_contact | new_contact | check_fields |
| --- | --- | --- | --- | --- | --- |
| 01-Company-A.docx | Old Company | Company A | Alice | Bob | Old Company,Alice |
| 02-Company-B.docx | Old Company | Company B | Alice | Carol | Old Company,Alice |表格型清单中，解析器会查找以 old_xxx 和 new_xxx 配对的列名。
批量模式会生成：
- 生成的
.docx文件 - 名为
check.md的 Markdown 检查报告
报告内容包括：
- 输入摘要
- 每个输出文件的生成状态
- 替换计数
- 残留旧值发现
- 常见占位符发现
- 替换预览
- 高风险警告
- 需要人工复核的问题
以下 Word 内容尚未完全覆盖，需要人工复核：
- 脚注
- 尾注
- 批注
- 文本框
- 文档属性
- 复杂域代码
- 目录
- 水印
- SmartArt
- 图片内文本
仅支持 .docx 格式。.doc、.docm、已签名文档、受保护文档及其他高风险结构不在支持范围内。
本项目设计用于确定性替换，而非内容创作。
- 不得自行编造替换值
- 不得自行推断公司名称、联系人、地址、日期、金额或项目编号
- 不得修改未在当前映射中明确列出的文本
- 如果映射存在冲突，应停止并修正清单，而不是猜测
MIT
- 为多个签约方生成合同变体
- 为多个客户生成提案变体
- 为多个项目生成验收或交付文档
- 包含不同公司、联系人或项目信息的投标或响应文件包