AWT (AI Watch Tester)

AWT — 你的 AI 编码工具的眼睛和双手

你的 AI 编码工具很聪明，但它看不到网页，也无法点击网页。 AWT 为它提供一个真实浏览器，让它无需你动手，就能测试、查找错误并修复问题。

无需 AI API——手动编写 YAML 场景，然后运行 aat run。无需 API 密钥。AI 编码工具能让操作更轻松，但并非必需。

---

什么是 AWT？

AWT 是 AI 驱动的 E2E 测试执行引擎。你的 AI 编码工具负责设计测试，AWT 则通过 Playwright 在真实浏览器中运行测试。

技能模式的工作方式（无需额外的 AI API 密钥）：

You: "Test the login flow on https://mysite.com"

Your AI coding tool:
  → Writes 5 YAML scenarios (30 steps)
  → Runs: aat run scenarios/
  → Reads failure: "Step 4: Dashboard text not visible"
  → Reads screenshot + source code
  → Fixes src/pages/login.js:23
  → Re-runs: aat run scenarios/
  → All 5 scenarios pass ✓

主要功能：

• 执行——在真实浏览器中通过模拟真人的鼠标和键盘操作运行测试
• 查看——截取屏幕截图，通过 OCR 和图像匹配检测元素
• 报告——逐步报告通过或失败的结果，并提供错误详情和屏幕截图
• 自我修复（CLI 模式）——aat loop 使用自带的 AI 自动修复失败
• 学习——将成功的匹配结果存储在 SQLite 中，随着时间推移运行得越来越快

安装

先安装 aat 命令——以下每种方式都会调用它：

pip install aat-devqa
python -m playwright install chromium

Claude Code 插件（推荐）

此仓库是一个插件包，内含 awt 技能，以及用于提供 aat_* 工具的 MCP 服务，因此安装一次即可同时获得两者。

claude plugin marketplace add ksgisang/awt-skill
claude plugin install ai-watch-tester@awt

MCP 服务需要 Python MCP SDK：

pip install "mcp[cli]>=1.0.0"

确认安装内容：

claude plugin details ai-watch-tester@awt

你应该会看到 Skills (1) awt 和 MCP servers (1) awt。

仅安装技能

如果你只想安装技能，不安装 MCP 服务：

npx skills add ksgisang/awt-skill --skill awt -g

也可以手动复制，安装到全局目录或项目目录：

git clone https://github.com/ksgisang/awt-skill.git /tmp/awt-skill
cp -r /tmp/awt-skill/skills/awt ~/.claude/skills/awt   # or .claude/skills/awt
rm -rf /tmp/awt-skill

安装后，该技能会在遇到与测试相关的提示词时自动触发。

更新

claude plugin update ai-watch-tester@awt          # plugin
npx skills add ksgisang/awt-skill --skill awt -g -y  # skill only

对于手动复制的安装：cd ~/.claude/skills/awt && git pull

与其他测试技能的对比

功能	webapp-testing	playwright-skill	AWT
场景格式	Python 脚本	Python 脚本	声明式 YAML
无代码创建测试	否	否	是
自然语言 → 测试	否	否	是
自我修复循环	否	否	是（DevQA Loop）
失败时自动修复	否	否	是（AI → PR）
视觉匹配（OpenCV + OCR）	否	否	是（OpenCV + OCR）
模式学习	否	否	是（SQLite）
服务生命周期管理	是	是	是（aat dashboard）
多种 AI 提供商	否	否	是（5 种提供商）
模拟真人的交互	否	否	是（贝塞尔曲线鼠标）
审批模式	否	否	是（手动/分支/自动）
成本优化	不适用	不适用	$0.02–0.05/次测试
实时屏幕截图	否	仅屏幕截图	是（WebSocket 流）
多语言 OCR	否	否	是（10 种以上语言）
离线支持	否	否	是（Ollama）
成本追踪	否	否	是（按调用记录 + aat cost）
源代码分析	否	否	是（仅限技能）
场景缓存	否	否	是（相同规范 = 无需再次调用）
浏览器测试叠加层	否	否	是（实时步骤进度）
依赖排序	否	否	是（depends_on 字段）
技能模式（无额外 AI 成本）	否	否	是
Canvas/Flutter OCR 回退方案	否	否	是（自动）
平台自动检测	否	否	是（7 种框架）
结构化失败诊断	否	否	是（不依赖 AI）
多文档 YAML	否	否	是（--- 分隔符）
严格验证	否	否	是（aat validate --strict）

