review-product-flow

审查产品流程

产品走查是由人操作真实应用，逐一体验所有面向用户的功能并判断所见内容。交付物包括一个 运行文件、一份渲染后的人类指南，以及一份 vet-product-flow 报告——内容以应用自身的渲染为依据，每项能力对应一行，并标注需求 ID 和用例类型。用例和判定结果保存在同一文件中，因此 Agent 验证的内容就是人们阅读的内容。请构建这些产物；聊天消息不算交付物。只有顺利路径的指南不算完成。只有在 vet 报告存在后，编写工作才算完成。

用例分类（每份指南都使用以下类型）

kind	含义	典型来源
happy	功能实现其预期用途	需求中的主要场景
edge	边界／空值／重复／最大长度／空白字符	同一 ID 或关联标准中的边界标准
error	用户可见的失败路径（验证提示标签、4xx 消息、保留输入）	需求中的错误标准
nonbehavior	不得发生的情况	范围外内容；否定性 SHALL 要求
persist	客户端重新加载／重新打开／重启后仍然保留	写明“持久保留”的标准或由存储管理的状态
visual	布局、颜色、空状态文案、观感——由人眼判断	表现层需求；不写入服务端
journey	将原子用例串联起来的多步骤工作流（可选，每份指南 ≤2 个）	跨场景用户路径

此处不要编造混乱、负载、竞争条件或安全模糊测试套件——这些不属于单席位用户测试。仅当 UI 暴露权限／角色用例时才纳入（该角色的 edge 或 error 用例 + setup）。

待办事项 — GATE

在 §1 之前，通过 TodoWrite 为每个章节（1–4）创建一个待办事项，并且创建一个终端待办事项 Vet product flow（现在就在运行文件中创建 vet-product-flow，不要留到之后）。只有当本次运行文件对应的 .skills/<CODE>/vet-product-flow.md 存在时，才勾选 vet 待办事项。 完成条件：在确定范围前创建待办清单，且其中包含 vet 待办事项。

1. 确定每项能力的范围 — 覆盖率门槛

阅读该功能的 requirements.md、design.md 和 tasks.md。列出所有用户可观察到的能力。应包含同一用户工作流中的相邻能力，不要只列新功能。

覆盖规则（完成 §4 前必须全部满足）：

1. 每个面向用户的需求 ID 至少有 1 个用例。
2. 每个能力领域（指南中的章节）至少有 1 个 happy 用例，并且至少有 1 个非顺利用例，类型为 edge | error | nonbehavior | persist。
3. 对于用户可能尝试的每项范围外内容／有意不提供的行为，都必须有一个 nonbehavior 用例（或者在交接说明中明确注明：没有面向用户的尝试方式——跳过）。
4. 对于每项声称具有持久性的标准，都必须有一个 persist 用例（或者有一个 happy／edge 用例，其 Expect + backend 能证明重新加载／存储——建议单独设置 persist 行，以免被跳过）。
5. 如果该领域在规范中没有任何 edge、error、nonbehavior 或 persist 内容，请在对应章节下写明一行：覆盖例外：规范未提及 edge/error/nonbehavior/persist——不要编造产品行为。该例外是便于搜索的如实记录；如果三类标准中存在边界情况，就不能借此规避。

如果某个 ID 或其关联标准中提到了边界情况，那么每个 ID 只有一个 happy 用例并不足够。

完成条件：满足上述覆盖规则，或在指南中写明每个例外。

2. 根据真实代码确定每个用例

逐个阅读代码，确认用户实际会看到什么：准确用词（关键词、命令名称、标签）、键盘快捷键和真实渲染效果——例如徽章颜色、提示标签样式、图标等；这些都必须依据源代码（主题令牌、CSS），绝不能靠猜测。如果代码揭示了真实存在的限制（例如分隔符被调暗而非移除、某个状态尚无 UI），用例中就要写明这一点。

3. 启动真实应用，找到可靠的观察点

使用 docs/agents/project.md 中的 Run locally (dev) 命令启动应用 （如果缺少该命令，请找到并记录——参见 validate-ui）。提前说明任何功能受限的区域：需要密钥的功能，或尚未实现的子功能。没有 UI 界面的行为仍需有对应的测试用例——并提供真实的观察方式（如 devtools 中的 invoke(...)、只读 DB 查看），绝不能伪造屏幕。完成标准：应用正在运行，且每个尚不可见的行为都有观察方法。

4. 编写测试用例 + 渲染外壳（不要自创 CSS）

编写内容的唯一事实来源（SSOT）是运行文件，不是手工制作的 HTML。

1. 编写 .skills/<CODE>/review-product-flow.json（不确定时，请查看同级的 references/cases-schema.md，了解架构）。每个测试用例都必须包含所有必需字段：id、req、kind、title、setup、try、expect、backend（backend 是服务端断言，或字面值 presentational）。 运行状态（run、human）会自动为你填入——你只需编写这八个字段。

