内容
# 👁️ Vigilis — 智能QA框架
> 一个智能QA框架，**生成、分类和自我修复** Playwright、Cypress 和 Selenium 测试，适用于任何Web应用程序 — 可从 Claude Code/Desktop 作为 **MCP服务器** 或从 CI 作为 **CLI** 使用 — 整个循环在 **GitHub Actions** 中作为部署门控运行。框架是**自动检测**的；传递 `--framework playwright|cypress|selenium` 以强制使用。
[](https://github.com/piyushpathakqa/Vigilis/actions/workflows/ci.yml)
[](https://github.com/piyushpathakqa/Vigilis/actions/workflows/qa.yml)
**🌐 实时网站 → [vigilis.dev](https://vigilis.dev)** · 登陆页面（`apps/web`），使用Next.js、Framer Motion和预渲染的Remotion英雄构建。
> [!NOTE]
> **M0–M3 完成，M4 进行中**。整个循环作为代码运行：从URL生成测试 → 在CI中设门控 → 分类失败 → 用PR自我修复DOM漂移（同时拒绝真实错误）。参见 [路线图](#路线图)。
---
## 为什么
测试套件编写成本高，维护脆弱。Vigilis将Claude代理放入循环中执行缓慢的部分：探索应用程序并编写真实测试（Playwright、Cypress或Selenium），然后 - 当UI漂移时 - 诊断失败并打开修复PR，同时拒绝掩盖真实错误。框架从您的项目中**自动检测**；使用`--framework`显式强制使用。
## 想法：一个核心，两个消费者
Vigilis定义其QA工具**一次**并将其公开**两次**。
```
┌──────────────────────────────┐
│ @argus/core │
│ 代理循环（Claude） │ Anthropic Messages API + 工具使用
│ + 单个工具注册表 │ 浏览器 · dom · fs · playwright · git
└───────┬───────────────┬──────┘
│ │
┌──────────────▼──┐ ┌──▼───────────────┐
│ @argus/mcp │ │ @argus/cli │
│ MCP服务器 │ │ npx argus ... │
│ （Claude桌面）│ │ （在CI中使用） │
└─────────────────┘ └──────────────────┘
```
## 循环
目前运行三个行为；**作者**在路线图上。
| 阶段 | 输入 | 代理… | 输出 |
|-------|-------|------------|--------|
| **作者** _(路线图)_ | 普通英文意图 | 将意图编译为结构化测试计划 | `*.plan.json` |
| **生成** | URL | 探索应用程序，编写带有断言的规范 | `tests/*.spec.ts` |
| **分类** | 失败运行 | 分类真实错误与DOM漂移与随机错误 | 根因报告 |
| **修复** | 漂移判决 | 重写定位器，验证绿色，打开PR | 拉取请求 |
## 快速开始
```bash
pnpm install
cp .env.example .env # 添加您的ANTHROPIC_API_KEY
pnpm build
```
### 代理运行（E2E）
代理循环是活跃的。将它指向捆绑的演示应用程序并观察它探索 - 导航，捕捉DOM快照，读取`data-testid`s，并点击登录 → 购物车流程：
```bash
pnpm --filter @argus/core exec playwright install chromium # 一次性
pnpm --filter @argus/sample-shop dev # 终端 1 → http://localhost:3100
node --env-file=.env packages/cli/dist/index.js smoke http://localhost:3100/login # 终端 2
```
它打印一步一步的跟踪和令牌/成本行（~$0.05–0.15每次运行在快速模型上）。需要真实的Anthropic **API**密钥（Max订阅不支持API）。
或者 **编写测试并运行绿色**：
```bash
node --env-file=.env packages/cli/dist/index.js generate http://localhost:3100/login --run
```
它探索应用程序，编写`tests/generated/login.spec.ts`，并运行它针对sample-shop（`3 passed, 0 failed`）。默认为Opus以确保质量；添加`--model claude-haiku-4-5`以运行~10¢。
### 看它自我修复
播种DOM漂移，然后观察Vigilis分类和修复它（完整运行手册：[`docs/DEMO.md`](./docs/DEMO.md)）：
```bash
NEXT_PUBLIC_ARGUS_DEMO_DRIFT=1 pnpm --filter @argus/sample-shop dev # 重命名data-testid
node --env-file=.env packages/cli/dist/index.js heal \
http://localhost:3100/login --spec tests/generated/login.spec.ts # → dom-drift → 修复 → PR
```
在`dom-drift`上，它重写定位器，**重新运行以验证绿色**，并打开PR。在真实错误（`NEXT_PUBLIC_ARGUS_DEMO_BUG=1`）上，它拒绝并阻止门控 - Vigilis提高信号，它不隐藏失败。
### 在您自己的Playwright、Cypress或Selenium项目中使用
安装[`vigilis`](https://www.npmjs.com/package/vigilis)包，然后`vigilis init`搭建`vigilis.config.json`，以便`generate`/`triage`/`heal`获取您的项目默认值（`baseUrl`、`testDir`、`model`、`framework`）- 显式标志始终覆盖它：
```bash
npm i -D vigilis
export ANTHROPIC_API_KEY=sk-...
vigilis init # 自动检测框架（playwright.config.*等），写入vigilis.config.json
vigilis generate https://your-app.com/login --run # 探索 → 编写并运行真实规范
vigilis generate https://your-app.com/login --framework cypress --run # 强制Cypress输出
```
所有三个框架都是**实时验证**的 - 每个都运行完整的`generate → run green`循环针对样本应用程序（Playwright、Cypress和Selenium）。它们共享相同的`generate`/`triage`/`heal`命令 - `--framework`标志（或`vigilis.config.json`中的`framework`字段）选择适配器。
或者直接将任何命令指向任何URL；`--base-url`运行生成的规范对抗任何主机：
```bash
node --env-file=.env packages/cli/dist/index.js generate https://your-app.com/login \
--run --base-url https://your-app.com
```
> 生成的文件是普通规范 - 将它们复制到您的存储库的测试文件夹中，并像任何其他测试一样拥有它们。发布在npm上：`npm i -D vigilis`（v0.2.1 - Playwright、Cypress和Selenium都实时验证：检测 → 生成 → 运行绿色）。
### 从Claude Desktop / Code（MCP）驱动
`@argus/mcp`通过MCP公开QA工具。设置 + 配置片段：[`docs/MCP.md`](./docs/MCP.md)。
### 来源收据
当[Treeship](https://www.treeship.dev) CLI安装时，**每次`argus heal`运行都会密封到签名、离线可验证的收据中** - *您可以审计的自我修复QA*。无硬依赖；`--no-receipt`退出。参见[`docs/TREESHIP.md`](./docs/TREESHIP.md)。
## 存储库布局
```
argus/
├─ packages/
│ ├─ core/ # 代理循环，工具注册表，Claude客户端，提示
│ ├─ mcp/ # MCP服务器包装注册表
│ └─ cli/ # `argus author|generate|triage|heal`
├─ apps/
│ ├─ sample-shop/ # Next.js演示目标（登录+产品+购物车）
│ └─ web/ # 登陆页面（Next 15 · 运动 · Remotion英雄）→ Vercel
└─ tests/ # 生成的Playwright规范在此处
```
## 路线图
- ✅ **M0 — 基础** · monorepo，工具，CI
- ✅ **M1 — 核心 + 样本商店 + 生成** · `argus generate <url> --run`编写并运行真实测试
- ✅ **M2 — CLI + GitHub Actions门控** · `QA Gate`检查运行生成的规范（红/绿）
- ✅ **M3 — 分类 + 修复** · `argus heal`修复DOM漂移与PR，拒绝真实错误
- 🚧 **M4 — MCP服务器 + 润色** · `argus-mcp`上线（[`docs/MCP.md`](./docs/MCP.md）; 演示GIF接下来
- ✅ **登陆页面** · [`apps/web`](./apps/web)部署到Vercel → [vigilis.dev](https://vigilis.dev)
## 许可证
[MIT](./LICENSE) © Piyush Pathak
