jam-annotate

jam-annotate

最终交付的是一张截图 Jam，审核者能在 5 秒内看懂：框出出问题的元素，编号与描述中的条目对应，并遮盖敏感信息。jam create jam 会在上传前将标记绘制到图像中；jam agent-context 会打印完整的负载架构。

请求创建或分享 Jam 即表示授权上传。若要仅在本地进行标注或遮盖，请使用可用的图像工具并返回本地文件。不要上传，也不要登录 Jam。

设置 CLI

command -v jam >/dev/null || echo "jam is not installed"
export PATH="$HOME/.local/bin:$PATH"
jam auth status --json || jam auth login

如果 jam 不在 PATH 中，请停止并让用户从 https://jam.dev/docs/cli 安装，然后继续。不要自行安装。

退出代码 3 表示尚未登录。如果没有浏览器（CI、云端 Agent），请让用户将个人访问令牌设置为机密 JAM_TOKEN，令牌可从 https://jam.dev/s/settings/mcp 获取。切勿将令牌写入文件。

选择标记

共有 5 种。根据标记表达的含义选择：

类型	含义	编号
box	此元素是主体	是
arrow	从这里看向那里（方向）	是
text	没有可指向元素的事实	否
redact	此区域不得离开屏幕	否
blur	此区域不是重点	否

正确设置坐标

坐标是图像文件中的像素，原点位于左上角。它们不是 CSS 像素。Retina 截图为 2 倍尺寸，因此 CSS 坐标为 (120, 340) 的按钮，在图像中的坐标是 (240, 680)。

1. 截取视口，而不是整个页面，以便元素边界和图像使用相同的原点。
2. 读取图像尺寸（PNG 文件头，或驱动程序的截图元数据），再除以视口宽度。所得比值即为缩放比例。
3. 从驱动程序获取元素边界（Playwright locator.boundingBox()、CDP DOM.getBoxModel），并将每个数值乘以缩放比例。
4. 在元素边界之外额外留出 6 到 10 个 CSS 像素的空白，避免轮廓压在元素自身的边框上。

如果只有图像文件而没有驱动程序，请读取其像素尺寸，凭目测在图像像素坐标中放置标记并留出较宽的框，然后在回复中说明坐标为估算值。

CLI 会拒绝超出图像范围的标记，并指出其索引。拒绝标记通常是因为漏用了缩放比例。

了解标记的覆盖范围

方框或箭头绘制的不只是轮廓。下文中，u 是图像宽度除以 1440 的值，且至少为 1；所有尺寸均以图像像素为单位。

• 徽标：一个半径为 14u 的圆，圆心位于方框左上角，或箭头的 from 位置。徽标内侧四分之一会覆盖角落处的内容，例如图标、头像或首字母。
• 方框标签：一个高度为 29u 的标签，其底边位于方框上方 7u 处，左边缘从方框左侧向右偏移 21u。如果方框距离图像顶部不足 36u，标签会放在方框内侧的上边缘，覆盖其中的内容。
• 箭头标签：一个高度为 29u 的标签，垂直方向上与 from 对齐，并从其右侧 21u 处开始。
• 标签宽度约为每个字符 8.4u，另加 14u。
• 在图像边缘处，CLI 会将徽标和标签向内移动，使其留在图像范围内。因此，它们会比上述数值所示覆盖方框的更多区域。

因此，带标签的方框上方需要留出 36u 的空白。列表、表格或活动动态中的行间距都比这小：一行上的标签会覆盖上一行，而下一行的标签会覆盖第一行的文字。

编写

