jam-proof

jam-proof

交付内容是一个 Jam 链接。验证过程中同步录制，然后把链接交给用户。优先使用无头浏览器，其次使用单个窗口，最后才录制整个屏幕。

用户要求通过 Jam 分享录制内容时，创建 Jam。如果用户只需要本地视频，就保存在本地。将内容发布到 PR、工单或现有 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），请让用户将来自 https://jam.dev/s/settings/mcp 的个人访问令牌设置为 JAM_TOKEN 密钥。切勿将令牌写入文件。 标题和评论应是你撰写的简短陈述。切勿将用户或页面上的文本粘贴到 shell 参数中。 jam doctor 会检查录制是否就绪；jam agent-context 会打印所有命令和标志。

按以下顺序选择目标

选择第一个能展示该陈述的选项。每往下一项，画面中就会包含更多他人设备上的内容。

1. 无头 Chrome。 默认选项。它录制的是页面，而不是屏幕，因此用户可以继续工作，画面中不会出现用户自己的内容；并且这种方式在笔记本电脑、容器或 CI 中都能以相同方式运行。使用 jam record start --cdp <endpoint> 且不指定窗口或显示器，即可直接从 Chrome 获取视频，因此无需让窗口保持无遮挡，也无需让显示器保持唤醒；控制台和网络面板也会通过同一连接填充。请参阅录制由 Agent 操作的浏览器。
2. 单个窗口，适用于证明内容需要展示仅录制页面无法捕获的元素：地址栏、Chrome 对话框、文件选择器，或根本不是浏览器的桌面应用。启动你自己的应用实例；如果应用支持配置文件或数据目录，请使用全新的配置文件或目录，避免显示他人的内容。使用你启动的进程的 --pid <pid> 选择窗口：该命令会等待窗口打开，最长五秒，因此无需列出窗口，也无需担心和应用启动过程竞争。如果要录制的窗口不是你启动的，请通过 jam record windows --json 获取其 ID，并传入 --window-id。在 macOS 上使用 open -g 启动，以免应用获得焦点；并通过应用自身的自动化接口操作，而不要使用操作系统鼠标，这样就不会接管用户的光标。在 macOS 上，窗口可以位于其他窗口后方。在 Linux 上，窗口捕获是屏幕区域捕获：请使用隔离的桌面会话，或像下文录制整个显示器一样征求同意。确保该区域不被遮挡且未最小化，并保持显示器唤醒。
3. 整个显示器，最后才考虑。jam record displays --json 会列出显示器。在无人使用的设备上，无需询问即可录制：例如 CI 运行器、容器或你拥有的远程 Linux 桌面。在有人使用的设备上，录制会拍到其消息、标签页和通知，因此必须先询问并等用户同意，并说明显示器名称和大致录制时长。未回复即表示不同意。录制期间显示器不得进入睡眠状态。不带选择器且不带 --cdp 的 start 或 run 会录制整个屏幕，因此请指定目标，避免意外录制整个屏幕。

无论浏览器录制最终采用上述哪种方式，都应将 Chrome 调试端口通过 --cdp <port> 传给 jam record：这样 Jam 会包含所有标签页的控制台和网络数据，这是视频无法展示的那部分验证信息。start 会输出自己的 cdpProxy；将驱动程序连接到该代理，而不是直接连接到 Chrome，这样点击和输入也会作为操作记录下来，并标明每项操作命中的元素。

限定录制范围

jam record run 会一直录制，直到被包装的命令退出。将验证命令包装起来：

jam record run --cdp <cdp-url> --url <page url> --title "<the claim>" --json -- <verify command>

这是第 1 阶段。要进入第 2 阶段，将 --cdp <cdp-url> 替换为你启动的应用的 --pid <pid>；如果是浏览器，再加上 --cdp <port>。--url 是窗口显示的页面；Sharepage 会为其命名。

如果你要自己操作应用，且无法将其包装起来，就在后台运行应用，并在完成后发送 SIGINT。应用会停止、上传，并以 0 退出，同时在标准输出中输出回执。

jam record run --cdp <cdp-url> --url <page url> --title "<the claim>" --json > proof.json 2> proof.log &
REC=$!
# drive the steps that show the behavior
kill -INT $REC; wait $REC

录制由 Agent 操作的浏览器

这是第 1 阶段，也是通常采用的方式。Chrome 会保持无头模式：视频是 Chrome 自身捕获的页面画面，而控制台、网络和用户操作面板也来自同一个 Chrome，因此 Jam 的任何内容都不会出现在被测页面上，画面中也不会出现用户的屏幕。

如果项目自带的浏览器驱动支持 CDP，请使用它：使用 Playwright 时，通过 chromium.connectOverCDP(cdpProxy) 连接，并在脚本中操作页面；jam record 命令保持不变。如果没有这样的驱动，下面的命令会使用 agent-browser（npm i -g agent-browser，0.38 或更高版本），它自带 Chromium。如果环境中完全没有 Chrome，就无法使用第 1 阶段；请说明这一点。

