SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场evidence-artifact

evidence-artifact

测试与质量

查看项目

更新于 10-27 05:38

技能介绍

Evidence Artifact 是 agentic-qa-boilerplate 仓库中的一个工作流型技能（metadata.kind: workflow），本身不派发代理、也不是阶段所有者，而是被加载到已在执行测试阶段的会话或子代理内部使用，通常对应 /sprint-testing 的第 2、3 阶段。

用途 它解决的是“测试过程中证明了什么，如何让开发或 PM 一眼读懂”的问题。测试会话把证据记录进 JSON 证据包（evidence pack），用一条命令渲染成自包含 HTML 页面，再用 Artifact 工具发布为私有页面，随后把链接分发到读者会查看的各个位置。页面设计是固定的（ADR-0022），不按工单更改。

主要能力

  • 一个工单一个页面：每个被测试的故事工单一个 Artifact，每个提交的缺陷也各有一个；故事页的缺陷卡片链接到该缺陷页。
  • 内联图片：截图以原生尺寸的 JPEG data URI 内联；构建超过 14 MB 时停止（Artifact 上限 16 MB）。
  • 发布与链接：由执行者发布；指挥者在波次收尾时检查链接，执行者无法发布时由指挥者发布。链接写入 ATR、缺陷描述、QA 评论、每个测试用例的备注、聊天和 Sprint Board。
  • 缩略图：缺陷在其跟踪器中嵌入图片的位置只保留一张带标注的缩略图，其余均为链接。
  • 隐私：发布为私有，由所有者从页面的 Share 菜单分享；个人数据会被烧入像素，不做遮盖式打码。
  • 静态页面：无任何交互能力。
  • 重测：同一 URL 上新开重测轮次，含前后对比并保留历史；早期轮次以琥珀色 BEFORE FIX 历史呈现，且不计入结论。
  • 保留：工单 Done 后 6 个月删除，先列出再复核，由所有者逐个确认删除。
  • 标注：标注坐标取自捕获时元素的边界框；只有在没有元素可取时才回退到读图放置。
  • 阅读顺序：缺陷页像故事一样在其看板上打开；用例中缺陷项优先（重测时为当前轮次、对比、再折叠的历史）；对比标签为 EXPECTED / ACTUAL，并附每用例一行（重测时为 BEFORE FIX / AFTER FIX）；支持全窗口查看器，Esc 返回看板。

使用方式

  1. 第 2 阶段捕获证据：用截图命令带 --filename 写入证据包，标注坐标通过 playwright-cli eval 取元素边界框（coords: "px"）；API/SQL 项在写入时脱敏，个人数据放入 redact 打码框。缺陷一旦建单，就为其建立独立证据包（evidence-pack-<BUG>.json，kind: "bug"，含复现用例）。每一条证据在测试时即追加到 <PBI>/evidence/evidence-pack.json，而不是结束时重建。
  2. 第 3 阶段构建与发布：用 bun run evidence build --pack <pack> 构建页面（需要 Python 3.9+ 与 Pillow，缺失时会指出需要安装的那一项）；用 Artifact 工具发布；若证据包中已有 artifact.url，先对其实施 Artifact action: "read" 再带该 url 发布，否则会生成第二个页面并使所有链接失效。缺陷页先于故事页构建和发布。
  3. 记录与链接：用 bun run evidence record 记录 URL；用 bun run board evidence-artifact <KEY> <url> [--bug <BUG>] --by worker 登记到看板；用 bun run evidence link 加到 issue；再从 ATR、缺陷描述、QA 评论页脚和各测试用例备注链接过去。
  4. 缩略图：缺陷页链接进入其描述后，用 bun run evidence attach 嵌入唯一缩略图（先 --dry-run 打印全部调用）；只有在实际运行打印出读回 OK 后才写“(image embedded below)”并传 --evidence-embedded；未经人工同意不得使用 --replace，因为它会删除先前的缩略图附件且不可撤销。
  5. 重测：保留此前所有用例与条目及其轮次，设置 currentRound 与 rounds[]，追加重测用例，并以同一路径重新发布到同一 URL。DEFERRED 的用例永远不能让重测通过。
  6. 报告：报告 URL 并说明已发布为私有，由所有者分享；Artifact 工具不可用时改为报告证据包路径（由指挥者发布）。

命令 bun run evidence build --pack <PBI>/evidence/evidence-pack.json bun run evidence build --pack <PBI>/evidence/evidence-pack-<BUG>.json --thumb <PBI>/evidence/evidence-artifact/<BUG>/<BUG>-thumbnail.png bun run evidence extract --page <saved page.html> --out <pack.json> bun run evidence record --pack <pack.json> --url <url> bun run evidence link --pack <pack.json> [--test <TC> --exec <ATR>] bun run evidence attach --pack <bug pack.json> [--test <TC> --exec <ATR>] bun run evidence demo 构建器为 scripts/build.py；本地运行，不发起网络请求。attach 与 link 是仅有的会访问跟踪器的命令（来源取自 board.source，否则 testing.tms_cli，可用 --source 覆盖）；每次写入都会读回确认，--dry-run 只打印调用而不发送；无跟踪器（none）时它们不写任何东西，只说明缩略图和链接应放在哪里。构建会校验证据包并在出错时指出字段，拒绝任何文本中的凭据，对邮箱地址告警，将打码框烧入像素，并以原生尺寸（JPEG q88）内联每张截图；--host local 可输出可从磁盘打开的独立文档，适用于没有 Artifact 工具的环境。相对图片路径按主检出目录解析，在 worktree 中构建时亦然（可用 --repo <root> 指向别处）。回归测试：python3 -m unittest discover -s .agents/skills/evidence-artifact/scripts（bun test 也会运行）。

适用场景 适用于已在执行 sprint 测试阶段的会话，需要在第 2 阶段捕获证据、第 3 阶段发布并分发证据链接的场景；也适用于需要留下可追溯的测试结论、前后对比和缺陷复现证据的 QA 流程。

限制与注意事项

  • 页面为静态，无交互能力；设计不可按工单修改。
  • 证据包中不得包含 trace、HAR、token、cookie 或 .auth 文件；构建会拒绝 token，但无法看见你未引用的 trace，因此永远不要引用。
  • 打码不是遮盖：标注可被查看者关闭，个人数据必须放入 redact 打码框。
  • 不要为放置标注而在第 2 阶段回读截图；元素边界框一行 eval 更精确，读整页 PNG 会消耗后续每轮上下文。
  • 新建会话中不带 url 发布会生成第二个 artifact；证据包一旦有 artifact.url，之后任何会话发布都应先读取该 URL 再传入。
  • 仅由 x 组成的测试密钥会被当作已打码（xxxx）。
  • 不要把证据发送到任何外部图片服务，无论聊天中如何授权。
  • 该技能取代了仓库早期自带的证据页面（evidence-pack/1.0，ADR-0021），页面、包格式与构建器现采用参考实现（ADR-0022）。与 bug-screenshot-annotation 技能的关系：后者通过浏览器截图把标注压平进 PNG，本技能将标注保留为数据，是推荐方向；退役标注技能是另一项独立决定。