无障碍代理团队：为 AI 编程工具装上"视障眼镜"

当 AI 写出"只有视力正常者才能使用"的代码

2025年，某科技公司上线了一款内部工具。功能完整，测试通过，PM满意。但两周后，一封来自视障员工的邮件让整个团队陷入沉默："这个页面，我用NVDA读屏软件什么都点不了。按钮没有名字，弹窗不读出来，焦点完全乱跳。"

这不是个例。根据W3C统计，全球约15%的人口存在某种形式的残疾，其中相当比例依赖屏幕阅读器、键盘导航等辅助技术。 但在AI辅助编程工具席卷开发界的今天，一个根本性问题被忽视了：LLM在生成代码时，几乎从不会主动考虑无障碍（Accessibility，A11Y）标准。ARIA属性被遗忘、对比度不达标、焦点管理缺失——这些问题在AI的"快速迭代"中被大规模复制粘贴。

accessibility-agents 正是为解决这一痛点而生的开源项目。它不是一个单纯的linter或工具，而是一套多平台AI代理团队，专门负责在AI编程工具（Claude Code、GitHub Copilot、Claude Desktop、Codex CLI、 Gemini CLI）工作流程中嵌入WCAG 2.2 AA合规检查，让AI生成的代码在产出时就带上"无障碍基因"。

80个专职代理：让AI记住那些它总忘记的事

项目的核心架构是80个高度专业化的AI代理，覆盖Web、文档、移动端、桌面端、PDF、Office等多个平台。每个代理都有自己明确的职责边界，例如：

• accessibility-lead：项目协调者，作为所有无障碍工作的总入口，负责任务分发和最终验收。
• contrast-master：专注色彩对比度检测，确保前景色与背景色的对比比至少达到4.5:1（普通文本）或3:1（大文本）。
• aria-specialist：审查ARIA标签的正确使用，包括角色（role）、属性（property）和状态（state）的准确性，防止"伪ARIA"——即写了但写错了的ARIA。
• keyboard-navigator：模拟键盘-only用户的行为，验证Tab键顺序、焦点可见性、快捷键冲突。
• screen-reader-lab：验证NVDA、VoiceOver、JAWS等主流读屏软件的内容朗读顺序和语义解析。
• document-accessibility-wizard：处理Word、Excel、PowerPoint等Office文档的无障碍导出。
• pdf-remediator：修复扫描版PDF的标签和结构。

代理之间不是简单的"平级协作"，而是形成层级指挥链：accessibility-lead作为协调者（Orchestrator），接收来自开发者的任务后，根据代码类型分发给对应的专职代理（如contrast-master负责CSS颜色，forms-specialist负责表单结构），最后汇总审查意见。这种架构解决了LLM"什么都想做但什么都做不精"的问题——每个代理只在自己的垂直领域内工作，激活率远高于通用的"技能（Skill）"模式。

Hooks强制执行：让AI"物理上"无法跳过无障碍检查

即使给LLM提供了无障碍检查指令，实际测试中LLM仍然会选择性忽略——读取指令、理解指令、然后继续写自己的代码。这是LLM的attention分散问题：上下文越满，最初的指令越容易被遗忘。

accessibility-agents 采用了三层Hook强制门控机制，彻底堵住这条"捷径"：

第一层（UserPromptSubmit）：自动检测当前项目是否涉及Web UI开发，如果是，则在LLM开始工作前自动注入"请先委托给accessibility-lead"的指令。这意味着LLM在看到代码之前，就已经被告知要进行无障碍审查。

第二层（PreToolUse）：硬性拦截所有对UI文件（.jsx、.tsx、.vue、.css、.html等）的写入操作——不是警告，是直接拒绝（permissionDecision: "deny"）。LLM必须先完成accessibility-lead的审查，才能解锁写入权限。这个机制从"物理层面"保证了审查不可能被跳过。

第三层（PostToolUse）：accessibility-lead完成审查后，生成会话标记（marker），解除PreToolUse的拦截锁定，LLM才能继续编辑UI文件。

这套机制的核心洞察是：指令是被遗忘的，执行是被绕过的，但工具调用失败是无法忽略的。 Hooks将"做无障碍检查"从软性建议变成硬性约束，这是项目在工程层面最值得借鉴的设计思路。

多平台覆盖：不是一套工具，而是五套工具链

accessibility-agents 的野心不只是服务Claude Code一个平台。项目原生支持五大AI编程环境：

