Skip to content

xinetzone/SpecWeave / .agents/skills/docx-template-report

docx-template-report

Verified

当用户提到'模板驱动报告'、'生成报告'、'批量报告'、'报告生成'、'模板填充'、'生成docx'、'导出Word报告'、'周报'、'月报'、'报告模板'、'docxtpl'时,必须使用此技能。提供模板驱动报告生成能力:输入校验→模板/数据准备→渲染→产物校验→交付。基于 docxtpl + python-docx,必须使用 py314 环境。不要硬编码 Word 排版——模板是唯一事实来源,代码只填数据。

Docx-Template-Report 模板驱动报告生成 Skill

本 Skill 从「Word 模板 + 结构化数据」确定性生成统一格式的 .docx 报告。 设计依据见 docx-template-report-skill-design.md(v1.1.0)。

1. Skill ID

docx-template-report

2. 功能描述

提供模板驱动报告生成能力,完成「输入校验 → 模板/数据准备 → 渲染 → 产物校验 → 交付」流程:

要素载体说明
模板.docx + Jinja2 占位符唯一事实来源,Word 内置样式
数据结构化 JSON/YAML/dict承载可变内容
渲染引擎docxtpl(依赖 python-docx)执行填充
产物校验文件存在性 + 非空 + 结构检测闭环保证

为什么用本 Skill 而非手动生成? 手动生成容易硬编码 Word 排版(样式不一致、维护成本高)、遗漏产物校验(生成损坏文件不自知)。本 Skill 封装了「模板唯一事实来源、零排版代码、闭环校验」三条原则,确保报告样式标准化、可复用、可验证。

3. 何时使用本技能

当用户提到以下任何内容时触发:

  • 「模板驱动报告」「生成报告」「批量报告」「报告生成」

  • 「模板填充」「生成 docx」「导出 Word 报告」

  • 「周报」「月报」「季度报告」「复盘报告」「评审报告」等需要格式统一的批量报告

  • 已有 Word 模板需要填充数据生成成品

  • 需要从结构化数据批量产出统一格式文档

关于触发:本 Skill 只做「模板填充生成报告」这一件事。文档分析、格式互转(docx↔Markdown/PDF)、RAG 加载、在线协作不属于本 Skill 职责。与系统内置 docx、consulting-analysis 互斥,不可同轮共存(历史格式冲突教训)。

4. 运行环境(强制)

必须使用 py314(Python 3.14.7),所有 Python 命令统一 py -3.14 前缀。

为什么锁定 py314? 本机 python 命令指向 TRAE 内置 Python 3.10.11,而 py 启动器默认版本才是 3.14.7。若不用 py -3.14 前缀,依赖会误装入 3.10 环境。

依赖安装(一次成功,无编译报错,均已 dry-run 验证 cp314 兼容):

py -3.14 -m pip install docxtpl==0.20.2 python-docx==1.2.0 lxml==6.1.2
依赖版本py314 兼容性
python-docx1.2.0requires_python >=3.9,纯 Python wheel
lxml6.1.2提供 cp314-cp314-win_amd64 官方 wheel
docxtpl0.20.2纯 Python,依赖均满足

5. 核心工作流(五步)

步骤1:输入校验 → 步骤2:模板/数据准备 → 步骤3:渲染 → 步骤4:产物校验 → 步骤5:交付

步骤1:输入校验(数据标准化前置)

  • 确认模板路径存在且为 .docx

  • 确认数据为标准结构(JSON/YAML/dict),非标准格式先收敛

  • 校验失败立即报错,不进入渲染

步骤2:模板/数据准备

  • 有现成模板 → 直接使用

  • 无模板 → 用 pandoc 从 Markdown 生成基础模板,或在 Word 中新建并加 Jinja2 占位符

  • 数据整理为渲染上下文(dict)

内置模板(templates/):

  • sample-report.docx:通用报告,三段式示例
  • tech-guide-template.docx:v2 美化版技术文档模板,科技蓝配色体系 + 三段式封面 + 深蓝表头表格 + 灰底代码块 + 标题分隔线,含封面/更新记录/多级章节/代码块/2-5列多类型表格(契约见 references/tech-guide-template.md,渲染示例见 examples/tech-guide-render-example.py)
  • xs-sdk-guide-template.docx:高保真复刻版 SDK 指南模板,以真实企业文档为基底副本构建(样式/编号链/主题/页眉表格 100% 继承源文档),含封面 sdt(标题/状态/版本/作者/日期/审核)、深色修订表行循环、TOC 域、九类正文块循环(h1-h4/p/list/shell/warn/code/2-5列表格/分页),模板已品牌脱敏(零水印/零媒体/零元数据,logo 占位按需注入)(使用说明见 references/xs-template-usage-guide.md,契约见 references/xs-sdk-guide-template.md,渲染示例见 examples/xs-render-example.py)

