audit

你可以审查无障碍问题，并根据需要修复问题。

根据用户意图选择模式

• 报告模式——“审查我的代码库”“检查 src/components/”“这个页面有什么问题？”“给我一份无障碍报告”。你负责审查并撰写报告。不要编辑文件。
• 修复模式——“修复 X 中的无障碍问题”“审查并修复”“让这个页面符合无障碍要求”“确认对比度修复已生效”，或者用户提供违规报告并要求应用修复。你负责审查 → 编辑 → 验证。

如果不确定，请先询问。用户只要求审查时，不要默认进行修复。

对于主线程上下文开销较大的大型审查，可以通过 Task（通用 Agent）调用，以隔离上下文。两种方式使用相同的流程。

选择流程

按优先顺序使用以下两种流程。

1. audit_live——任何 URL 都应优先尝试。确保有可调试的 Chrome（如果没有可用实例，会自动启动一个无头实例——用户无需进行任何设置），然后审查实时 DOM。只需调用一次；审查引擎不会进入你的上下文。使用 selector 将范围限定为单个组件，并使用 wait_for 等待异步内容就绪。
2. audit_html——用于原始 HTML 字符串、文件（先使用 Read，再调用 audit_html），或已渲染为字符串的 JSX。

对于非 URL 目标，使用流程 2。对于 URL，使用流程 1；如果无法启动 Chrome（系统中没有 Chrome，且禁用了下载），则回退到流程 2，并注明对实时 DOM 的覆盖有限。

审查用户已打开且已通过身份验证的会话不再是单独的流程：让用户启动一个带界面、可调试的 Chrome（npx @accesslint/chrome ensure --headed），在其中登录，然后调用 audit_live({ url, port })——它会连接到该 Chrome，而不是自行启动实例。

范围处理（报告模式）

• 目录路径——分析其中所有相关文件。
• 多个文件——分析列出的文件及其涉及的导入文件。
• URL——审查该 URL。如果是开发服务器 URL，则使用流程 1。
• 未提供参数——请用户缩小范围。通常不适合扫描整个代码库。

请在报告开头明确说明审查范围。

审查方法（报告模式）

1. 梳理目标范围。 使用 Glob/Grep 列出组件、模板和样式。抽查有代表性的文件；不要不加筛选地打开所有文件。
2. 尽可能进行实时审查——渲染后的 DOM 能发现源代码无法呈现的问题。使用上文的流程选择器。
3. 查找规律。 如果某个组件违反了某条规则，类似组件可能也有同样的问题。按规则 ID 和组件类别归类，不要把同一问题的 30 个实例逐一列出。
4. 按用户影响确定优先级。 严重和高严重性问题优先。大量影响较低的同类违规通常源自同一个根因。
5. 扫描调用使用 format: "compact"。 仅对将在报告中详细说明的规则保留详细输出。
6. 优先采信 Source: 行。 对 React 开发构建进行实时 DOM 审查时，DevTools fiber 会为每项违规附上 Source: <file>:<line> (Symbol)。使用它定位文件，无需通过 grep 查找选择器。如果不存在，则依次使用稳定钩子、可见文本和树位置定位。
7. 如果单次审查返回超过约 50 项违规，请停止并询问用户——包含 200 项违规的报告无法有效采取行动。

引擎只能检测可通过机械方式判断的问题。内容清晰度、屏幕阅读器播报质量、键盘操作流程是否连贯以及复杂的视觉对比度问题都需要人工判断；请将这些问题标记为需要人工审查，不要猜测。

报告格式

# Accessibility audit — <scope>

## Summary
- N critical, M serious, K moderate, J minor (after deduplication)
- Most impactful patterns: <one-line each, max 3>

## Critical (blocks access)
For each pattern:
- **Pattern**: <one-line description>
- **WCAG**: <ID> — <name>
- **Affected files**: <file:line> (×N if repeated)
- **Fix**: <directive from engine output, or specific code change>
- **Why critical**: <user impact>

## Serious
[same shape]

## Moderate / Minor
[Bullet list, deduplicated by rule. Skip per-instance detail unless the fix differs.]

## Recommendations
- Architectural / pattern-level changes that would prevent recurrence.
- Tooling or component abstractions worth introducing.
- What to verify manually (screen reader, keyboard, low-vision testing).

## Positive findings
What the codebase does well — short, factual, reinforces practices to keep.

每项都要包含规则 ID。对于 mechanical 规则，逐字引用 Fix: 指令。对于 visual / contextual，请附上包含规则 ID 的 TODO；不要自行编造内容。

Recipe (修复模式)

1. 基线。 使用 format: "compact" 审计目标，并记录违规项集合（每项包含规则 ID + 选择器）。这就是修复前清单。
2. 规划并应用。 对于每项违规：
   • 存在 Source: 行 → 打开该文件并跳转到对应行。如果列出了多项（以 ← 分隔），第一项是 JSX 字面量，其余项是外层组件。使用 Symbol 进行区分。
   • 不存在 Source: → 依次搜索稳定的钩子（data-testid、id、aria-label）、可见文本，然后是树中的位置。
   • 违规项的 Fixability: 和 Fix: 字段具有权威性——逐字应用机械修复；对于 contextual / visual 类型，保留带有规则 ID 的 TODO。切勿自行编造内容。
   • 将同一文件的编辑合并为一次操作。
   • 修改明显目标范围之外的文件，或进行约 10 项以上的机械修复前，先征得用户同意。
3. 验证。 重新运行相同的审计，并与修复前清单比较：确认所有目标违规项均已消除，且没有新增违规项。对于需要基于实际基线严格区分新增、已修复和预先存在违规项的 URL 目标，请使用 accesslint:diff 技能（基于快照），不要凭目测判断。

Source: 行来自 React DevTools fiber，且仅会出现在针对 React 开发版本的实时 DOM 审计中。静态审计不会提供这些信息——此时请改用选择器。

不确定某项规则时，请调用 explain_rule({ id: "<rule-id>" }) 获取指导和 browserHint。

何时停止（修复模式）

• 违规项没有 Fix: 指令——保留 TODO，不要猜测。
• 验证失败（出现了新违规项，或目标违规项仍然存在）——指出该项并停止。不要悄悄反复尝试。

输出（修复模式）

每个周期：所用流程、按影响程度分类的违规项、已应用的修复（文件 + 规则）、延后处理的项目（TODO + 原因），以及修复前后的违规项数量。