argus

Argus 为何存在

如今，AI Agent 编写了大部分代码 — 而它们判断工作是否完成的依据是代码能否编译且看起来已完成，而不是浏览器中实际发生了什么。第三次点击时未捕获的异常。通过 HTTP 发送凭据的表单。4 秒的 LCP。暗色模式下消失的按钮。在无限循环中被反复请求的 API 端点。

Argus 弥合了这一差距。 它通过 Chrome DevTools Protocol 驱动真正的 Chrome，对本地运行的应用进行检查，并向 Agent（或你）提供一份按严重程度排序的结构化错误报告。Agent 修复；Argus 重新检查；在代码离开你的设备之前，整个循环就已完成。

快速开始

无需安装。 首次运行时，npx 会获取 Argus。

1 — 在项目根目录的 .mcp.json 中添加两行：

{
  "mcpServers": {
    "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] },
    "argus":           { "command": "npx", "args": ["-y", "argusqa-os"] }
  }
}

或通过 Claude Code 命令行添加：

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
claude mcp add argus -- npx -y argusqa-os

2 — 启动 Chrome（自动检测你的 Chrome 并设置正确的标志）：

npx -y -p argusqa-os argus-chrome

# macOS
open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new

# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"

# Linux
google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox

3 — 向你的 Agent 提问：

Run argus_audit on http://localhost:3000

就是这样。发现的问题会以结构化形式返回，并按严重程度排序 — 可直接显示在对话中、发送到 Slack，或保存为本地 report.html。遇到问题？运行 npx -y -p argusqa-os argus-doctor，即可通过一条命令诊断你的设置。

修复循环

Argus 在 Agent 编码会话中的工作方式如下：

You:    Build me a checkout page with a card form.
Agent:  [writes the code, dev server renders it]

You:    Run argus_audit on http://localhost:3000/checkout
Argus:  ● 2 critical · 3 warnings
        ● uncaught TypeError in checkout.js (visible on submit)
        ● form posts over HTTP — security_no_https
        ▲ card inputs missing labels + autocomplete (a11y/WCAG)
        ▲ LCP 4.1s — hero image unoptimized
        ▲ duplicate POST /api/cart ×7 — likely render loop

Agent:  [fixes all five]

You:    Run argus_get_context
Argus:  ✓ resolved: 5 · persisting: 0 · new: 0

argus_get_context 会与之前的快照进行差异比较，让 Agent 准确了解修复了什么、破坏了什么，以及还剩下什么 — 无需重新阅读大段输出。

“但我的 Agent 已经能驱动浏览器了……” — 确实如此。驱动不等于判断。原始浏览器 MCP（Playwright MCP、裸用的 chrome-devtools-mcp）为 Agent 提供了手和眼睛；Agent 随后必须在每次会话中重新推导要检查的内容，把上下文消耗在翻查控制台日志上。Argus 则是在此之上的判断层：包含 149 种已编码的问题类型，并具备阈值、严重程度策略、跨运行基线、偶发问题过滤、重复项去重和根因提示 — 一次调用即可返回，默认脱敏。

Argus 能捕获的问题

32 个分析引擎、149 种不同的问题类型，无需维护测试文件：

此外，每项发现都会经过后处理：

所有发现都会归类为 critical / warning / info，并发送到相应的 Slack 频道，或显示在本地 HTML 报告中。有关每项发现的严重性表格和检测方法，请参阅 REFERENCE.md。

适配你的技术栈

Argus 检查的是渲染后的输出，而不是源代码，因此从设计上就与框架无关。只要能在 Chrome 中运行，Argus 就能检查：

**如实说明其局限：**仅支持 Chrome/Chromium 渲染（不涉及 Safari/Firefox 引擎差异），仅支持 Web（不支持原生移动/桌面应用），后端服务通过页面生成的流量进行检查，而不是作为独立的 API 测试套件进行检查。

保密性 — Aegis 出站边界

默认开启。 Argus 会审计你的应用，查找机密信息和漏洞，因此它的发现结果恰恰是你最不希望离开本机的数据。它们跨越任何外部边界之前，Aegis 都会对其进行脱敏。对于采用 AI Agent 的团队，这正是“我们在使用 AI QA 工具”与“我们能准确告诉安全负责人它为何安全”之间的区别。

发送到外部接收端的发现结果——MCP 工具响应（会进入发起调用的 Agent 的上下文窗口，并传输到该 Agent 的模型提供商）、Slack 消息、GitHub PR 评论及其 ::error 注释、托管版/CI HTML 报告或 CI 日志——都会被精简为按需展示的内容：敏感发现结果只会以其 type + route + severity 和一个 🔒 标记的形式传出，绝不会包含原始载荷（message、evidence、请求/响应正文、标头、Cookie、堆栈）。URL 会去除查询字符串后再展示（令牌可能藏在其中）。良性发现结果会保留其消息，但仍会对消息进行清理，以去除其中意外嵌入的机密信息或个人身份信息（PII）。