步骤3:渲染

# 运行方式:py -3.14 report.py
from docxtpl import DocxTemplate

doc = DocxTemplate("template.docx")
context = {
    "title": "项目周报",
    "items": [
        {"name": "任务1", "status": "完成"},
        {"name": "任务2", "status": "进行中"},
    ],
}
doc.render(context)
doc.save("output.docx")

步骤4:产物校验(错误分类)

错误类别指向处置
渲染异常(Jinja2 语法错误/未定义变量)模板报告精确占位符问题
产物校验失败(文件不存在/空/损坏)生成逻辑检查渲染链路
样式丢失模板样式改用 Word 内置样式

⚠️ 校验必须区分两个维度:doc.paragraphs 仅返回正文段落,不包含表格单元格文本。若只用 paragraphs 收集文本,会出现「报告生成了、表格数据却没进去」却误判成功的情况。须同时遍历 doc.tables 的单元格:

from docx import Document

doc = Document("output.docx")
body_text = "\n".join(p.text for p in doc.paragraphs)          # 正文段落
table_text = "\n".join(                                         # 表格单元格
    cell.text for tbl in doc.tables for row in tbl.rows for cell in row.cells
)
# 分别断言正文与表格内容,确保两者均已正确渲染
assert "标题内容" in body_text
assert "表格单元格内容" in table_text

步骤5:交付

  • 返回产物绝对路径 + computer:// 链接

  • 报告意外情况(中文编码、特殊字符)

6. 三段式最小示例(新人上手路径)

示例 A:简单字段

模板占位符:{{ title }}、{{ author }}

context = {"title": "季度总结", "author": "张三"}

示例 B:列表循环

模板占位符:{% for item in items %} {{ item.name }} {% endfor %}

context = {"items": [{"name": "A"}, {"name": "B"}]}

示例 C:表格行循环

表格行循环必须用三行分离结构:{%tr for row in rows %} 独占一个标记行 (渲染时整行移除)→ 数据行单元格只放 {{ row.col }} → {%tr endfor %} 独占 另一标记行。不可把纯标签放在数据行单元格内(会导致单元格横向增生), 不可在同一行放两个 {%tr %} 标记(会报 unknown tag 'endfor')。 详见 references/troubleshooting.md 第 7 节。

context = {"rows": [{"col1": "x", "col2": "y"}]}

7. 反模式与陷阱对策

反模式后果对策
使用系统默认 python 而非 py -3.14依赖装进 3.10 环境,违反约束所有命令统一 py -3.14 前缀
在代码中硬编码 Word 排版样式不一致、维护成本高模板唯一事实来源
与 consulting-analysis/docx 同时加载输出格式偏离 DOCX/Markdown互斥元数据 + 单一职责
用非 UTF-8 编码或 PowerShell 管道传中文中文乱码统一 UTF-8,临时文件读写
忽略产物校验生成损坏文件不自知闭环校验
表格行循环把 {% for %} 放在数据行单元格内单元格横向增生(列数 = 1+数据行数)三行分离:{%tr %} 标记行独占
同一表格行放两个 {%tr %} 标记unknown tag 'endfor'for/endfor 分属两个独立标记行
只断言文本不断言表格物理结构横向增生坏结构误判 PASS断言 len(tbl.rows)/columns
副本基底法只继承不脱敏水印/logo/截图/WPS 用户 ID 随模板分发三脱敏:图形(pict/水印/drawing 占位)+ 敏感关系(image/customXml/custom-properties)+ 元数据
脱敏只扫 document.xml水印藏 header*.xml、userId 藏 docProps/custom.xml全包遍历 .xml/.rels 关键词扫描
尝试处理修订追踪/TOC 自动更新超出 python-docx 能力边界交给 Word 模板域字段,本 Skill 不做

