pixelcheck

PixelCheck

为编写前端的 AI Agent 提供真正的双眼和双手。

即插即用的 MCP 服务。五种浏览器基本操作。来自 15 个国家的 18 种用户画像。
本地优先 · 不绑定供应商 · MIT 许可 · 完全由你掌控。

快速开始 →  ·  基本操作  ·  MCP 服务  ·  审查预设  ·  为何不用端到端测试  ·  更新日志

---

如果 PixelCheck 对你有帮助，请点个星——这能帮助其他人发现这个项目。

---

此刻，你正充当截图中间人。

你的 AI Agent 正在编写你 80% 的前端。它速度很快，代码也写得很好，但它看不见。

• 它写了一个按钮。 你打开 Chrome 检查渲染是否正确，再把截图粘贴回去，让它修复。
• 它调整了 OAuth 流程。 你登录验证流程没有悄悄出问题。这个月已经是第六次了。
• 它更新了日文字符串。 用户发来邮件：“半个页面都是英文。”你没发现。
• 它重写了结账流程。 你在 iPhone、Android、iPad 上逐步操作，只为亲自感受第 3 步是否让人困惑。
• 它修改了阿拉伯语布局。 RTL 布局没有传递下去。你两天后才发现。

你成了桥梁。Agent 有想法，你有浏览器。两者却始终无法相遇。 每周都要耗费你数小时，而且周而复始，没有尽头。

PixelCheck 就是这座桥。

一个 MCP 服务。五种基本操作。只需接入一次——你的 Agent 就有了双眼和双手。

see(url, opts)              snapshot a page (DOM + screenshot + console + network)
act(url, steps)             execute an action sequence (semantic + selector + Computer Use)
extract(url, schema)        pull structured data matching a Zod / JSON schema
judge(url, rubric)          score a page against a rubric ("is this dark-pattern free?")
compare(a, b, criteria)     A/B comparison of two URLs (incl. blind mode)

现在，你的 Agent 可以导航、查看渲染后的 HTML、读取控制台错误、点击、填写、判断和比较。全程无需离开工作流——只需在 ~/.mcp.json 中添加四行，即可接入 Claude Desktop、Cursor、Cline、Continue、Zed 或 Claude Code。

npm install -g pixelcheck        # browser binary auto-installs on install
pixelcheck doctor                # verify environment (--fix self-heals)
pixelcheck-mcp                   # MCP server (stdio transport)

