# Web App Acceptance

> 对本地 Web 项目进行交付风险评审，并给出可发布、有条件发布或不建议发布的依据。当用户要求发布前判断、验收关键用户路径、评估问题是否阻塞、检查构建与链接，或需要一份可解释的发布决策单时使用。

- Skill: `jiaxuan-tao/web-app-acceptance` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jiaxuan-tao/web-app-acceptance`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiaxuan-tao/web-app-acceptance/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: jiaxuan-tao (https://skillmd.com/u/jiaxuan-tao)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/jiaxuan-tao/web-app-acceptance

---


# Web 交付风险评审

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

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

## 输出原则

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

## 1. 范围与关键路径

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

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

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

## 2. 证据采集

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

### 项目检测

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

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

### 构建与已有测试

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

```bash
npm test
npm run build
```

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

### 静态引用检查

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

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

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

### 浏览器辅助验收

读取 [浏览器验收清单](references/browser-acceptance-checklist.md)，用当前可用的浏览器能力逐条验证关键路径：

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

## 3. 风险分级

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

| 等级 | 判断条件 | 发布处理 |
| --- | --- | --- |
| **阻塞** | 用户无法进入产品，或核心任务无法完成、数据明显错误、存在不可接受的隐私或安全暴露 | 不建议发布；先修复并复验 |
| **高** | 重要路径对一部分用户不可用，或没有可理解的绕过方式 | 默认不发布；只有明确缩小发布范围时才可有条件发布 |
| **中** | 非核心流程受影响、存在临时绕过方式，或当前证据不足但影响尚未确认 | 可以有条件发布，但需列入后续修复与监控 |
| **低** | 文案、轻微视觉、非关键体验或不影响任务完成的问题 | 可发布；记录在后续迭代 |

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

## 4. 未覆盖范围

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

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

## 5. 发布建议

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

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

使用以下结构输出：

```text
Web 交付风险评审 · YYYY-MM-DD

发布目标：<本次交付什么>
范围与环境：<项目路径、运行方式、浏览器或数据条件>

关键路径与证据
1. <路径>：通过 / 失败 / 未覆盖
   证据：<命令、页面操作、检查结果>

风险
- [阻塞 / 高 / 中 / 低] <问题>
  影响：<谁无法完成什么>
  依据：<可复现证据>
  建议：<最小修复或降级动作>

未覆盖范围
- <事项、原因、对本次发布的影响>

发布建议：可发布 / 有条件发布 / 不建议发布
理由：<将关键路径、风险和未覆盖范围连成明确判断>
下一步：<按优先级排列的最小动作>
```

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