8. 安全检查清单(生成质量门)

  • 全程使用 py -3.14 解释器执行,未落到系统默认 3.10 环境

  • 模板已存在且为 .docx,数据为标准结构

  • 未与系统 docx/consulting-analysis 同轮共存

  • 模板使用 Word 内置样式(Heading/Normal/Table Grid),未硬编码排版

  • 产物通过存在性 + 非空 + 结构完整性校验

  • 以真实文档为基底构建时,已执行三脱敏(水印/logo 等品牌图形、媒体与 customXml 等敏感部件、docProps 元数据),全包扫描无品牌/人员关键词残留、无悬空关系引用

  • 中文内容无乱码

9. 关键参考

参考层级路径何时查阅
方案设计文档设计docx-template-report-skill-design.md理解设计背景与第一性原理推导
Jinja2 模板编写指南L2references/template-guide.md编写模板占位符时(A-2 行动项)
技术文档模板契约L2references/tech-guide-template.md使用 tech-guide-template.docx 时(数据契约/边界/反模式)
技术文档渲染示例L2examples/tech-guide-render-example.py复制即用的完整渲染脚本,覆盖 2/3/4/5 列全部表格类型
xs 模板使用说明L2references/xs-template-usage-guide.md用 xs-sdk-guide-template.docx 生成文档时(快速开始/context 字段/logo 注入/目录更新/FAQ)
xs 高保真模板契约L2references/xs-sdk-guide-template.md维护模板时(格式规范/块类型契约/三行分离机制/脱敏细节)
xs 模板构建脚本L2examples/build-xs-template.py副本基底法从源 DOCX 重建高保真模板
xs 渲染验证示例L2examples/xs-render-example.py37 项断言(表格物理维度 + H 组脱敏专项)
品牌残留扫描工具L2examples/scan-brand-residue.py副本基底模板交付前必跑:关键词/media/pict/悬空关系四查
xs 模板脱敏扫描报告L2references/xs-template-desensitization-scan.md审计模板品牌中立性时(脱敏前后对照/八项检查/低危痕迹披露/验收结论)
行循环十变体实验L2examples/debug-rowloop-patterns.py表格行循环写法对照(A-F 反模式 / G-J 三行分离)
错误分类与排查L2references/troubleshooting.md渲染异常/产物失败/乱码/行循环排查(第 7 节专项)
docxtpl 官方文档外部https://docxtpl.readthedocs.io/高级语法(条件/循环/图片)
python-docx 官方文档外部https://python-docx.readthedocs.io/底层 API 细节

