每个仓库都会累积结构化数据，最终需要将其作为文档呈现：发布说明的变更、年度贡献者名单、API 清单、未解决风险列表。数据已经是 JSON；缺失的步骤是生成一个格式化的 PDF 或 Word 文件，供客户、审计员或经理实际打开。使用本地运行的 GroupDocs.Assembly.Mcp（与 Claude Code 并行，claude mcp add 加 dnx GroupDocs.Assembly.Mcp --yes），代理会从仓库中的 JSON 文件填充保存在仓库中的 Word 模板，并写出 PDF，无需任何人手动排版表格：

生成 4.2.0 版本的发布说明 PDF，使用 data/release-4.2.0.json 与 templates/release-notes.docx，并为 data/contributors-2026.json 中的每位贡献者生成一份贡献证书。

带有配置和故障排除的逐步版本请参见文档：How to generate a PDF or Word report from JSON data in a repository with Claude Code。

为什么不让编码代理直接写文档？

编码代理非常擅长生成数据，却相对不擅长生成文档。让它生成“PDF 格式的发布说明”，它会先写一个 Markdown 文件，然后写一个转换脚本，接着调试脚本的字体。下一次发布，它又会稍有不同地实现。输出的外观取决于转换库的默认设置，而不是贵公司正式发送的文档样式。

模板可以固定外观并将其纳入版本控制。templates/release-notes.docx 是普通的 Word 文件，内含徽标、标题样式和表格，以及若干 <<…>> 标记。布局的所有者在 Word 中编辑模板；代理从不触碰它。JSON 由发布工具生成，或由代理从 git log 中提取，这正是编码代理擅长的部分。

这也让工作可审查。修改 data/release-4.2.0.json 的 Pull Request 能逐行显示哪些变更会出现在发布说明中，审阅者可以在一分钟内读完 diff。修改生成的 PDF 的 Pull Request 则什么也看不到。将数据与布局分别存放为独立的、受版本控制的文件，并把文档视为从它们渲染的产物，这与保持源代码与构建产物分离的理念相同，且对文档同样适用。

仓库结构示例

repo/
  data/
    release-4.2.0.json       {"release":{...}, "changes":[...4 items]}
    contributors-2026.json   {"contributors":[...3 items]}
  templates/
    release-notes.docx       <<[release.Version]>>, <<foreach [c in
                             changes]>> table row, counts
    certificate.docx         <<[contributor.Name]>> ...
  out/                       GROUPDOCS_MCP_OUTPUT_PATH, in .gitignore
        |
        |  Claude Code -> GroupDocs.Assembly MCP server (local, stdio)
        v
  release-notes-4.2.0.pdf    pnair.pdf  tvarga.pdf  mrossi.pdf

调用流程

首先，代理检查模板需要哪些字段，以便告知你 JSON 是否缺失某些内容：

-> get_template_fields {"template":{"filePath":
     "repo/templates/release-notes.docx"}}
<- { "dataSourceNames": [ "release", "changes" ],
     "fields": [ "release.Product", "release.Version", "release.Date",
                 "changes[].Type", "changes[].Title",
                 "changes[].PullRequest", "changes[].Author" ] }

随后进行渲染调用：

-> assemble_document {"template":{"filePath":
     "repo/templates/release-notes.docx"},
     "data":{"filePath":"repo/data/release-4.2.0.json"},
     "format":"pdf","outputName":"release-notes-4.2.0.pdf"}
<- Assembled 'release-notes.docx' with 'release-4.2.0.json' (JSON
   object) as PDF
   Saved to: .../release-notes-4.2.0.pdf

模板的表格行会为每条变更重复一次，最后一行使用 changes.Count() 与 changes.Select(c => c.Author).Distinct().Count() 统计变更数量和不同作者数。这些数字在渲染时从数据中计算，而不是由代理预先写入。

证书采用“分支输出”：为 contributors 数组的每个元素生成一个 PDF，文件名使用贡献者的句柄：

-> assemble_per_record {"template":{"filePath":
     "repo/templates/certificate.docx"},
     "data":{"filePath":"repo/data/contributors-2026.json"},
     "recordsPath":"contributors","fileNameField":"Handle",
     "format":"pdf"}
<- Assembled 3 of 3 document(s) from 'certificate.docx' with
   'contributors-2026.json', one per record (each record as
   'contributor'), as PDF.
   Saved to:
   .../pnair.pdf
   .../tvarga.pdf
   .../mrossi.pdf

recordsPath 用于指明当 JSON 文件是对象时数组所在的路径，这是实际数据文件的常见结构。

养成习惯，而非一次性提示

在 CLAUDE.md 或 AGENTS.md 中加入几行说明，可将此过程固化为约定：

Documents for people (release notes, reports, certificates) are generated
with the groupdocs-assembly MCP server from templates/*.docx and data/*.json.
Call get_template_fields first; never edit a template. Generated files land
in out/, which is in .gitignore. Dates in JSON as yyyy-MM-ddTHH:mm:ss.

将输出文件排除在 git 之外。默认情况下服务器会写入其存储文件夹旁边；在服务器注册时将 GROUPDOCS_MCP_OUTPUT_PATH 设置为仓库的 out/ 文件夹，并将该文件夹加入 .gitignore。JSON 与模板是源码，PDF 则是构建产物，可在几秒内重新生成，提交 PDF 只会产生无法审阅的差异。

诚实的限制

  • 评估模式：每个 PDF 开头都会出现 “Evaluation Only. Created with GroupDocs.Assembly 26.7…”。用于试用尚可；在正式使用前请为服务器获取许可证。
  • 模板是受信任的输入。图片和文档标签会加载其表达式返回的路径和 URL，因此请像对待代码一样审查来自 Pull Request 的模板，并为服务器提供唯一的存储文件夹。
  • 日期：在 JSON 中写成 2026-11-03T00:00:00，并在模板中格式化（<<[release.Date]:"d MMMM yyyy">>）。我们在 UTC+2 机器上测试时，纯日期字符串会被错误地提前一天；Docker 镜像默认使用 UTC。
  • 按记录生成仅读取 JSON，maxDocuments（默认 100）可在写入前阻止异常大的数组。
  • get_template_fields 为静态查询：在 Select 或 GroupBy 投影内部计算的值不会被追踪。

FAQ

Claude Code 能否在不使用云服务的情况下，从仓库中的 JSON 生成 PDF？
可以。MCP 服务器作为 Claude Code 的子进程本地运行，直接读取你指定文件夹中的模板和 JSON。

这可以在 CI 中运行吗？
服务器本身是 MCP 服务器，需要 MCP 客户端：可以是无头模式的 Claude Code，或任何代理运行器。Docker 镜像 (ghcr.io/groupdocs-assembly/assembly-net-mcp) 是在流水线中使用的便捷方式。

Word 还是 PDF？
两者皆可。省略 format 参数则输出与模板同类型的 DOCX；"format":"pdf" 则生成 PDF。get_supported_formats 会列出每个模板支持的所有目标格式。

深入了解