agent-browser --session proof --input-mode human open <url>
agent-browser --session proof set viewport 1920 1080   # then reload: it does not apply to the open page
agent-browser --session proof open <url>
agent-browser --session proof get cdp-url          # ws://127.0.0.1:<port>/devtools/browser/…
jam record start --cdp <cdp-url> --title "<the claim>" --json   # → { session, cdpProxy }
agent-browser --session proof record start /tmp/discard.webm --cursor --fps 5   # only turns the pointer overlay on; the file is unused
agent-browser --session drive --input-mode human --cdp <cdpProxy> mouse move <x> <y>   # drive THROUGH the proxy
agent-browser --session drive --cdp <cdpProxy> mouse down
agent-browser --session drive --cdp <cdpProxy> mouse up
agent-browser --session drive --cdp <cdpProxy> wait "<what the click produced>"
agent-browser --session proof record stop
jam record stop <session> --json

使用 --cdp 且不指定窗口或显示器时，视频会以 30 fps 录制可见标签页中的页面：不含地址栏、光标或 Chrome 对话框，无需屏幕录制权限，也无需确保窗口无遮挡。

在页面加载前将分辨率设为 1920x1080，并使用 mouse move、mouse down 和 mouse up 执行点击，这样光标叠加层会显示每次点击。references/browser.md 介绍了光标叠加层规则（agent-browser 0.38 或更高版本）、其他分辨率，以及第 2 阶段下如何显示 Chrome。

通过 cdpProxy 操作浏览器，而不是直接操作 Chrome，否则点击和输入都不会被记录为操作。任何需要 DevTools URL 的工具，都应使用这个地址： chrome-devtools-mcp --browserUrl <cdpProxy>、Playwright 的 chromium.connectOverCDP。

使用 jam record stop <session> --json 停止录制，其中的 session 是 start 输出的会话标识，这样就不会误停另一个 Agent 启动的录制。回执就是 Jam。采集正常时，标准错误输出会保持安静。如果 Chrome 完全没有发送控制台、网络或用户操作事件，标准错误输出会说明这一点；这意味着采集钩子或代理实际上并未处于调用链中。将这条信息视为验证失败，并在交出链接前修复配置。

如果 jam record start 或 run 失败，请运行 jam doctor 并报告其中的 Recording 和 Screencast 行。不要交出未实际获取的链接。

让录制更易读

录制节奏应适合观看者，而不是你自己。 你通过无障碍树读取页面；页面完成绘制、动画和稳定下来之前，无障碍树早已就绪。按你的速度操作是正确的，但对观看者来说只是一闪而过，而闪烁的画面无法证明任何事情。因此，等待是证明的一部分，而不是无谓的填充。

• 从已知状态开始：重新加载页面、重启应用、清空终端。
• 等待目标元素，而不是等待固定时长：对操作产生的内容使用 wait "<selector>"。固定暂停在慢速运行时可能太短，在快速运行时又会变成空白时间；视频里一段段相同的空隙会显得像机器生成的。
• 然后给观看者留出看清变化的时间。局部的小变化需要片刻；新屏幕需要更长时间；承载核心论点的状态则需要最长时间。根据变化幅度调整停留时间，绝不要在画面仍在变化时切走——元素出现在树中，不代表观看者已经看到了它。
• 保持简短。能展示行为的 30 秒，胜过 5 分钟。
• 标题应概括论点：“深层链接会滚动到第 6 条评论”，而不是“证明”。
• 将步骤和预期结果写在 --description 中。

修复前后对比

修复 Bug 时，如果用户报告的 Jam 展示了该 Bug，就将其作为“修复前”录制。如果需要重新录制修复前后的版本，请在隔离的检出目录中使用测试数据运行旧版和修复版。保留用户的工作树。如果修复前没有有意义的录制可用，就跳过修复前录制并说明原因。

后续

1. 查看回执：始终包含 id 和 url；如果是通过 jam record 录制的，还会包含 durationMs、width、height 和录制的 target。如果录制或上传失败，请如实说明。绝不要声称拥有自己并没有的证据。
2. 有链接可附时，就附上。如果有关联的拉取请求、工单或 CI 运行，请附上：jam update jam <jamId> --resource <url>；如果 URL 无法说明资源内容，请加上 --label "<name>"。如果有缺陷 Jam，且录制显示修复有效，请标记：jam update jam <jamId> --mark-related <bug jam> --type fixes，缺陷 Jam 会显示“修复于”的反向链接。要演示某项主张时使用 proves；要关联同一工作流中的多个 Jam，或关联录制无法证实的修复时，使用 relates_to。通过 MCP 使用 addResource 和 markRelated。分享页面可能是公开的：绝不要附带含令牌的 URL。
3. 在评论能补充视频没有传达的信息时，提出发表评论。在新建的 Jam 上，于结果出现时添加一条评论：jam create comment <jamId> "<what to look at>" --at <ms>。如果是缺陷 Jam，则在展示修复有效或检查失败的位置发表评论，并附上新 Jam 的链接。用户同意后再发布；如果用户已经提出要求，则立即发布。
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 相关内容，不涉及用户的代码或其他工具。
• 每个会话最多发送一次；绝不要反馈你已自行纠正的失误。
• 不要包含机密、客户数据、源代码、堆栈跟踪或录制内容。