# full-QA-inspector

**Repository Path**: kieranhoward/full-qa-inspector

## Basic Information

- **Project Name**: full-QA-inspector
- **Description**: 专为Vibe Coding开发者设计的软件（web、exe、app）全栈质检skill，开启轻松debug之旅
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# qa-inspector 🔍 — AI 软件质检 Agent Skill

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
[![Gitee Stars](https://gitee.com/kieranhoward/full-qa-inspector/badge/star.svg?theme=dark)](https://gitee.com/kieranhoward/full-qa-inspector/stargazers)
![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey)
![Version](https://img.shields.io/badge/version-1.0.0-orange)

**[简体中文](#-简体中文) | [English](#-english)**

一个让 AI Agent（WorkBuddy / Claude Code / Cursor 等任何支持 Agent Skills 规范的智能体）
对**开发完成但尚未打包**的软件产品进行系统化质检的 Skill。覆盖需求对照、代码审查、
动态测试、UI 视觉评审、回归记忆与发布门禁的完整闭环。

---

## 🇨🇳 简体中文

### 它解决什么问题

产品/功能刚开发完、还没打包时，最容易积累 bug 却最没人管。qa-inspector 让 AI Agent
扮演质检员：拿着 PRD/设计文档逐条对照实现，跑接口冒烟、断言数据库、驱动浏览器/手机
做端到端走查，最后给出 **Go / No-Go** 的发布判定——每条结论都挂证据。

### 五阶段流水线

| 阶段 | 名称 | 做什么 |
|---|---|---|
| **S0** | 意图识别 + 环境自检 | 识别项目类型（Web/全栈/后端/桌面/移动）、用户意图三要素（范围/深度/产出物）、探测依赖与引擎可用性，缺失先问用户、拒绝则三级降级 |
| **S1** | 需求提取矩阵 | 七步法从 PRD/设计文档提取 F-001~F-xxx 覆盖矩阵（无文档则反推），须用户确认后冻结 |
| **S2** | 静态代码审查 | 错误处理、SQL 注入、N+1、事务、并发、密钥泄露等清单式审查，结论挂 `文件:行号` |
| **S3** | 动态引擎路由 | API 冒烟（零依赖）→ DB 断言（sqlite 零依赖）→ **Midscene** Web E2E → **Maestro** Android E2E → 截图评审兜底，按环境自动路由 |
| **S4** | UI 九维度评审 | 布局/对齐/层级/文案/配色/交互态/响应式/状态完备/一致性，playwright 自动截图或手动兜底 |
| **S5** | 汇总 + 回归 + 门禁 | 生成报告与 bugs.json 快照 → 与历史快照对比得出 **new / persisting / fixed / regressed** 四态 → Go/No-Go 门禁（CI 可用） |

### 核心特性

- 🎯 **PRD 对照矩阵**：每条需求编号可追溯，implemented / partial / missing 一目了然
- 🧪 **三层动态测试**：API 冒烟 → DB 数据断言 → 视觉驱动 E2E，深度按需选择
- 🧠 **回归记忆库**：二次质检自动对比历史，"修了又坏"（regressed）直接 No-Go
- 🚦 **机器可读门禁**：`go_nogo_gate.py` 输出 verdict.json + 退出码，可直接嵌入 CI
- 🛟 **三级降级兜底**：环境缺什么都不阻塞——L1 全动态 / L2 半动态 / L3 纯静态，报告标注置信度
- 📦 **零硬依赖**：核心脚本纯 Python 标准库（3.10+），E2E 引擎全部可选
- 🔒 **证据纪律**：所有结论必须挂 `文件:行号` / 截图 / 响应体；数据正确性只在 API/DB 层断言

### 快速开始

```bash
# 1. 安装到 WorkBuddy（或任意支持 skills 目录的 Agent）
git clone https://gitee.com/kieranhoward/full-qa-inspector.git ~/.workbuddy/skills/qa-inspector

# 2. 对话中触发（WorkBuddy）
使用 @skill:qa-inspector 质检一下 "D:\path\to\your-project"
```

Agent 会先问三个问题（检查范围 / 深度 / 产出物形式），确认矩阵后自动走流水线。

### Bug 分级与发布判定

| 级别 | 定义 | 对发布的影响 |
|---|---|---|
| **P0 致命** | 崩溃 / 数据丢失 / 安全漏洞 / 主流程不可用 | **No-Go** |
| **P1 严重** | 主流程受阻有绕行 / 数据错误 | ≥3 条或涉数据 → 有条件 Go |
| **P2 一般** | 次要功能异常 / UI 错乱 | 计划修复 |
| **P3 轻微** | 文案 / 样式打磨 | 择期处理 |

### 目录结构

```
qa-inspector/
├── SKILL.md                     # 主控：五阶段流程 + 硬规则
├── references/
│   ├── prd-matrix.md            # S1 七步法与矩阵列定义
│   ├── backend-check.md         # S2 审查清单 + S3 API/DB 方法
│   ├── engine-midscene.md       # S3 Web E2E 引擎接入（Midscene）
│   ├── engine-maestro.md        # S3 Android E2E 引擎接入（Maestro）
│   ├── ui-review.md             # S4 截图与九维度评审
│   ├── severity.md              # 分级标准 + 引擎结果映射 + Go/No-Go
│   ├── regression-memory.md     # 历史快照约定 + 四态回归
│   └── ci-integration.md        # CI 集成（GitHub Actions / Gitee Go）
├── scripts/
│   ├── smoke_api.py             # API 冒烟（零依赖 urllib）
│   ├── db_assert.py             # DB 断言（sqlite 零依赖，mysql/pg 可选）
│   ├── grab_screens.py          # 截图（playwright 自动 / 手动兜底）
│   ├── regress_diff.py          # 回归四态对比
│   └── go_nogo_gate.py          # 发布门禁（verdict.json + 退出码）
└── assets/
    ├── report-template.html     # 质检报告模板
    └── bug-entry-template.md    # 单条 bug 模板
```

### CI 集成示例

```yaml
# .github/workflows/qa-gate.yml
- name: QA Gate
  run: python scripts/smoke_api.py --cases smoke_cases.json && python scripts/go_nogo_gate.py --bugs bugs.json
```

详见 [references/ci-integration.md](references/ci-integration.md)。

### 关键词

AI 质检 / 软件测试 / QA agent / bug 检测 / PRD 对照 / 需求覆盖矩阵 / API 冒烟测试 /
数据库断言 / E2E 自动化 / Midscene / Maestro / UI 视觉评审 / 回归测试 / 发布门禁 /
Go No-Go / CI/CD 质量卡口 / Agent Skills / WorkBuddy

---

## 🇬🇧 English

### What It Solves

The window between "feature is done" and "app is packaged" is where bugs pile up
unnoticed. qa-inspector turns your AI agent into a QA engineer: it cross-checks the
implementation against the PRD/design doc, runs API smoke tests, asserts database
state, drives browsers/phones for end-to-end walkthroughs, and issues a **Go / No-Go**
release verdict — every conclusion backed by evidence.

### Five-Stage Pipeline

| Stage | Name | What It Does |
|---|---|---|
| **S0** | Intent + Env Check | Detects project type (web/full-stack/API/desktop/mobile), user intent (scope/depth/deliverable), probes dependencies; asks before installing, degrades gracefully if refused |
| **S1** | Requirements Matrix | Extracts an F-001~F-xxx coverage matrix from the PRD via a 7-step method; frozen after user confirmation |
| **S2** | Static Review | Checklist-driven audit: error handling, SQL injection, N+1, transactions, concurrency, leaked secrets — every finding cites `file:line` |
| **S3** | Dynamic Engine Routing | API smoke (zero-dep) → DB assertions (zero-dep sqlite) → **Midscene** web E2E → **Maestro** Android E2E → screenshot fallback, auto-routed by environment |
| **S4** | UI 9-Dimension Review | Layout / alignment / hierarchy / copy / color / interaction states / responsive / state completeness / consistency |
| **S5** | Report + Regression + Gate | Emits report + bugs.json snapshot → diffs against history into **new / persisting / fixed / regressed** → Go/No-Go gate (CI-ready) |

### Highlights

- 🎯 **Traceable requirement matrix** — every requirement has an ID; implemented / partial / missing at a glance
- 🧪 **Three-layer dynamic testing** — API smoke → DB assertion → vision-driven E2E
- 🧠 **Regression memory** — second-run diffs against history; "fixed then broken" (regressed) → automatic No-Go
- 🚦 **Machine-readable gate** — `go_nogo_gate.py` outputs verdict.json + exit codes for CI
- 🛟 **3-level graceful degradation** — missing anything never blocks: L1 full-dynamic / L2 semi / L3 static-only, with confidence noted
- 📦 **Zero hard dependencies** — core scripts are pure Python stdlib (3.10+); E2E engines optional
- 🔒 **Evidence discipline** — every conclusion cites `file:line` / screenshot / response body

### Quick Start

```bash
# 1. Install into WorkBuddy (or any skills-folder-based agent)
git clone https://gitee.com/kieranhoward/full-qa-inspector.git ~/.workbuddy/skills/qa-inspector

# 2. Trigger in conversation (WorkBuddy)
Use @skill:qa-inspector to QA "D:\path\to\your-project"
```

### License

MIT — see [LICENSE](./LICENSE). No third-party source is bundled; the optional
regression-memory dependency [agent-qa](https://github.com/vostride/agent-qa) is
FSL-1.1-ALv2 (user-installed externally; internal QA use permitted). Midscene is MIT,
Maestro is Apache-2.0.

### Keywords

AI QA agent / software testing skill / bug detection / PRD compliance / requirements
coverage matrix / API smoke test / database assertion / E2E automation / Midscene /
Maestro / UI visual review / regression testing / release gate / Go No-Go /
CI quality gate / Agent Skills / WorkBuddy