10. Changelog

  • v1.3.4 (2026-08-30): 模板代号品牌中立化更名——高保真模板的原产品代号整体更名为中立代号 xs(原代号不再出现在已跟踪交付物中,旧名仅保留于品牌残留扫描工具的检测词表中):6 个文件经 git mv 重命名(模板 docx / 构建脚本 / 渲染示例 / 契约 / 使用说明 / 脱敏扫描报告),全部路径引用、Markdown 链接、frontmatter id/source、SKILL.md 索引同步更新;渲染示例演示数据全部替换为虚构中立数据(公司/作者/审核/示例命令/演示标题),渲染产物品牌词零命中;R 阶段分析脚本的本地源文档引用改为通配符定位(脚本内不固化源文件名);品牌残留扫描工具 KEYWORDS 检测词表原样保留(检测职责即检出敏感词),并作为检测签名唯一事实源:扫描器重构为可导入模块(main() 守卫),渲染示例的品牌断言统一复用其 KEYWORDS 词表;构建脚本封面字段标签化改用通用中文标签(「作 者:」「审 核:」)与版本号/日期正则为结构锚点、页眉公司名以通用后缀「有限公司」为锚点,取证分析脚本以「document.xml 第一个表格」定位封面表——检测/变换逻辑全部零硬编码敏感词。渲染示例 37 项断言全部通过。
  • v1.3.3 (2026-08-29): 新增脱敏扫描报告 references/xs-template-desensitization-scan.md——基于 OPC 全包深度取证(源基线/模板/对照模板/渲染产物四目标),含八项检查判定(水印/图形/媒体/关键词/customXml 用户 ID/元数据/悬空关系/logo 占位)、脱敏前后量化对照、3 项低危工具链痕迹完整披露(settings.xml 排版兼容标记、app.xml 编辑器标识、cp:revision 计数)与验收结论;参考表同步登记。
  • v1.3.2 (2026-08-29): 新增脱敏模板使用者指南 references/xs-template-usage-guide.md——任务导向的使用说明(环境准备/五分钟快速开始/context 全字段参考/九类正文块/InlineImage logo 注入/目录更新/品牌中立数据责任/8 项 FAQ),与维护者视角的契约文档分工;参考表与内置模板清单同步登记。
  • v1.3.1 (2026-08-29): 副本基底模板品牌资产脱敏——xs 模板构建流程新增三脱敏步骤:①删除三个页眉部件的 VML 水印(PowerPlusWaterMarkObject,源水印文字为原品牌标识)与 mc:AlternateContent 装饰图形,logo drawing 替换为 {{ header_logo }}/{{ cover_logo }} 占位(可传 InlineImage 注入,不传留空);②删除 image/customXml/custom-properties 三类敏感部件关系(12 个媒体约 1.26MB、WPS 校对缓存、含 WPS 用户 ID 的 custom.xml 随序列化排除),模板 1.25MB→43KB、部件 29→19;③docProps/core.xml 作者/修改者/标题/打印时间清空。新增 examples/scan-brand-residue.py 全包扫描工具(关键词/media/pict/悬空关系四查);渲染断言 31→37 项(B3/G4 反转 + H1-H6 脱敏专项);反模式表与安全检查清单新增脱敏条目;契约文档新增 6.1 脱敏章节。
  • v1.3.0 (2026-08-29): 新增 xs-sdk-guide-template.docx 高保真复刻版模板——以真实企业 SDK 指南为基底副本构建(styles/numbering/theme/header/media 100% 继承),含封面 sdt 六字段(标题/状态/版本/作者/日期/审核)、深色修订表三行分离行循环、TOC 域 + updateFields、九类正文块循环;配套契约文档 references/xs-sdk-guide-template.md、构建脚本 examples/build-xs-template.py、31 项断言渲染示例 examples/xs-render-example.py。确诊并沉淀 docxtpl 表格行循环正确机制:三行分离({%tr for%} 标记行 / 数据行仅变量 / {%tr endfor%} 标记行);两种反模式(数据行格内纯标签→单元格横向增生;同行双 {%tr%} 标记→unknown tag 'endfor')经 A-J 十变体实验实证(examples/debug-rowloop-patterns.py);troubleshooting.md 新增第 7 节行循环专项排查 + sdt 文本提取盲区 + 物理结构断言要求。
  • v1.2.1 (2026-08-29): 封面布局调整——品牌栏左公司名、右版本号(版本号移至右上角醒目位置);字号体系统一优化:正文/表格 11pt、H1 16pt、H2 13pt、封面标题 24pt、代码块 10pt,层级比例更协调。
  • v1.2.0 (2026-08-29): tech-guide-template v2 美化版——科技蓝配色体系重构(深蓝 #1F4E79 / 中蓝 #2E75B6 / 浅蓝 #D6E4F0);封面升级为三段式(品牌栏+大标题+信息表),带分隔线与标签列配色;表格升级深蓝表头白字 + 灰网格边框;代码块升级浅灰底纹 + Consolas 等宽字体;一级标题增加蓝色下分隔线;新增封面信息表字段(doc_status/doc_version/doc_date/doc_author);示例脚本同步升级为 12 项断言校验;契约文档新增设计规范章节(配色/字体/页面布局)。
  • v1.1.0 (2026-08-29): tech-guide-template 扩展:单 4 列表格升级为 2/3/4/5 列四种预置表格(按 tbl.cols 条件切换),sec.table 改为 sec.tables 列表支持多表格;新增 examples/tech-guide-render-example.py 渲染示例脚本(覆盖全部列数类型 + 产物校验);更新契约文档 v1.1.0。
  • v1.0.1 (2026-08-29): 新增 templates/tech-guide-template.docx 技术文档模板(从真实 SDK 使用指南萃取,含封面/更新记录/多级章节/代码块/4列参数表),配套契约文档 references/tech-guide-template.md。
  • v1.0.0 (2026-08-29): 初始版本,封装模板驱动报告生成能力(输入校验→渲染→产物校验五步工作流 + 三段式示例 + 6 条反模式),运行环境锁定 py314。
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 196kUpdated Claude CodeCodexVerifiedInstall