Doc Image Sync

Doc Image Sync

Overview

这个 skill 用于把“原型截图”收敛成一个稳定工作流：定位需求文档、优先使用 HTML 中的 data-shot 语义锚点确定截图主体、在必要时补最少的交互动作、执行 Playwright 截图，并把图片插入到目标章节。

它自带 scripts/ 下的执行脚本，可直接嵌入任何以 HTML 原型 + Markdown 文档为核心的产品设计项目中使用，不要求项目本身预置额外工具目录。

何时使用

当用户出现下面这些意图时使用：

• “给这个需求文档补一轮配图”
• “把原型截图插到需求说明文档里”
• “只更新某一节的截图”
• “帮我给新需求初始化截图配置”
• “这个章节的图不对，重新抓弹窗打开后的状态”
• “这个原型已经加了 data-shot，直接按锚点出图”

如果用户只是要做普通网页截图、浏览器测试、表单自动化，改用更通用的浏览器 skill，不要用这个 skill。

先做什么

1. 先定位目标需求目录、HTML 原型和 Markdown 文档。
2. 如果用户给的是某个需求目录，优先自动推断：
   • 📒 需求说明文档.md
   • 同目录下与文件夹同名的 .html 原型
3. 先检查原型中是否已有 data-shot="<功能锚点>"，静态区域优先基于 data-shot 定位。
4. 如果已有配置，优先复用并只更新需要的截图项。
5. 如果没有配置，使用 scripts/init-shot-config.mjs 先生成配置骨架，再补充必要的 selector 或 actions。

标准工作流

1. 构建上下文

• 识别目标需求文档、原型 HTML、截图配置文件。
• 若用户只说“补配图”，优先在当前需求目录或项目内约定的 configs/ 目录中寻找已有配置。
• 扫描原型中是否存在 data-shot；如果有，优先把它当作截图主体定位锚点。
• 若配置不存在，按 references/config-patterns.md 的规则初始化。

2. 初始化或调整配置

• 新需求：运行 node "<skill-dir>/scripts/init-shot-config.mjs" ... 生成配置骨架。
• 旧需求：优先补充或修正以下字段：
  • sectionHeading / sectionHeadingIncludes / sectionHeadingRegex
  • selector
  • actions
  • padding
  • mode
• 如用户只更新单张图，优先加 --id 限定范围。
• 选图逻辑优先级：
  • 先判断文档在讲哪个功能点。
  • 再找原型中最能表达该功能点的区域或状态。
  • 静态功能块优先用 data-shot。
  • hover、展开、下钻等动态场景保留最小必要动作，不要强行追求零动作。

3. 执行截图与回写

• 默认使用统一入口：
  • node "<skill-dir>/scripts/sync-doc-images.mjs" --config "<config.json>"
• 只更新某一项：
  • node "<skill-dir>/scripts/sync-doc-images.mjs" --config "<config.json>" --id "<shot-id>"
• 只预演文档回写：
  • node "<skill-dir>/scripts/sync-doc-images.mjs" --config "<config.json>" --dry-run --skip-capture

4. 验证结果

• 确认图片已生成到 附件/<需求名>/screenshots/latest/ 或配置指定路径。
• 确认 Markdown 对应章节下只保留一张正确图片，避免重复插图。
• 确认图片真正表达了该段文档描述的功能点，而不只是“技术上成功截到一个区域”。
• 如果截图内容不对：
  • 静态区域先检查 data-shot 是否打在正确主体上；
  • 动态区域再调整 actions；
  • 不要手改文档图片路径。

失败排查顺序

1. pagePath 是否指向正确原型文件。
2. 如果原型已打 data-shot，优先检查锚点是否命中到正确主体。
3. selector 是否能在当前状态下命中。
4. actions 是否缺少点击、悬浮、展开、等待。
5. 章节匹配是否需要从 sectionHeading 改为 sectionHeadingIncludes 或 sectionHeadingRegex。
6. 图片路径是否符合项目附件规范。

注意事项

• 不要把这个 skill 当成通用截图器使用，它的目标是“需求文档配图闭环”。
• 不要直接修改业务说明文档正文来规避章节匹配问题，优先修配置。
• 默认先最小化变更范围，优先更新单个 id，避免整批回写影响其他章节。
• data-shot 主要解决“截哪块”，不自动解决“怎么进入那个状态”；hover、展开、下钻场景通常仍需要最小动作编排。
• 不要把 data-shot 打到按钮、文案碎片或纯布局容器上，优先打在值得单独成图的功能主体上。
• 如果项目里还没有截图配置目录，直接在需求目录附近新建 configs/ 即可，没必要强制套某个固定项目结构。

参考

• 配置字段与示例：见 references/config-patterns.md
• skill 内置工具入口：scripts/