doc-snapshot-agent

适用场景

当 Markdown 文档需要真实图片时，加载此技能，例如实时网页截图、AI 生成的编辑类插图，或仅修复已处理文件中图片位置的重新运行。

在用户要求以下操作时使用：

• 为 Markdown 文章添加图片
• 处理带有图片标记的案例文件
• 为文档截取屏幕截图
• 生成文章配图并插入文档
• 重新运行或修复已处理文档中的图片位置

不要将此技能用于纯文本编辑、校对或翻译——这些任务无法从浏览器自动化或图片生成中获益，应直接处理。

架构

此技能有一个入口点（本文件）和四份用于深入了解的同级参考文档。它不会创建隐藏的记忆文件夹，不会持久化浏览器状态，也不会发送超出目标工作流所需范围的数据。

所有路径（输入案例、输出图片、配图 Markdown、缓存）都基于用户在运行开始时指定的同一个 {project-root}。浏览器操作仅通过 Playwright MCP 服务执行；生成图片则通过捆绑的 Python 脚本调用 OpenRouter。

快速开始

1. 检查 Playwright MCP 工具 — 确认 mcp__playwright__browser_navigate 和其他 mcp__playwright__* 工具可用。如果缺少，请将 references/mcp-setup.md 中的安装代码发送给用户，然后停止。
2. 确认项目根目录 — 询问一次；如果用户没有偏好，默认使用 /tmp/doc-snapshot-agent。
3. 检查现有产物 — 复用磁盘上已有的内容（参见增量执行）。
4. 解析案例文件 — 合并标题形式、HTML 注释形式和图片摘要表格中的标记。
5. 截取、生成、放置、编写 README — 按照工作流部分执行。

快速参考

主题	文件
为每个客户端安装 Playwright MCP、授予权限、运行时设置	references/mcp-setup.md
导航、快照、登录、截取、验证——完整浏览器流程和工具模式	references/browser-capture.md
构建并维护特定网站的导航知识	references/site-explorer.md
生成图片的提示词构建和脚本用法	references/image-generation.md
图片生成命令行工具	scripts/generate_image.py

方案选择

情况	最佳方案	原因
文章已在 output/{article-id}/raw/ 中包含屏幕截图，用户只想重建 Markdown	跳过截取，重新运行第 5 步（配图 Markdown）	浏览器操作开销大；重新生成 Markdown 成本低
标记类型为 screenshot，且页面可公开访问	Playwright MCP 导航 → 快照 → 截取	可靠、可检查，并能处理 JS 渲染
标记类型为 screenshot，且页面需要身份验证	使用 PLAYWRIGHT_CRED_* 环境变量通过 Playwright MCP 操作	避免在提示词和对话记录中泄露机密信息
标记类型为 generated（编辑类、主视觉、概念类）	通过 OpenRouter 使用 scripts/generate_image.py	截图无法呈现概念图像
标记落在了错误的段落	重新解析案例文件，重新应用语义位置	重新截取无法修复位置错误
运行时缺少所需的 MCP 工具	停止，并引导用户查看 references/mcp-setup.md	缺少 MCP 时无法继续工作流

工作流

步骤 0：验证 Playwright MCP

每次执行开始时都运行此检查，而不仅仅是第一次。

1. 检测名称以 mcp__playwright__ 开头的工具。必需工具：browser_navigate、browser_snapshot、browser_take_screenshot。
2. 如果缺少这些工具，请停止，并向用户提供 references/mcp-setup.md 中相应的安装片段（Claude Code、Codex、VS Code/Cursor/Kiro、Claude Desktop 或独立模式）。对于 Claude Code 和 Codex，请附上 permissions.allow: ["mcp__playwright__*"] 说明。
3. 用户安装并重启客户端后，从此处继续，而不是重新开始本次运行。

不要改用 Playwright 库直接调用，或使用任何名称没有 mcp__playwright__ 前缀的浏览器工具。缺少此前缀时，调用不会经由 MCP 服务。

步骤 0.5：确认项目根目录

询问一次：

本次运行应使用哪个目录作为项目根目录？

• 如果用户提供路径，请将其用作 {project-root}。
• 如果用户表示“没有偏好”、跳过或未回答，则默认使用 /tmp/doc-snapshot-agent。
• 如果目录不存在，请创建该目录。

后续所有路径（cases/、output/、.cache/、scripts/、references/）均相对于 {project-root}/。

建议的 {project-root}/ 内部布局：

{project-root}/
├── cases/
│   └── {article-id}.md
├── output/
│   ├── {article-id}/
│   │   ├── raw/
│   │   │   ├── A1_example.png
│   │   │   └── A2_example.png
│   │   ├── A1_example.png
│   │   ├── A2_example.png
│   │   └── README.md
│   └── markdowns/
│       └── {article-id}.md
└── .cache/
    └── screenshots/
        └── {article-id}/