// ~/.mcp.json
{
  "mcpServers": {
    "pixelcheck": {
      "command": "pixelcheck-mcp",
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

重启客户端。你的 Agent 就有了双眼。

三项始终不变的承诺。

本地优先。 PixelCheck 完全在你的机器上运行。唯一的出站网络目的地是你的 Agent 已在使用的大模型提供商。截图、DOM、业务流程、OAuth 令牌、客户 URL——都属于你。零遥测。零远程存储。零 SaaS 注册。只有当视觉评审器主动为截图评分时，审计数据才会发送给 Anthropic；首次运行时，你只需选择加入一次。

不绑定供应商。 目前支持 Claude；多提供商抽象（OpenAI、Gemini、Ollama-local）已列入 v1.x 路线图，你的 Agent 只需切换一个配置标志即可更换提供商。原因很简单：把你锁定在单一大模型提供商的 AI 工具将在 2026 年消亡。PixelCheck 正是解药。

产品由你掌控。 MIT 许可证。开放源代码。没有付费层级。没有“专业版”升级路径。也没有正在筹备中的商业分支。本仓库中的产品，拥有 1858 项测试、29 份 ADR、30 个已发布的架构，是完整的产品。没有注册后才能使用的高级版本——过去没有，现在没有，将来也不会有。

---

审计预设——当你想成为用户，而不是桥梁时

当你亲自担任操作者时，这五项基本功能可以组合成更强大的能力：PixelCheck 在这些基本功能之上打包了涵盖 15 个国家、18 种角色的审计预设——以 CLI 为先的组合方案，可在每次部署后运行“让 18 位真实用户评审你的产品”。

你完成部署。测试通过。CI 显示绿色。但随后：

• 一位日本用户打开你的应用，发现 UI 中混杂着未完全翻译的英文字符串
• 一位在尼日利亚使用低价 Android 手机的用户，等了 12 秒才看到主视觉图片加载完成
• 你的 OAuth 登录流程又一次悄无声息地出错——这是 10 次部署中的第 6 次
• 阿拉伯语版本从左到右显示，导致整个布局无法使用
• 你的“可信”评分徽章显示绿色，文案却写着“请立即停止交互”

这些问题都无法通过 E2E 测试发现。 E2E 测试检查代码能否运行，却不会检查产品在真实情境下能否服务真实用户。

审计预设会启动真实的 Chromium 浏览器，模拟来自 17 个国家的 18 种不同用户，走查产品的核心流程并给出评估——就像让一位资深 PM、QA 工程师和 UX 评审人员在每次部署后，用每种语言、在每类设备上审计产品。

pixelcheck init projects/my-app --name "My App" --url "https://myapp.com"
pixelcheck run --project projects/my-app

输出：结构化报告，包含每个步骤的截图、视频录制、网络日志、WCAG 无障碍违规项，以及涵盖 6 个维度的 AI 评分；报告以 JSON、HTML 仪表盘或 Markdown 格式提供。

工作原理

对于每一种**（角色 x 场景）**组合：

 1. Launch Chromium with device-accurate fingerprint
    (viewport, locale, timezone, UA, regional proxy)
                        |
 2. Execute scenario steps semantically via Stagehand 3.x
    ("click the sign-up button" not "click #btn-37")
                        |
 3. 5-Layer Reliability Stack ensures 98%+ step success
    Stability Gate -> LLM Rewrite -> Selector Discovery -> Auto Selector -> Computer Use
                        |
 4. Claude Vision Critic + axe-core score each checkpoint on 18 dimensions
    completion | localization | visual_polish | trust_signals | accessibility | ...
                        |
 5. Critical steps escalate to Computer Use for pixel-level review
                        |
 6. Generate report: JSON + HTML dashboard + Markdown + video + HAR

为什么不只用 E2E 测试？

	传统 E2E	PixelCheck（审计预设）
测试内容	代码逻辑	产品体验
决策方式	硬编码选择器	AI 像人一样阅读页面
断言形式	expect(text).toBe("Welcome")	“作为一位使用免费层级的日本用户，这个 CTA 是否清晰且已完整本地化？”
UI 变更时	选择器失效，测试失败	语义指令自动适配
失败输出	堆栈跟踪	截图 + 视频 + 6 维评分 + 具体 UX 问题
能够发现的问题	功能缺陷	i18n 缺失、UX 阻碍、视觉回归、信任问题、无障碍违规、文化差异

PixelCheck 的审计预设并非 E2E 测试的替代品。 它是在 E2E 测试之后运行的工具——位于“代码能运行”和“产品够好”之间的一层。

与现有工具对比

	PixelCheck	Playwright	Cypress	Stagehand	Browserbase
开箱即用的 MCP 服务	✅	❌	❌	❌	❌
AI Agent 可调用的浏览器原语	5 个（see / act / extract / judge / compare）	不适用（底层页面 API）	不适用	3 个（act / extract / observe）	不适用
AI 视觉能力（judge / critique）	✅ 通过 Anthropic	❌	❌	❌（仅限操作）	❌
内置用户画像	15 个国家／地区，共 18 个	❌	❌	❌	❌
本地化报告（5 种语言）	✅	❌	❌	❌	❌
WCAG 2.x 审计 + SARIF 导出	✅（基于 axe-core，可用于 GitHub Code Scanning）	通过插件手动实现	通过插件手动实现	❌	❌
默认本地优先	✅（你的机器、你的 API 密钥）	✅	✅	✅（或使用 Browserbase）	❌（仅限云端）
供应商锁定	无（MIT，无 SaaS）	无	无	可选使用 Browserbase	完全锁定（付费 SaaS）
大模型提供商	可自由切换（默认使用 Anthropic；原语不依赖特定供应商）	不适用	不适用	可自由切换	不适用
开源	✅ MIT	✅ Apache 2.0	✅ MIT	✅ MIT	部分开源

简而言之：Playwright / Cypress 是确定性的浏览器驱动工具——你要明确告诉它们点击什么。Stagehand 为 Playwright 封装了自然语言 act / extract，让 Agent 能操控浏览器。PixelCheck 则更进一步：它提供 MCP 形态的接口，让任何 AI Agent 都能在操作能力（act / extract）之上使用视觉能力（see / judge / compare），并通过跨用户画像组合的审计预设开展审计。单元测试风格的测试用 Playwright；只需 Agent 填写表单时用 Stagehand；当 Agent 需要评估 UI，而不只是操作 UI 时用 PixelCheck。

用户画像

内置 18 个用户画像，涵盖现实世界中的用户多样性。订阅级别列表示该用户在你正在审计的 SaaS 产品中的订阅等级（免费用户 / Pro 订阅者 / 高级用户 / 企业用户），以便 PixelCheck 审计产品中按等级区分的功能（付费墙、增购提示、受限 UI、仅限 Pro 的流程）。PixelCheck 本身采用 MIT 许可证，完全免费，没有付费等级或商业分支。

用户画像	国家／地区	语言	设备	订阅级别（在你的应用中）
美国大学生	US	英语	iPhone 14	免费
东京家庭主妇	JP	日语	MacBook Pro	Pro
柏林安全分析师	DE	德语	iPad Pro	Power
上海学生	CN	中文	Xiaomi Android	免费
圣保罗自由职业者	BR	葡萄牙语	桌面电脑	免费
利雅得商人	SA	阿拉伯语（RTL）	iPhone 15 Pro	Pro
孟买上班族	IN	印地语	入门级 Android	免费
首尔设计师	KR	韩语	QHD 桌面电脑	Pro
河内学生	VN	越南语	Android	免费
莫斯科工程师	RU	俄语（西里尔字母）	Windows 桌面电脑	免费
拉各斯创业者	NG	英语	入门级 Tecno	免费
墨西哥城教师	MX	西班牙语（拉美）	Android	免费
雅加达零工劳动者	ID	印度尼西亚语	Android	免费
美国退休教师（72 岁）	US	英语	iPad	免费
伦敦安全分析师	UK	英语	桌面电脑	Power
巴黎市场经理	FR	法语	iPhone	免费
曼谷学生	TH	泰语	iPhone SE	免费
台北工程师	TW	繁体中文	iPad	Pro

每个用户画像都包含一个心智模型（他们是谁、有什么预期）和关键顾虑（哪些情况会让他们失去信任）。AI 审查者会从他们的视角评估你的产品。

6 种文字系统：拉丁字母、CJK、阿拉伯字母（RTL）、西里尔字母、天城文、泰文。

场景采用声明式 YAML 编写

无需编写代码。描述用户会做什么，而不是如何点击：

id: signup-flow
name: New User Signup
priority: P0
steps:
  - id: open-home
    type: visit
    url: https://myapp.com/${persona.url_locale}

  - id: click-signup
    type: act
    instruction: Click the sign-up or get-started button

  - id: check-language
    type: assert_visual
    instruction: |
      Is all visible text in ${persona.language}?
      Flag any English strings outside of brand names.

  - id: complete-oauth
    type: act
    instruction: Sign in with Google

  - id: verify-email
    type: check_email
    subject_contains: "welcome"
    timeout: 60000

  - id: a11y-check
    type: assert_a11y
    standard: wcag2aa          # axe-core WCAG analysis
    exclude: [".cookie-banner"]

  - id: rate-onboarding
    type: assert_visual
    critical_review: true    # escalates to Computer Use
    instruction: |
      Rate the post-signup experience. Is the value proposition
      clear within 10 seconds? Is the first action obvious?

12 种步骤类型：visit、act、extract、observe、wait_for、assert_visual、assert_dom、assert_a11y、check_email、screenshot、computer_use、custom

5 层可靠性堆栈

AI 驱动的浏览器并不稳定（基准成功率约为 75%）。我们通过工程手段解决了这个问题：

Layer 1: Page Stability Gate                              +10%  (zero cost)
         Wait for network idle + DOM stable + framework hydration
                            |
Layer 2: LLM Rewrite + Local Mutation                     +7%   (~$0.001/call)
         Haiku rewrites failed instructions using DOM context;
         local rules rephrase/decompose/specify as fallback
                            |
Layer 3a: Selector Hint                                   +3%   (zero cost)
          Optional CSS selector fallback (manual or YAML-defined)
                            |
Layer 3b: Auto Selector Discovery                         +3%   (zero cost)
          Stagehand observe() extracts candidate selectors automatically
                            |
Layer 4: Computer Use Fallback                            +2-4% ($0.01-0.15/call)
         Claude sees the actual pixels and operates the browser directly
         (Sonnet for non-critical steps, Opus for critical reviews)

目标：所有 persona / 场景组合的步骤成功率达到 98%–99%。

每个步骤都会通过 execution_method 记录成功的层，让你了解每次运行的可靠性细分情况。

报告

每次审计都会生成完整的证据包：

reports/2026-04-11_post-deploy/
 |-- audit.json              # Machine-readable, all scores and issues
 |-- audit.html              # Dark-theme dashboard with trend sparklines
 |-- audit-explorer.html     # Filterable SPA view of every (scenario × persona) — open with ?lang=zh-CN/ja/es/de for localised UI chrome
 |-- audit.pdf               # Stakeholder-facing summary (A4, 12pt, vector text)
 |-- summary.md              # Terminal-friendly overview
 |-- jp-japanese-pro-desktop__signup-flow/
      |-- 01-open_home.png          # Timestamped screenshot
      |-- 02-check_language.png     # + SHA-256 hash for each
      |-- network.har               # Full network log
      |-- console.log               # Browser console errors
      |-- video/*.webm              # Session recording

audit.json 和每个 MCP 工具响应都带有顶层 schema_version 字段（SemVer）。接口约定记录在 docs/contracts/RESULT_SCHEMA.md 中；机器可读的 JSON Schema 位于 docs/schemas/，可通过 npm run schemas 重新生成。

WCAG 合规报告

assert_a11y 场景步骤会运行 axe-core 来检测无障碍违规项。从 v1 开始，每项违规都会携带结构化的 WCAG 归属信息，并同步到所有利益相关方报告中：

• PDF 报告 — 包含“WCAG 合规摘要”部分，按符合性等级（A / AA / AAA）和四项 WCAG 原则（可感知、可操作、可理解、健壮）分组，并提供违规最多的准则表格，其中包含指向 W3C 理解文档的深层链接。
• SARIF（GitHub Code Scanning / GitLab SAST） — 每项准则都有独立的 ruleId，例如 wcag/1-4-3、wcag/2-1-1。可直接在 Security 选项卡中按 W3C 条款筛选。每条规则的详情面板会显示“WCAG 1.4.3 对比度（最低）（AA 级）”，并附上 W3C 规范链接。
• audit.json — 每项无障碍问题都会在现有的 description / recommendation 字段之外，增加 wcag_level 和 wcag_criterion 字段。

目录涵盖 WCAG 2.1（生产环境采用的标准）以及 WCAG 2.2 新增的 9 项成功准则（例如 2.4.11 焦点不被遮挡、2.5.8 目标尺寸）。以 zh-CN / ja / es / de 语言阅读报告的合规团队会看到已翻译的章节标题；SC 名称和编号（1.4.3、2.1.1）保持规范形式，以确保合规文档的一致性。

使用场景——回答 RFP 中“贵方是否符合 WCAG 2.1 AA？”的问题：

pixelcheck run --project myapp                                    # writes audit.pdf + audit.sarif
# Open audit.pdf → "WCAG Compliance Summary" section shows A / AA / AAA counts
# Or upload audit.sarif via github/codeql-action/upload-sarif → grouped under wcag/* ruleIds

完整设计请参阅 ADR-024。

本地化报告

面向利益相关方的报告（PDF / 趋势仪表板 / PR 差异 Markdown / PR 差异 HTML）会以受众使用的语言生成。v1 支持 5 种语言区域设置：

代码	语言	用途
en	英语（默认）	基准
zh-CN	简体中文	面向中国市场的团队
ja	日语	面向日本市场的产品组织
es	西班牙语	西班牙及拉丁美洲
de	德语	DACH 地区的企业

pixelcheck run --project myapp --locale ja          # Japanese PDF + reports
pixelcheck trends --project myapp --locale zh-CN     # Chinese trends dashboard
pixelcheck diff <a> <b> --format markdown --locale es  # Spanish PR comment

也可以在 config.yaml 中固定默认设置：

project_name: myapp
base_url: https://myapp.com
default_locale: ja    # any audit run on this project defaults to ja

翻译内容：报告框架——章节标题、表头、状态 / 严重性徽章、免责声明文本。未翻译的内容：PixelCheck 的调查结果本身（这些内容由大模型以你要求 Claude 使用的语言生成），以及数值 / 日期 / 运行 ID。完整设计请参阅 ADR-023。

翻译审校情况：机器辅助草稿，等待母语人士审校。我们会公开记录审校人员鸣谢信息——请参阅 docs/translation-review-template.md 和翻译审校问题模板。随着 v1.x 审校工作的完成，确认参与审校的人员将在下方列出。

语言区域设置	审校人员	日期	已应用的更正
en	（源文——无需审校）	—	—
zh-CN	待定	待定	待定
ja	待定	待定	待定
es	待定	待定	待定
de	待定	待定	待定

PDF 报告（audit.pdf）

面向工程团队之外的决策者——产品经理、高管、客户、销售 / 客户成功代表的 A4 纵向 PDF，共 4 个部分。这种格式可由所有邮件客户端内嵌呈现，可嵌入所有幻灯片，也可在所有手机上打开。

部分	内容
封面	项目 + URL + 运行日期 + 颜色编码的总评分（绿色 ≥ 8，琥珀色 5–8，红色 < 5）+ 7 项计数摘要卡片
主要发现	按严重程度排序（严重 → 高 → 中 → 低），最多 5 项；每项均注明场景 × 用户画像上下文 + 建议
场景结果	每个（场景 × 用户画像）对应一个区块：状态徽章、评分 + 费用、各维度表格、所有问题
方法	审计工作原理、用户画像列表、场景列表、校准免责声明、用于存档的运行 ID

矢量文本（可选择 / 搜索 / 访问），而非 HTML 截图。不嵌入截图，让文件保持在约 1 MB 以下并便于通过电子邮件发送；如需查看视觉证据，收件人可打开 audit-explorer.html（方法部分的免责声明中有引用）。

默认情况下，每次运行均启用。传入 --no-pdf 可在本地快速迭代时跳过。完整设计请参阅 ADR-020。

历史趋势

评分会记录在本地 SQLite 数据库中。查看历史记录有三种方式：

pixelcheck history                    # Terminal table of recent runs with scores
pixelcheck diff run_0412 run_0411     # Score deltas, new/resolved issues
pixelcheck trends                     # Full HTML dashboard with 5 charts (writes <reports>/trends.html)

pixelcheck trends 会读取 <reports>/history.db 并生成独立的 HTML 仪表板，回答“我们的 UX 是变好了还是变差了？”。其中包含 5 个内嵌 SVG 图表（无 Chart.js / 外部 CDN——可在任何防火墙环境下打开，也便于通过电子邮件发送 / 打印 / 存档）：

图表	所回答的问题
总评分折线图	趋势是上升还是下降？
Pass / Warn / Fail 堆叠柱状图	表现稳定还是时好时坏？
随时间变化的问题数（总数 + 严重问题）	回归问题的热点在哪里？
随时间变化的费用	效率是否在逐渐变化？
各维度多折线图	哪个评分维度导致了问题？

此外，顶部还有 6 张摘要卡片（最新评分、最近 7 次的平均值、最近 30 次的平均值、总费用、问题总数、严重问题总数），以及便于导航的近期运行记录表。完整设计请参阅 ADR-021。

pixelcheck trends --project myapp -n 90 --dashboard reports/trends.html

每次运行生成的 audit.html 还包含内嵌迷你折线图，可快速查看单份报告中的趋势。

质量门禁

如果体验低于你的标准，就让 CI 构建失败：

pixelcheck run --project projects/my-app --min-score 7.5
# Exit code 1 if overall score < 7.5

快速入门

1. 安装

npm install pixelcheck

pixelcheck 所需的浏览器二进制文件（Chrome Headless Shell）会在 postinstall 步骤中自动获取。如果该步骤被跳过——例如 CI、--ignore-scripts、离线机器，或设置了 PIXELCHECK_SKIP_BROWSER_DOWNLOAD=1——可按需运行以下命令获取：

npx pixelcheck install            # headless audits (default)
npx pixelcheck install --headed   # also fetch full Chromium for --headed runs

无需单独运行 npx playwright install——pixelcheck 会安装其启动所需的确切浏览器版本（单独安装可能会下载不匹配的版本）。如果缺少浏览器，首次运行 run / explore 时也会自动修复；pixelcheck doctor --fix 则会直接下载浏览器。

关于企业代理 / Alpine Linux / Docker / 隔离网络环境，请参阅 docs/INSTALLATION.md。

2. 检查环境

npx pixelcheck doctor

报告 Node 版本、API 密钥、配置 / 场景 / 用户画像、网络代理，以及与 api.anthropic.com 的连通性。准备就绪时退出代码为 0，任意检查失败时退出代码为 1——可用于 CI 脚本，在运行审计前快速失败。

添加 --verbose 可显示诊断详情；在离线 / 隔离网络环境中添加 --skip-network。

3. 设置项目（交互式或脚本化）

交互式向导（首次使用时推荐）：

npx pixelcheck init
# Walks you through project name, base URL, sample scenario, and runs
# `doctor` at the end to confirm setup.

非交互式（CI / 脚本化）：

npx pixelcheck init my-project --name acme-shop --url https://acme.example.com

无论采用哪种方式，都会创建以下文件：

• config.yaml（项目名称 + 基础 URL + 模型默认值 + 预算）
• scenarios/00-smoke.yaml（入门级视觉 + 无障碍检查）

4. 设置 API 密钥

export ANTHROPIC_API_KEY=sk-ant-...

请在 console.anthropic.com 获取密钥。上述向导会在密钥缺失时提醒你；也可随时运行 pixelcheck doctor 重新检查。

5. 创建你的第一个审计

npx pixelcheck init projects/my-app --name "My App" --url "https://myapp.com"

这会生成一个项目目录，其中包含配置文件和初始场景。编辑该场景，使其符合你的应用流程。

6. 运行

# Dry run — validate config, print the persona x scenario matrix
npx pixelcheck run --project projects/my-app --dry-run

# Full audit
npx pixelcheck run --project projects/my-app

# Debug mode — visible browser
npx pixelcheck run --project projects/my-app --headed

# Single persona
npx pixelcheck run --project projects/my-app --persona jp-japanese-pro-desktop

CI 集成

在每次部署后触发审计：

# .github/workflows/deploy.yml
audit-after-deploy:
  needs: [deploy]
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    # CI sets CI=true, which skips the auto browser-download; fetch it explicitly.
    - run: npm install pixelcheck && npx pixelcheck install
    - run: npx pixelcheck run --project .audit --min-score 7.0
      env:
        ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    - uses: actions/upload-artifact@v4
      if: always()
      with:
        name: audit-report
        path: reports/

也可以将任务分派到一个集中的 PixelCheck 仓库，由它审计你的所有项目：

    - run: |
        gh workflow run post-deploy-audit.yml \
          --repo your-org/pixelcheck \
          --field project="my-app"
      env:
        GH_TOKEN: ${{ secrets.GH_PAT }}

退出代码：0 = 通过，1 = 失败，2 = 警告。

CI 输出格式

当 PixelCheck 检测到 CI 环境（CI=true、GITHUB_ACTIONS=true、GITLAB_CI=true、CIRCLECI=true、TF_BUILD=True 或 JENKINS_URL）时，除了 audit.json/audit.html 外，还会自动生成四种标准格式：

文件	格式	使用方
junit.xml	JUnit XML	Jenkins、GitLab CI、Azure DevOps、CircleCI
audit.sarif	SARIF 2.1.0	GitHub Code Scanning、GitLab SAST
audit.jsonl	JSON Lines（每行一条记录）	jq、日志聚合器、自定义仪表板
github-annotations.txt	GHA 工作流命令	GitHub Actions 内联 PR 注释

在 GitHub Actions 中，工作流命令行也会输出到 stderr，这样问题就能直接显示在 PR 差异中，无需单独执行注释步骤。

可显式覆盖行为：

• --ci-format auto — 默认值；在 CI 中生成全部 4 种格式，在开发者笔记本上不生成
• --ci-format all — 无论环境如何，都强制生成全部 4 种格式
• --ci-format none — 跳过 CI 格式
• --ci-format junit,sarif — 以逗号分隔的格式子集

严重性映射：critical/high → SARIF error / GHA error；medium → warning/warning；low → note/notice。完整设计请参阅 ADR-019。

示例 — 将 SARIF 上传到 GitHub Code Scanning：

- run: npx pixelcheck run --project .audit
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: reports/<run-id>/audit.sarif

PR 差异报告

只需两条命令，即可将“此 PR 是否改善或损害了 UX？”的摘要作为 PR 评论发布：

# Audit main → audit PR → diff → post
- run: pixelcheck run --tag main && pixelcheck run --tag pr
- run: pixelcheck diff <MAIN_RUN_ID> <PR_RUN_ID> --format markdown --output diff.md
- uses: marocchino/sticky-pull-request-comment@v2
  with: { path: diff.md }

Markdown 内容包括：

• 标题指标表（总体评分 / 问题 / 严重问题 / 成本 / 时长），并带有 ▲ / ▼ 趋势箭头
• 各维度的变化（按绝对变化幅度排序）
• 🆕 此 PR 引入的新问题（附严重性标签和建议）
• ✅ 此 PR 修复的已解决问题
• 两个列表均为空时显示“没有有意义的 UX 变化”消息

其他输出格式：--format html 用于邮件 / Slack，--format json 用于下游图表，--format text（默认）用于终端。使用 --output <path> 直接写入文件（根据扩展名自动检测格式），或省略该选项以打印到 stdout。完整设计请参阅 ADR-022。

通知：完成时发送 Slack webhook 和 Telegram bot 通知。

MCP 服务

PixelCheck 附带一个 MCP 服务，可让任何模型上下文协议客户端（Claude Code、Cursor、Cline、Continue、Zed agent）在不中断工作流的情况下执行审计。

在 Claude Code 中注册

添加到 ~/.mcp.json（或你的客户端对应的配置文件）：

{
  "mcpServers": {
    "pixelcheck": {
      "command": "pixelcheck-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

工具

工具	类型	适用场景
audit_url	预设	想对一个 URL 执行完整审计流程，包括 Agent 循环、评分以及 JSON + HTML 报告。
explore_url	预设	想快速自主运行并指定自由格式的目标；无需场景 YAML。
see	基础工具	想查看一次 URL，并获取 DOM 摘要、截图、控制台错误以及可选的自然语言备注。省略 goal 时，LLM 成本为 0。
act	基础工具	想执行一系列操作（点击 / 填写 / 滚动 / 截图 / 自然语言 act / 视觉 note），并获取每步状态、最终 DOM 和截图。
extract	基础工具	想从 URL 获取符合指定类型的数据，例如定价层级、功能列表、常见问题条目，并严格按照要求的格式返回。向工具提供 JSON Schema，即可获取与其匹配的 data，以及 DOM / 控制台 / 截图。
judge	基础工具	想根据评分标准评判一个 URL，例如评估美观度、暗黑模式风险或任何自定义标准。返回各项标准的评分（0..10），以及标明严重程度和屏幕位置的问题发现。需调用 1 次视觉模型。
compare	基础工具	想根据同一评分标准比较两个 URL。默认的 double_blind 模式会先独立评判两边，再综合比较（调用 3 次视觉模型，不受锚定偏差影响）。fast 模式只调用 1 次（成本较低，但存在锚定偏差）。
list_personas	元工具	查看项目中已安装的角色。
list_scenarios	元工具	查看项目中已安装的场景。
list_capabilities	元工具	自我描述服务：列出所有内置工具及其类型 / 是否可缓存 / 静态成本等级 / 副作用 / 依赖声明，并提供公开的环境变量表和实时结果缓存状态。纯粹的自省工具——首次连接时调用一次，为本次会话的后续操作做好规划。
calibrate_critic	元工具	使用带标签的测试样例运行评判器校准门禁（返回通过 / 失败状态及一致性指标）。
get_last_report	元工具	从本地历史数据库中读取最近一次审计的摘要 JSON。

see — 单次导航快照

工具集中最轻量的工具。想知道“此刻这个页面上有什么？”时调用它，无需启动完整审计。

// MCP tools/call arguments
{
  "url": "https://stripe.com/pricing",
  "goal": "Is there a free tier?",      // optional — runs one vision call, ~$0.005
  "wait_for": "networkidle",            // or "load", "domcontentloaded", or a CSS selector
  "viewport_width": 1280,
  "viewport_height": 800,
  "include_dom": true,
  "include_console": true,
  "headless": true,
  "timeout_ms": 30000
}

返回一个 SeeResult（见 docs/schemas/see-result.schema.json），包含 url_final（重定向后的 URL）、title、dom（交互元素数量 + 标题 + 摘要）、console.errors、screenshot（路径 + sha256）以及 note（设置目标时的目标答案）。生成的产物存放在 $AUDIT_SEES_DIR 或 ~/.pixelcheck/sees/<UTC-iso>-<rand6>/ 下。设计原理请参见 ADR-011。

act — 执行动作序列

运行一系列浏览器操作（确定性操作 + AI 操作），返回逐步追踪、最终 DOM 和最终截图。引擎会自动选择：纯确定性步骤列表使用原始 Playwright（冷启动约 1 秒，无需 LLM 密钥）；只有在至少一个步骤为 { "type": "act" } 时才会启动 Stagehand。

// MCP tools/call arguments
{
  "url": "https://stripe.com/pricing",
  "steps": [
    { "type": "fill", "selector": "input[name=email]", "value": "[email protected]" },
    { "type": "click", "selector": "button[type=submit]" },
    { "type": "wait_for", "selector": ".dashboard", "state": "visible" },
    { "type": "screenshot", "label": "after-login" },
    { "type": "act", "instruction": "Click the Upgrade to Pro button" },
    { "type": "note", "goal": "Was the upgrade modal shown? Any error?" }
  ],
  "stop_on_error": true
}

每种步骤类型：

类型	成本	说明
goto	0	重新导航。支持 wait_for（load / domcontentloaded / networkidle / CSS 选择器）。
click / fill / press / wait / wait_for / scroll	0	直接使用 Playwright。无需 LLM。
screenshot	0	将 <label>.png（默认 step-<index>.png）写入本次调用的资源目录。
act	约 1 次 LLM 调用	由 Stagehand 解析的自然语言操作。整个会话都会强制使用 Stagehand 引擎。
note	约 $0.005	针对当前页面进行一次视觉调用。两种引擎均可使用。

返回一个 ActResult（参见 docs/schemas/act-result.schema.json），包含 engine（"playwright" | "stagehand"）、steps[]（每项包含 status、duration_ms、cost_usd，以及可选的 screenshot / note / output / error）、最终的 dom / console / screenshot，以及总计 cost_usd。失败语义：stop_on_error: true（默认值）会在首次失败后跳过剩余步骤（记录为 status: "skipped"）；false 会运行所有步骤，只要有任何步骤失败，顶层 status 就会是 "error"。资源文件位于 $AUDIT_ACTS_DIR 或 ~/.pixelcheck/acts/<UTC-iso>-<rand6>/ 下。设计原因请参见 ADR-012。

extract — 基于 Schema 的结构化提取

向工具提供描述所需数据结构的 JSON Schema，即可获取形状匹配的 data。每次调用会进行一次 LLM 调用。始终使用 Stagehand（extract 从根本上由 LLM 驱动；对于“给我一个形状任意的对象”这类需求，没有确定性替代方案）。

// MCP tools/call arguments
{
  "url": "https://stripe.com/pricing",
  "schema": {
    "type": "object",
    "properties": {
      "plans": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name":     { "type": "string" },
            "price":    { "type": "number", "description": "Monthly price in USD" },
            "features": { "type": "array",  "items": { "type": "string" } }
          },
          "required": ["name", "price"]
        }
      }
    },
    "required": ["plans"]
  },
  "instruction": "Extract every pricing plan card",   // optional — auto-synthesised from schema field names if omitted
  "selector": "main"                                   // optional — constrain to a sub-region
}

接受的 JSON Schema 子集（转换器会拒绝所有其他内容，并给出精确错误消息，指出关键字和 JSON 路径）：

接受	拒绝
type: object | array | string | number | integer | boolean | null	oneOf、anyOf、allOf、not
type: ["string", "null"]（可空简写）	$ref、patternProperties、dependencies
properties、required、items、enum、description、nullable	if / then / else、const（请改用只有一个元素的 enum）
additionalProperties（接受但忽略——z.object 默认会剥除额外属性）
pattern、minLength、maxLength、minimum、maximum（接受但不强制执行——LLM 不会遵守这些约束）

根类型必须是 type: "object"，因为 Stagehand 的 extract() 要求对象 Schema。也接受不带 type 的简写形式 { properties: {…} }，并将其视为对象。

返回一个 ExtractResult（参见 docs/schemas/extract-result.schema.json），包含 engine: "stagehand"、data（与 Schema 匹配）、schema_used / instruction_used / selector_used（原样返回，供客户端重新验证和调试）、dom / console / screenshot，以及根据 Stagehand 的 metrics.extractPromptTokens × estimateCost(model, …) 得出的 cost_usd。data.json 资源文件也会与截图一同保存，以便重放。如果在 recordUsage 期间触发严格的成本上限保护，status 会变为 "error"，但仍会返回 data 和 cost_usd（部分成功）。资源文件位于 $AUDIT_EXTRACTS_DIR 或 ~/.pixelcheck/extracts/<UTC-iso>-<rand6>/ 下。设计原因请参见 ADR-013。

judge — 由评估标准驱动的页面评审

根据评估标准为一个 URL 评分——美观度、暗黑模式风险，或你提供的任意自定义标准。每次调用只进行一次视觉模型调用。内置评估标准以数据形式定义在 src/core/critics/ 中；标准 ID 属于公开契约的一部分，因此使用方可以在不同运行之间将评审结果关联回对应的评估标准。

// MCP tools/call arguments
{
  "url": "https://stripe.com/pricing",
  "rubrics": ["aesthetic", "dark_pattern"],          // 8 + 12 built-in criteria
  "custom_criteria": [                                // optional one-off rubric
    { "id": "pricing_clarity", "label": "Pricing clarity", "description": "Is total cost visible without scrolling?" }
  ],
  "persona": "us-power-user-desktop",                  // optional — drives viewport/locale via personas/
  "wait_for": "networkidle"
}

内置评估标准：

评估标准	评分项	示例
aesthetic（8 项）	visual_hierarchy、typography、alignment_grid、color_contrast、spacing_rhythm、polish、information_density、brand_cohesion	以 Stripe / Linear / Vercel / Notion 为基准
dark_pattern（12 项）	forced_continuity、hidden_costs、preselected_options、fake_urgency、confirmshaming、obstruction、misdirection、trick_questions、disguised_ads、bait_and_switch、privacy_zuckering、nagging	Brignull 分类法 + 2018 年挪威消费者委员会的标准
custom	调用方提供	任意一次性评估标准——定价清晰度、转化路径、无障碍体验说明，……

评分方向统一：无论类型如何，分数越高越好。美观度评分为 10 表示极佳；暗黑模式评分为 10 表示未检测到暗黑模式。因此，overall_score（所有评审评分的平均值）在混合评估标准下也保持单调一致。

返回一个 JudgeResult（参见 docs/schemas/judge-result.schema.json），包含 rubrics、criteria（渲染到提示词中的完整评估标准列表）、verdicts[]（每项标准对应的 { criterion_id, score, rationale, evidence }）、findings[]（带严重程度评级且包含 location 的问题）、overall_score、summary，以及标准的 dom / console / screenshot / cost_usd 封装。产物存放在 $AUDIT_JUDGES_DIR 或 ~/.pixelcheck/judges/<UTC-iso>-<rand6>/judge.json 下。设计理由请参见 ADR-014。

compare — A/B 页面比较

根据共同的评估标准，对两个页面进行 A/B 比较。默认模式为 double_blind：先使用相同的评估标准分别（并行）评审两侧，再进行一次综合视觉模型调用，同时查看并排显示的两张截图，并将先前的评审结果作为上下文。总计进行三次视觉模型调用；由于两次评审并行运行，实际耗时约为两次调用。这与 Nielsen Norman、Baymard Institute 等商业 UX 评审实践一致：先独立评估每个候选页面，再进行综合比较。这样做是为了避免锚定偏差：要求模型在同一提示词中为两个页面评分时，绝对分数会被两者之间的差异拉动，而非反映页面本身。

fast 模式会简化为一次并排视觉模型调用——成本更低（约便宜 3 倍），但会受到锚定偏差影响。适用于批量比较（例如通宵评估 100 个竞争对手）等更看重成本比而非单次调用准确性的场景。

// MCP tools/call arguments
{
  "a": { "url": "https://stripe.com/pricing" },
  "b": { "url": "https://intercom.com/pricing", "viewport_width": 375, "viewport_height": 812 },
  "rubrics": ["aesthetic", "dark_pattern"],
  "mode": "double_blind"                                // default; use "fast" for cheap batches
}

每一侧的 viewport 都可单独设置，因此你可以比较桌面端 A 与移动端 B。任一侧也可以使用先前 see / extract / judge 调用预先捕获的快照（{ "capture": { ... } }）；该工具会跳过该侧的浏览器操作。

返回一个 CompareResult（参见 docs/schemas/compare-result.schema.json），包含 mode、rubrics、criteria、side_a / side_b（在 double_blind 模式下各自包含内嵌的 JudgeResult、单侧截图和产物目录）、per_criterion[]（{ criterion_id, score_a, score_b, winner: "a"|"b"|"tie", rationale }）、overall_winner、summary 和总计 cost_usd。产物存放在 $AUDIT_COMPARES_DIR 或 ~/.pixelcheck/compares/<UTC-iso>-<rand6>/ 下，其中包含 a/ 和 b/ 子目录以及 compare.json 旁车文件。

list_capabilities — 自我描述

首次连接时调用一次，获取整个服务端的结构化映射：所有工具的类型、输入架构、结果架构标题、可缓存性、静态成本估算档位、副作用和依赖声明；以及公开的环境变量表和结果缓存的实时状态。

// MCP tools/call arguments — none required
{}

返回 ListCapabilitiesResult（参见 docs/schemas/list-capabilities-result.schema.json）：

{
  "schema_version": "1.2.0",
  "server": { "name": "pixelcheck", "version": "0.3.0" },
  "result_schema_version": "1.2.0",
  "tools": [
    {
      "name": "judge",
      "kind": "primitive",
      "result_schema": "JudgeResult",
      "cacheable": true,
      "cost_estimate_usd": { "typical": 0.02, "min": 0.01, "max": 0.06, "unit": "per_call", "notes": "..." },
      "side_effects": ["navigation", "network_egress", "fs_writes_artifacts"],
      "requires": { "api_keys": ["ANTHROPIC_API_KEY"], "browser": true }
      /* …plus name / description / input_schema */
    }
    /* …11 more rows */
  ],
  "env": [
    { "name": "ANTHROPIC_API_KEY", "scope": "auth", "default": "", "required": true, "description": "..." }
    /* …20 more rows across auth / cache / cost_guard / artifacts / logging / memory / reports */
  ],
  "cache": { "enabled": true, "ttl_ms_default": 86400000, "path": "~/.pixelcheck/result-cache.db" }
}

