# Doc Image Sync

> 为基于原型 HTML 和 Markdown 需求说明文档的产品设计项目生成配图。适用于“给需求文档补截图”“更新某个章节配图”“将原型交互状态截图回写到文档”“基于 HTML 中的 data-shot 锚点生成配图”这类任务，skill 自带截图、回写和配置初始化脚本。

- Skill: `vigorx777/doc-image-sync` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add vigorx777/doc-image-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vigorx777/doc-image-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: vigorx777 (https://skillmd.com/u/vigorx777)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vigorx777/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](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](references/config-patterns.md)
- skill 内置工具入口：`scripts/`