Back to Details

annotate-screenshots

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Annotating screenshots

截图标注

When to annotate

何时进行标注

Add annotations when a screenshot needs to draw the reader's eye somewhere specific — a new element, a bug, a diff — rather than leaving them to find it in the caption. A plain before/after pair is often enough; reach for annotation when "look at the top-right corner" is easier to say with an arrow than with words, or when a screenshot contains a secret that must be hidden before it's shared anywhere (uploads.sh URLs are public).
Two commands, same underlying spec format:
CommandInputTargeting
uploads screenshot <url|file.html> --annotate <spec>
captures a live pageCSS selectors (preferred) or pixel coordinates
uploads annotate <image> --spec <spec>
an existing PNG/JPEG filepixel coordinates only — selectors are rejected
Prefer selectors, resolved live, over guessing pixel coordinates. An agent estimating 
x
/
y
/
w
/
h
by eye is unreliable — it's easy to point at the wrong element or clip a box awkwardly. 
uploads screenshot --annotate
resolves a CSS selector against the real DOM at capture time (local backend only in v1 — 
--via remote
rejects selector-bearing specs up front), so use it whenever you're capturing the page yourself. Fall back to pixel coordinates with 
uploads annotate
only when you're marking up an image you already have and there's no live page to query — a screenshot someone else took, a photo, a diagram exported from elsewhere.
当截图需要引导读者关注特定位置时添加标注——比如新元素、Bug、差异内容——而非让他们从说明文字中自行查找。通常一组简单的前后对比图就足够；当“看右上角”用箭头比文字更易表达，或者截图包含必须隐藏的敏感信息（uploads.sh的URL为公开链接）时，就可以使用标注功能。
两个命令，遵循相同的底层规范格式：
命令输入定位方式
uploads screenshot <url|file.html> --annotate <spec>
捕获实时页面CSS选择器（优先推荐）或像素坐标
uploads annotate <image> --spec <spec>
已有的PNG/JPEG格式文件仅支持像素坐标——选择器会被拒绝
**优先选择实时解析的选择器，而非猜测像素坐标。**人工估算
x
/
y
/
w
/
h
坐标并不靠谱——很容易指向错误元素或框选区域位置尴尬。
uploads screenshot --annotate
会在捕获时针对真实DOM解析CSS选择器（v1版本仅支持本地后端——
--via remote
会直接拒绝包含选择器的规范），因此只要是自行捕获页面，就优先使用该命令。只有当你需要标注他人提供的截图、照片或其他来源导出的图表，且没有可查询的实时页面时，才退而求其次使用
uploads annotate
的像素坐标方式。

The spec format

规范格式

A spec is a JSON document: 
{ "version": 1, "annotations": [...] }
. 
annotations
is a non-empty array; each entry has a 
type
plus fields for that type. House style (color, stroke weight, sketchy roughness, font) is fixed and not configurable — the one style knob is a per-annotation 
color
override.
Annotation types:
TypeRequired fieldsNotes
box
x, y, w, h
(or 
selector
)		outlines a region
arrow
from, to
points (or 
selector
)
to
= element center when resolved from a selector; 
from
defaults to an offset above-right if omitted
label
text
, plus 
target
or 
at
point (or 
selector
)		a callout bubble with a leader line to 
target
draw
points
(>= 2 
[x, y]
pairs)		freeform stroke, pixel-only, no selector support
redact
x, y, w, h
(or 
selector
), optional 
style: "blur" | "solid"
hides a region (default 
solid
; always 
solid
for secrets)
svg
fragment
(raw SVG; no 
<script
, 
href=
, or 
url()
)		escape hatch, injected verbatim
Rules: a geometric annotation (
box
/
arrow
/
label
/
redact
) takes either pixel geometry or 
selector
, never both — supplying both is rejected as ambiguous. 
draw
and 
svg
never take a selector. Every type accepts an optional 
color
override.
规范是一个JSON文档：
{ "version": 1, "annotations": [...] }
。
annotations
为非空数组；每个条目包含
type
字段以及对应类型的专属字段。样式（颜色、线条粗细、手绘粗糙感、字体）为固定不可配置——唯一的样式可选项是为单个标注设置
color
覆盖默认值。
标注类型：
类型必填字段说明
box
x, y, w, h
（或
selector
）		勾勒出一个区域
arrow
from, to
坐标点（或
selector
）		通过选择器解析时，
to
为元素中心；若省略
from
，默认值为元素右上方的偏移位置
label
text
，加上
target
或
at
坐标点（或
selector
）		带引线的标注气泡，指向
target
位置
draw
points
（至少2组
[x, y]
坐标对）		自由线条，仅支持像素坐标，不支持选择器
redact
x, y, w, h
（或
selector
），可选
style: "blur" | "solid"
遮蔽指定区域（默认样式为
solid
；敏感信息必须使用
solid
样式）
svg
fragment
（原始SVG内容；不支持
<script
、
href=
或
url()
）		自定义扩展入口，会直接注入原始内容
规则：几何类标注（
box
/
arrow
/
label
/
redact
）只能选择像素坐标或
selector
中的一种，同时提供两者会因歧义被拒绝。
draw
和
svg
类型不支持选择器。所有类型都接受可选的
color
覆盖字段。