纯粹的自省。 不调用大模型、不启动浏览器，也不探测机密是否存在。机密环境变量的名称会公开（方便你知道要设置什么），但永远不会返回其值。缓存文件路径会公开，因为路径不属于机密——编写诊断或清理脚本的 Agent 确实需要这些路径。设计理由详见 ADR-016，其中包括为什么 tools/list 保留严格规范子集，以及为什么刻意不探测运行时是否存在机密。

每个工具响应都根据 docs/contracts/RESULT_SCHEMA.md 携带顶层 schema_version 字段。同一服务端进程中的两个并行工具调用拥有各自独立的运行费用上限（参见 ADR-009），但共享持久化的每日账本。

添加新工具：在 src/mcp/tools/<name>.ts 下创建文件并导出 ToolDefinition，然后将其加入 src/mcp/server.ts 中的 ALL_TOOLS。注册表设计理由详见 ADR-010。

多项目支持

一次 PixelCheck 安装即可服务你的所有项目：

pixelcheck/
 |-- personas/              # 18 shared personas (used by all projects)
 |-- projects/
      |-- my-saas/          # Project A
      |    |-- config.yaml
      |    |-- scenarios/
      |-- my-mobile-web/    # Project B
      |    |-- config.yaml
      |    |-- scenarios/
      |    |-- personas/    # Optional: project-specific persona overrides
      |-- my-docs-site/     # Project C
           |-- config.yaml
           |-- scenarios/

