name: artifact_pdf
metadata: { "includeInPrompt": false }
description: Build, revise, or manipulate a fixed-layout PDF (report, guide, one-pager, printable document). Use whenever a build task's artifact kind is pdf, a document build's output format is pdf, or the task reads, merges, splits, crops, or fills an existing PDF, including fillable AcroForms. Covers authoring the print-CSS HTML source, rendering, the geometry and validation gates, existing-PDF manipulation and form filling, and delivery under workspace/your_files.
PDF artifacts / PDF 产物
A PDF is authored as HTML with print CSS and rendered through the
shared capture engine. The kept source under .src/ is the editable truth
for every future revision; the PDF binary is always regenerated, never
patched.
PDF 以带打印 CSS 的 HTML 编写，并通过共享的截图（capture）引擎渲染。.src/ 下保留的源文件是后续每次修订时可编辑的事实来源；PDF 二进制文件总是重新生成，绝不打补丁。
【评论】“始终重新生成、绝不打补丁”的约定让产物状态可复现，避免了在二进制上做增量修改带来的不可追溯性。
| Task | Read first |
|---|---|
| Any PDF build or edit | /opt/hatch/skills/artifacts/pdf/references/workflow.md (the workflow: authoring, render, gates, validation loop) |
| Design and layout | /opt/hatch/skills/artifacts/pdf/references/visual.md |
| What the words say: outline, headings, tone, the prose read-back | /opt/hatch/skills/artifacts/references/prose.md (shared) |
| The document plots data | /opt/hatch/skills/artifacts/references/charts.md (shared) |
| The document shows a place or a map | /opt/hatch/skills/artifacts/references/maps.md (shared) |
| Read, merge, split, or extract from an existing PDF; fill a PDF form | /opt/hatch/skills/artifacts/pdf/references/existing-pdfs.md |
| 任务 | 先读 |
|---|---|
| 任何 PDF 构建或编辑 | /opt/hatch/skills/artifacts/pdf/references/workflow.md（工作流：编写、渲染、门禁、验证循环） |
| 设计与布局 | /opt/hatch/skills/artifacts/pdf/references/visual.md |
| 文字内容：大纲、标题、语气、文稿朗读 | /opt/hatch/skills/artifacts/references/prose.md（共享） |
| 文档绘制数据图表 | /opt/hatch/skills/artifacts/references/charts.md（共享） |
| 文档展示地点或地图 | /opt/hatch/skills/artifacts/references/maps.md（共享） |
| 读取、合并、拆分或提取现有 PDF；填写 PDF 表单 | /opt/hatch/skills/artifacts/pdf/references/existing-pdfs.md |
Scripts / 脚本
| Script | What it does |
|---|---|
/opt/hatch/skills/artifacts/scripts/render_audit.mjs (shared) |
Renders the HTML source to PDF and PNGs and runs the render gates; workflow.md names the flags |
/opt/hatch/skills/artifacts/scripts/validate_pdf.sh |
Integrity, page metadata, data-URI embedding, full rasterization; run until it passes |
| 脚本 | 作用 |
|---|---|
/opt/hatch/skills/artifacts/scripts/render_audit.mjs（共享） |
将 HTML 源渲染为 PDF 与 PNG，并运行渲染门禁；各标志的说明见 workflow.md |
/opt/hatch/skills/artifacts/scripts/validate_pdf.sh |
完整性、页面元数据、data-URI 嵌入、完整栅格化检查；运行直到通过 |
Verification / 验证
Follow /opt/hatch/skills/artifacts/testing/SKILL.md: run the gates, then read every
validation PNG before returning a link.
遵循 /opt/hatch/skills/artifacts/testing/SKILL.md：先运行各门禁，然后在返回链接之前逐一查看每张验证 PNG。
【评论】将“在返回链接前查看每张验证 PNG”设为强制步骤，属于对自动化渲染结果的人工兜底质检设计。