documents

文档 — PDF、Word、Excel 和 PowerPoint 技能

一个技能，涵盖四种最常见的文档格式。这四种格式共用一个 Agent 工作流——输入结构化内容，输出可渲染且经过验证的成品——因此它们归属于同一个家族技能，并为每种格式提供单独的参考文档，遵循 epub 的先例。先加载下方的共享工作流，再按需加载你实际处理的格式所对应的参考文档。

格式	扩展名	参考文档（按需加载）
PDF	.pdf	references/pdf.md
Word	.docx	references/word.md
Excel	.xlsx	references/excel.md
PowerPoint	.pptx	references/powerpoint.md
所有格式	—	references/output-quality.md

每种格式的生成模板位于 templates/，包含各格式测试样例的验证脚本位于 scripts/。

适用场景

任务涉及以下四种格式时，加载此技能：

• 生成：根据结构化内容（Markdown、JSON、数据表、提纲）创建报告、备忘录、电子表格或演示文稿。
• 编辑：就地修改现有文档的内容、布局或元数据。
• 提取：从现有文件中提取文本、表格或结构。
• 转换：在格式之间转换内容，或将数据源中的内容转换为文档。
• 验证：检查生成的成品在结构上是否可靠，并确保交付前能够正确渲染。

不适用场景

• 电子书和 EPUB — 使用 epub 技能；它负责 EPUB 容器、阅读顺序和包验证。
• 图像、视频和其他媒体 — 此技能仅涵盖文档格式；媒体制作应交由相应的媒体技能处理。
• 代码和 API 文档网站 — 使用技术文档和文档网站规范，而不是办公文档。
• 数据管道 — 原始数据的迁移或转换属于 data-engineering；此处的 Excel 是一种交付格式，而非数据存储。
• 将办公文档转换为 Markdown — 将现有办公文档（docx、xlsx、pptx、pdf、odt、rtf、epub、csv）转换为 GitHub-Flavored Markdown 属于 anydoc 技能；此技能负责生成、编辑和验证，而非从文档中提取内容并转换为 Markdown。

共享工作流

无论格式如何，每项文档任务都遵循相同的六个步骤。格式专属的详细信息放在各格式的参考文档中——在相关步骤阅读即可。

1. 明确范围

处理文件前，先明确文档的用途：

• 受众和目的 — 谁会阅读，以及文档支持什么决策。
• 格式 — PDF（固定版式、打印、存档）、Word（可编辑文本、审阅）、Excel（数据、计算）、PowerPoint（演示）。
• 限制条件 — 页数或幻灯片数、大小限制、品牌或样式约束。
• 可信数据源 — 生成文档所依据的结构化内容（Markdown、JSON、CSV、提纲），确保成品可重复生成。

2. 内容模型

渲染前，先将文档内容表示为结构化数据：

• 文本类文档应包含标题、章节/标题、正文和元数据。
• 电子表格应采用表格模型（表头、行、列类型）。
• 演示文稿应采用幻灯片提纲（每张幻灯片的标题和项目符号、演讲者备注）。
• 将内容与布局分开：内容放在模型中，布局放在模板中。这样才能低成本地重新生成文档。

3. 模板

从 templates/ 中选择目标格式的生成模板：

• templates/pdf-template.md — 固定版式 文档骨架（可直接打印的 HTML/CSS 或 LaTeX 源代码）。
• templates/word-template.md — 文字处理 文档结构（样式、标题、表格）。
• templates/excel-template.md — 工作簿 结构（工作表、单元格、共享字符串、公式）。
• templates/powerpoint-template.md — 幻灯片 演示文稿结构（幻灯片、版式、备注）。

用内容模型中的内容填充模板里的 [fill: ...] 标记。模板是内容与版式之间的约定——修改模板即可更改外观，而无需改动内容。

4. 渲染

生成产物文件：

• PDF — 将模板渲染为 PDF（使用浏览器或引擎中的打印 CSS，或使用 LaTeX 工具链）。工具说明见 references/pdf.md。
• Word / Excel / PowerPoint — 直接编写 OOXML 包（小型产物可使用标准库 zipfile 和 XML），或使用相应格式的常用库（python-docx、openpyxl、python-pptx）。有关要生成的确切包布局，请参阅各格式对应的参考文档。

5. 验证

绝不要交付未经验证的输出。运行验证脚本：

python3 scripts/validate-documents.py --render-check --json report.pdf brief.docx data.xlsx deck.pptx

该脚本会执行结构检查（容器签名、必需部分、XML 格式是否正确），并在安装了渲染器时执行渲染检查（实际渲染文件）。没有可用渲染器时，脚本会报告 unavailable，而不会失败——验证绝不会强制要求渲染器。完整的输出质量检查清单见 references/output-quality.md，也可使用 fixtures/ 中按格式提供的 fixture 文件对脚本本身进行冒烟测试：

python3 scripts/validate-documents.py --json fixtures/sample.pdf fixtures/sample.docx fixtures/sample.xlsx fixtures/sample.pptx

6. 交付

交付产物时，附上其来源信息：

• 源内容模型（以便重新生成）。
• 使用的模板版本。
• 验证结果（结构检查通过；已完成渲染检查或渲染检查不可用）。
• 任何已知偏差（替换的字体、缩小的图像、版式偏移）。

退出条件

当产物已生成、通过结构验证（且在渲染器可用时通过渲染检查），并且内容符合约定范围时，任务即告完成。交付通过验证的产物及其来源信息后即停止；除非收到新的范围说明，否则不要继续迭代版式。

脚本

所有脚本均位于相对于此技能目录的 scripts/ 中，并遵循 cli-builder 约定：使用 --json 输出机器可读结果，以非交互方式运行，错误输出到 stderr。运行时使用 --help 查看所有标志的详细说明。

validate-documents.py — 结构检查 + 渲染检查

python3 scripts/validate-documents.py report.pdf            # human report
python3 scripts/validate-documents.py --json report.pdf    # machine report
python3 scripts/validate-documents.py --render-check --json report.pdf data.xlsx deck.pptx

行为：

• 结构检查按格式进行：PDF 标头/EOF/页面对象；OOXML ZIP 容器、[Content_Types].xml、必需部分、XML 格式正确性。 通过 OLE2 魔数识别旧版 .doc/.xls/.ppt 文件。
• 渲染检查（--render-check）：使用 pdftoppm/mutool/gs 渲染 PDF， 使用 LibreOffice 渲染 Office 格式。未安装渲染器时报告 unavailable 并以退出码 0 结束（优雅降级，绝不崩溃）。
• 退出码：0 表示全部通过（或渲染检查不可用）；1 表示文件未通过结构或渲染检查；2 表示用法/I/O 错误。
• JSON 输出：顶层 status（ok / fail / unavailable / error），包含逐文件检查结果和渲染结果。

相关技能

• epub — 电子书容器技能；是该格式系列中同级技能的先例。
• data-engineering — 数据流水线和转换；Excel 在此处是交付格式，而非数据存储。
• cli-builder — 验证脚本所遵循的 CLI 约定（--json、非交互式运行、退出码）。