安全性

• Stripe 实时密钥保护 — 如果在环境中检测到 pk_live_，则拒绝启动
• 凭据脱敏 — OAuth 令牌、密码、API 密钥和 Webhook URL 绝不会写入报告或日志（采用两层防护：apiKey / password / token / cookie 等常见字段名始终会被屏蔽；从环境变量获取的具体机密值则会在任何出现位置被子串替换，包括日志消息中）
• Computer Use 防护措施 — 默认启用 Anthropic 的提示词注入分类器
• 预算上限 — 当累计 API 费用超过阈值时，停止启动新的审计单元

日志记录

内部事件使用结构化日志记录器（pino）。输出写入 stderr，因此 stdout 可保持干净，用于 CLI 结果和 MCP stdio 协议。默认情况下，当 stderr 是 TTY 时使用人类可读格式，否则使用 JSON。

环境变量	取值	默认值	效果
LOG_LEVEL	trace、debug、info、warn、error、fatal、silent	info	最低日志级别
LOG_PRETTY	1、true、0、false、auto	auto	强制使用美化格式或 JSON；auto 会根据 TTY 决定
LOG_FILE	/path/to.log	未设置	同时将日志写入文件

示例：

# CI / piped: JSON to stderr automatically (no TTY)
pixelcheck run --project projects/my-app 2> audit.log