• Claude Code：通过.claude/agents/目录下的50个代理文件工作，支持CLAUDE.md全局指令和Hook机制。
• GitHub Copilot：通过.github/agents/目录下的.agent.md文件工作，集成到VS Code Copilot Chat和GitHub CLI。
• Claude Desktop：通过MCP（Model Context Protocol）服务器架构提供服务，支持HTTP（SSE回退）和stdio两种传输方式。
• Codex CLI：通过.codex/目录的skills和subagent机制集成。
• Gemini CLI：通过gemini-extension.json和专属代理文件集成。

每个平台的安装都通过统一的install.sh脚本完成，支持全局安装（~/.claude/）和项目级安装（.claude/）两种模式。Windows平台还提供了PowerShell安装脚本（install.ps1）。项目还包含一个Go语言原生命令行工具（go-cli/），提供gh skill setup、gh skill health、gh skill repair、gh skill hooks等命令，用于GitHub CLI的skill生命周期管理。

此外，项目提供了MCP服务器（mcp-server/）作为独立Node.js包发布（@a11y-agent-team/mcp-server），开发者可以将其对接任何兼容MCP协议的客户端，不受限于特定AI工具。

VS Code扩展：把无障碍代理装进编辑器

对于使用GitHub Copilot的VS Code用户，项目提供了专门的扩展插件（vscode-extension/），在VS Code Copilot Chat中注册了64个@a11y slash命令，覆盖ARIA、对比度、键盘、表单、文档等各类无障碍检查场景。扩展集成axe-core扫描引擎，以SARIF格式输出诊断结果，直接在编辑器的问题面板中展示。

GitHub Actions CI工作流（.github/workflows/a11y-check.yml）则将无障碍检查自动化——每次PR提交时自动运行检查，确保合并前代码的无障碍合规。

部署体验：纯CLI工具集，上手门槛低

accessibility-agents 是一个纯命令行工具集，不提供Web界面。安装过程高度自动化：

# Claude Code 全局安装
bash install.sh --global

# Copilot + CLI 全部安装
bash install.sh --global --copilot --cli

安装脚本会自动检测平台（Linux/macOS/Windows），拉取对应平台的代理文件，配置VS Code和GitHub CLI集成。安装后，开发者只需在终端或编辑器中正常开发，Hook机制会自动介入进行无障碍审查。

硬件需求极低：无需GPU，普通开发机即可运行。安装包约200MB，运行时内存占用约1GB。唯一的硬性依赖是Node.js >= 18（用于MCP服务器）和bash环境（Windows通过PowerShell模拟）。

局限与争议：AI不是万能的无障碍专家

项目文档开篇即声明了一个重要免责条款："AI和自动化工具并不完美。它们会遗漏内容、犯错，无法替代真实的读屏软件和辅助技术测试。"这是项目的诚实之处，也是它的局限所在。

首先，自动化工具无法检测**认知无障碍（Cognitive Accessibility）**问题，比如内容是否易于理解、导航是否合乎逻辑——这些需要真人测试。其次，动态交互（拖拽、手势、实时更新）的无障碍实现高度依赖具体实现细节，自动化工具的覆盖范围有限。第三，项目依赖的AI代理本身存在LLM的固有缺陷——上下文窗口溢出、指令遗忘、特殊边界情况处理不当等。

此外，80个代理的维护本身是一个巨大工程。GitHub上已有超过60个release版本，每次平台API变更（如GitHub Copilot的agent格式更新）都需要同步维护，工作量不小。社区贡献虽然是项目成功的关键，但也带来了质量参差不齐的风险。

行业意义：从"修复无障碍"到"预防无障碍"

accessibility-agents 代表了一种思路转变：不是在代码写完后去做无障碍修复，而是在代码生成时就预防无障碍问题的产生。 传统工作流中，无障碍测试通常在开发周期末尾进行，此时改动成本高、阻力大。项目将AI代理嵌入开发工作流，让无障碍检查成为开发过程的自然组成部分，降低了"后期打补丁"的成本。

项目的高速增长（342 stars，持续活跃更新至2026年6月）说明社区对这类工具的需求是真实且迫切的。随着AI编程工具在企业中的普及，让AI在生成代码时就具备无障碍意识，将对最终产品的包容性产生深远影响。这不只是技术问题，更是社会公平问题——让每一个人，无论是否患有视力或运动障碍，都能平等地使用数字产品。