ce-dogfood-beta

Dogfood（Beta 版）

作为一名 QA 工程师，对当前分支进行端到端的实际使用测试：了解每项更改，像用户一样在真实浏览器中测试每项更改，并自主修复问题，直到该分支真正达到可发布状态。

测试范围仅限于 diff，而非探索整个应用。你要测试的是此分支相较于 main 引入或修改的内容。（如需对整个应用进行探索性 QA，请改用 dogfood skill。）

浏览器自动化仅使用 agent-browser

此工作流只能通过 agent-browser CLI 操作浏览器。不要使用 Chrome MCP 工具（mcp__claude-in-chrome__*）、任何浏览器 MCP 集成或其他内置浏览器控制工具。如果平台提供多种浏览器控制方式，请始终选择 agent-browser。使用直接二进制文件，绝不要使用 npx agent-browser（直接二进制文件使用速度更快的 Rust 客户端）。

先决条件

• 可以启动的本地开发服务器（bin/dev、rails server、npm run dev 等）。

• 已安装 agent-browser。检查：

  command -v agent-browser >/dev/null 2>&1 && echo "Ready" || echo "NOT INSTALLED"
  

  如果尚未安装，请运行 ce-setup skill 获取当前安装命令，安装 agent-browser，然后继续。未安装前不要继续。

复用 Compound-Engineering Skills

ce-dogfood-beta 是一个协调器。优先委派给现有的 CE skills，而不是重新推导其行为：

何时	Skill	原因
第 0 阶段隔离	ce-worktree	在隔离的 worktree 中运行 dogfood，确保主检出目录保持干净。
缺少 agent-browser	ce-setup	提供当前的 agent-browser 安装命令。
故障根因不明显	ce-debug	系统地分析根因，而不是反复猜测。
为每项修复提交更改	ce-commit	使用一致且范围明确的提交消息。
Bug 揭示了可复用的经验	ce-compound	记录经验，让团队不断积累知识。

复用 ce-test-browser 的端口检测和开发服务器启动机制（参见第 3 阶段），不要自行重新实现。

工作流

0. Scope        Pick the branch, get onto it (offer worktree), never touch main
1. Analyze      Diff branch vs main, understand every change
2. Map+Matrix   Map user flows as Mermaid flowcharts, then derive the test matrix as a task list
3. Serve        Detect port, start dev server, open agent-browser
4. Execute      Work the matrix one item at a time with agent-browser
5. Fix loop     On failure: fix -> add regression test -> commit -> continue
6. Report       Write durable doc to docs/dogfood-reports/ (flows, matrix, fixes, learnings, verdict)

第 0 阶段：确定范围并切换到正确的分支

解析 $ARGUMENTS：PR 编号、分支名称或空值（使用当前分支）。如果存在 --port PORT，请将其移除。

1. 确定目标分支：
   • PR 编号： gh pr checkout <number>（先检查是否存在对应的 worktree）。
   • 分支名称： 切换到该分支（先检查是否存在对应的 worktree）。
   • 空值： 使用当前分支。
