jiaxuan-tao/vibe-coding-lab/web-app-acceptance-skill

Web 交付风险评审

这不是“跑完一串检查就说通过”的工具。它把关键用户路径、实际证据、发现的问题和未覆盖范围组织成可追溯的发布建议。

验收范围仅限用户指定项目；未指定时先说明将检查当前工作目录。脚本只读、不安装依赖、不修改项目文件，也不上传数据。

输出原则

• 先定义本次发布要让谁完成什么任务，再决定检查什么。
• 每个“通过”都附上执行过的命令、页面操作或检查结果；没有证据的事项只能写“未覆盖”。
• 将事实、风险判断和发布建议分开陈述，避免把主观判断伪装成自动化结论。
• 不以发现问题数量计分；风险取决于核心任务影响、用户可达性、绕过方式和证据确定性。

1. 范围与关键路径

开始时确认或根据项目文档提炼以下内容：

1. 发布目标：本次要交付的新能力或要修复的问题。
2. 目标用户与核心任务：用户打开产品后必须能够完成的 1 至 3 条任务。
3. 验收环境：项目路径、启动方式、浏览器尺寸、是否需要登录或外部服务。
4. 明确排除项：例如真实支付、第三方登录、生产数据或无凭证的接口。

将每条关键路径写成“起点 → 操作 → 可观察结果”。例如：首页 → 填写表单并提交 → 看到成功状态且结果可再次访问。

2. 证据采集

按可获得的环境依次采集证据，不要为了完成流程而安装依赖或猜测命令。

项目检测

python3 scripts/inspect_web_project.py <项目目录>

记录包管理器、已有脚本、候选构建目录和警告。检测到配置不等于构建成功。

构建与已有测试

仅在依赖已经就绪、且项目提供明确脚本时，运行已有命令，例如：

npm test
npm run build

记录完整退出结果。构建失败时，不将与该构建相关的路径列为已验证。

静态引用检查

对已存在的静态输出目录运行：

python3 scripts/check_static_site.py <静态目录>

它只检查 HTML 中可静态确定的本地页面链接与资源引用。外链、锚点、动态路由和越出站点目录的引用必须作为跳过项或警告记录。

浏览器辅助验收

读取 浏览器验收清单，用当前可用的浏览器能力逐条验证关键路径：

1. 打开页面并等待渲染稳定，记录控制台错误和失败请求。
2. 先观察已渲染的页面，再使用稳定元素定位执行路径操作。
3. 检查成功、加载、空数据和错误状态是否可理解。
4. 在窄屏与宽屏下检查明显溢出、遮挡、不可点击或无法返回的问题。

3. 风险分级

基于证据对每个问题分级；同一问题的级别应写明原因。

不要把未覆盖项自动定为缺陷。它们是决策风险：需要说明为什么未覆盖、影响什么，以及是否足以阻止当前发布。

4. 未覆盖范围

单独列出未实际验证的关键条件，例如：登录账户、付费流程、真实第三方 API、生产权限、特定设备或数据量。

• 若未覆盖项属于核心任务且没有替代证据，不能给出“可发布”。
• 若它不属于本次发布范围，说明排除理由和后续验证人或条件。
• 不用“未发现问题”描述没有执行过的检查。

5. 发布建议

根据关键路径覆盖、风险分级和未覆盖范围给出唯一结论：

• 可发布：所有定义的关键路径都有足够证据，且没有阻塞或高风险；未覆盖项不影响本次目标。
• 有条件发布：没有阻塞问题，但存在明确的中风险、可接受的高风险降级方案或非关键未覆盖项；必须写清条件、受影响用户和最小后续动作。
• 不建议发布：存在阻塞问题、未验证的核心路径，或高风险会破坏本次发布目标。

使用以下结构输出：

Web 交付风险评审 · YYYY-MM-DD
 
发布目标：<本次交付什么>
范围与环境：<项目路径、运行方式、浏览器或数据条件>
 
关键路径与证据
1. <路径>：通过 / 失败 / 未覆盖
   证据：<命令、页面操作、检查结果>
 
风险
- [阻塞 / 高 / 中 / 低] <问题>
  影响：<谁无法完成什么>
  依据：<可复现证据>
  建议：<最小修复或降级动作>
 
未覆盖范围
- <事项、原因、对本次发布的影响>
 
发布建议：可发布 / 有条件发布 / 不建议发布
理由：<将关键路径、风险和未覆盖范围连成明确判断>
下一步：<按优先级排列的最小动作>

不要在存在阻塞问题、关键路径失败或核心范围未覆盖时写“可发布”。