用途
该技能解决的是“把结构化数据填入 Word（.docx）模板并输出成品文档”的问题，同时保留模板中的品牌元素。它采用一命令清点、二写计划、三执行校验的工作方式：先清点模板，再以数据形式编写处理计划，最后应用并验证。
主要能力
- 品牌完整性：计划未触及的部分（logo、样式、主题、字体、编号、无待填内容的页眉页脚）保持字节级不变；被触及的部分也只重写承载替换值的 run。
- 占位符识别：开箱识别
{{ x }}、{x}、${x}、%x%、[x]、<x>、<<x>>、«x»、三个以上下划线、六个以上点号，以及文本或富文本内容控件。日期选择器、下拉框或数据绑定控件会被报告为不可填充。 - 处理决策：对每个标记为
!的候选逐一定夺——填充、作为普通文本保留、删除文本、删除段落或保留并标出。 - 字段定义：字段含名称、类型（string、integer、decimal、date、boolean）、格式、缺失策略（required、sentinel、empty）和来源路径（如
client.name、items[0].qty）。来源是纯路径，按 key 逐层遍历，不支持表达式、拼接、计算或汇总；需要推算的值写入该字段的literal，并会被标记供复核。 - 结构操作：删除段落、删除区间（含区间内表格）、删除行、删除单个换行或分页符、重复行（支持按分组值仅在连续行首行打印）、在指定段落后插入段落（字段值为列表时每个条目生成一段，用于多段内容）。
- 非英文区域：通过
locale设置月份、true/false 文本、分隔符和日期格式。 - 缺失值处理：缺失值按字段的 absence policy 执行，并在报告中具名指出，不静默猜测；每个字面量、哨兵、空值与未用输入都成为复核项；所有变更与计划校验，未通过则运行失败且不发布。
- 干跑与报告：
--dry-run打印每项变更的前后文本及全部复核项或阻断错误；正式执行后写report.json、attempts/<id>/，验证通过时写output/<stem>__<job_id>.docx。退出码 0 为成功、2 为需复核、1 为失败；可重复运行，失败的重跑不会删除此前已验证的文档。 - 区间删除安全性：涉及分节符、书签或批注范围的删除会被拒绝；未经
allow_large_deletion不允许删除超过一半段落；含书签、批注标记、控件或绘图的行不可重复；跟踪修订、域结果或存有类型值的控件内文本不可填充。 - 安全护栏：在代码层强制，包括不得重建文档、不得因锚点难找而在末尾追加内容、不得重建表格或行、不得编造值、不得凭文本猜测段落、不得在边界不清时扩大删除范围。
使用方式
- 清点模板：
python scripts/run_job.py inspect --template <file.docx> --workdir <dir> [--profile <profile.json>]，在<dir>/<job_id>/下生成snapshot.docx、manifest.json与plan.draft.json，并打印段落清单，候选以!（需决策）、?（可选）或x（不可填，附原因）标记。 - 将
plan.draft.json复制为plan.json并补全。可参考references/examples/plan.json与references/examples/values.json了解各决策类型、类型化与格式化字段、哨兵、派生字面量、重复行、区间删除与多段插入的写法。 - 计划包含：
decisions[]（每个!候选一条）、fields[]（名称、类型、格式、缺失策略、来源）、operations[]（如delete_paragraph、delete_range、delete_row、delete_break、repeat_row、insert_paragraph_after）、locale、notes（可选，最多 2000 字符）。 - 编写
values.json，格式为{"data": <任意 JSON 输入>}。 - 干跑：
python scripts/run_job.py execute --job <job dir> --dry-run，反复修正计划直至通过。 - 正式执行：
python scripts/run_job.py execute --job <job dir> [--out <dir>]，应用、验证并写出报告与成品文档；需将output/<stem>__<job_id>.docx复制到会话交付目录，或执行时用--out指向该目录。 - 交付前应转述结果状态、变更清单与全部复核项，并原样转达各命令打印的耗时。
ok仅表示已按模板与计划完成机器验证，并不代表有人在 Word 中打开检查过。
如遇模板族自有约定，可通过小 profile 声明额外字段正则（Python 正则，作用于段落文本，第 1 组为字段标签）、纳入范围的部件、指令标记与 locale，无需改代码。
适用场景
- 已有 Word 模板、需由结构化数据填充生成成品文档，且要求保留品牌样式。
- 需要批量或可重复地生成套版文书，并对每次变更留痕、可复核。
- 模板包含占位符、下划线空白或内容控件等常见填写约定。
限制
- 不适用于无模板的从零撰写或编辑 Word 文档、添加批注或修订、转换 .doc 或导出 PDF。
- 不读取也不写出 PDF；PDF 表单及合并拆分 PDF 应使用其他工具。
- 不处理电子表格、CSV 或任何行列数据。
- 不从文档中抽取需求或数据；本技能只把提供的数据写入模板。
- 无 .docx 模板的数据集不适用，应索取模板而非自行生成。
- 签名或启用宏的模板在清点时即被阻止。
- 无法从文件中读取分页信息；分页由 Word 排版决定，清单只显示作者强制的分页符。
- 不得编辑
manifest.json、任何哈希、references/policy.json或生成的文档。
文件结构
scripts/run_job.py：入口，含 doctor、inspect、execute、selftest。scripts/models.py：契约、严格校验、值格式化与编译步骤。scripts/inspect_template.py：段落清单、候选、发现项与计划草稿。scripts/apply_plan.py：带删除安全规则的字节级填充器。scripts/verify_document.py：独立校验器、残留扫描与变更清单。scripts/ooxml_common.py、scripts/namespace_validation.py：OOXML 基础组件。scripts/build_fixtures.py、assets/：17 个测试样本及预期结果，供 selftest 使用。references/policy.json：固定安全策略。references/profile.default.json：默认模式、纳入范围部件与 locale，可按任务覆盖。references/examples/：完整的 plan.json 与 values.json 示例，由 selftest 运行。references/contract.md：规范性契约。references/verification.md：检查项、复核代码、报告与退出码。references/template-handling.md：Word 处理难点说明。