浏览器证据包（Browser Proof）

搜索意图：browser proof、browser QA、browser debugging evidence、QA evidence pack

目标

将一次浏览器会话转化为具备发布质量的证据包，包含以下四项内容：

• 一份机器可读的会话清单（session manifest）
• 一份按顺序组织的操作步骤日志（step log）
• 一次结构化完整性校验（structural bundle check）
• 一份可共享的 Markdown 报告（markdown report）

本技能专用于浏览器端证据采集与交付质量保障，不替代 Playwright、OpenClaw 或任何测试运行器（test runner）。

适用场景

• 用户需要一份可复现的浏览器缺陷报告，而非零散截图
• 上线流程或 QA 流程需交付一份可共享的证据包
• 浏览器调试需在同一位置同时记录：预期结果、实际结果及所有相关产物（artifacts）
• 需从 OpenClaw、Playwright 或人工 QA 向其他工程师进行清晰、无歧义的交接
• 同一浏览器问题反复在聊天记录中被重新解释，而未归档为单一证据包
• Chrome 扩展发布或审核流程需提供针对确切打包 ZIP 文件及对应浏览器版本的验证证据

快速上手

1. 初始化会话清单（session manifest）。

   • 执行命令：python3 {baseDir}/scripts/init_browser_proof_session.py --out --session-id --app --goal
   • 可选添加：--base-url、可重复使用的 --surface，以及可选的 --run-context 或 --environment 字段。

2. 逐次追加浏览器操作步骤。

   • 执行命令：python3 {baseDir}/scripts/append_browser_proof_step.py --manifest --step-id --action --expected --actual --status passed|failed|blocked
   • 通过以下参数附加证据：--screenshot、--dom-dump、--console-log、--network-log、--video，以及可重复使用的 --issue-key。

3. 分享前校验证据包完整性。

   • 执行命令：python3 {baseDir}/scripts/check_browser_proof_bundle.py --manifest --repo-root --out
   • 在发布报告前，修复缺失截图、绝对路径、失败步骤缺少说明、或会话元数据缺失等问题。

4. 生成最终报告。

   • 执行命令：python3 {baseDir}/scripts/render_browser_proof_report.py --manifest --out
   • 直接共享生成的 Markdown 报告，无需依赖记忆重述整个执行过程。

操作规范

会话规范（Session rules）

• 每次浏览器运行或紧密关联的一组运行，应仅对应一个清单文件（manifest）。
• 在会话起始阶段即记录应用名（app）、目标（goal）、基础 URL（base URL）及涉及的界面区域（surfaces）。
• 优先使用相对路径存储产物（artifacts），确保证据包具备可移植性（portable）。

步骤规范（Step rules）

• 每一步骤均须明确说明：所执行的操作（action）、预期结果（expected）、实际结果（actual）。
• 失败步骤（failed）必须包含说明文字（note）或至少一个 --issue-key。
• 每个失败步骤及关键检查点（checkpoint）均须附带截图（screenshot）。
• 步骤状态（status）仅限使用以下三种取值：passed、failed、blocked。

Chrome 扩展规范（Chrome extension rules）

• 在会话元数据或首个步骤中，明确记录扩展的精确 ZIP 包路径或解压路径、清单版本（manifest version）、扩展 ID（如可用）、Chrome 版本号。
• 针对操作弹窗（action popup）类流程，须记录所选文本或输入源、点击的动作按钮、目标语言或选项、以及观察到的结果。
• 当问题主张（claim）依赖于浏览器 API 时，须捕获扩展错误、控制台输出（console output）及对应 API 的可用性状态（API availability states）。
• 若 Chrome Web Store 已存在待审草稿（draft），仅需采集当前审核状态证据；除非存在经确认的验收阻塞项（verified acceptance blocker），否则不得将证据采集流程转为取消/重新提交指令。

证据包规范（Bundle rules）

• 禁止在笔记（notes）或产物路径（artifact paths）中存储密钥（secrets）、Cookie 或原始 Token。
• 最终生成的清单（manifest）中应避免使用绝对文件系统路径。
• 在将证据包发送至 GitHub、Linear、Slack 或发布通道前，务必执行校验（check）。

配套脚本

• scripts/init_browser_proof_session.py
  • 为浏览器 QA 或调试运行创建一份机器可读的会话清单（session manifest）。
• scripts/append_browser_proof_step.py
  • 向会话清单中追加一条带证据支撑的操作步骤。
• scripts/check_browser_proof_bundle.py
  • 校验证据包结构、产物路径有效性及最低证据质量要求。
• scripts/render_browser_proof_report.py
  • 基于会话清单生成一份简洁明了的 Markdown 报告。