mcpField
A
annotate-screenshots

annotate-screenshots

github.com/buildinternet创意与媒体1959 次安装今天更新
代码仓库

关于 annotate-screenshots

annotate-screenshots 是用于截图标注的技能，可在捕获网页时或处理现有图片时添加标记。它支持按 CSS 选择器定位网页元素，也可用像素坐标标注，并能遮盖敏感区域。

主要功能

  1. 01网页截图时按 CSS 选择器标注
  2. 02现有图片按像素坐标标注
  3. 03添加框、箭头、标签和涂画
  4. 04遮盖或模糊敏感区域
  5. 05生成带标注的 PNG

适用场景

  1. 01突出网页中的新元素或缺陷
  2. 02标出截图中的差异区域
  3. 03分享图片前隐藏秘密信息

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/buildinternet/uploads --skill annotate-screenshots

安装后在 Claude Code 中输入/annotate-screenshots确认已加载。

详细介绍

为截图添加标注

何时添加标注

当截图需要将读者的注意力引向某个特定位置（例如新元素、Bug 或差异），而不是让读者自己从说明文字中寻找时，就应添加标注。简单的前后对比通常已足够；如果用箭头比用文字更容易表达“看右上角”，或者截图中含有必须在分享前隐藏的秘密（uploads.sh URL 是公开的），则应添加标注。

以下两个命令使用相同的底层规范格式：

命令输入定位方式
uploads screenshot <url|file.html> --annotate <spec>捕获实时页面CSS 选择器（首选）或像素坐标
uploads annotate <image> --spec <spec>现有的 PNG/JPEG 文件仅支持像素坐标——不接受选择器

优先使用实时解析的选择器，而不是猜测像素坐标。 Agent 凭目测估算 x/y/w/h 并不可靠——很容易指错元素，或让框线裁切得不自然。uploads screenshot --annotate 会在捕获时根据真实 DOM 解析 CSS 选择器（v1 中仅限本地后端——--via remote 会直接拒绝含有选择器的规范），因此只要是你自己捕获页面，就应使用它。只有在标注已有图片且没有实时页面可供查询时，才使用 uploads annotate 回退到像素坐标——例如他人拍摄的截图、照片，或从其他地方导出的示意图。

规范格式

规范是一个 JSON 文档：{ "version": 1, "annotations": [...] }。 annotations 是一个非空数组；每个条目都包含 type 以及该类型所需的字段。统一的样式（颜色、线条粗细、粗略手绘效果、字体）固定不变，不可配置——唯一的样式选项是为每条标注单独设置 color。

标注类型：

类型必填字段说明
boxx, y, w, h（或 selector）框出一个区域
arrowfrom, to 点（或 selector）从选择器解析时，to = 元素中心；若省略 from，则默认为右上方的偏移位置
labeltext，以及 target 或 at 点（或 selector）带引导线指向 target 的标注气泡
drawpoints（>= 2 组 [x, y] 坐标）自由绘制线条；仅支持像素坐标，不支持选择器
redactx, y, w, h（或 selector），可选的 style: "blur" | "solid"隐藏一个区域（默认为 solid；对于秘密内容始终使用 solid）
svgfragment（原始 SVG；不允许 <script、href= 或 url()）逃生通道，按原样注入

规则：几何标注（box/arrow/label/redact）必须使用像素几何参数或 selector，二者不可同时使用——同时提供会因存在歧义而遭拒。draw 和 svg 不接受选择器。每种类型都可选用 color 覆盖颜色。

工作示例 — 选择器模式（首选）

在实时页面上定位特定元素，为其添加标签，并遮盖附近的 API 密钥，然后通过一次调用完成截图和标注：

{
  "version": 1,
  "annotations": [
    { "type": "box", "selector": "#save-button" },
    { "type": "label", "text": "New: bulk save", "selector": "#save-button" },
    { "type": "redact", "selector": "[data-testid=api-key]", "style": "solid" }
  ]
}

uploads screenshot http://localhost:4321/settings --via local \
  --annotate ./callouts.json --out settings.png
工作示例 — 像素模式（仅限现有图像）

为已有截图添加标注——没有实时页面可供查询，因此需直接提供几何参数：

{
  "version": 1,
  "annotations": [
    { "type": "box", "x": 120, "y": 84, "w": 220, "h": 48, "color": "#2563eb" },
    { "type": "arrow", "from": [520, 60], "to": [360, 108] },
    {
      "type": "draw",
      "points": [
        [40, 400],
        [80, 380],
        [120, 420],
        [160, 390]
      ]
    }
  ]
}

uploads annotate ./before.png --spec ./callouts.json --out ./before.marked.png

坐标以图像像素为单位，而非 CSS／视口像素——对于使用 --viewport 1280x800@2x 截取的图像，其尺寸为 2560x1600，因此像素模式的几何参数必须按比例缩放。这正是只要有实时页面就优先使用选择器模式的原因：解析器会为你处理设备缩放转换。

使用 - 从标准输入读取规格：

cat ./callouts.json | uploads annotate ./shot.png --spec -

遮盖机密信息

上传后，uploads.sh 中的每个对象都会公开——请参阅 github-screenshots 技能的“注意事项”部分。在截取或附加显示 API 密钥、令牌、密码、会话 Cookie 或其他机密信息的截图之前，请在其上添加 style: "solid" 的 redact 标注。机密信息务必使用 solid——模糊文本可能被还原，因此 style: "blur" 仅用于非敏感的视觉清理，且应让周围形状保持清晰可辨，绝不可用于凭据。尽可能在截图时通过 screenshot --annotate 完成此操作，以免图像公开前忘记遮盖。

工作流：截图、标注、附加

  1. 有实时页面时，同时截图和标注：uploads screenshot <url> --via local --annotate ./spec.json ...。只需一次调用——无需单独执行“截图再标注”的往返操作。
  2. 为现有图像添加标注：没有实时页面时，使用 uploads annotate <image> --spec ...（例如来自其他位置的图像，或为已截取的图像进行第二轮标注）。
  3. 将结果附加到 PR 或 issue——此技能的作用仅限于生成已标注的 PNG。托管、嵌入和管理附件评论（uploads attach、uploads put --pr、前后对比表等）请交给 github-screenshots 技能处理。

无效规格会立即失败，并逐条显示标注错误消息（annotations[i]: <reason>）；如果选择器在页面上未匹配到任何内容，命令会指出该选择器并失败，而不会静默跳过。完整的标志参考请参阅 uploads annotate --help／uploads screenshot --help，其中包括 --seed（确定性草图效果渲染）和 --format json。

评论

支持 Markdown