这会在 Argus 自身的边界处实施 OWASP LLM02:2025 — 敏感信息泄露缓解措施（数据最小化、脱敏、默认拒绝的出站过滤）。可选的仅限本地重新填充保险库（ARGUS_REDACT_VAULT=1）可生成可逆且不含信息的令牌，用于生成差异稳定的工件；使用 npm run report:rehydrate 可在本地还原。完整的行为变更说明请参阅 CHANGELOG.md。

MCP 工具

向 Claude（或任何 MCP 客户端）提问——无需终端：

每个工具响应在到达 Agent 前，都会经过 Aegis 出站边界处理；如果有敏感详细信息被隐藏，还会附带可选的 redaction 附加信息（{ redacted, total }）。

示例提示词：

Run argus_audit on http://localhost:3000/checkout
Run argus_audit_full on http://localhost:3000/dashboard
Run argus_compare
Run argus_get_context

经实战检验，而非凭感觉检验

Argus 自身的正确性也通过审计你时所用的方式来保障：

• 171 个区块的集成测试框架中，998/998 项硬性断言全部通过，使用真实 Chrome 测试 64 个固定页面——包括每个类别的负向对照（误报为零）、全部 9 个 MCP 工具的黄金响应架构，以及一个上游漂移哨兵，可在版本升级时捕获 chrome-devtools-mcp API 变更
• 562 个无需 Chrome 的单元测试（Vitest）+ 基于属性的解析器模糊测试
• npm audit：0 个漏洞 · 每个 PR 均运行 CodeQL + Dependabot · Socket.dev：漏洞/质量/许可证评分均为 100/100/100
• 会话文件和捕获的令牌均以 0600 权限写入，仅所有者可访问

完整设置

前置条件

选项 A — MCP 服务 （推荐 Claude Code 用户使用）

无需本地安装。使用上面的快速开始，然后添加目标 URL：

# .env in your project root
TARGET_DEV_URL=http://localhost:3000
TARGET_STAGING_URL=https://staging.example.com   # optional — enables argus_compare

可选 — Slack 通知：

1. 前往 api.slack.com/apps → 创建新应用 → 将其命名为 BugBot
2. OAuth & Permissions → Bot Token Scopes：chat:write、files:write、files:read
3. 安装到工作区 → 复制 xoxb-... 令牌
4. 创建频道 #bugs-critical、#bugs-warnings、#bugs-digest，并在每个频道中运行 /invite @BugBot

SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_CRITICAL=C0000000000
SLACK_CHANNEL_WARNINGS=C0000000001
SLACK_CHANNEL_DIGEST=C0000000002

不使用 Slack 时：Argus 会自动生成 reports/report.html 并在浏览器中打开——无需额外配置。

选项 B — npm 包（CI / 开发依赖）

npm install --save-dev argusqa-os
npx argus init   # interactive wizard — detects framework, discovers routes, writes .env
npm run crawl    # run after Chrome is started

选项 C — 克隆仓库（贡献者 / 完整源代码）

git clone https://github.com/ironclawdevs27/Argus.git
cd Argus
npm install
npm run init     # interactive setup wizard

手动设置（跳过向导）：

cp .env.example .env
# Fill in TARGET_DEV_URL and optional Slack tokens

然后在 src/config/targets.js 中配置路由：

export const routes = [
  { path: '/',          name: 'Home',      critical: true,  waitFor: 'main' },
  { path: '/login',     name: 'Login',     critical: true,  waitFor: 'form' },
  { path: '/dashboard', name: 'Dashboard', critical: true,  waitFor: '[data-testid="dashboard"]' },
  { path: '/settings',  name: 'Settings',  critical: false, waitFor: null },
];

• critical: true — 此路由上的错误会发送到 #bugs-critical
• waitFor — Argus 在捕获前等待的 CSS 选择器（表示页面已就绪）

CLI 命令

npm run chrome         # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary)
npm run doctor         # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL
npm run crawl          # Batch audit of all configured routes
npm run compare        # Dev vs staging diff (CSS-only if no staging URL)
npm run watch          # Passive monitor — polls open Chrome tab every 1s
npm run report:html    # Generate reports/report.html from last JSON audit
npm run report:pdf     # Export HTML report to A4 PDF (requires: npm install puppeteer)
npm run server         # Start Slack slash-command server (port 3001)
npm run init           # Interactive setup wizard
npm run test:unit          # 562 unit tests — no Chrome required
npm run test:harness       # 171-block correctness harness — requires Chrome
npm run test:harness:log   # same, but tees full output to harness-results.txt
npm run test:coverage      # merged unit + harness coverage gate (requires Chrome)

