用途
该技能用于非软件产物的导出与交付。当 artifact_type 为 document、article、deck 或 visual,且需要导出 PDF、DOCX、PPTX、PNG,或提到“导出”“交付”“PDF”“PPTX”时适用。它解决“源文件看起来完成”但接收方无法打开、使用或追踪的问题,把内容交付变成可验证、可归档的流程。
主要能力
- 入口与出口:入口为非软件产物通过内容或视觉审查、准备交付;出口为最终导出文件、预览验证、版本归档和交付记录。
- 角色定位:作为制片和交付 QA,确认交付规格、导出最终格式、打开最终文件验证、记录 source/final/format/verification/known limitations,并把可编辑源文件和最终文件一起归档。
- 核心原则:source 和 final 分离;格式契约优先;最终文件必须验证;归档要能复现;限制必须显式记录;命名承载上下文。
- 决策框架:确认最终格式、确认 source of truth、执行导出、进行源文件验证与导出验证、记录证据、归档交付包、执行 Go/No-Go 判断。
- 产物类型判断:针对 document、article、deck、visual 分别给出最终交付判断标准。
- 流程:包括确认交付规格、导出最终文件、源文件验证(agent 负责)、导出验证(human partner 或 CI 负责)、记录交付证据、归档。
- 反模式与修复:提供反模式、判断方式、修复动作对照表,并给出好/坏示例。
- 验证失败处理与红旗清单:列出失败场景处理方式、常见说辞与现实后果,以及 STOP 条件。
- 输出模板:提供 Artifact Export 记录模板,包含 artifact_type、Source、Final、Format、命名规则、源文件验证、导出验证、Known limitations、归档路径。
使用方式
技能按流程执行:先从 spec 读取 artifact_type、最终格式、文件命名规则、交付路径、是否需要源文件一起归档、已通过的内容/视觉审查记录。然后按产物类型导出最终文件:document 导出 DOCX/PDF,必要时保留源 Markdown 或编辑源文件;article 导出 Markdown/HTML/PDF,必要时附封面图或元数据;deck 导出 PPTX/PDF,必要时附 speaker notes;visual 导出 PNG/SVG/PDF,必要时附源文件和尺寸说明。
随后进行两层验证:源文件验证由 agent 在导出前检查结构完整性、frontmatter 字段、内部链接可达、图片引用、元数据、格式与 spec 一致;导出验证由 human partner 或 CI 在导出后打开最终文件检查文件能否打开、页数/画布数/页面顺序或尺寸、字体/图片/表格/图表、链接/引用/speaker notes/元数据、文件名和路径。agent 在 ship 记录中标记 Export verification: pending human partner review,提示 human partner 验证;human partner 确认后标记 Export verification: passed。
之后在 docs/features/<name>/05-ship.md 或对应 ship 记录中写入交付证据,并归档最终交付文件、可编辑源文件、内容/视觉审查记录、导出验证记录、已知限制和版本说明。
适用场景
适用于 document、article、deck、visual 四类非软件产物的导出与交付,尤其在需要 PDF/DOCX/PPTX/PNG 等最终格式、需要源文件与最终文件分离追踪、需要记录验证证据和已知限制、需要归档可复现交付包的场景。
限制
不适用于 artifact_type 为 software 且需要部署到运行环境的场景(应使用 ship-workflow-ship 和部署技能);不适用于仍处于草稿阶段、内容或视觉审查未通过的情况;不适用于只做内部临时预览、不准备交付的情况。该技能明确要求导出验证由 human partner 或 CI 执行,agent 不能替代;若导出验证标记为 pending 但已声明交付完成,属于红旗。已知限制必须显式记录,不能隐瞒。