word-template-fill

这是一个”基于 Word 模板填充”的 skill。它适合把 Markdown 或结构化内容写入已有的 .docx 模板，通过克隆模板元素保留页面、段落、标题、表格、编号和字体格式；最终分页仍需排版引擎验证。

它的核心原则是：模板只读，先复制模板，再在副本中替换内容。不会把 Markdown 直接转换成一个全新的 Word 文档，也不会覆盖原模板。

目录结构

word-template-fill/
├── SKILL.md                         精简的 skill 入口与流程选择
├── README.md                        项目用法与开发说明
├── scripts/
│   ├── inspect_docx.py              模板检查命令
│   ├── fill_docx.py                 字段填充命令
│   ├── render_markdown_into_docx.py Markdown 迁移命令
│   ├── verify_rendered_docx.py      逻辑校验命令
│   ├── wps_finalize.py              WPS 更新命令
│   ├── template_profile.py          旧模块导入兼容入口
│   └── word_template_fill/          Python 实现包
│       ├── __init__.py
│       ├── markdown.py             Markdown 块解析
│       ├── inspect_docx.py
│       ├── fill_docx.py
│       ├── render_markdown_into_docx.py
│       ├── template_profile.py     模板结构发现
│       ├── verify_rendered_docx.py
│       └── wps_finalize.py
├── references/
│   ├── filling.md                  字段填充流程与约束
│   ├── fill-plan.md                填充计划格式
│   ├── markdown-migration.md       正文迁移与验证规则
│   ├── profile-format.md           profile 格式
│   └── finalization.md             WPS、分页与字体处理
└── tests/
    └── test_workflows.py            命令入口与核心行为回归检查

基本用法

1. 检查模板

python3 scripts/inspect_docx.py 模板.docx --summary --output 模板摘要.json

需要精确定位段落时，再去掉 --summary 生成完整清单。

2. 按占位符替换

python3 scripts/fill_docx.py 模板.docx 计划.json 输出.docx --report 替换报告.json

计划文件使用 references/fill-plan.md 中的格式。输出路径必须和模板路径不同。

3. Markdown 整体迁移

python3 scripts/render_markdown_into_docx.py \
  模板.docx \
  内容.md \
  输出.docx \
  --profile profile.json \
  --cover-title "XXX软件" \
  --report 渲染报告.json

该模式适用于 Markdown 内容要替换模板正文主体的情况。渲染器会在运行时从模板发现以下结构约定：

按列数在旧正文范围内找规整的原生表格族作为克隆样板（列宽/边框/单元格样式原生）；
按结构特征（两级表头 + vMerge 序号列 + gridSpan 文档标题）识别需求正/反向跟踪表，方向由文档标题顺序推断，每张表独立编号、都从 1 开始；
自动发现带自动编号的单元格样式，纯文本单元格换成普通样式，杜绝幽灵序号；
识别并剥离”样式级把每一行都标成重复表头”的模板 bug。

Markdown 内容约定（写在源文档里的语义标记）：

写法	效果
独立一行 `表：标题` / `图：标题`	下方表格/图获得 SEQ 域编号 + 正文 REF 交叉引用
围栏块	按结构自动分类：闭环框线 → 固定 Netrans 示例图（仅适用于相符内容）；单行箭头流 → 正文；其余 → 原生代码样式
单元格内 `^`	纵向合并，渲染成真正的 vMerge，符号不进文档
`文档结束`	GJB 惯例黑色粗实线，不是文字

--profile 指向的 JSON 是每次任务的输入，不是 skill 自带文件：锚点引用的是当前模板封面上的原文，换模板必须现写。格式见 references/profile-format.md。不带 profile 也能渲染，只是封面等前置部分保持模板原文。

4. 渲染后逻辑校验（自动，也可手动复查）

每次渲染结束，校验器自动重读生成的 docx 和源 Markdown，检查表格结构（vMerge 孤儿、gridSpan 足迹）、编号（未定义 numId、双重编号、序列表共享计数器）、域（悬空 REF、SEQ 稠密性）、内容（表格单元格丢失、合并符/Markdown 语法泄漏）。任何 error 级发现，输出文件直接删除，不交付。

