jam-proof-table

jam-proof-table

多条主张，一张表格：记录你说的每件事是正常还是有问题、其状态，以及能证明这一点的 Jam。用户应能一键核实每条主张，无需再问“这件事对应的 Jam 在哪儿？”

要记录新的 Jam，请使用 jam-proof。此技能负责命名、归档、检查和报告 Jams。

设置 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。绝不要将令牌写入文件。 jam agent-context 会打印所有命令和标志。

1. 一条主张对应一个 Jam

一行就是一条主张：“价格不再被截断”“退出登录后可以正常登录”。每行都要有一个能展示该主张的 Jam。如果一个 Jam 涵盖多条主张，请为每行标明对应画面出现的时间（at 0:48）。

没有 Jam 的主张仍要保留在表格中，标为“未记录”。绝不要将本地视频文件或截图路径列为 Jam。

2. 为每个 Jam 命名并归档

标题决定了人们之后如何找到 Jams。使用 <工单或来源> <展示内容>。如果某个 Jam 用于检查先前 Jam 对应问题的修复，则沿用该 Jam 的标题，并在前面加上“fix check: ”，这样两个 Jam 就能通过一次搜索找到。

jam list folders --query "Release 4.2 checks" --json      # reuse it if it exists
jam create folder "Release 4.2 checks" --json             # otherwise; returns its id
jam update jam "$ID" --folder "$FOLDER_ID" --title "ENG-412 fix check: Pro price wraps"

每次调用 jam create folder 都会新建文件夹，即使已有同名文件夹也一样，所以先查找，再传入 ID。每次运行只建一个文件夹。 创建文件夹可能会将 Viewer 升级为 Creator，从而改变席位计费；如果是 Viewer 账户，请先询问。 除非用户提出要求，否则只重命名和移动本次运行记录的 Jams。

3. 查找已有的 Jams

再次记录之前，先查找该 Jam。某次运行的文件夹是找到该次运行全部 Jams 最可靠的方式：

jam list folders --query "checks" --json
jam list jams --folder "$FOLDER_ID" --json
jam list jams --created-at -P1D --json                    # created in the last day
jam list jams --query "price" --order-by createdAt --limit 20 --json
jam list jams --url "https://example.com/pricing" --json

--query 是模糊搜索，不是标题筛选：使用搜索结果之前，请逐一阅读标题。--order-by createdAt 会按最新到最旧的顺序列出，因此 --limit 会排除最早的结果。

“我给你的 Jam 是哪个？”应先查看对话：在其中搜索 jam.dev/c/，然后再搜索工作区。

4. 列出每个 Jam 前先检查

jam get jam "$ID" --json                                  # reads back, type, duration

然后按 type 检查；其他类型都没有视频帧：

jam get frames "$ID" --at 48000 --size medium --out "$(mktemp -d)"   # video; outside the repo
jam get screenshots "$ID" --out "$(mktemp -d)"                       # screenshot

回放没有视频帧或截图：请检查其中的事件、控制台和网络信息；如果这些信息无法确定主张是否成立，请将该行标记为未确认。

对于视频，请打开主张出现时的画面；--at 必须小于 Jam 的 duration。空白页面、单张静止画面或错误的标签页都不能作为证据。截图本来就是一张静态图：如果主张在图中清晰可见，它就能作为证据。如果 Jam 未展示该主张，请用 jam-proof 重新记录，并说明你已这样做。

有些主张发生在屏幕之外：API 状态、数量、已发送的消息。请通过 jam get network、jam get console 或 jam get user-events 检查，并在表格中说明视频展示了哪部分、事件展示了哪部分。

5. 编写表格

保持工作完成时的顺序。每条主张的状态只能是以下之一：正常、有问题、未确认（Jam 无法确定）、未记录。

| # | Claim | Status | Jam | Source |
|---|-------|--------|-----|--------|
| 1 | Pro price wraps on narrow cards | works | [ENG-412 fix check](https://jam.dev/c/...) | [ENG-412](...) · [original Jam](https://jam.dev/c/...) |
| 2 | Sign-in after sign-out | broken | [ENG-415 repro](https://jam.dev/c/...) | [ENG-415](...) |

在表格下方，为每条状态不是“正常”的行各写一行，说明原因。

后续

对每个能确定事项（正常或有问题）的原始 Jam 各发表评论，并注明状态和对应修复检查 Jam 的链接。跳过未确认和未记录的行：

jam create comment "$ORIGINAL_ID" "Fix check: works. https://jam.dev/c/<id>"

用户同意后发布；如果用户已提出要求，则立即发布。

只有当对应行标记为正常时，才将修复检查 Jam 标记为原始 Jam 的修复（通过 MCP 使用 markRelated）；原始 Jam 随后会显示“修复者”反向链接：

jam update jam <fix check id> --mark-related "$ORIGINAL_ID" --type fixes

如果 Jam 展示的是一条主张而非修复，请使用 --type proves。有问题或未确认的行最多使用 --type relates_to，绝不要使用 fixes。

在聊天中发布表格。只有用户提出要求时，才将表格发布到拉取请求或工单。

向 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 界面，不反馈用户的代码或其他工具。
• 每个会话最多反馈一次；自己已纠正的失误不要反馈。
• 不要包含机密信息、客户数据、源代码、堆栈跟踪或录制内容。