# Force JSON even in a terminal
LOG_PRETTY=0 pixelcheck run --project projects/my-app

# Verbose debugging
LOG_LEVEL=debug pixelcheck run --project projects/my-app

成本保护

进程级支出上限可防止大模型账单失控。每次 Anthropic API 调用都会根据以下两个上限进行跟踪：

• 单次运行 — 单次审计 / MCP 工具调用。在运行开始时重置。
• 每日 — UTC 日累计值，通过 JSON 账本在多个进程间持久保存（默认路径为 ~/.pixelcheck/cost-ledger.json，可通过 AUDIT_COST_LEDGER_PATH 覆盖）。

超出任一上限都会抛出 BudgetExceededError，使调用循环立即停止。账本会自动清理 30 天前的条目。

环境变量	默认值	作用
AUDIT_COST_MAX_RUN_USD	5	每次审计运行 / MCP 工具调用的最高美元金额
AUDIT_COST_MAX_RUN_TOKENS	10000000	每次运行的输入和输出 Token 总数上限
AUDIT_COST_MAX_DAILY_USD	50	每个 UTC 日所有运行的最高美元金额
AUDIT_COST_MAX_DAILY_TOKENS	100000000	每个 UTC 日的输入和输出 Token 总数上限
AUDIT_COST_LEDGER_PATH	~/.pixelcheck/cost-ledger.json	持久化每日账本的路径
AUDIT_COST_GUARD_DISABLED	未设置	设为 1 / true 可完全绕过（CI / 测试）