何时使用各项：

• webapp-testing — 用于简单页面检查的一次性 Playwright 脚本
• playwright-skill — 需要对 Playwright API 进行精细控制时
• AWT Skill Mode — 由 AI 编码工具设计测试，AWT 负责执行。无需额外的 AI API 密钥。
• AWT CLI Mode — 使用 aat generate + aat loop 进行独立自动化测试，适用于 CI/CD

支持的 AI 编码工具

AWT 遵循 Agent Skills open standard，并兼容以下工具：

工具	状态
Claude Code	支持
Cursor	兼容
Codex	兼容
Gemini CLI	兼容
Amp	兼容
Cline	兼容
Aider	兼容
Windsurf	兼容
Roo Code	兼容
PearAI	兼容
Antigravity	支持

快速示例

YAML 场景

id: "SC-001"
name: "User Login"
tags: ["auth", "login"]
depends_on: ["SC-000"]
steps:
  - step: 1
    action: navigate
    value: "{{url}}/login"
    description: "Go to login page"

  - step: 2
    action: find_and_type
    target:
      text: "Email"
      match_method: ocr
    value: "[email protected]"
    humanize: true
    description: "Enter email"

  - step: 3
    action: find_and_click
    target:
      text: "Login"
    description: "Click login button"

  - step: 4
    action: assert
    assert_type: text_visible
    expected:
      - type: text_visible
        value: "Welcome back"
    description: "Verify login success"

自然语言（在 Claude Code 中）

“使用 [email protected] 登录 mysite.com，然后检查仪表板是否加载”

AWT 会将其转换为 YAML 场景并自动执行。

5 步 DevQA 工作流

Scan → Plan → Review → Execute → Heal
  ↑                                 |
  └─── Loop back on failure ────────┘

1. 扫描 — 抓取网站、分析 DOM、检测功能
2. 规划 — AI 生成 YAML 测试场景
3. 审核 — 用户在执行前审核/编辑
4. 执行 — Playwright 运行测试并实时截取屏幕截图
5. 修复 — AI 分析失败 → 提出修复建议 → 重新测试

AI 提供商

提供商	视觉能力	费用	离线
Claude（默认）	是	中	否
OpenAI（GPT-4o）	是	较高	否
Gemini（默认：免费）	是	免费层级	是
DeepSeek	否	低	否
Ollama	否	免费	是

项目结构

awt-skill/                      # ← this repository is the plugin folder
├── .claude-plugin/
│   ├── plugin.json             # Plugin manifest
│   └── marketplace.json        # Marketplace entry for this one plugin
├── .mcp.json                   # Declares the bundled MCP server
├── skills/
│   └── awt/                    # ← Skill content (installed by npx skills)
│       ├── SKILL.md            # Main skill definition
│       ├── references/
│       │   ├── scenario-schema.md  # Full YAML schema reference
│       │   ├── cli-reference.md    # CLI command reference
│       │   └── config-reference.md # Configuration options
│       └── templates/
│           ├── scenario-template.yaml
│           └── config-template.yaml
├── mcp/
│   ├── server.py               # MCP server — the 12 aat_* tools
│   └── requirements.txt
├── server.json                 # MCP Registry entry
├── README.md
├── LICENSE
├── CONTRIBUTING.md
└── package.json

主要 CLI 命令

命令	说明
aat doctor	检查环境（Python、Playwright、Tesseract、AI）
aat init	初始化项目 + AI 设置 + 环境检查
aat setup	配置 AI 提供商和 API 密钥
aat generate	使用 AI 生成场景（含费用估算 + 缓存）
aat run --learn	执行测试 + 从修复中学习（始终使用 --learn）
aat loop	自我修复 DevQA 循环
aat cost	查看 AI API 使用费用
aat validate --strict	验证 YAML + 质量检查
aat learn platform -p <key> -t <tip>	添加平台特定提示