2. 使用已检入的外壳渲染人工测试指南——不要加载 craft-page，也不要自创配色方案或布局，除非用户明确要求定制设计：

   python3 <skill-root>/scripts/review-product-flow render .skills/<CODE>/review-product-flow.json \
     -o .skills/<CODE>/review-product-flow.html
   

   将 <skill-root> 解析为此技能的安装路径（在此 monorepo 中：skills/acceptance/review-product-flow）。外壳位于 shell/guide.html——包含可适配主题的 CSS/JS、类别标签、结果徽章和 data-* 属性。渲染后的页面会显示渲染时的结果，并注明这一点，因此即使应用未运行，双击打开页面也能正确显示。

3. **覆盖率自检：**按章节统计各 kind 的测试用例数量。如果某个能力领域缺少非 happy 类别的测试用例，且没有 Coverage exception 条目，请在交接前补上缺失的测试用例。

可选：journey 行最多两条；它们不能替代原子级覆盖。

绝不要只交付聊天清单。绝不要将重新生成完整的自定义 HTML 页面作为默认流程——正确流程是编写测试用例并执行 render。

完成标准：运行文件和渲染后的 HTML 已保存到已知路径，覆盖率达标，且每个测试用例都包含所有必需字段。

5. 交接

顺序：交付物 → 运行 vet → 可选启动服务 → 只有 vet 通过后才能进行实际体验测试。

1. 交付物——提供两个路径（运行文件 + HTML），以及最快的入门方式——约 30 秒即可启动该功能的首次测试（通常是第一个 happy 行）——随后说明功能受限情况和覆盖率例外。

2. **立即执行 Vet。**运行文件和渲染后的 HTML 保存到磁盘，且 §4 覆盖率达标后，立即使用必需的子技能：对运行文件执行 vet-product-flow——必须在启动服务、实际体验测试或声称“编写完成”之前完成。只有 .skills/<CODE>/vet-product-flow.md 存在时，才将 Vet product flow 待办标记为完成。§1 / §4 覆盖率自检属于编写规范，不能替代此报告。

3. 可选启动服务——如果用户会和 Agent 一起手动测试，可提供实时指南：

   python3 <skill-root>/scripts/review-product-flow serve .skills/<CODE>/review-product-flow.json
   

   服务会绑定到 127.0.0.1:8787，在 Agent 记录结果时同步更新，并将用户的勾选写回到 Agent 可查看的位置。请明确说明勾选的含义：它只表示用户查看过，绝不会变成 pass。使用 serve --stop 停止服务。即使直接作为普通文件打开，指南仍会显示渲染时的结果——服务只让结果保持最新。

4. Agent 实际体验测试——只有在 vet-product-flow 报告通过后（或对未解决的问题指定明确的豁免），才能提供 run-product-walkthrough 和运行文件路径。实际体验流程仍会执行自身的门槛检查；交接顺序不能替代该检查。

完成标准：交付物已保存到磁盘且有依据，§1 覆盖率门槛达标，每个测试用例都包含所有必需字段，并且本运行文件对应的 .skills/<CODE>/vet-product-flow.md 已存在。

合理化借口

想法	事实
“在聊天中用 Markdown 清单就够了”	它无法勾选，也无法显示要对照检查的真实徽章，而且会随着滚动消失。交付物是运行文件 + 渲染后的指南。
“我会为这个功能精心打造独特布局”	默认使用已检入的外壳。只有用户提出要求时才进行定制。
“他们用的是原生桌面应用，不是浏览器，所以不适合用制品”	制品是配套参考资料，可以在应用旁边保持打开；应用是原生的，并不意味着要把指南直接放进聊天中。
“我会用文字描述徽章”	用户会对照自己看到的内容进行检查。要复现真实的渲染效果，否则预期结果就无法验证。
“每项要求只测一个正常情况就够了”	覆盖率门槛要求包含非正常情况（或书面例外）。只有正常情况的内容是演示，不是产品流程审查。
“边界情况应该放在单元测试中，而不是指南里”	产品流程审查面向用户。如果用户可能遇到这种情况，就要列出一行。
“更糟的情况指的是负载、混沌或模糊测试”	那些属于其他测试框架。产品流程审查中的更糟情况包括边界、错误、无行为和持久化。
“§4 覆盖率自检已经运行过了——跳过 vet 吧”	自检是同一会话中的编写规范，不是对实现表面的独立判断。它不能替代 vet。
“我会把 vet 列为下一步，然后就此停下——控制器会运行它”	步骤 2 会运行 vet-product-flow；仅仅列出它不算完成
“制品已经写入磁盘——编写工作结束了”	只有 vet 报告存在时才算完成，而不是 JSON/HTML 文件生成时

警示信号

• 手写完整的 HTML/CSS 页面，而不是编写运行文件并使用 review-product-flow render
• 任何用例缺少 backend / setup / kind
• 只有正常情况的章节，却没有可用 grep 查找的覆盖率例外说明
• 要求 Agent 通过勾选指南中的项目来标记进度，而不是使用 review-product-flow mark
• 把 §4 覆盖率自检当作 vet-product-flow 的替代品
• 未为本次运行文件生成 .skills/<CODE>/vet-product-flow.md 就宣布此技能已完成
• vet 报告生成前就列出 run-product-walkthrough（或提出 dogfood）
• 报告路径不存在时就勾选 Vet product flow 待办事项