内容
# Axe DevTools 实现代理
> **⚠️ 免责声明：** 本软件是预发布版本，不得到Deque Systems, Inc.的官方支持。它按“原样”提供，不提供任何形式的保证。 Deque 不对因使用此工具而导致的任何问题、损害或损失负责。**请勿在生产分支上运行此工具。** 在使用此代理时，请始终使用专用的开发或功能分支。
**注意：** 这是公共存储库，仅包含发布二进制文件。
实现代理是一个MCP服务器，可以安装在开发者的工作站上，并有助于使用IDE的AI聊天代理实现Deque的Axe DevTools for Web产品。
从 0.5.0 版本开始，代理支持以下实现：
- **axe-watcher**（结果 → Axe开发者中心）
- Java Selenium
- Cypress
- Playwright（库）
- Playwright Test
- Puppeteer
- WebdriverIO（即将推出）
- **Axe DevTools API**（本地扫描结果 + 报告）
- Playwright
- Cypress
- Puppeteer
- Java Selenium
- Python Robot Framework
- **Axe DevTools CLI** — 独立页面/工作流测试
- **Linter 预提交钩子** — 阻止提交包含可访问性缺陷
- **axe-linter.yml**（`#adt-linter-yml`）— 映射自定义组件，设置`exclude`路径，并为DevTools Linter配置`global-libraries`（仅在不存在时写入启动文件）
- **Axe MCP 服务器** — IDE中的AI驱动的可访问性分析
- **多语言支持** — 所有响应都可以在您首选的语言中显示
代理还会自动检测：
- 项目中的测试框架（JavaScript、Python、Java等）
- axe-watcher所需的CDP启用浏览器（Chrome for Testing 或 Chromium）
- Docker 和 Podman（存在时，用于 axe MCP 服务器设置指导）
- Deque 的 Agora 工件存储库（npm、Maven、pip）的包访问权限
- 项目中已存在的 Axe DevTools 集成
MCP 服务器本身是一个独立的可执行文件，没有网络访问或 Docker 等外部依赖项。
## 快速设置
**macOS / Linux**
```bash
curl -fsSL https://raw.githubusercontent.com/dequelabs/axe-devtools-implementation-agent-public/main/setup.sh | bash
```
**Windows**（PowerShell）
```powershell
irm https://raw.githubusercontent.com/dequelabs/axe-devtools-implementation-agent-public/main/setup.ps1 | iex
```
脚本下载二进制文件，检测您的IDE（VS Code 或 Cursor），并自动写入MCP配置。
---
## 手动安装说明
1. 从发行部分下载适用于您操作系统的发行版。
2. 下载后，将可执行文件放在您的IDE可以访问的位置。
3. 将MCP配置添加到IDE（参见下文）。
### macOS 和 Linux 说明
下载的可执行文件需要在macOS和Linux上执行额外的步骤才能使其可执行。
**macOS**
```shell
chmod +x axe-imp-agent-macos
xattr -d com.apple.quarantine axe-imp-agent-macos
```
**Linux**
```shell
chmod +x axe-imp-agent-linux
```
## MCP 配置
### VS Code
将 `mcp.json` 放在项目根目录或用户主目录的 `.vscode` 目录中。
```json
{
"servers": {
"axe-imp-agent": {
"command": "/path/to/axe-imp-agent-executable",
"args": ["mcp"]
}
}
}
```
### Cursor
将 `mcp.json` 放在项目根目录或用户主目录的 `.cursor` 目录中。
```json
{
"mcpServers": {
"axe-imp-agent": {
"command": "/path/to/axe-imp-agent-executable",
"args": ["mcp"]
}
}
}
```
## 在 IDE AI 聊天中使用
开始前，请确认您正在项目中实施 Axe DevTools。
⚠️ 建议在非生产分支上运行实现代理。 `#adt-start` 命令将在继续实施前检查分支。
🤖 确保您的 IDE AI 聊天处于 **代理模式**。
配置完成后，在您的 IDE AI 聊天中使用以下命令：
### 完整工作流程（推荐）
```
#adt-start → 步骤 1：欢迎，语言选择和 Git 分支管理
#adt-discovery → 步骤 2：扫描框架，检测浏览器和环境
#adt-solution → 步骤 3：获取个性化建议
#adt-agora-access → 步骤 4：设置 Agora 注册表访问（需要 @axe-devtools 包）
#adt-watcher → 步骤 5a：实现 axe-watcher（结果 → 开发者中心）
#adt-api → 步骤 5b：实现 Axe DevTools API（本地扫描结果）
#adt-reporter → 步骤 5c：添加 HTML/CSV/XML 报告生成（仅在 API 之后）
#adt-setup-precommit → 步骤 6a：完成预提交钩子集成（Web 框架）
#adt-linter-yml → 步骤 6b：为项目组件自定义 axe-linter.yml
#adt-axe-mcp → 步骤 7：在 IDE 中添加 AI 驱动的可访问性分析和修复
```
### 单个命令
| 命令 | 描述 |
|---------|-------------|
| `#adt-hello` | 测试 MCP 服务器连接 |
| `#adt-start` | 欢迎介绍，选择首选语言和 Git 分支管理 |
| `#adt-discovery` | 扫描项目以获取测试框架，检测 CDP 浏览器（Chrome for Testing / Chromium），验证包访问权限，并检测环境 |
| `#adt-agora-access` | 设置对 Deque 的 Agora 工件存储库（NPM/Yarn，Maven，pip）的访问权限 — 凭证从不通过聊天传递 |
| `#adt-solution` | 根据项目获取个性化的可访问性集成建议 |
| `#adt-watcher` | 实现带有框架特定指令的 axe-watcher — 结果转到 Axe 开发者中心 |
| `#adt-api` | 实现带有框架特定指令的 Axe DevTools API — 生成本地扫描结果 |
| `#adt-reporter` | 添加 HTML/CSV/XML 报告生成（仅在 `#adt-api` 之后 — 不与 `#adt-watcher` 一起使用） |
| `#adt-cli` | 无需框架更改的独立页面/工作流可访问性测试 |
| `#adt-setup-precommit` | 为 Web 框架设置预提交钩子集成 |
| `#adt-linter-yml` | 生成或自定义带有组件映射、排除和库配置的 axe-linter.yml |
| `#adt-axe-mcp` | 设置 Axe MCP 服务器以进行 AI 驱动的可访问性分析（需要 Docker 或 Podman） |
| `#adt-set-python-venv` | 设置或更改 Python 虚拟环境路径并测试 pip 访问权限 |
| `#adt-implementations` | 根据项目的发现数据和安装状态显示可用的实现选项 |
| `#adt-set-language` | 更改所有响应的语言（例如，`#adt-set-language language: "es"` 表示西班牙语） |
> **注意：** 为给定的测试套件选择 `#adt-watcher` 或 `#adt-api` — 不要在同一测试文件中同时实现两者。
### 语言支持
`#adt-start` 命令将要求您在继续之前选择首选语言。您也可以在任何时候通过运行 `#adt-set-language` 并提供区域代码或语言名称（例如 `es`、`French`、`日本語`）来更改语言。
### axe-watcher 的浏览器要求
axe-watcher 需要一个支持 CDP 的浏览器 — 既可以是 **Chrome for Testing**，也可以是 **Chromium**。`#adt-discovery` 命令将检查您的环境中是否已经有一个可用。在观察者设置期间（`#adt-watcher`），代理将为您提供以下选项：
1. **安装 Chrome for Testing**（推荐）— `npx @puppeteer/browsers install chrome@stable`
2. **安装 Chromium** — `npx playwright install chromium`
3. **使用已安装的浏览器** — 提供路径
4. **自行安装** — 手动下载并提供路径
> **Java Selenium 注意：** Selenium 4.x CDP 仅支持到 ~v122，因此您必须使用 Chrome for Testing v122 或 Chromium ~v122（不是最新的）。
## 视频演示
▶️ [在 YouTube 上观看演示（v 0.2.0）](https://www.youtube.com/watch?v=PkagCwknrfA)