约定：

• cases/ 存放源 Markdown。
• output/{article-id}/raw/ 存放原始浏览器截图——绝不覆盖此处的文件。
• output/{article-id}/ 存放最终 Markdown 所引用的后处理资源。
• output/markdowns/ 存放最终的配图 Markdown。
• .cache/screenshots/ 存放可复用的截图缓存条目。

如果用户指定了不同布局，请遵循其指示。

步骤 1：解析案例文件

合并来自以下三个来源的图片要求：

1. 行内的基于标题的截图标记
2. 行内的 `` 标记
3. Image Summary 表格

对于每张图片，记录：类型（screenshot 或 generated）、文件名、标记 ID（如有）、描述或用途、来源 URL（如有）、后处理指令（如有）、精确的行内位置（如有），以及是否仍需进行语义定位。还要检测文章中提及的目标网站。

步骤 2：准备环境

• 创建输出目录
• 检查截图缓存中是否有可复用条目
• 从环境变量加载凭据（模式：PLAYWRIGHT_CRED_{SERVICE}_{FIELD}）
• 重新确认 Playwright MCP 工具是否存在
• 如果缺少 Chromium 运行时，请运行 npx playwright install chromium（参见 references/mcp-setup.md）
• 如果目标流程需要登录/注册/邀请/验证，且尚未提供所需信息，请暂停并在采取任何特定于账户的操作前询问用户

步骤 2.5：了解目标网站

糟糕的截图通常是因为进入了错误的页面，而不是截图命令有误。截图前：

1. 检查 $IMAGE_AGENT_SITE_KNOWLEDGE_DIR/ 和 $IMAGE_AGENT_SITE_LEARNING_DIR/ 下是否已有网站知识。
2. 根据域名推导稳定的 site-key（memclaw.me → memclaw，app.felo.ai → felo）。
3. 如果 {site-key}.md 存在且内容较新，请在浏览前阅读。
4. 如果知识缺失或已过时，请运行结构化的网站探索——参见 references/site-explorer.md——并保存探索结果以供复用。
5. 将每条截图描述对应到具体页面或 UI 状态：目标 URL 或点击路径、需要显示的元素、所需的滚动/标签页/展开操作。
6. 每当浏览发现值得记录的信息时，都将新知识追加到网站知识文件中。

第 3 步：截取浏览器截图

请按照 references/browser-capture.md 中的完整导航 → 快照 → 操作 → 等待 → 截取 → 验证流程，以及具体的工具使用模式进行操作。

典型流程：

• 打开目标网站
• 如有需要，登录（凭据从环境变量中获取）
• 导航至正确的页面或 UI 状态
• 等待关键内容加载
• 如果请求的布局需要，调整视口大小
• 将截图保存到 {project-root}/output/{article-id}/raw/

命名规则：

• 如果存在标记 id，保存为 {marker-id}_{filename}（例如 A1_workspace-dashboard.png）
• 否则使用原始文件名

每次截取后，打开图像文件并确认其符合描述。检查 DOM 不能代替查看保存的 PNG。

第 4 步：后期处理截图

如果存在 Processing: 指令，则按要求处理（裁剪、调整大小、调整宽高比）。从 raw/ 复制到最终输出目录——切勿直接编辑 raw/ 中的文件。

• raw/ 保留未经修改的原始文件。
• output/{article-id}/ 存放 Markdown 引用的资源。

第 5 步：生成带插图的 Markdown

5.1 在原位替换行内标记

标题标记：

### 📷 Screenshot: A1 (workspace-dashboard.png)
Use: Show the authenticated workspace homepage
Processing: Full-width screenshot

替换为：

![Authenticated workspace homepage](../{article-id}/A1_workspace-dashboard.png)

HTML 注释标记：

替换为：

![Workspace dashboard showing Architecture Decisions](../{article-id}/architecture-decisions.png)

5.2 为没有行内标记的图像选择语义位置

对于只出现在 Image Summary 表格中的图像：

• 仔细阅读描述
• 提取关键概念
• 逐段搜索文档
• 找到最直接讨论相同概念的段落
• 将图像插入该段落之后——不要放在章节末尾或文章末尾

例如：描述为 Share panel showing team members and invite controls 的图像，应放在提到邀请队友的段落旁边，而不是一般入门章节的末尾。

5.3 处理生成的图像

对于 generated 标记，请遵循 references/image-generation.md 并调用随附脚本：

python {project-root}/scripts/generate_image.py "{description}" -o "{project-root}/output/{article-id}/{filename}"