成本保护是在运行器的 budget_usd 上限之上叠加的，且与之相互独立；该上限只会阻止运行器调度新单元。成本保护还能捕获单元调度器无法监控的直接 MCP 工具调用、计算机使用循环和指令变更。

可通过 run started 日志行中包含的快照检查当前状态，或使用：

LOG_LEVEL=debug pixelcheck run --project projects/my-app
# emits one "llm usage recorded" debug line per Anthropic call with running totals

并发安全

PixelCheck 支持多个进程同时运行，适用于两个并行的 pixelcheck 终端、一个 MCP 服务并行处理两个 audit_url 调用，或 CLI 运行与 MCP 服务调用同时进行等场景。具体而言：

• 成本账本（cost-ledger.json）：受跨进程建议锁文件（<ledger>.lock）保护。并发记录不会丢失更新。
• 单次运行成本计数器：每次 MCP 工具分发和每次 runAudit 调用都会获得各自的 AsyncLocalStorage 作用域，因此两个并行调用拥有独立的单次运行美元上限。持久化的每日账本仍为共享。
• 内存数据库（memory.db）：record(fact) 使用一条原子性的 INSERT … ON CONFLICT DO UPDATE。不存在先 SELECT 再写入的竞态。
• 视觉差异基线：首次运行时先复制到 .tmp 路径，再通过 linkSync 写入目标位置。两个并行的首次运行都能成功；先写入的一方胜出。

