audit-a-page

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Audit a page with Real A11y

使用Real A11y审计页面

Same engine, two surfaces. Prefer MCP when an agent session already has the server connected; prefer CLI for shell/CI one-shots.

Docs: https://real-a11y.dev/packages/mcp · https://real-a11y.dev/packages/cli

同一引擎，两种使用方式。如果Agent会话已连接服务器，优先使用MCP；如果是Shell/CI一次性任务，优先使用CLI。

文档：https://real-a11y.dev/packages/mcp · https://real-a11y.dev/packages/cli

MCP path

MCP 使用流程

Ensure MCP is wired (
```
wire-up-mcp
```
). Browser installed via
```
npx real-a11y install
```
.
```
open_page
```
with the URL. For SPAs use
```
waitUntil: "networkidle"
```
and/or
```
settleMs
```
. Pass
```
device
```
when auditing mobile layouts.

Prefer

inspect_page

for a single coherent read on dynamic pages; otherwise

audit_page

plus views as needed:

```
get_semantic_tree
```
```
get_heading_outline
```
```
get_tab_order
```
```
list_elements
```

Explain findings in plain language and propose concrete fixes.
Optional findings loop:
```
checkpoint_findings
```
→ change →
```
diff_findings
```
.
```
close_browser
```
when finished.

Respect tool output caps (~40k chars). Do not invent CSS selectors for later acts — use role + accessible name (see

a11y-act-loop

确保已配置MCP（
```
wire-up-mcp
```
）。通过
```
npx real-a11y install
```
安装浏览器。
使用
```
open_page
```
打开目标URL。对于SPA（单页应用），需设置
```
waitUntil: "networkidle"
```
和/或
```
settleMs
```
。审计移动端布局时需传入
```
device
```
参数。
若需对动态页面进行一次性连贯检测，优先使用
```
inspect_page
```
；否则可使用
```
audit_page
```
并按需调用以下视图：
- ```
get_semantic_tree
```
  （获取语义树）
- ```
get_heading_outline
```
  （获取标题大纲）
- ```
get_tab_order
```
  （获取Tab键导航顺序）
- ```
list_elements
```
  （列出元素）
用通俗易懂的语言解释检测结果，并提出具体修复方案。
可选的结果循环流程：
```
checkpoint_findings
```
（记录检测结果）→ 修改页面 →
```
diff_findings
```
（对比结果差异）。
完成后调用
```
close_browser
```
关闭浏览器。

注意工具输出限制（约40000字符）。请勿为后续操作自行编写CSS选择器——请使用角色+无障碍名称（详见

a11y-act-loop

）。

CLI path

CLI 使用流程

npm i -D @real-a11y-dev/cli@beta playwright
npx real-a11y install
npx real-a11y audit https://example.com

Useful companions:

npx real-a11y tree https://example.com
npx real-a11y outline https://example.com
npx real-a11y tabs https://example.com
npx real-a11y inspect https://example.com

```
audit
```
exits 1 on error-severity findings (CI gate).
Unreachable URL must exit 2 (or equivalent failure) — never a clean “no issues” report.
There is no
```
--producer
```
flag. Only
```
tabs
```
takes
```
--root
```
.
Optional project config:
```
a11y.config.json
```
(
```
defaults
```
,
```
urls
```
).

Auth: use

real-a11y login … --save

+ storage-state flags/env — never type passwords into agent tool calls. Guide: https://real-a11y.dev/guide/authenticated-pages

npm i -D @real-a11y-dev/cli@beta playwright
npx real-a11y install
npx real-a11y audit https://example.com

常用辅助命令：

npx real-a11y tree https://example.com
npx real-a11y outline https://example.com
npx real-a11y tabs https://example.com
npx real-a11y inspect https://example.com

```
audit
```
在检测到严重级别问题时会以1状态码退出（用于CI门禁）。
若URL无法访问，必须以2（或等效错误状态）退出——绝不能返回“无问题”的干净报告。
不存在
```
--producer
```
参数。仅
```
tabs
```
命令支持
```
--root
```
参数。
可选项目配置文件：
```
a11y.config.json
```
（包含
```
defaults
```
、
```
urls
```
配置项）。

身份验证：使用

real-a11y login … --save

+ storage-state参数/环境变量——切勿在Agent工具调用中输入密码。指南： https://real-a11y.dev/guide/authenticated-pages

Scope reminder

范围说明

Not a full WCAG/axe suite. Say so when the user expects exhaustive rule coverage; pair with axe when needed.

本工具并非完整的WCAG/axe测试套件。当用户期望全面的规则覆盖时，请明确告知；必要时可搭配axe工具使用。

下一步

Interact after open →
```
a11y-act-loop
```
CI / PR diffs →
```
gate-ci-a11y
```

打开页面后进行交互 →
```
a11y-act-loop
```
CI / PR差异检测 →
```
gate-ci-a11y
```