• 每个事实标注一个标记。标注 3 到 5 个。更多内容就做成视频。
• 标记绘制的内容不得遮挡读者需要阅读的文字，包括其他标记的目标。添加标签前，先检查它的文本块和徽标是否遮挡上方章节中的内容。
• 对于相邻元素（堆叠的行、相邻的按钮），分别框出每个元素，不加标签，并在编号说明中描述文字。必须在图片上添加标签时，使用箭头，并让箭尾落在有足够空间放置文本块的空白边缘，文本块放在箭尾右侧。
• 如果图标或头像位于元素开头，框选区域左侧至少留出 14u 的边距，避免徽标遮住它。
• 框出出错的元素。只有当方向本身是重点时才用箭头：例如点击后本该跳转到哪里，哪个控件更改了哪个值。将箭尾放在空白处，箭头指向目标边缘，而不是中心。
• 只有在没有对应元素时，才用文字说明事实，例如“点击后没有任何反应”。将说明放在其所描述区域附近的空白处。
• 先进行遮盖，并尽量扩大范围：电子邮件、姓名、头像、令牌、内部 URL、客户标识符。遮盖整行，而不只是其中的单词。
• 模糊用于清理杂乱内容，而非隐藏机密：侧边栏、无关行列表、演示中的人脸。模糊会柔化该区域，让视线略过它。大号文字经模糊后仍清晰可读，因此任何不得离开屏幕的内容都必须遮盖。
• 顺序就是叙事。编号按载荷顺序排列，因此标记顺序要与说明中的叙述顺序一致。
• 标签最多 5 个词，使用拉丁文字，不加句号。完整句子写在说明中。
• 颜色传达含义，同一种含义使用一种颜色。默认的 lime 表示“看这里”。有多个标记时，用 strawberry 标出出错的内容。其他颜色：grape、blueberry、mint、lemon、black。
• 标记只绘制在主截图上。secondaryScreenshotPath 会原样上传，因此主截图上的遮盖不会覆盖它。只有当辅助截图完全不包含你已遮盖的内容时，才附上辅助截图；否则先用图像工具将其遮盖，或者不要附上。

载荷

下面的截图是 2 倍图，因此 1440×900 的视口对应 2880×1800 的图像，所有坐标都扩大一倍。

使用文件写入工具将载荷写入文件（例如 payload.json），然后运行 jam create jam @payload.json。URL、标题和说明来自用户或页面，因此绝不能作为 shell 参数传入。

{
  "url": "https://app.example.com/checkout",
  "title": "Pay button does nothing on retry",
  "description": "1. The Pay button, clicked twice.\n2. Where the confirmation should have appeared.\nCard number redacted.",
  "screenshotPath": "./checkout.png",
  "screenDimensions": { "width": 1440, "height": 900 },
  "annotations": [
    { "type": "redact", "x": 1200, "y": 640, "width": 560, "height": 48 },
    { "type": "blur", "x": 0, "y": 0, "width": 480, "height": 1800 },
    { "type": "box", "x": 1180, "y": 1120, "width": 320, "height": 88, "label": "Pay, clicked twice", "color": "strawberry" },
    { "type": "arrow", "from": { "x": 600, "y": 1400 }, "to": { "x": 1440, "y": 980 }, "label": "no confirmation here" }
  ]
}

编写说明时，让其中的编号与徽标编号对应：“1.”是载荷中的第一个方框或箭头，“2.”是第二个。遮盖、模糊和文字注释均不编号。

完成后

1. 阅读回执：id、url、kind。如果命令失败，说明失败并修正载荷。绝不要提供你没有实际获取到的链接。
2. 查看绘制效果：运行 jam get screenshots <id> --out <dir>，然后打开 PNG。如果文本块或徽标遮挡了论点所依赖的文字，修正载荷，重新创建 Jam，并只分享新链接。删除第一个 Jam 前，先征求用户同意，因为删除后无法恢复。
3. 有相关链接时再添加链接。截图所属的拉取请求或工单，可使用：jam update jam <id> --resource <url>。每种 UI 状态对应一个 Jam 时，可使用 jam update jam <id> --mark-related <other jam> --type relates_to 将它们关联起来。绝不要附上带有令牌的 URL：分享页面可能是公开的。
4. 附上链接，并说明它支持的论点。只有用户要求时，才将链接发布到 PR 或工单上。

向 Jam 提交反馈

当此技能、Jam MCP 工具、jam 命令或 Jam 文档有错误、过时或令人困惑之处，或表现异常出色时，请告诉 Jam。请自行提交：Jam 的 Agent 会阅读反馈，因此无需审批。

调用 submitFeedback MCP 工具，并填写 body、category 和 subject。

MCP 不可用时，请使用 CLI：

jam feedback "<what you were doing, what you expected, what happened, the mistake>" --category <skills|mcp|cli|docs> --subject <skill name, tool name or command>

• 仅针对 Jam 界面，不涉及用户的代码或其他工具。
• 每个会话最多提交一次；如果你已自行纠正错误，则不要提交。
• 不要包含机密信息、客户数据、源代码、堆栈跟踪或录制内容。