如果进程在持有成本账本锁时崩溃，锁会在 30 秒后自动恢复（如果持有锁的进程 PID 已不再运行，则会更早恢复）。设计说明见 ADR-009。

SQLite 存储共用统一的迁移运行器

PixelCheck 使用四个本地 SQLite 文件（history.db / memory.db / plan-cache.db / result-cache.db）。它们都通过 src/core/db-migrate.ts > openManagedDatabase() 打开；该函数会集中处理父目录创建、busy_timeout pragma、文件锁定的 WAL 转换，以及由 PRAGMA user_version 驱动的迁移流程。每项迁移都在独立的 BEGIN IMMEDIATE / COMMIT 块中运行，因此 SQL 执行失败时，该步骤中的所有 CREATE / ALTER / INSERT 都会原子性回滚，不可能留下不完整的架构。旧版二进制程序打开新版数据库时，会明确报错并抛出 MigrationVersionError，而不是针对缺失列运行错误的查询。设计说明见 ADR-026。

结果缓存

持久化本地缓存会记忆确定性原语的结果，因此重复的相同调用会立即返回，且 cost_usd = 0。AI Agent 可以更积极地规划，而不必每次调用工具都消耗新的视觉令牌。

已缓存的原语：

原语	已缓存	备注
judge	✅	相同的 URL + 评分标准 + 自定义条件 + 角色设定/模型 → 相同的判定结果。
extract	✅	相同的 URL + 架构 + 指令 + 选择器 + 角色设定/模型 → 相同的 data。
see	✅（设置了 goal 时）	不设置目标时不会产生 LLM 成本——缓存快照可能导致数据过时。
act	❌	会改变状态；始终执行全新调用。
compare	透明	两个逐侧执行的 judge 调用会自动命中缓存；综合调用不会单独缓存。

命中/未命中语义：每个支持缓存的结果都带有可选的 cache?: { hit, age_ms, key, cost_saved_usd? } 字段。命中时，结果自身的 cost_usd 会被置为零，原始成本则移至 cache.cost_saved_usd——因此调用方汇总嵌套成本（例如 compare）时，不会重复计算已缓存的工作。

配置：

环境变量	默认值	作用
AUDIT_RESULT_CACHE_PATH	~/.pixelcheck/result-cache.db	SQLite 路径；按环境隔离
AUDIT_RESULT_CACHE_TTL_MS	86400000（24 小时）	超出此时长的条目会被视为未命中并清理
AUDIT_RESULT_CACHE_DISABLED	未设置	设为 1 / true 可完全绕过缓存（读取 = 未命中，写入 = 无操作）
AUDIT_RESULT_CACHE_MAX_ROWS	10000	LRU 上限；超出后淘汰 last_used_at 最早的行。0 表示禁用。
AUDIT_RESULT_CACHE_MAX_DISK_MB	500	按数据库大小设置 LRU 上限；淘汰顺序相同。0 表示禁用。

单次调用覆盖项（也可在每个 MCP 工具上通过 cache / cache_bust / cache_ttl_ms 使用）：

• cache: false — 本次调用跳过读取和写入。
• cacheBust: true — 跳过读取，但保存新结果，以便后续相同调用命中缓存。
• cacheTtlMs: number — 覆盖本次调用的 TTL。

**架构版本失效：**在不同 RESULT_SCHEMA_VERSION 下写入的条目会被视为未命中，并在下次清理时移除。缓存会自动兼容新增内容的小版本升级；大版本升级会使所有条目失效。

设计说明请参阅 ADR-015。

工件保留

每次调用 MCP 原语（see / act / extract / judge / compare）都会在 ~/.pixelcheck/<kind>/ 下写入一个独立子目录，其中包含屏幕截图、DOM 转储、负载 JSON 和 LLM 响应。长期运行的 MCP 服务可能在一个月内累积数 GB 数据。PixelCheck 默认强制执行 30 天保留期限，并按需清理。

pixelcheck prune          # explicit cleanup; prints summary, exit 1 on errors

MCP 服务启动时最多每 24 小时执行一次相同的清理 （prune-stamp.json 记录上次运行时间；在此时间窗口内后续连接会完全跳过清理）。

环境变量	默认值	作用
AUDIT_SEES_RETENTION_DAYS	30	see 工件的保留期限；0 表示禁用
AUDIT_ACTS_RETENTION_DAYS	30	act 的保留期限
AUDIT_EXTRACTS_RETENTION_DAYS	30	extract 的保留期限
AUDIT_JUDGES_RETENTION_DAYS	30	judge 的保留期限
AUDIT_COMPARES_RETENTION_DAYS	30	compare 的保留期限
AUDIT_<KIND>_DIR	~/.pixelcheck/<kind>	每种类型的自定义存储目录

将保留期限设为 0 表示无限期保留（跳过该类型的清理），这与所有 Linux 保留工具的行为一致。若要批量删除某种类型的数据，可直接使用 rm -rf ~/.pixelcheck/<kind>。

构建所用技术

• Playwright — 浏览器自动化
• Stagehand 3.x — AI 驱动的语义化浏览器控制
• Claude（视觉 + Computer Use）— 视觉评估和像素级审查
• axe-core — WCAG 无障碍审计
• better-sqlite3 — 本地审计历史记录与趋势跟踪

有何不同？

如果你希望 AI Agent 现在就能操作可视化 Web，实际上有四种选择，各自采用了不同的思路：

• 开源自动化框架 — browser-use（91k★）、Stagehand（22k★）、Skyvern（21k★）。在执行 Agent 指定的任务方面堪称一流。它们都没有提供多角色模拟层，也没有为可缓存的 AI 工作流设计严格的结果架构契约。
• 基于规则的审计工具 — axe-core（7k★）、pa11y（4.4k★）、Lighthouse。非常擅长回答“是否符合 WCAG？”，但无法回答“这个产品实际体验好吗？”
• 托管式 Agent 浏览器 — Comet、Atlas、BrowserOS、Dia。取代 Chrome 的消费级产品。你提供信用卡和会话，它们提供 UI，而非基础设施。
• PixelCheck — 运行在 AI Agent 工作流之下的 MCP 服务。完全本地、完全开源、完全由你掌控。

	开源框架	基于规则的审计工具	托管式 Agent 浏览器	PixelCheck
回答的问题	如何控制浏览器？	是否符合 WCAG 2.x？	产品能替我浏览 Web 吗？	我的 AI Agent 如何查看和操作 Web？
主要接口	库 / SDK	CLI	桌面应用 + 云端会话	MCP 服务（+ 面向用户的 CLI）
智能能力	大模型驱动的操作	静态规则	托管大模型（按会话付费）	大模型视觉 + 规则 + Computer Use，使用你自己的大模型密钥
用户模拟	单一匿名会话	无	单一登录会话	18 种角色 × 17 个国家 × 6 种脚本系统
反检测	无	不适用	内置（浏览器身份）	9 种指纹 + 15 个隐身补丁
输出契约	操作结果	通过/失败检查清单	对话回复	31 个公开的 JSON Schemas + 89 个命名 API
历史记录	无	无	按会话记录，受供应商锁定	SQLite 趋势 + 运行间差异，由你掌控
成本模式	免费开源，你承担大模型费用	免费开源	订阅费 + 按会话付费	免费开源，你承担大模型费用，PixelCheck 不加价
数据存储位置	你的设备	你的设备	供应商云端	你的设备。仅此而已。
供应商锁定	有时（云端附加服务）	无	严重	无 — MIT 许可、无付费层、无商业分支