2. 拒绝在 main/master 上运行。 如果解析出的分支是主干分支，请停止并告知用户——没有可供 dogfood 的 diff。
3. 提供隔离选项。 询问是否要在 git worktree 中运行，以避免改动主检出目录（使用平台的阻塞式提问工具）。如果选择是，移交给 ce-worktree；如果选择否，则在当前目录继续。
4. 如有之前的运行记录，则恢复任务。 查找 docs/dogfood-reports/*-<branch-slug>-dogfood.md 中是否存在报告。如果找到未完成的场景，询问是恢复原任务还是重新开始。若选择恢复，请根据报告中的矩阵重新生成任务列表（Pass/Fixed/Skipped 保持已完成；Pending/Blocked/进行中的项目列为剩余工作），并从剩余工作继续。

可恢复性（可随时停止并继续）

此工作流旨在支持中断后继续。两项状态信息可以确保安全恢复：

• 任务列表（TaskCreate/TaskUpdate）是实时待办事项——矩阵中的每个场景对应一项任务。开始处理时将其标记为 in_progress，只有在确实通过后才标记为 completed。
• 报告文档位于 docs/dogfood-reports/<YYYY-MM-DD>-<branch-slug>-dogfood.md，是可跨会话保留的持久检查点。矩阵生成后（第 2 阶段结束时）立即创建该文档，并将所有场景列为 Pending；同时逐步更新文档——每个场景完成判定后、每次修复提交后都要更新，而不是只在最后更新。

由于任务仅在会话期间有效，而报告文档保存在磁盘上，因此恢复工作时应以报告为准。务必让两者保持同步，以便后续运行或队友能准确接续未完成的工作。

第 1 阶段：分析变更

拉取并阅读相对于 main 的完整差异。

git diff --name-only main...HEAD     # what changed
git diff main...HEAD                 # how it changed

在脑海中梳理每项变更：新功能、行为调整、新路由/视图/组件，以及受影响的数据流。记下所有会产生用户可见行为的内容——这些都必须纳入矩阵测试。

结合产品的用户角色和愿景进行判断。 查找用户角色和愿景相关信息，以真实用户的视角评估流程，而不只是判断“能不能用”。按顺序检查：STRATEGY.md（其中的“适用对象”部分会说明主要用户角色及其待完成任务）、VISION.md，以及任何用户角色文档（例如 docs/personas/、PERSONAS.md）。记录 1-3 个主要用户角色，以及每个角色关注的事项。如果没有相关资料，则根据产品和差异推断合理的主要用户角色，并在报告中说明。

第 2 阶段：梳理流程，再构建矩阵

不要直接列出页面清单。先理解差异涉及的用户流程，再据此生成矩阵。缺少流程模型的矩阵只会孤立地测试页面，遗漏完整旅程——例如，邮件“已发送”，却进入了错误的对话串。

2a. 梳理用户流程（必需）

对于每项用户可见的变更，追踪并绘制完整的端到端旅程。将每个流程绘制为 Mermaid flowchart，让旅程在测试开始前清晰明了，便于审查——包括入口点、每项用户操作、分支点（成功 / 校验错误 / 空状态 / 权限拒绝）、副作用（邮件、任务、通知），以及真正的最终状态。

邮件示例：仅确认“邮件已发送”还不够。邮件是否发给了正确的收件人？用户点击邮件后，应用是否跳转到并滚动至正确的消息？内容是否合理？整个流程是否符合产品愿景和用户体验？流程图必须包含点击邮件后的操作及其目标位置，不能止步于“邮件已发送”。

flowchart TD
    A[User opens /threads] --> B[Clicks 'Reply']
    B --> C{Form valid?}
    C -->|No| D[Inline validation error shown]
    C -->|Yes| E[Reply saved]
    E --> F[Notification email sent to thread participants]
    E --> G[UI scrolls to new reply, focus on it]
    F --> H[Recipient clicks email link]
    H --> I{Lands on correct thread + scrolls to the reply?}

每段不同的旅程都要绘制一张流程图。覆盖顺利路径，以及各个分支点（错误、空状态、边界、权限）。这些图表就是对流程的理解——它们构成矩阵的主干，并应纳入最终报告。

2b. 根据流程推导矩阵

逐一检查每张流程图，将每个节点和分支转化为一个或多个测试场景。阅读 references/test-matrix-taxonomy.md，了解完整的测试维度（旅程、功能检查、体验检查、边界/错误/空状态、无障碍、响应式）。同时覆盖功能性（“能否正常工作？”）和体验性（“使用感受是否合适，是否符合产品定位？”）。

将变更文件映射到具体路由（视图 -> 对应页面、组件 -> 渲染这些组件的页面、布局 -> 所有页面、样式表 -> 关键页面的视觉回归），并将这些路由关联到会覆盖它们的流程。

将矩阵作为任务列表载入（使用 TaskCreate），每个场景对应一项任务，以跟踪进度并确保不遗漏。按流程顺序排列任务，遵循流程图，而不是按文件排列。

第 3 阶段：检测端口并启动开发服务器

确定端口（优先级：显式指定的 --port > 当前上下文中的项目说明明确指定的端口 > package.json 开发脚本 > .env* 中的 PORT= > 默认值 3000）。如果已有服务器正在监听，则复用它；否则，在后台运行项目的开发命令，并等待端口就绪。这与 ce-test-browser 使用的机制相同——遵循其第 5–6 阶段的逻辑。

agent-browser open "http://localhost:${PORT}"
agent-browser snapshot -i

第 4 阶段：执行矩阵

一次处理一个任务。对于每个场景，将任务标记为 in_progress，然后：

1. 记录你要测试的内容（用户历程和预期结果）。

2. 使用 agent-browser 操作——导航、为交互引用生成快照、点击、填写、提交，并沿着用户历程走到真实的最终状态：

   agent-browser open "http://localhost:${PORT}/<route>"
   agent-browser snapshot -i
   agent-browser click @e1
   agent-browser fill @e2 "value"
   agent-browser screenshot <scenario>.png
   agent-browser errors      # check console/page errors
   

3. 评估正确性和体验：数据是否正确、目的地是否正确、内容是否合理、是否存在控制台错误，以及整体体验是否符合产品定位。

4. 以每个用户角色的身份体验。从头脑中分别以每个主要用户角色（来自第 1 阶段）的视角重新走一遍用户历程，找出他们可能遇到的小摩擦——这类小问题不会导致功能测试失败，但会降低体验：令人困惑的标签、多余的一次点击、意外跳转、感觉缓慢的步骤、缺少反馈，或不符合该用户角色思维方式的文案。场景的功能性结果可能是 Pass，但仍然存在小摩擦。记录每个小摩擦、受影响的用户角色及其严重程度。

5. 记录通过/失败结果及所有小摩擦，并注明具体情况。只有确实通过时，才将任务标记为 completed（记录小摩擦，但不视为阻塞项——在第 5 阶段修复严重问题，其余问题列入报告）。

涉及外部交互的流程（OAuth、真实邮件发送、支付、SMS）无法完全通过无头方式操作——暂停并请用户验证该环节，然后继续。

第 5 阶段：修复循环（自主处理）

当场景失败时，修复并验证——但首先判断该修复应由你自主完成，还是需要由人来决定。

修改代码前，先评估修复的规模。当变更小、清晰且风险低时，自动修复：例如原因明确且修复方法显而易见的错误，影响范围仅限少数文件，且不涉及架构、架构设计或产品取舍。不要自动修复大型或含糊不清的变更——这类变更需要架构或架构设计决策，会改变产品行为或 UX 意图，涉及许多文件，存在多种合理方案，或你无法确定正确答案是否明确。自主强行做出重大判断，比升级给人处理更糟。

对于可自主处理的修复：

1. 调查根本原因。如果原因不明显，使用 ce-debug。
2. 在代码中应用修复。
3. 添加自动化回归测试，确保修复前测试失败、修复后测试通过，防止问题再次出现。
4. 使用清晰的提交说明提交修复（使用 ce-commit）。每个提交只包含一个逻辑修复。
5. 在浏览器中重新运行失败的场景，确认现在已通过；然后继续执行矩阵。
6. 如果这个错误带来了可复用的经验，使用 ce-compound 记录下来。

对于不适合自主处理的大型变更：不要实施。在报告的需要人工决策部分记录：问题所在、无法安全地自主修复的原因、可行方案（及其取舍）以及你的建议。在矩阵中将场景标记为 Blocked (human decision)，然后继续处理其余场景。绝不要为了清除矩阵中的一项而实施重大、不可逆或会改变产品的变更。

持续迭代，直到每项任务都标记为 completed 或明确标记为 Blocked (human decision)。重新测试任何可能受到修复影响的内容（留意相邻用户历程中的回归问题）。

阶段 6：撰写报告文档

报告文档在阶段 2 结束时创建，并在整个过程中逐步更新（参见可恢复性）。当矩阵全部通过（或所有剩余项都明确标记为受阻）时，在被测试的仓库中将其定稿为 docs/dogfood-reports/<YYYY-MM-DD>-<branch-slug>-dogfood.md，然后在聊天中简要总结，并附上文件路径。

使用 references/dogfood-report-template.md 作为格式模板——与根据模板记录计划和头脑风暴的方式相同。定稿后的文档必须包含：

1. 差异摘要 —— 分支与 main 之间有哪些变化。
2. 用户角色 —— 评估所依据的主要用户角色（以及来源：STRATEGY.md / VISION.md / 推断）。
3. 测试流程 —— 阶段 2a 中的 Mermaid 流程图，以保留各项用户旅程。
4. 测试矩阵与结果 —— 每个场景：测试内容、通过/失败、发现的问题、应用的修复、提交 SHA。
5. 已修复的问题 —— 每个 Bug 的根本原因、修复方案、添加的回归测试以及对应提交。
6. 体验瑕疵（按用户角色分类） —— 发现的体验阻碍、受影响的用户角色、严重程度，以及是否已修复或延期处理。
7. 需由人工决策的事项 —— 无法自主修复的重大问题：故障内容、升级处理的原因、各种方案及其权衡，以及建议。
8. 经验总结 —— 值得沿用的经验（将重要经验提供给 ce-compound）。
9. 最终状态 —— 就绪情况的判定，以及任何仍受阻或需要人工验证的事项。

文档中使用相对于仓库根目录的路径，绝不要使用绝对路径，以保持可移植性。