对于文本较多的图像，请使用更强大的模型：

python {project-root}/scripts/generate_image.py "{description}" -o "{project-root}/output/{article-id}/{filename}" -m google/gemini-3-pro-image-preview

如果生成成功，插入常规 Markdown 图像引用。如果失败，插入警告块并在 README 中记录失败情况：

> Warning: AI image generation failed for {filename}

生成提示词指南：清楚说明主体；如果文章暗示了某种视觉风格，则注明该风格；指出图像用于技术文章还是教程；明确写出任何必需的可见文本。

5.4 移除 Image Summary 表格

Image Summary 块是工作流元数据。从最终的带插图 Markdown 中删除它。

第 6 步：编写 README 清单

创建 {project-root}/output/{article-id}/README.md：

# {article-id} Illustration Output

Article: {title}
Completed: {timestamp}

## Image Inventory

| Filename | Marker | Description | Size | Processing |
|----------|--------|-------------|------|------------|
| A1_example.png | A1 | Workspace dashboard | 1200x800 | resized |

## Notes

- Credentials source: environment variables
- Additional comments

## Remaining Work

- [ ] Any missing screenshot or failed generated image

返回简洁的运行摘要，其中包含：文章 id、复用了哪些图像以及新生成了哪些图像、输出 Markdown 路径、图像输出目录，以及任何失败或缺失的图像。

标记格式

此技能支持三种标记格式。同一文档可以混用这些格式。

A. 基于标题的截图标记

### 📷 Screenshot: {marker-id} ({filename})
Use: {why this screenshot exists}
Processing: {post-processing instruction}
Difference: {optional distinction from similar screenshots}

字段：marker-id 是唯一 id，例如 A1、B3-1、D3；filename 是不带标记前缀的基本文件名；Use 说明截图应传达的内容；Processing 涉及裁剪或调整大小；Difference 用于区分相似截图。

B. HTML 注释标记

截图：

生成的图像：

C. Image Summary 表格

文档末尾可以包含一张汇总表，列出所有必需的图像：

## Image Summary

| # | Type | Description | Filename |
|---|------|-------------|----------|
| 1 | generated | Description... | `hero.png` |
| 2 | screenshot | Description... | `dashboard.png` |

重要提示：

• 汇总表是完整清单
• 有些图像也会作为行内标记出现在正文中
• 有些图像只出现在汇总表中，必须在第 5.2 步中根据语义选择位置

增量执行

不要假设工作流从零开始。先检查当前状态，再从正确的步骤继续。

检查现有产物

对于给定的文章 ID，检查：