Worked example — selector mode (preferred)

示例——选择器模式（优先推荐）

Point at a specific element on a live page, label it, and redact a nearby API key, then capture and annotate in one call:
json
{
  "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" }
  ]
}
bash
uploads screenshot http://localhost:4321/settings --via local \
  --annotate ./callouts.json --out settings.png
指向实时页面上的特定元素，添加标签，并遮蔽附近的API密钥，一步完成捕获和标注：
json
{
  "version": 1,
  "annotations": [
    { "type": "box", "selector": "#save-button" },
    { "type": "label", "text": "新增：批量保存", "selector": "#save-button" },
    { "type": "redact", "selector": "[data-testid=api-key]", "style": "solid" }
  ]
}
bash
uploads screenshot http://localhost:4321/settings --via local \
  --annotate ./callouts.json --out settings.png

Worked example — pixel mode (existing image only)

示例——像素模式（仅适用于已有图像）

Annotating a screenshot you already have — no live page to query, so geometry is given directly:
json
{
  "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]
      ]
    }
  ]
}
bash
uploads annotate ./before.png --spec ./callouts.json --out ./before.marked.png
Coordinates are in image pixels, not CSS/viewport pixels — for a capture at 
--viewport 1280x800@2x
the image is 2560x1600, so pixel-mode geometry must be scaled accordingly. This is exactly why selector mode is preferable whenever a live page is available: the resolver handles device-scale conversion for you.
Read a spec from stdin with 
-
:
bash
cat ./callouts.json | uploads annotate ./shot.png --spec -
标注已有的截图——无实时页面可查询，因此直接提供坐标：
json
{
  "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]
      ]
    }
  ]
}
bash
uploads annotate ./before.png --spec ./callouts.json --out ./before.marked.png
坐标为图像像素，而非CSS/视口像素——如果以
--viewport 1280x800@2x
捕获，图像分辨率为2560x1600，因此像素模式下的坐标必须相应缩放。这也是为什么只要有实时页面就优先选择选择器模式的原因：解析器会自动帮你处理设备缩放转换。
通过
-
从标准输入读取规范：
bash
cat ./callouts.json | uploads annotate ./shot.png --spec -

Redacting secrets

遮蔽敏感信息

Every uploads.sh object is public once uploaded — see the github-screenshots skill's "Cautions" section. Before capturing or attaching a screenshot that shows an API key, token, password, session cookie, or other secret, add a 
redact
annotation with 
style: "solid"
over it. Always use 
solid
for secrets — blurred text can be recoverable, so reserve 
style: "blur"
for non-sensitive visual cleanup where the surrounding shape should stay legible, never for credentials. Do this at capture time with 
screenshot --annotate
when possible — it's one less chance to forget before the image goes anywhere public.
所有uploads.sh上传的对象一旦上传即为公开——可查看github-screenshots技能的“注意事项”部分。在捕获或附加包含API密钥、令牌、密码、会话Cookie或其他敏感信息的截图前，添加
redact
标注并设置
style: "solid"
覆盖敏感区域。敏感信息必须始终使用
solid
样式——模糊处理的文本仍可能被恢复，因此
style: "blur"
仅用于非敏感的视觉清理（需保留周围形状可读性的场景），绝不能用于凭证遮蔽。尽可能在捕获时使用
screenshot --annotate
完成遮蔽——减少图像公开前遗忘遮蔽的风险。

Workflow: capture, annotate, attach

工作流：捕获、标注、附加

  1. Capture and annotate together when there's a live page: 
    uploads screenshot <url> --via local --annotate ./spec.json ...
    . This is one call — no separate "capture then annotate" round-trip.
  2. Annotate an existing image with 
    uploads annotate <image> --spec ...
    when there's no live page (an image from elsewhere, or a second annotation pass on something already captured).
  3. Attach the result to a PR or issue — this skill stops at producing the annotated PNG. Hand off to the github-screenshots skill for hosting, embedding, and the managed attachments comment (
    uploads attach
    , 
    uploads put --pr
    , before/after tables, etc.).
Invalid specs fail fast with per-annotation error messages (
annotations[i]: <reason>
); a selector that matches nothing on the page fails the command naming the selector rather than silently skipping it. See 
uploads annotate --help
/ 
uploads screenshot --help
for the full flag reference, including 
--seed
(deterministic sketchy rendering) and 
--format json
.
  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]: <原因>
）；页面上未匹配到任何元素的选择器会直接导致命令失败，而非静默跳过。查看
uploads annotate --help
/ 
uploads screenshot --help
获取完整的参数参考，包括
--seed
（确定性手绘渲染）和
--format json
。