1. 项目概述一个为AI智能体而生却意外好用的无障碍审查工具最近在折腾一个AI驱动的客服聊天机器人项目团队里有个同事提了个挺尖锐的问题“咱们这个AI对视力障碍用户友好吗它能被屏幕阅读器正确识别吗” 这一问直接把大家问住了。我们花了大把时间在模型调优和对话流设计上却很少从“无障碍”这个角度去审视自己的产品。要知道一个无法被屏幕阅读器正常读取的按钮或者一个对比度不足的提示框对残障用户来说可能就是一道无法逾越的数字鸿沟。就在我们准备手动去啃WCAGWeb内容无障碍指南那本厚厚的手册并计划投入大量人力进行人工审查时我在GitHub上发现了这个项目guillempuche/ai-agent-a11y-accessibility-reviewer。初看名字我以为它只是一个为AI智能体AI Agent设计的、检查其交互界面无障碍性的工具。但深入使用后才发现它的设计理念和实现方式让它成为了一个通用性极强的自动化无障碍审查助手。它巧妙地利用了大语言模型LLM的理解能力将复杂的无障碍规范转化为可执行的、上下文相关的审查点不仅能审查AI Agent的界面对常规的Web页面、移动端组件甚至设计稿和代码片段都能给出极具针对性的改进建议。这个项目的核心价值在于它把“无障碍审查”从一个高度依赖专家经验和手动操作的“玄学”变成了一套可自动化、可解释、可融入开发流程的“工程实践”。对于前端工程师、产品经理、测试人员乃至AI应用开发者来说它都是一个能显著提升产品包容性同时降低合规风险的得力工具。接下来我就结合自己的实际使用经验把这个工具的里里外外、从原理到实操给大家彻底拆解一遍。2. 核心设计思路当LLM遇见无障碍规范2.1 为什么传统无障碍审查工具不够用在介绍这个项目之前我们先得理解现有工具的痛点。市面上主流的无障碍审查工具比如axe-core、Lighthouse的Accessibility审计或者浏览器插件如WAVE它们的工作原理主要是基于规则匹配。它们会扫描DOM结构检查诸如img标签是否有alt属性、按钮是否有可访问名称、颜色对比度是否达标等。这些工具非常高效能快速发现“硬伤”。但它们的局限性也很明显缺乏上下文理解一个alt图片的属性在规则检查器看来是“合规”的因为它确实存在。但这个描述对用户毫无意义。工具无法判断这个描述是否准确、是否传达了图片的核心信息。无法处理动态和复杂交互对于由JavaScript动态生成的内容、复杂的ARIA无障碍富互联网应用控件状态如折叠面板、标签页、或者需要一系列键盘操作才能完成的流程静态规则检查器往往力不从心。难以评估“感知”和“理解”层面的问题无障碍不仅仅是技术合规更是用户体验。一段文字的阅读等级是否合适一个错误提示是否清晰易懂图标的意思是否不言自明这些关乎认知和感知的问题传统工具无法解决。报告不友好工具输出的报告常常是一长串错误代码如WCAG 1.1.1, 4.1.2开发者需要额外去查阅规范文档才能理解问题所在和如何修复学习成本高。ai-agent-a11y-accessibility-reviewer项目的设计者显然深刻意识到了这些问题。它的核心思路不是替代这些规则检查器而是用大语言模型LLM的语义理解能力去弥补规则检查的不足并提供更人性化、更具操作性的指导。2.2 项目的三层架构设计这个工具的设计可以抽象为三层第一层输入适配层。它接受多种形式的输入URL直接提供一个网页链接工具会去抓取内容。HTML片段/代码直接粘贴待审查的HTML代码。组件描述对于尚未实现的设计稿或AI Agent的交互描述可以用自然语言描述例如“一个包含搜索框和结果列表的聊天窗口组件”。截图通过集成OCR光学字符识别能力甚至可以分析截图中的内容。这种灵活性让它能覆盖从设计、开发到测试的全流程。第二层LLM智能分析引擎核心。这是项目的灵魂。它并不是让LLM漫无目的地“看看”页面而是设计了一套精妙的“审查提示词Prompt”。这套提示词做了几件关键事角色设定让LLM扮演一个“资深无障碍专家”。任务分解将庞大的WCAG准则分解为一个个具体的审查任务例如“检查所有图像是否有有意义的替代文本”、“评估主要操作流程是否可以通过键盘完成”、“分析颜色对比度是否可能存在问题”。上下文提供将输入的内容HTML、描述等作为上下文提供给LLM。结构化输出要求要求LLM必须按照固定的格式如JSON输出审查结果包括问题描述、违反的准则、严重程度高/中/低、以及具体的修复建议代码示例。第三层结果输出与集成层。将LLM生成的结构化结果以清晰易读的方式呈现出来可以是命令行输出、Markdown报告或者通过Webhook集成到CI/CD流水线、项目管理工具如Jira、Slack中实现自动化卡点。注意这个工具的成功极度依赖提示词工程的质量。一个糟糕的提示词会让LLM胡言乱语而一个优秀的提示词能让它像真正的专家一样工作。项目作者提供了经过精心调校的基础提示词模板这是我们能直接受益的关键。3. 从零开始环境搭建与快速上手理解了核心思路我们来看看怎么把它用起来。项目是基于Python的所以你需要一个Python环境建议3.8以上。3.1 基础环境准备与安装首先克隆项目仓库并安装依赖。这里我假设你已经安装了Git和Python。# 克隆项目 git clone https://github.com/guillempuche/ai-agent-a11y-accessibility-reviewer.git cd ai-agent-a11y-accessibility-reviewer # 创建并激活虚拟环境推荐避免包冲突 python -m venv venv # 在Windows上 venv\Scripts\activate # 在macOS/Linux上 source venv/bin/activate # 安装项目依赖 pip install -r requirements.txt安装过程会拉取一些必要的库比如用于HTTP请求的requests用于解析HTML的beautifulsoup4以及用于处理环境的python-dotenv等。3.2 核心配置API密钥与模型选择这个工具需要调用大语言模型的API所以你必须配置一个API密钥。目前它主要支持OpenAI的GPT系列模型如gpt-4, gpt-3.5-turbo理论上通过修改代码也能接入其他兼容OpenAI API格式的模型如Azure OpenAI, 或一些开源模型网关。安全第一永远不要将API密钥硬编码在代码里或提交到版本库。正确做法是在项目根目录创建一个名为.env的文件内容如下OPENAI_API_KEY你的_OpenAI_API_密钥_在这里然后在代码中通过os.getenv(OPENAI_API_KEY)来读取。项目源码中通常会有一个config.py或类似的文件来管理这些配置你需要根据示例进行修改。模型选择建议GPT-4如gpt-4-turbo-preview审查质量最高对复杂上下文和细微差别的理解更好但成本也高。适合对审查质量要求极高的正式评审或关键页面。GPT-3.5-Turbo性价比之选速度更快成本低很多。对于大多数常规的审查任务其准确度已经足够可靠是日常开发和自动化流水线的首选。3.3 你的第一次无障碍审查项目提供了几种使用方式最直接的是通过命令行工具。假设我们有一个简单的HTML文件test_page.html!DOCTYPE html html langen head titleTest Page/title /head body h1Welcome/h1 img srclogo.png altimage button onclicksubmitForm()Click Me/button p stylecolor: #aaa; background-color: #fff;This is a low contrast text./p /body /html我们可以使用工具内提供的Python脚本进行审查。通常主脚本叫review.py或main.py。运行方式可能类似python review.py --input test_page.html --output report.md或者如果工具提供了更友好的命令行接口python -m a11y_reviewer.cli review --html-file test_page.html执行后工具会做以下几件事读取你的HTML文件。结合内置的提示词模板构造一个包含系统指令、用户查询即你的HTML内容的完整提示。调用配置的LLM API。解析LLM返回的JSON格式结果。将结果生成为一份Markdown报告report.md。打开report.md你可能会看到如下内容# 无障碍审查报告 **审查对象**: test_page.html **审查时间**: 2023-10-27 10:30:00 **使用模型**: gpt-3.5-turbo ## 发现问题 ### 1. 高 - 图像缺少有意义的替代文本 - **位置**: img srclogo.png altimage - **违反准则**: WCAG 1.1.1 (非文本内容) - **描述**: 图像的alt属性值为“image”这是一个无意义的、泛泛的描述。对于使用屏幕阅读器的视障用户他们无法理解这张图片的内容或作用。 - **修复建议**: 将alt属性修改为能准确描述图片内容或功能的文本。例如如果这是公司Logo可以改为altAcme Corporation Logo。 - **修复后代码示例**: html img srclogo.png altAcme Corporation Logo2. 高 - 按钮缺乏可访问名称位置:button onclicksubmitForm()Click Me/button违反准则: WCAG 4.1.2 (名称、角色、值)描述: 按钮虽然有关联的文本“Click Me”但某些辅助技术可能更依赖明确的aria-label或按钮内的文本来确定其目的。当前实现是良好的但为了最佳实践和动态内容兼容性可以进一步优化。修复建议: 确保按钮的交互目的明确。当前文本“Click Me”可以更具体。如果按钮是用于提交表单建议改为button typesubmitSubmit Form/button或使用更具体的aria-label。修复后代码示例:button onclicksubmitForm() aria-labelSubmit the contact formSubmit/button3. 中 - 文本对比度不足位置:p stylecolor: #aaa; background-color: #fff;.../p违反准则: WCAG 1.4.3 (对比度最小值)描述: 文本颜色(#aaa)与背景色(#fff)的对比度约为2.3:1低于WCAG AA级标准要求的4.5:1对于正常文本。这可能导致视力不佳的用户阅读困难。修复建议: 加深文本颜色或调暗背景色以提高对比度。例如将文本颜色改为#666666对比度可提升至5.7:1符合标准。修复后代码示例:p stylecolor: #666; background-color: #fff;This is a low contrast text./p看这就是一次完整的审查。它不仅仅告诉你“错了”还告诉了你“为什么错”违反哪条准则、“严重程度如何”以及“具体怎么改”甚至给出了修改后的代码。这对于开发者来说 actionable可操作的信息价值巨大。 ## 4. 深入核心提示词工程与审查策略解析 工具的效能核心在于其提示词。我们来深入看看一个简化版的审查提示词可能长什么样以及为什么这样设计。 ### 4.1 解码系统提示词System Prompt 系统提示词用于设定LLM的“角色”和基础行为准则。一个好的系统提示词是这样的你是一个专业的网络无障碍Web Accessibility专家精通WCAG 2.1/2.2准则。你的任务是对提供的用户界面代码或描述进行全面的无障碍审查。请严格按照以下要求执行只针对提供的材料进行审查不要虚构不存在的问题。将问题按严重程度分为“高”、“中”、“低”三级。“高”导致功能完全无法使用或严重违反核心准则如缺少alt文本、键盘陷阱。“中”影响使用体验但用户可通过其他方式勉强完成操作如对比度不足、标签关联不完美。“低”最佳实践问题或细微的改进建议如语义化标签使用可以更优化。对每个发现的问题必须提供 a. 问题描述清晰、简洁。 b. 违反的WCAG准则编号如1.1.1。 c. 具体的代码位置或元素描述。 d. 详细的修复建议。 e. 可选修复后的代码示例。最终输出必须是一个格式严格的JSON数组每个元素是一个问题对象。这个提示词明确了角色、划定了范围、定义了输出标准极大地约束了LLM的输出使其结果结构化、可预测。 ### 4.2 用户查询User Query的构造 用户查询是将待审查内容“喂”给LLM的方式。工具会智能地构造查询例如请对以下HTML代码进行无障碍审查[这里粘贴完整的HTML代码]请重点关注图像替代文本、表单标签关联、键盘导航、颜色对比度以及ARIA属性的正确使用。它会把待审查的代码块清晰地标记出来并可以附加一些重点关注的指令引导LLM优先审查某些关键领域。 ### 4.3 自定义审查规则与场景适配 项目的强大之处在于其可扩展性。你完全可以修改或扩增提示词模板以适应你项目的特殊需求。 **场景一针对AI聊天机器人的审查** 如果你的AI Agent前端是一个聊天窗口你可以定制提示词加入针对性的审查点 * “检查聊天消息的气泡是否通过ARIA属性如role’log’或aria-live正确告知屏幕阅读器有新消息到达。” * “评估‘正在输入…’指示器是否对屏幕阅读器用户可见且不会造成干扰。” * “审查语音输入按钮的激活状态是否清晰传达。” **场景二融入品牌或设计系统** 你可以将公司的设计系统规范融入提示词 * “根据我司设计系统主要按钮的颜色为#007BFF请审查其与白色背景的对比度是否达标。” * “检查所有图标按钮是否都同时提供了可见的文本标签或aria-label。” **实操心得**不要试图在一个提示词里塞进所有WCAG准则。最好创建多个针对性的提示词模板例如“基础语义审查”、“交互与键盘导航审查”、“视觉与色彩审查”然后分批次运行或者通过程序串联起来。这样每个LLM调用的任务更聚焦成本更低效果也更好。 ## 5. 高级应用与集成融入开发生命周期 单独运行脚本只是开始。这个工具真正的威力在于将其自动化嵌入到团队的工作流中。 ### 5.1 集成到CI/CD流水线 你可以在GitHub Actions、GitLab CI或Jenkins中增加一个无障碍审查步骤。以下是一个GitHub Actions工作流的示例片段 yaml name: Accessibility Review on: [pull_request] jobs: a11y-review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install dependencies run: | pip install -r requirements.txt - name: Run Accessibility Reviewer on changed HTML files env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} run: | # 假设我们有一个脚本能找出PR中变更的HTML文件 for file in $(find . -name *.html -newer ../base_commit); do python review.py --input $file --output a11y-report-$(basename $file).md # 将报告作为工作流产物上传或解析后以评论形式提交到PR done - name: Upload accessibility reports uses: actions/upload-artifactv3 with: name: a11y-reports path: ./a11y-report-*.md这样每次提交Pull Request时都会自动对修改过的HTML文件进行审查并将报告作为构建产物保存。更高级的做法是解析报告如果发现“高”级别问题则让CI流程失败阻止合并或者通过GitHub API将问题以评论的形式自动提交到PR中直接给开发者反馈。5.2 与测试框架结合可以编写一个Pytest插件在端到端E2E测试或组件测试中集成无障碍审查。例如使用Playwright进行浏览器自动化测试时在测试结束后抓取页面HTML然后调用本工具进行分析。import pytest from playwright.sync_api import Page from a11y_reviewer import review_page # 假设有这样一个函数 def test_homepage_accessibility(page: Page): page.goto(https://your-app.com) # ... 执行一些交互测试 ... # 获取当前页面的HTML html_content page.content() # 进行无障碍审查 report review_page(html_content, modelgpt-3.5-turbo) # 断言没有高优先级问题 high_issues [issue for issue in report if issue[severity] 高] assert len(high_issues) 0, f发现高优先级无障碍问题: {high_issues}5.3 构建实时审查插件概念虽然项目本身可能没有直接提供但基于其核心逻辑我们可以畅想一个浏览器扩展或IDE插件。开发者边写代码边可以右键点击某个元素或组件选择“审查无障碍性”插件会将当前组件的代码片段发送给后端服务调用本项目逻辑并实时在侧边栏显示审查结果和修改建议。这能将无障碍性检查变成一种“编码时”的即时反馈极大地提升修复效率。6. 优势、局限与最佳实践6.1 与传统工具对比的优势为了更直观我们用一个表格来对比特性传统规则检查器 (如 axe-core)AI无障碍审查器 (本项目)检查原理基于静态规则匹配基于LLM的语义理解上下文理解弱只能检查显式属性强能理解内容含义和交互意图动态内容处理有限对JS生成内容支持不一较好可分析最终渲染的HTML或交互描述问题诊断深度告诉你“是什么”错了告诉你“为什么”错以及“怎么改”报告可读性技术性强需专业知识解读人性化用自然语言描述问题和建议适用阶段开发后期、测试阶段全周期设计稿评审、代码开发、测试成本开源免费或一次性购买按API调用次数计费GPT模型速度极快毫秒级较慢秒到十秒级依赖API确定性高规则固定结果一致中受模型、提示词影响可能有轻微波动可以看到两者是互补关系而非替代关系。最佳实践是先用传统工具进行快速、全面的“地毯式”扫描修复所有硬性规则错误再用AI审查器进行深度“专家式”审查解决语义、交互和体验层面的复杂问题。6.2 当前局限性及应对策略成本与速度调用GPT-4 API审查一个复杂页面可能需要几十秒和一定费用。不适合对海量页面进行全量扫描。策略在CI/CD中针对变更文件使用GPT-3.5-Turbo对于核心页面或发布前的最终检查再使用GPT-4。将审查作为“门禁”而非“全量扫描”。结果的非绝对确定性LLM可能偶尔“幻觉”出不存在的问题或对某些边缘情况判断不一致。策略永远不要完全依赖AI的结果作为唯一标准。应将AI审查报告视为一位“专家顾问”的意见需要开发者结合WCAG官方文档和实际测试如使用屏幕阅读器进行最终判断。可以将AI发现的问题标记为“待确认”纳入开发任务列表。无法进行实际交互测试工具分析的是静态代码或描述无法模拟真实的键盘操作、屏幕阅读器朗读等。策略AI审查必须与真实用户测试尤其是残障用户测试和自动化端到端无障碍测试如使用axe-core配合Playwright相结合。对复杂前端框架的支持对于Vue、React等组件化框架直接审查编译前的单文件组件.vue/.jsx可能效果不佳因为缺乏渲染后的DOM上下文。策略审查这些框架的应用时最佳输入是渲染后的HTML。可以通过在开发服务器运行测试或者使用无头浏览器抓取页面状态后的HTML再进行分析。6.3 打造团队无障碍文化的工作流建议设计阶段用AI审查器分析设计稿描述或高保真原型提前发现视觉对比度、组件语义等问题。开发阶段将工具集成到IDE或代码提交钩子pre-commit中对正在编写的组件进行即时审查。提交流程在CI/CD中设置强制关卡任何新代码引入的“高”级别无障碍问题必须修复后才能合并。测试阶段作为自动化测试套件的一部分对关键用户流程进行AI辅助审查。发布前对核心页面进行GPT-4级别的深度审查并辅以人工抽查和屏幕阅读器测试。这个项目就像一个不知疲倦、知识渊博的无障碍顾问7x24小时为你的团队服务。它不能替代专家的深度评估和真实用户的反馈但它能极大地提升发现问题的效率和广度将无障碍性从“事后补救”转变为“事前预防”和“事中检查”真正推动无障碍成为开发文化的一部分。从我个人的使用体验来看最大的收获不是它帮我找到了多少个BUG而是它以一种“润物细无声”的方式不断教育和提醒我和我的团队成员在写下一行代码、设计一个交互时去思考“所有人都能平等地使用它吗”。这种意识的建立远比工具本身的价值更大。
基于LLM的智能无障碍审查工具：从原理到工程实践
发布时间：2026/5/17 2:49:35
1. 项目概述一个为AI智能体而生却意外好用的无障碍审查工具最近在折腾一个AI驱动的客服聊天机器人项目团队里有个同事提了个挺尖锐的问题“咱们这个AI对视力障碍用户友好吗它能被屏幕阅读器正确识别吗” 这一问直接把大家问住了。我们花了大把时间在模型调优和对话流设计上却很少从“无障碍”这个角度去审视自己的产品。要知道一个无法被屏幕阅读器正常读取的按钮或者一个对比度不足的提示框对残障用户来说可能就是一道无法逾越的数字鸿沟。就在我们准备手动去啃WCAGWeb内容无障碍指南那本厚厚的手册并计划投入大量人力进行人工审查时我在GitHub上发现了这个项目guillempuche/ai-agent-a11y-accessibility-reviewer。初看名字我以为它只是一个为AI智能体AI Agent设计的、检查其交互界面无障碍性的工具。但深入使用后才发现它的设计理念和实现方式让它成为了一个通用性极强的自动化无障碍审查助手。它巧妙地利用了大语言模型LLM的理解能力将复杂的无障碍规范转化为可执行的、上下文相关的审查点不仅能审查AI Agent的界面对常规的Web页面、移动端组件甚至设计稿和代码片段都能给出极具针对性的改进建议。这个项目的核心价值在于它把“无障碍审查”从一个高度依赖专家经验和手动操作的“玄学”变成了一套可自动化、可解释、可融入开发流程的“工程实践”。对于前端工程师、产品经理、测试人员乃至AI应用开发者来说它都是一个能显著提升产品包容性同时降低合规风险的得力工具。接下来我就结合自己的实际使用经验把这个工具的里里外外、从原理到实操给大家彻底拆解一遍。2. 核心设计思路当LLM遇见无障碍规范2.1 为什么传统无障碍审查工具不够用在介绍这个项目之前我们先得理解现有工具的痛点。市面上主流的无障碍审查工具比如axe-core、Lighthouse的Accessibility审计或者浏览器插件如WAVE它们的工作原理主要是基于规则匹配。它们会扫描DOM结构检查诸如img标签是否有alt属性、按钮是否有可访问名称、颜色对比度是否达标等。这些工具非常高效能快速发现“硬伤”。但它们的局限性也很明显缺乏上下文理解一个alt图片的属性在规则检查器看来是“合规”的因为它确实存在。但这个描述对用户毫无意义。工具无法判断这个描述是否准确、是否传达了图片的核心信息。无法处理动态和复杂交互对于由JavaScript动态生成的内容、复杂的ARIA无障碍富互联网应用控件状态如折叠面板、标签页、或者需要一系列键盘操作才能完成的流程静态规则检查器往往力不从心。难以评估“感知”和“理解”层面的问题无障碍不仅仅是技术合规更是用户体验。一段文字的阅读等级是否合适一个错误提示是否清晰易懂图标的意思是否不言自明这些关乎认知和感知的问题传统工具无法解决。报告不友好工具输出的报告常常是一长串错误代码如WCAG 1.1.1, 4.1.2开发者需要额外去查阅规范文档才能理解问题所在和如何修复学习成本高。ai-agent-a11y-accessibility-reviewer项目的设计者显然深刻意识到了这些问题。它的核心思路不是替代这些规则检查器而是用大语言模型LLM的语义理解能力去弥补规则检查的不足并提供更人性化、更具操作性的指导。2.2 项目的三层架构设计这个工具的设计可以抽象为三层第一层输入适配层。它接受多种形式的输入URL直接提供一个网页链接工具会去抓取内容。HTML片段/代码直接粘贴待审查的HTML代码。组件描述对于尚未实现的设计稿或AI Agent的交互描述可以用自然语言描述例如“一个包含搜索框和结果列表的聊天窗口组件”。截图通过集成OCR光学字符识别能力甚至可以分析截图中的内容。这种灵活性让它能覆盖从设计、开发到测试的全流程。第二层LLM智能分析引擎核心。这是项目的灵魂。它并不是让LLM漫无目的地“看看”页面而是设计了一套精妙的“审查提示词Prompt”。这套提示词做了几件关键事角色设定让LLM扮演一个“资深无障碍专家”。任务分解将庞大的WCAG准则分解为一个个具体的审查任务例如“检查所有图像是否有有意义的替代文本”、“评估主要操作流程是否可以通过键盘完成”、“分析颜色对比度是否可能存在问题”。上下文提供将输入的内容HTML、描述等作为上下文提供给LLM。结构化输出要求要求LLM必须按照固定的格式如JSON输出审查结果包括问题描述、违反的准则、严重程度高/中/低、以及具体的修复建议代码示例。第三层结果输出与集成层。将LLM生成的结构化结果以清晰易读的方式呈现出来可以是命令行输出、Markdown报告或者通过Webhook集成到CI/CD流水线、项目管理工具如Jira、Slack中实现自动化卡点。注意这个工具的成功极度依赖提示词工程的质量。一个糟糕的提示词会让LLM胡言乱语而一个优秀的提示词能让它像真正的专家一样工作。项目作者提供了经过精心调校的基础提示词模板这是我们能直接受益的关键。3. 从零开始环境搭建与快速上手理解了核心思路我们来看看怎么把它用起来。项目是基于Python的所以你需要一个Python环境建议3.8以上。3.1 基础环境准备与安装首先克隆项目仓库并安装依赖。这里我假设你已经安装了Git和Python。# 克隆项目 git clone https://github.com/guillempuche/ai-agent-a11y-accessibility-reviewer.git cd ai-agent-a11y-accessibility-reviewer # 创建并激活虚拟环境推荐避免包冲突 python -m venv venv # 在Windows上 venv\Scripts\activate # 在macOS/Linux上 source venv/bin/activate # 安装项目依赖 pip install -r requirements.txt安装过程会拉取一些必要的库比如用于HTTP请求的requests用于解析HTML的beautifulsoup4以及用于处理环境的python-dotenv等。3.2 核心配置API密钥与模型选择这个工具需要调用大语言模型的API所以你必须配置一个API密钥。目前它主要支持OpenAI的GPT系列模型如gpt-4, gpt-3.5-turbo理论上通过修改代码也能接入其他兼容OpenAI API格式的模型如Azure OpenAI, 或一些开源模型网关。安全第一永远不要将API密钥硬编码在代码里或提交到版本库。正确做法是在项目根目录创建一个名为.env的文件内容如下OPENAI_API_KEY你的_OpenAI_API_密钥_在这里然后在代码中通过os.getenv(OPENAI_API_KEY)来读取。项目源码中通常会有一个config.py或类似的文件来管理这些配置你需要根据示例进行修改。模型选择建议GPT-4如gpt-4-turbo-preview审查质量最高对复杂上下文和细微差别的理解更好但成本也高。适合对审查质量要求极高的正式评审或关键页面。GPT-3.5-Turbo性价比之选速度更快成本低很多。对于大多数常规的审查任务其准确度已经足够可靠是日常开发和自动化流水线的首选。3.3 你的第一次无障碍审查项目提供了几种使用方式最直接的是通过命令行工具。假设我们有一个简单的HTML文件test_page.html!DOCTYPE html html langen head titleTest Page/title /head body h1Welcome/h1 img srclogo.png altimage button onclicksubmitForm()Click Me/button p stylecolor: #aaa; background-color: #fff;This is a low contrast text./p /body /html我们可以使用工具内提供的Python脚本进行审查。通常主脚本叫review.py或main.py。运行方式可能类似python review.py --input test_page.html --output report.md或者如果工具提供了更友好的命令行接口python -m a11y_reviewer.cli review --html-file test_page.html执行后工具会做以下几件事读取你的HTML文件。结合内置的提示词模板构造一个包含系统指令、用户查询即你的HTML内容的完整提示。调用配置的LLM API。解析LLM返回的JSON格式结果。将结果生成为一份Markdown报告report.md。打开report.md你可能会看到如下内容# 无障碍审查报告 **审查对象**: test_page.html **审查时间**: 2023-10-27 10:30:00 **使用模型**: gpt-3.5-turbo ## 发现问题 ### 1. 高 - 图像缺少有意义的替代文本 - **位置**: img srclogo.png altimage - **违反准则**: WCAG 1.1.1 (非文本内容) - **描述**: 图像的alt属性值为“image”这是一个无意义的、泛泛的描述。对于使用屏幕阅读器的视障用户他们无法理解这张图片的内容或作用。 - **修复建议**: 将alt属性修改为能准确描述图片内容或功能的文本。例如如果这是公司Logo可以改为altAcme Corporation Logo。 - **修复后代码示例**: html img srclogo.png altAcme Corporation Logo2. 高 - 按钮缺乏可访问名称位置:button onclicksubmitForm()Click Me/button违反准则: WCAG 4.1.2 (名称、角色、值)描述: 按钮虽然有关联的文本“Click Me”但某些辅助技术可能更依赖明确的aria-label或按钮内的文本来确定其目的。当前实现是良好的但为了最佳实践和动态内容兼容性可以进一步优化。修复建议: 确保按钮的交互目的明确。当前文本“Click Me”可以更具体。如果按钮是用于提交表单建议改为button typesubmitSubmit Form/button或使用更具体的aria-label。修复后代码示例:button onclicksubmitForm() aria-labelSubmit the contact formSubmit/button3. 中 - 文本对比度不足位置:p stylecolor: #aaa; background-color: #fff;.../p违反准则: WCAG 1.4.3 (对比度最小值)描述: 文本颜色(#aaa)与背景色(#fff)的对比度约为2.3:1低于WCAG AA级标准要求的4.5:1对于正常文本。这可能导致视力不佳的用户阅读困难。修复建议: 加深文本颜色或调暗背景色以提高对比度。例如将文本颜色改为#666666对比度可提升至5.7:1符合标准。修复后代码示例:p stylecolor: #666; background-color: #fff;This is a low contrast text./p看这就是一次完整的审查。它不仅仅告诉你“错了”还告诉了你“为什么错”违反哪条准则、“严重程度如何”以及“具体怎么改”甚至给出了修改后的代码。这对于开发者来说 actionable可操作的信息价值巨大。 ## 4. 深入核心提示词工程与审查策略解析 工具的效能核心在于其提示词。我们来深入看看一个简化版的审查提示词可能长什么样以及为什么这样设计。 ### 4.1 解码系统提示词System Prompt 系统提示词用于设定LLM的“角色”和基础行为准则。一个好的系统提示词是这样的你是一个专业的网络无障碍Web Accessibility专家精通WCAG 2.1/2.2准则。你的任务是对提供的用户界面代码或描述进行全面的无障碍审查。请严格按照以下要求执行只针对提供的材料进行审查不要虚构不存在的问题。将问题按严重程度分为“高”、“中”、“低”三级。“高”导致功能完全无法使用或严重违反核心准则如缺少alt文本、键盘陷阱。“中”影响使用体验但用户可通过其他方式勉强完成操作如对比度不足、标签关联不完美。“低”最佳实践问题或细微的改进建议如语义化标签使用可以更优化。对每个发现的问题必须提供 a. 问题描述清晰、简洁。 b. 违反的WCAG准则编号如1.1.1。 c. 具体的代码位置或元素描述。 d. 详细的修复建议。 e. 可选修复后的代码示例。最终输出必须是一个格式严格的JSON数组每个元素是一个问题对象。这个提示词明确了角色、划定了范围、定义了输出标准极大地约束了LLM的输出使其结果结构化、可预测。 ### 4.2 用户查询User Query的构造 用户查询是将待审查内容“喂”给LLM的方式。工具会智能地构造查询例如请对以下HTML代码进行无障碍审查[这里粘贴完整的HTML代码]请重点关注图像替代文本、表单标签关联、键盘导航、颜色对比度以及ARIA属性的正确使用。它会把待审查的代码块清晰地标记出来并可以附加一些重点关注的指令引导LLM优先审查某些关键领域。 ### 4.3 自定义审查规则与场景适配 项目的强大之处在于其可扩展性。你完全可以修改或扩增提示词模板以适应你项目的特殊需求。 **场景一针对AI聊天机器人的审查** 如果你的AI Agent前端是一个聊天窗口你可以定制提示词加入针对性的审查点 * “检查聊天消息的气泡是否通过ARIA属性如role’log’或aria-live正确告知屏幕阅读器有新消息到达。” * “评估‘正在输入…’指示器是否对屏幕阅读器用户可见且不会造成干扰。” * “审查语音输入按钮的激活状态是否清晰传达。” **场景二融入品牌或设计系统** 你可以将公司的设计系统规范融入提示词 * “根据我司设计系统主要按钮的颜色为#007BFF请审查其与白色背景的对比度是否达标。” * “检查所有图标按钮是否都同时提供了可见的文本标签或aria-label。” **实操心得**不要试图在一个提示词里塞进所有WCAG准则。最好创建多个针对性的提示词模板例如“基础语义审查”、“交互与键盘导航审查”、“视觉与色彩审查”然后分批次运行或者通过程序串联起来。这样每个LLM调用的任务更聚焦成本更低效果也更好。 ## 5. 高级应用与集成融入开发生命周期 单独运行脚本只是开始。这个工具真正的威力在于将其自动化嵌入到团队的工作流中。 ### 5.1 集成到CI/CD流水线 你可以在GitHub Actions、GitLab CI或Jenkins中增加一个无障碍审查步骤。以下是一个GitHub Actions工作流的示例片段 yaml name: Accessibility Review on: [pull_request] jobs: a11y-review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Set up Python uses: actions/setup-pythonv4 with: python-version: 3.10 - name: Install dependencies run: | pip install -r requirements.txt - name: Run Accessibility Reviewer on changed HTML files env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} run: | # 假设我们有一个脚本能找出PR中变更的HTML文件 for file in $(find . -name *.html -newer ../base_commit); do python review.py --input $file --output a11y-report-$(basename $file).md # 将报告作为工作流产物上传或解析后以评论形式提交到PR done - name: Upload accessibility reports uses: actions/upload-artifactv3 with: name: a11y-reports path: ./a11y-report-*.md这样每次提交Pull Request时都会自动对修改过的HTML文件进行审查并将报告作为构建产物保存。更高级的做法是解析报告如果发现“高”级别问题则让CI流程失败阻止合并或者通过GitHub API将问题以评论的形式自动提交到PR中直接给开发者反馈。5.2 与测试框架结合可以编写一个Pytest插件在端到端E2E测试或组件测试中集成无障碍审查。例如使用Playwright进行浏览器自动化测试时在测试结束后抓取页面HTML然后调用本工具进行分析。import pytest from playwright.sync_api import Page from a11y_reviewer import review_page # 假设有这样一个函数 def test_homepage_accessibility(page: Page): page.goto(https://your-app.com) # ... 执行一些交互测试 ... # 获取当前页面的HTML html_content page.content() # 进行无障碍审查 report review_page(html_content, modelgpt-3.5-turbo) # 断言没有高优先级问题 high_issues [issue for issue in report if issue[severity] 高] assert len(high_issues) 0, f发现高优先级无障碍问题: {high_issues}5.3 构建实时审查插件概念虽然项目本身可能没有直接提供但基于其核心逻辑我们可以畅想一个浏览器扩展或IDE插件。开发者边写代码边可以右键点击某个元素或组件选择“审查无障碍性”插件会将当前组件的代码片段发送给后端服务调用本项目逻辑并实时在侧边栏显示审查结果和修改建议。这能将无障碍性检查变成一种“编码时”的即时反馈极大地提升修复效率。6. 优势、局限与最佳实践6.1 与传统工具对比的优势为了更直观我们用一个表格来对比特性传统规则检查器 (如 axe-core)AI无障碍审查器 (本项目)检查原理基于静态规则匹配基于LLM的语义理解上下文理解弱只能检查显式属性强能理解内容含义和交互意图动态内容处理有限对JS生成内容支持不一较好可分析最终渲染的HTML或交互描述问题诊断深度告诉你“是什么”错了告诉你“为什么”错以及“怎么改”报告可读性技术性强需专业知识解读人性化用自然语言描述问题和建议适用阶段开发后期、测试阶段全周期设计稿评审、代码开发、测试成本开源免费或一次性购买按API调用次数计费GPT模型速度极快毫秒级较慢秒到十秒级依赖API确定性高规则固定结果一致中受模型、提示词影响可能有轻微波动可以看到两者是互补关系而非替代关系。最佳实践是先用传统工具进行快速、全面的“地毯式”扫描修复所有硬性规则错误再用AI审查器进行深度“专家式”审查解决语义、交互和体验层面的复杂问题。6.2 当前局限性及应对策略成本与速度调用GPT-4 API审查一个复杂页面可能需要几十秒和一定费用。不适合对海量页面进行全量扫描。策略在CI/CD中针对变更文件使用GPT-3.5-Turbo对于核心页面或发布前的最终检查再使用GPT-4。将审查作为“门禁”而非“全量扫描”。结果的非绝对确定性LLM可能偶尔“幻觉”出不存在的问题或对某些边缘情况判断不一致。策略永远不要完全依赖AI的结果作为唯一标准。应将AI审查报告视为一位“专家顾问”的意见需要开发者结合WCAG官方文档和实际测试如使用屏幕阅读器进行最终判断。可以将AI发现的问题标记为“待确认”纳入开发任务列表。无法进行实际交互测试工具分析的是静态代码或描述无法模拟真实的键盘操作、屏幕阅读器朗读等。策略AI审查必须与真实用户测试尤其是残障用户测试和自动化端到端无障碍测试如使用axe-core配合Playwright相结合。对复杂前端框架的支持对于Vue、React等组件化框架直接审查编译前的单文件组件.vue/.jsx可能效果不佳因为缺乏渲染后的DOM上下文。策略审查这些框架的应用时最佳输入是渲染后的HTML。可以通过在开发服务器运行测试或者使用无头浏览器抓取页面状态后的HTML再进行分析。6.3 打造团队无障碍文化的工作流建议设计阶段用AI审查器分析设计稿描述或高保真原型提前发现视觉对比度、组件语义等问题。开发阶段将工具集成到IDE或代码提交钩子pre-commit中对正在编写的组件进行即时审查。提交流程在CI/CD中设置强制关卡任何新代码引入的“高”级别无障碍问题必须修复后才能合并。测试阶段作为自动化测试套件的一部分对关键用户流程进行AI辅助审查。发布前对核心页面进行GPT-4级别的深度审查并辅以人工抽查和屏幕阅读器测试。这个项目就像一个不知疲倦、知识渊博的无障碍顾问7x24小时为你的团队服务。它不能替代专家的深度评估和真实用户的反馈但它能极大地提升发现问题的效率和广度将无障碍性从“事后补救”转变为“事前预防”和“事中检查”真正推动无障碍成为开发文化的一部分。从我个人的使用体验来看最大的收获不是它帮我找到了多少个BUG而是它以一种“润物细无声”的方式不断教育和提醒我和我的团队成员在写下一行代码、设计一个交互时去思考“所有人都能平等地使用它吗”。这种意识的建立远比工具本身的价值更大。