• {project-root}/output/{article-id}/raw/*.png
• {project-root}/output/{article-id}/*.png
• {project-root}/output/{article-id}/README.md
• {project-root}/output/markdowns/{article-id}.md
• {project-root}/.cache/screenshots/{article-id}/

决策规则

• 新文章 — 不存在任何文件 → 运行完整工作流。
• 截图已存在，但 Markdown 不存在 — 跳过截图采集，重新生成 Markdown 和 README。
• Markdown 已存在，且用户要求修复 — 重新解析案例文件，不重新采集截图，重新生成图片排版。
• 部分截图缺失 — 仅采集缺失的截图，然后继续。
• 用户要求重新采集特定图片 — 仅重新生成这些图片，然后重新生成 Markdown。
• 用户要求从头开始 — 忽略缓存，重新生成所有内容。

核心原则：默认采用增量处理，尽可能复用截图；将 Markdown 重新生成视为低成本操作，将浏览器操作视为高成本操作；告知用户哪些步骤会跳过、哪些会重新运行。

缓存策略

简单的基于文件的缓存：

• 目录：{project-root}/.cache/screenshots/{article-id}/
• 缓存键：截图文件名
• 如果存在匹配的缓存文件，且用户未要求刷新，则复用该文件
• 如果用户明确要求重新采集或刷新，则忽略缓存条目

核心规则

1. 只使用 MCP

所有浏览器交互都必须通过 mcp__playwright__* 工具进行。如果这些工具不可用，请停止并让用户安装（参见 references/mcp-setup.md）。不要改用直接调用的 Playwright 或通用浏览器工具——这些工具会绕过本技能所依赖的约定。

2. 点击前先获取快照，状态改变后重新获取快照

点击时必须使用最新无障碍快照中的引用，不得凭记忆操作。导航、打开模态框、切换标签页或展开折叠面板后，在执行下一步操作前重新获取快照。

3. 有意识地选择交互类型

默认使用单击鼠标左键。只有当页面语义、对网站的了解或可见的界面提示明确表明需要“打开”“重命名”“深入查看”或其他必须双击的操作时，才使用双击。仅在明确需要上下文菜单时才使用右键单击。不要将双击用作单击失败后的重试方式，也不要为了“看看会发生什么”而右键单击。双击或右键单击后，等待界面状态发生可见变化，并在执行下一步操作前重新获取快照。

4. raw/ 中的文件只写入一次

原始截图存放在 output/{article-id}/raw/ 中，并保持原样。所有裁剪、调整大小和处理都应在父目录 output/{article-id}/ 中进行。绝不要覆盖 raw/ 中的文件。

5. 重新采集前先复用

浏览器操作是成本最高的步骤。默认复用现有截图和缓存条目；仅在用户提出要求、图片缺失或图片未通过可见验证时重新采集。

6. 凭据存放在环境中

从 PLAYWRIGHT_CRED_{SERVICE}_{FIELD} 环境变量中读取凭据。绝不要硬编码凭据，也绝不要向用户回显机密；如果缺少必需变量，请明确指出其名称。

7. 遇到需要用户操作的流程时暂停并询问

如果页面要求注册、邀请、电子邮件验证、双重身份验证或入门设置，而必需的用户专属信息尚未提供，请停止并询问用户。未经用户明确输入，不要创建账户、接受邀请或编造个人资料。用户回复后，从中断的步骤继续，而不是重新开始。

8. 验证实际图片

仅有 DOM 快照还不够。每次截图后，都要打开保存的 PNG 并确认所描述的内容清晰可见、没有模态框或加载骨架屏遮挡，且语言与文章一致。如果图片不符合要求，请重新截取——不要试图在 README 中掩盖问题。

9. 语义化放置，而非堆到章节末尾

对于摘要表中的图片，请阅读段落内容，并将图片插入讨论相同概念的段落旁边。不要把剩余图片追加到文章末尾或宽泛章节的末尾。

陷阱

• 因为“更快”而改用非 MCP 浏览器工具——会破坏可复现性和 MCP 快照流程
• 凭记忆点击，而不是根据最新快照操作——偶尔能成功，之后就会时灵时不灵
• 单击无效时，把双击当作通用重试方式——通常会打开错误状态，或掩盖真正的问题
• 没有明确目的，或没有等待上下文菜单出现信号就右键点击——往往会让页面处于不明确的状态
• 加载指示器尚未消失就截图——截到的会是骨架屏
• 模态框或标签页打开后忘记重新生成快照——下一次点击会指向过期的 ref
• 只保存裁剪后的资源，丢失 raw/ 原件——恢复时需要重新完整抓取
• 把所有无法锚定的图片都追加到文章末尾，而不是按语义放置
• 将凭据硬编码，或在提示词或对话记录中回显凭据
• 把每次运行都当作全新开始——重新抓取磁盘上已有的图片
• 认为 DOM 断言意味着截图正确——始终检查 PNG
• 为特定语言的文章抓取了错误语言版本的网站

外部端点

端点	发送的数据	用途
用户要求访问的网站	任务所需的浏览器请求、表单输入、Cookie 和交互	截图抓取和已验证身份的导航
https://openrouter.ai/api/v1/chat/completions	图像生成提示词文本和请求的模型 ID	通过 scripts/generate_image.py 生成图像标记
https://registry.npmjs.org	可选安装期间的软件包元数据和压缩包	安装 @playwright/mcp 和 Chromium 运行时

不会向外部发送其他数据。

安全与隐私

离开你设备的数据：

• 发送到用户要求抓取的网站的请求
• 生成图像时发送到 OpenRouter 的提示词文本
• 安装 Playwright MCP 或 Chromium 运行时产生的可选 npm 流量

保留在本地的数据：

• 源 Markdown、生成的截图、生成的图像、插图版 Markdown 和运行说明文件
• {project-root}/.cache/ 下的截图缓存
• 环境变量（凭据和 API 密钥）——此技能会读取它们，但绝不会将其写入文件或对话记录

此技能不会：

• 创建隐藏的记忆文件或持久化的配置文件夹
• 默认在不同运行之间保留浏览器会话状态
• 将截图、生成的图像或源 Markdown 上传到任何地方
• 代表用户创建账户、接受邀请或完成验证流程
• 对凭据、API 密钥或个人数据进行硬编码或回显

信任

运行此技能时，浏览器流量会发送到你要求抓取的网站，生成提示词会发送到 OpenRouter，可选的软件包下载会通过 npm 进行。请仅在你信任的网站和图像生成服务上运行此技能。对于具有破坏性、涉及财务或医疗，或生产环境中的流程，建议使用预发布环境，并在继续之前征求用户确认。

反馈

问题和改进建议：https://github.com/Felo-Inc/felo-skills/issues