监视模式 — 在你（或你的 Agent）开发时实时监控：

# Terminal 1: start your app
npm run dev

# Terminal 2: start Argus watcher
npm run watch
# Ctrl+C → stops monitor and writes reports/report.html

Slack 斜杠命令（可在任意频道中按需调用）：

/argus-retest https://staging.example.com/checkout

要通过隧道公开服务：cloudflared tunnel --url http://localhost:3001（免费，无需账户）。将生成的 URL 设置为 Slack App → Slash Commands 中的 Request URL。

GitHub Actions CI — PR 门禁

Argus 以复合 GitHub Action 的形式提供：每次 PR 触发时，它都会将差异映射到受影响的路由并进行审计，仅当发现 PR 引入的问题时才阻止合并（考虑基线）——同时生成幂等的 PR 评论和 Check Run。

将以下内容添加到仓库的机密中（Settings → Secrets → Actions）：

随附的 工作流 会在推送到 main、每天 UTC 时间上午 6 点以及手动触发时运行。如果发现严重问题，流水线将失败。

环境变量

故障排除

遇到任何问题，首先运行：npx -y -p argusqa-os argus-doctor——它会检查 Chrome 是否可访问、MCP 配置是否有效以及必需的环境变量键是否齐全，并为每项故障给出确切的修复方法。

Chrome DevTools MCP 无法连接

claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
# Restart Claude Code after adding

Slack 消息未能发送

• 令牌必须以 xoxb- 开头（不能是 xoxp-、xoxe- 或 xapp-）
• 在每个频道中运行 /invite @BugBot
• 必需的权限范围：chat:write、files:write、files:read

截图为空白

• 页面尚未加载完成——在 src/config/targets.js 中增大 pageSettleMs，或为该路由添加 waitFor 选择器

/argus-retest 返回 "dispatch_failed"

• 隧道 URL 已更改——在 Slack App → Slash Commands 中更新 Request URL，然后重新安装

CSS 分析结果为空

• 页面可能需要身份验证——确保你已在 Argus 控制的 Chrome 实例中登录

CI 流水线立即失败

• Chrome 可能无法及时启动——在 .github/workflows/argus.yml 中将 sleep 3 增加到 sleep 5

Argus 与 Playwright / Cypress 的区别

Argus 是一个互补层，并非单元测试或 E2E 测试的替代品：

已知限制

全部 998 项测试框架断言均已通过（998/998）——目前没有已知的 MCP 或 Chrome 层限制。Lighthouse 以无头模式运行（修复 lighthouse_audit 参数后）；其余软断言（性能跟踪、依赖 GC 的堆增长）仅在每周严格软断言流程（harness-strict.yml）中通过 ARGUS_HARNESS_STRICT_SOFT 提升为计入结果的硬断言。范围限制：仅支持 Chrome / Chromium，仅支持 Web 应用——请参阅适配你的技术栈。

托管版 Argus——创始会员

想要获得审计、历史记录、趋势、计划任务和团队仪表板，而无需运行 Chrome 或 npm？Argus Cloud 已开放创始会员早期体验：每月 $19，永久锁定此价格（常规价格为 $29）。

成为创始会员 → argus-qa.com

本页上的开源引擎始终采用 MIT 许可且功能完整——托管版提供的是便利和记忆能力，而非检测功能。

项目结构

src/
  argus.js              — single-page audit entry point
  mcp-server.js         — 9 MCP tools exposed to Claude / any MCP client
  orchestration/        — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
  utils/                — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
  adapters/browser.js   — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
  config/targets.js     — routes, thresholds, auth steps
  cli/
    init.js             — argus init interactive setup wizard
    chrome-launcher.js  — npm run chrome / argus-chrome — launches Chrome with correct flags
    doctor.js           — npm run doctor / argus-doctor — pre-flight checks
    pr-validate.js      — headless CI entry point for GitHub Actions
test-harness/           — 171-block correctness harness, 998 hard assertions, 64 fixture pages
test/unit/              — 562 Vitest unit tests (no Chrome required)
landing/                — Product landing page (React 19 + Vite + Tailwind)

完整源代码索引 → CLAUDE.md · MCP / DSL 参考 → SKILL.md

贡献

欢迎贡献——测试页面、新的检测类别、框架路由发现功能、文档等。请从 CONTRIBUTING.md 开始。

1. Fork 此仓库并创建一个分支
2. npm run test:unit — 无需 Chrome 即可验证（562 项测试）
3. npm run test:harness — 完整集成测试覆盖（需要在 9222 端口运行 Chrome）
4. 提交 PR — Argus 会通过 CI 工作流审计自身

许可证

MIT © ironclawdevs27