也可以对任意已渲染文档单独运行：

python3 scripts/verify_rendered_docx.py 输出.docx 内容.md

5. 可选的 WPS 更新

如果本机 WPS 和 pywpsrpc 可用（运行时需另行提供，可放到 skill 根目录 .vendor/ 下，或安装到 Python 环境），可以只更新 DOCX 内的目录、图表编号和页码：

python3 scripts/wps_finalize.py 输出.docx --report wps报告.json

PDF 不是默认输出。只有明确需要 PDF 或必须进行视觉复核时，才把 PDF 路径作为第二个参数传入。

字体

生成器不会修改模板中的 rFonts 来伪造字体。若当前目录提供了用户有权使用的字体文件，先检查内部名称：

fc-scan simsun.ttc
fc-scan SimHei.ttf

然后安装到当前用户字体目录并刷新缓存。例如：

mkdir -p ~/.local/share/fonts/WordTemplateChinese
cp simsun.ttc SimHei.ttf ~/.local/share/fonts/WordTemplateChinese/
fc-cache -f

宋体/黑体等字体可能受授权限制，请只使用用户提供且有权使用的字体文件。

已知限制

WPS 不可用时，脚本只能保证 OOXML 结构和更新域标记，不能声称目录页码已经重新分页。
模板自身可能含有错误的表格样式或隐藏编号属性；skill 会在输出副本中清理这些属性，但不会修改原模板。
如果没有真正的模板字体文件，Linux/WPS 的屏幕显示可能仍与 Windows 略有差异；这属于字体环境问题，不应通过修改 DOCX 字体名来掩盖。
框图渲染（闭环框线块 → 嵌入图片）需要 Pillow。
当前闭环框图函数写死了 Netrans 示例内容，并依赖固定的 Noto 字体路径；它还不是通用框图渲染器，不可用于其他内容。

开发与验证

使用 Python 3.10 或更新版本。检查、字段填充和不含框图的 Markdown 迁移只依赖标准库；Pillow 和 WPS RPC 按对应功能另行准备。

命令入口保留在 scripts/，实现改动集中在 scripts/word_template_fill/。从其他 Python 程序使用时，将 scripts/ 加入模块搜索路径，再导入 word_template_fill 的对应模块。新增模式的详细操作规则放入 references/，并从 SKILL.md 链接。

python3 -m unittest discover -s tests -v

测试使用临时生成的最小 OOXML 包，验证跨 run 占位符替换、原模板保护、段落锚点保护、Markdown 解析和逻辑校验，以及从其他工作目录调用命令。真实模板排版和 WPS 分页仍需在具备模板及 WPS 的环境中复核。

skill-up 端到端评测

evals/ 下是 skill-up 评测套件：三个真实 agent 用例（占位符填充、Markdown 正文迁移、错误锚点拒绝）。

skill-up run            # 需要 PATH 上有 skill-up，或直接调用其绝对路径

关键约定：

skill-up 安装 skill 时始终排除 evals/ 目录，因此用例不能依赖 skill 目录里的脚手架文件。测试输入改为 evals/fixtures/workspace/input/ 下的预生成 fixture，由每个用例的 context.repo_fixture 复制进 agent 工作区。
fixture 由生成器产出，模板结构改动后需要重新生成：
```
python3 evals/make_fixture.py evals/fixtures/workspace/input
```
判定分两层：expect 做文件存在性快速门控，judge.type: script 调用 evals/fixtures/scripts/check_*.py 直接读产物 DOCX，检查占位符是否替换、原生表格/样式是否保留、原模板是否只读、错误锚点是否被拒绝。脚本退出码 0 视为通过，stdout 作为评分理由。
evals/eval.yaml 默认引擎为 claude_code；若本机 codex 可用，可用 --engine codex 覆盖。
产物与报告写入 .skill-up-results/iteration-<N>/。agent 需要能在自己的宿主环境里读写会话状态（如 ~/.claude/），在受限沙箱里运行会因只读文件系统而整例失败。