report-to-pdf

报告转 PDF

仅当用户明确需要从现有的数据分析报告、仪表板或内嵌图表界面生成 PDF 时，才使用此技能。优先使用静态 HTML 导出文件或静态报告文件作为来源。不要依赖实时 MCP 应用内直接打印的方式；Codex MCP 应用运行在沙盒化宿主中，不提供受支持的打印／PDF 桥接功能。

预期流程为：静态 HTML → Chrome 无头打印为 PDF → 验证 PDF。如果只有实时 MCP 应用报告，先创建或获取相应的静态 HTML／导出文件作为来源。

工作流

1. 确定静态来源。

   使用静态 HTML 报告／导出文件的本地绝对路径，或由该静态导出文件提供服务的本地 URL。如果来源是实时 MCP 应用、blob 占位页、登录页面、重定向页面、不完整的查看器，或仅包含启动脚本而不含报告内容的应用外壳，请停止并先获取静态 HTML／导出文件作为来源。

   用户提供托管的制品 URL 时，先确定该 URL 是否提供可用的静态导出或包来源。如果静态导出不可用，但当前运行中仍有经过验证的制品负载，请根据该负载创建相应的静态 HTML／导出文件，并在交付说明中保留来源溯源信息。如果静态导出和制品负载都不可用，请停止并报告阻碍，不要打印实时应用外壳，也不要凭记忆重建报告。

   创建或修复静态来源时，确保可见元数据面向读者。不要将内部制品运行时字段、包处理细节或验证器／调试状态复制到报告正文、页眉、页脚或来源部分。例如，不要在 PDF 中显示“快照状态”“包路径”“小组件类型”“清单路径”“渲染器 ID”“验证状态”和本地临时路径等原始标签。如果某项运行时细节对审计或故障排查很重要，请将其保存在支持说明中，而不是放入 PDF 的可见内容中。只有当数据状态注意事项会影响解读时，才将其转化为读者易懂的表述，例如“合成演示数据”或“来源覆盖不完整”。

2. 使用 Chrome CLI 无头打印生成 PDF。

   使用环境中可用的平台专属 Chrome 可执行文件。常见示例包括 macOS 上的 /Applications/Google Chrome.app/Contents/MacOS/Google Chrome，以及 Linux 上的 google-chrome、chromium 或 chromium-browser。这是首选转换方式，因为它使用浏览器渲染引擎打印静态 HTML，通常能保留可选中文本、布局、图表、表格和打印 CSS。

   chrome \
     --headless=new \
     --disable-gpu \
     --no-first-run \
     --no-default-browser-check \
     --no-pdf-header-footer \
     --print-to-pdf=/absolute/path/to/report.pdf \
     /absolute/path/to/report.html
   

3. 如果 Chrome 不可用或无法生成有效 PDF，请使用基于渲染器的备用方案。

   使用下一个可用的本地机制渲染同一静态 HTML／导出来源，并将渲染后的页面打印或保存为 PDF。备用方案应与具体工具无关：要求是忠实渲染 HTML 后输出 PDF，而不是指定某种实现方式。不要改用模型编写的 PDF 布局、手动重绘图表，或凭记忆重建报告。

   只有满足以下条件，备用方案才可接受：

   • 静态 HTML／导出文件仍是唯一真实来源
   • 渲染结果保留报告标题、叙述内容、图表、表格、注意事项和来源详情
   • 不包含仅属于应用的控件
   • 生成的 PDF 通过与首选 Chrome 流程相同的验证检查

   如果没有可用的本地渲染器能够忠实打印静态 HTML／导出文件，请停止并报告阻碍，说明缺少的能力以及无法转换的来源文件。

4. 验证 PDF 本身。 使用 pdfinfo 或等效工具确认页数和元数据。如果 PDF 应包含可选择的文本，则使用 pdftotext 或等效工具提取文本。使用 pdftoppm 或等效工具渲染有代表性的页面，并检查是否存在空白图表、内容被裁切、来源详情缺失、不需要的控件、内部运行时元数据和布局回归。对于简短报告，渲染每一页。检查是否出现仅限应用的控件标签，例如分享、编辑、刷新、发布、工具栏、菜单和拖动操作提示，以及内部产物标签，例如快照状态、控件类型、清单路径、包路径、验证状态和本地临时路径。

5. 交付前修复问题。

   如果输出为空白、内容被裁切、图表或来源详情缺失，或包含仅限应用的界面元素，请修复静态 HTML／导出源、打印样式表或渲染器调用，然后重新生成。除非用户明确接受此限制，否则不要交付未经验证的 PDF。

6. 交付 PDF。

   返回 PDF 路径，并在有用时提供源 HTML 路径或 URL。将常规检查详情保留在辅助文件中。除非检查失败、无法进行或产生了与用户相关的注意事项，否则不要在面向用户的交付说明中列出内部检查。如果必须根据产物负载创建静态 HTML／导出源，因为托管 URL 未提供该内容，请简要说明。如果无法完成必要检查，请明确说明这一缺口。

标准

• 保留面向读者的产物内容：标题、叙述、图表、表格、注意事项、来源详情，以及其中包含的生成时间或来源时效信息。
• 删除仅限应用的控件：顶栏、分享菜单、编辑控件、刷新控件、拖动手柄、悬停菜单和仅供交互使用的操作提示。
• 从 PDF 可见内容中删除内部产物和转换元数据。不要显示原始运行时字段、实现状态、包标签、本地路径、验证器／调试标签，或仅用于应用或导出流程的状态字符串。将审计所需的内部信息保留在辅助文件中；如果数据状态会影响解读，则在 PDF 中使用面向读者的通俗说明。
• 优先使用文本 PDF，以便选择和搜索文本。只有在无法生成忠实的文本 PDF 时才使用截图／图像 PDF，并说明文本可能无法选择或搜索。
• 保留静态源文件作为 PDF 的唯一事实来源。如果存在源 HTML／导出内容，不要凭记忆重建报告。
• 通常不要从头创建由模型撰写的 PDF 作为备用方案。只有在用户接受质量限制后，才可将直接构建 PDF 作为明确标注的最后手段。
• 尽可能将生成的 PDF 辅助文件放在一起：静态 HTML 源文件、PDF 输出、提取的文本、页面预览，以及关于来源获取或渲染器回退的说明。

验证指南

交付前，使用环境中可用的本地工具验证 PDF：

• 确认 PDF 存在且非空，并检查页数和页面尺寸是否符合预期。
• 如果预期为文本 PDF，请确认文本可选择和搜索。
• 渲染或预览有代表性的页面；对于简短报告，优先检查每一页。
• 检查是否存在空白页、图表被裁切、表格缺失、来源详情缺失、不需要的应用控件，以及泄露的内部产物或转换元数据。
• 如果编辑了技能文件本身，请运行仓库常规的 Markdown 或差异检查。

可用时的示例：pdfinfo、pdftotext、pdftoppm、文件大小检查和 git diff --check。