系统依赖

macOS：

brew install [email protected] tesseract
pipx install aat-devqa
playwright install chromium

Linux（Ubuntu/Debian）：

sudo apt install python3.12 python3.12-venv tesseract-ocr
pipx install aat-devqa
playwright install chromium

Windows：

winget install Python.Python.3.12
choco install tesseract
pip install aat-devqa
playwright install chromium

安装后，运行 aat doctor 验证一切正常。

OCR 语言包。 Tesseract 仅安装英语语言包。如果你要测试其他语言的应用，还需安装相应语言包——否则，回退到 OCR 的文本断言会将明明存在于页面上的文本报告为 not visible on page。aat doctor 会指出缺少的语言包。

brew install tesseract-lang                 # macOS, all languages
sudo apt install tesseract-ocr-kor          # Linux, one language

此插件运行、发送和获取的内容

以下所有内容均以可读源代码的形式保存在此仓库中。安装时不会运行任何压缩或编译后的代码，也不会下载任何内容。

在你的计算机上运行。 mcp/server.py 由 python3 启动，只做一件事：构建参数列表，并以子进程方式运行你通过 pip install aat-devqa 安装的 aat 命令。它绝不运行 shell，因此收到的任何内容都不会被重新解析为命令。aat 会通过 Playwright 驱动本地 Chromium，并在进行 OCR 时调用本地 tesseract 二进制文件。

写入磁盘。 在你的项目目录下：.aat/（配置、运行历史、截图、SQLite 学习数据库、仅追加的审计日志）和 reports/。在你的主目录下：~/.awt/templates/<host>/，用于存放 AWT 保存的元素图像，以便在选择器失效后重新找到目标。

通过网络发送。 没有遥测，也没有分析数据。以下每个目的地要么由你自行指定，要么是 AWT 自行发起的唯一一次调用；此处将其列在首位，以免被埋没：

• api.github.com，由 AWT 自行每天调用一次。 CLI 会查询最新版本，以便在有更新版本时显示提示。不包含请求正文、账户、机器 ID、版本字符串，也不包含任何与你的测试内容有关的信息；所有用户发出的请求都相同。请求会在 3 秒后超时，所有失败都会被忽略，因此屏蔽该主机不会造成任何影响。这是 AWT 发起的唯一一次调用。
• 你正在测试的网站。 Chromium 会加载你在场景中指定的 URL。这正是此工具的用途，测试运行不会联系其他网站。
• AI 提供商，仅用于需要 AI 的命令 — aat generate、aat loop、aat devqa 和 Vision 匹配。请求会携带页面文本或截图，以及你的场景。由你选择提供商并提供密钥；使用 Ollama 时，请求绝不会离开你的计算机。普通的 aat run 完全不会联系 AI 提供商。
• 你输入的 URL，用于检查其是否可访问 — aat doctor 和 aat start 会请求你提供的地址，并报告该地址是否有响应。
• http://localhost:<port>，用于查找你的开发服务器 — aat devqa 只会探测本地端口。
• 写入你自己的场景中的任何端点。 teardown 中类型为 api_call 的步骤会准确调用你在 YAML 中填写的 URL，以便在运行后清理测试数据。

PRIVACY.md 列出了上述每项内容对应的文件和代码行。

运行时获取。 无。安装后，插件不会下载任何代码。

审批。 aat run 会直接读取 /dev/tty 请求确认，因此管道输入无法代替你确认，并且每次尝试都会记录在 .aat/audit.log 中。没有 --auto-approve 标志，也没有任何方式可让 AI Agent 代你批准。在默认的 manual 模式下，AI 提出的场景修改不会写入你的文件。

链接

• 主仓库： github.com/ksgisang/AI-Watch-Tester
• 云端演示： ai-watch-tester.vercel.app
• Agent Skills 标准： agentskills.io

许可证

AGPL-3.0 — 完整文本请参阅 LICENSE 文件。

由 AILoopLab 构建。