screenshot

Screenshot Skill — 通用 HTML 截图

环境依赖：Node.js 18+ · puppeteer-core（首次运行自动装到 tmp/screenshot-deps/）· Edge / Chrome / Chromium（系统已有任一即可，跨平台自动探测）

1. 定位

只做一件事：把 HTML 或本地 URL 渲染成 PNG。

做：

• 启动 headless 浏览器
• 设置 viewport
• 打开 source（本地 HTML / file:// URL）
• 按配置依次执行 setup_js（可选 raw JS hook）→ wait_selector / wait_ms → 截图（全页或 selector）
• 自适应宽度（fit_to_selector 自动扩 viewport，源自原 flowchart-screenshot 能力）
• 输出 PNG 到 tmp/screenshots/<task-id>/

不做：

• 不上传任何外部文档系统（属项目配备的发布 skill，如 feishu-publish）
• 不生成 PRD/spec / 不写需求文档（属 prd-writer / requirement-analysis）
• 不长期保留图片——任务结束 tmp/ 整体清理；调用方需要长期保留则显式移到 assets/
• 不实现业务交互 DSL——不接受 actions: [openWizard, goToStep:2] 这类业务步骤抽象。复杂交互让调用方在 setup_js 里写 raw JS（可访问 page 和 sleep）

定位澄清（与 Claude in Chrome 互补，勿混）：本 skill = HTML / URL → 静态 PNG 归档（headless 出图，供入库 / 发布引用）；交互式页面的实时调试核对（边改边看视觉 / 动效 / 交互）走 Claude in Chrome 扩展 + 本地 http server 流程（见 html-demo / prd-writer/html-prototype.md）。两者互补：前者沉淀静态图，后者驱动实时调试，不互相替代。

2. 输入输出契约

2.1 配置文件（JSON）

示例中 <iteration-dir> 占位符 = 调用方的子需求目录（定义见 prd-writer/html-prototype.md 「落盘路径」）；不经 prd-writer 直接调用时，source 填实际 HTML 路径即可。

{
  "source": "<iteration-dir>/prototypes/index.html",
  "task_id": "T-20260429-001",
  "viewport": { "width": 1440, "height": 900, "deviceScaleFactor": 2 },
  "captures": [
    {
      "name": "01-entry",
      "wait_ms": 800
    },
    {
      "name": "02-step1",
      "setup_js": "await page.evaluate(() => openWizard()); await sleep(500);"
    },
    {
      "name": "03-step2-upload",
      "setup_js": "await page.evaluate(() => goToStep(1)); await sleep(400);"
    },
    {
      "name": "00-flowchart",
      "selector": ".mermaid svg",
      "fit_to_selector": ".mermaid svg",
      "wait_selector": ".mermaid svg",
      "wait_timeout": 45000,
      "wait_ms": 2500
    }
  ]
}

2.2 字段说明

字段	类型	必填	说明
source	string	△	默认页面：HTML 文件路径（相对 cwd 或绝对）/ file:// URL / http(s):// URL。与 captures[].source 二选一——两者皆无时该 capture 报错 既无顶层 config.source，也无 cap.source
task_id	string	否	输出子目录名；省略时用 YYYYMMDD-HHmmss-<8位hash>
viewport	object	否	默认 {width:1440,height:900,deviceScaleFactor:2}
captures[]	list	是	每项一张截图。字段名就是 captures——写成 items 之类不报错，静默产出 0 张图
captures[].name	string	是	输出文件名（不含 .png）
captures[].source	string	△	覆盖顶层 source（与上一次不同则重新 goto）。每个 Mermaid 块各渲一个 HTML 时用它，此时顶层 source 可省略
captures[].selector	string	否	CSS 选择器；省略则全页 (fullPage: true)
captures[].setup_js	string	否	raw JS（async body），打开页面后、截图前执行；可访问 page 和 sleep(ms)
captures[].wait_selector	string	否	截图前等待该 selector 出现（page.waitForSelector）
captures[].wait_timeout	number	否	wait_selector 超时（默认 30000ms）
captures[].wait_ms	number	否	截图前固定等待（默认 0）
captures[].fit_to_selector	string	否	测量该 selector bounding box 后，扩大 viewport 重新渲染（自适应宽度）