目前没有任何开源项目同时具备 MCP 优先的浏览器原语、多角色模拟、AI 视觉评分、WCAG 分析、隐身指纹和历史趋势跟踪。PixelCheck 是 AI Agent 与可视化 Web 之间缺失的基础设施层——而且在上表中，只有它对“我的数据会怎样？”这一问题的回答是“数据从未离开你的设备”。

测试覆盖率

运行并测量覆盖率：

npm run test:coverage          # writes ./coverage/index.html
npm run test:coverage:check    # CI gate — fails on regression below thresholds

覆盖率通过 vitest.config.ts > coverage.thresholds 强制执行（提供程序为 v8）。入口点（cli.ts、index.ts、mcp/server.ts）和纯类型契约（core/types.ts、core/result-schema.ts）不计入覆盖率——它们通过使用方测试（CLI 冒烟测试 + MCP tools/list 握手 + 架构往返测试）进行验证。将它们计入会稀释指标。

阈值下限设在当前全局基线或其以下，以便检查能捕捉回归问题，同时不阻碍构建。每次新增测试 PR 推出后，都会相应提高下限。各模块的覆盖率可在文本表格报告或 coverage/index.html 中查看。阶段计划请参阅 docs/decisions/ADR-017-coverage-tooling-and-m1-2-phase-1.md。

性能回归门禁

热点路径基准测试位于 tests/perf.bench.ts，与测试套件分开运行（vitest 对 *.bench.ts 和 *.test.ts 的发现彼此独立，因此 npm test 仍能保持快速）。9 项基准测试覆盖了报告渲染和聚合路径，这些路径在有人重构模板或添加 O(N²) 循环时最容易出现回归：

• renderPdfHtml / renderTrendsHtml / renderDiffMarkdown / renderDiffHtml
• renderJunitXml / renderSarif
• summarizeWcag / computeSummary / t() i18n lookup

npm run bench          # measure (writes docs/perf-current.json)
npm run bench:check    # compare to docs/perf-baseline.json — exit 1 on regression > 50%
npm run bench:update   # bake current as new baseline (after intentional perf changes)

默认的 50% 容差是根据测得的多次运行间波动（安静硬件上为 8–53%）校准的。使用 --tolerance 0.30 可进行更严格的本地检查。初始基线记录为 连续 5 次运行中的最小值，因此回归会被识别为“比以往任何时候都慢”——即使噪声高于最低值，也能保持稳健。完整设计请参阅 ADR-025。

稳定性承诺

从 v1.0.0 开始，以下接口将按照 语义化版本保持稳定：

• CLI — 标志、子命令、退出代码、环境变量名称
• 配置架构 — config.yaml / personas/*.yaml / scenarios/*.yaml
• 结果架构 — 版本 1.2.0，docs/schemas/ 中发布的 31 个 JSON 架构
• MCP 工具接口 — 13 个工具名称及输入/输出架构
• 库导出 — 从 src/index.ts 导出的 89 个命名项

破坏性变更只会在主版本升级（v2.0、v3.0……）中推出。次版本和补丁版本发布保证向后兼容。弃用周期记录在 docs/DEPRECATION-POLICY.md 中： 在 v1.x 中弃用的功能会继续可用至少两个次版本，之后才会在下一个主版本中移除。

从 v0.3 升级到 v1.0？请参阅 MIGRATION.md。

性能基线（暂定，待 v1.0-rc1 校准）

典型的 5 单元审计（1 个场景 × 5 个角色，完整 AI 流水线）预计耗时如下：

指标	v1.0 目标	说明
墙钟时间	~2–5 分钟	因网站复杂度、角色数量和模型而异。v1.0-rc1 校准将设定硬性 SLA。
API 成本	~$0.10–$0.30	Claude Sonnet 4.6 视觉模型；Computer Use 的峰值可能会推高至 $0.50 以上
内存峰值	< 1 GB RSS	Chromium ~500 MB + Node 堆 ~300 MB

渲染热点路径（已通过 npm run bench:check 回归门禁跟踪）：

路径	M 系列上的 ops/sec	说明
renderPdfHtml（20 单元审计）	~12,000	A4 纵向 + WCAG 部分 + 5 个图表
renderTrendsHtml（100 行历史记录）	~1,000	5 个内联 SVG 图表
renderDiffMarkdown（典型 PR）	~90,000	适合用作固定 PR 评论
renderSarif（20 单元，12 个问题）	~190,000	按 WCAG-SC 区分规则 ID

这些是微基准测试（单次函数调用）。完整审计流水线 （启动 Chromium → 导航 → 评分）的墙钟基线正在 v1.0-rc1 中校准。

贡献

欢迎贡献。完整的开发者指南（开发环境设置、提交规范、PR 流程、ADR 实践、分支保护）请参阅 CONTRIBUTING.md。

我们采用 Contributor Covenant 2.1 作为社区行为准则。

我们尤其欢迎在以下方面提供帮助：

• 为代表性不足的地区/人口群体新增角色
• 为常见应用模式（电商结账、入门引导、仪表盘）创建场景模板
• 改进报告格式
• 制定成本优化策略

有关安装故障排查（企业代理、Alpine、隔离网络等），请参阅 docs/INSTALLATION.md。

隐私与数据处理

pixelcheck 完全在你的计算机上运行。唯一的出站网络目标是 api.anthropic.com，用于你明确触发的审计调用。零遥测。

运行审计时，哪些数据会离开你的计算机：

• 页面截图 + DOM 摘要 → Anthropic Claude API
• 你的场景步骤文本 + Persona 配置字段 → Claude API
• 其他数据一概不会离开（URL / 环境变量 / 路径 / 以往审计记录均保留在本地）

隐私优先的默认设置：

• 密码 / 密钥 / API 密钥输入内容会在截图前被替换为 ********（默认启用 --redact-inputs；仅对固定样例审计使用 --no-redact-inputs 退出此保护）
• 首次运行时会显示同意提示，明确告知你哪些数据会发送给 Anthropic。同意状态保存在 ~/.pixelcheck/consent.json 中，后续运行不会再次提示。在 CI / 非 TTY 环境中可通过 AUDIT_AUTO_CONSENT=1 环境变量或 --auto-consent 标志跳过提示（请先阅读 PRIVACY.md）。
• 每次运行的报告均以 0700 权限模式存储（仅所有者可访问），路径为 <projectDir>/reports/

如需了解完整的数据流披露、GDPR / CCPA 立场、数据保留控制 以及如何删除数据，请参阅 PRIVACY.md。

安全

发现了漏洞？请使用 GitHub Security Advisories（私密披露）—— 参阅 SECURITY.md。安全报告请勿作为公开 议题提交。

许可证

MIT — 完整文本请参阅 LICENSE。

第三方依赖及其许可证记录在 docs/THIRD_PARTY_LICENSES.md 中。

帮助与参考

• FAQ.md — 关于 API 密钥 + 费用、场景 + Persona、报告 + 输出、隐私及原生二进制文件的常见问题
• docs/TROUBLESHOOTING.md — 运行时错误及修复方法（API + 身份验证、审计运行、浏览器、报告、CI、性能）
• docs/INSTALLATION.md — 安装矩阵 + 企业代理 + Alpine / Docker / 隔离网络环境配置方案
• API 参考 — 使用 npm run docs:api 在本地生成 → docs/api/index.html（TypeDoc，不纳入版本控制）
• docs/decisions/ — 28 份架构决策记录，阐释设计理由

---

E2E 测试可验证你的代码是否正常运行。PixelCheck 为 AI Agent 提供真实的眼睛和双手，以验证你的产品是否正常运行。
2 分钟快速入门