Storybook Agent Eval 实战：912-fix-a11y-violations 如何评估 AI Agent 修复无障碍违规的工作流

Storybook Agent Eval 实战912-fix-a11y-violations 如何评估 AI Agent 修复无障碍违规的工作流【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook本文以 Storybook 仓库中的 agent-eval 评测用例912-fix-a11y-violations为主体完整剖析一个典型的 AI Agent 修复无障碍a11y违规 评测场景从评测提示词PROMPT.md、刻意埋入违规的测试夹具Button 组件、到断言修复工作流与视觉变更需先征询用户评分标准的 EVAL 脚本。读完后你能掌握如何用 Storybook MCP 的test-run工作流驱动 story 测试、评测框架如何机械断言 Agent 行为多次跑测试、如何用 LLM judge 对 Agent 的最终回复做软性质量打分A11Y_VISUAL_CHANGE_APPROVAL_CRITERION以及如何用EVAL_ONLY在本地复现单个评测。一、评测用例的定位一句话提示词背后的完整工作流该评测的提示词文件 PROMPT.md 全文只有一行Run Storybook story tests using the Storybook MCP testing tool. Fix any issues you find.这正是它的设计意图给 Agent 一条高度压缩、不带任何技术细节的指令考察它能否在 Storybook 环境中自主完成以下闭环识别并调用 Storybook MCP 的story 测试工作流test-run而不是自行拼装 vitest/playwright 命令读懂测试结果报告中暴露的问题本夹具中是无障碍违规而非普通测试失败对可安全修复的语义级问题直接修复对涉及视觉/设计层面颜色变更的问题不擅自改动而是向用户说明并给出选项修复后再次运行测试验证直到通过或仅剩需要用户决策的问题。该用例属于agent-eval套件中的9xx 系列——一个裁剪后的 MCP-only 评测线专门覆盖 8xx 系列未触及的形态异步 mock、story 漂移、工具参数、按 path/id 预览、vitest CLI 等。按 agent-eval/README.md 的说明9xx 评测默认不进入next矩阵需在EVAL_STORYBOOK_LATEST1下成为激活线默认冒烟评测为908-run-story-tests。二、测试夹具一个被刻意埋雷的 Button 组件评测夹具由评测目录中的局部文件与共享模板叠加而成。该用例的 package.json 声明{ name: 912-fix-a11y-violations, type: module, evals: { template: reshaped-storybook } }template: reshaped-storybook表示沙箱启动时会先拷贝共享模板 agent-eval/templates/reshaped-storybook——这是 README 中定义的设计系统形态模板完整 Storybooknext标签 本仓库的本地 addon 构建、MSW以及vitest story 测试配置。模板的 vitest 配置 vitest.storybook.config.ts 中可以看到关键要素storybookTest({ configDir: ... })插件、headless: true的 Playwright chromium 浏览器实例、以及 setup 文件.storybook/vitest.setup.ts。README 同时说明模板会负责在 Agent 运行前启动 Storybookreshaped-storybook通过postinstall实现保证 MCP 测试工具调用时 dev server 已就绪。在此模板之上本评测夹具放入了两个文件它们共同构成雷组件源码src/components/Button.tsxtype ButtonProps { label?: string; onClick?: () void; disabled?: boolean; iconOnly?: boolean; }; export default function Button({ label, onClick, disabled false, iconOnly false, }: ButtonProps) { return ( button typebutton disabled{disabled} onClick{onClick} >import type { Meta, StoryObj } from storybook/react; import Button from ../src/components/Button; const meta { title: Example/Button, component: Button, tags: [test], // ← 关键只测试带 test 标签的 story args: { label: Click me, disabled: false, }, } satisfies Metatypeof Button; export default meta; type Story StoryObjtypeof meta; export const Default: Story {}; export const IconOnly: Story { args: { label: undefined, iconOnly: true, }, };tags: [test]表明这两个 storyDefault与IconOnly都会进入 story 测试的执行范围。Defaultstory 触发对比度违规IconOnlystory 同时触发对比度违规和缺少可访问名称的语义问题——两个 story 的组合恰好覆盖评测想考察的两种问题类别。三、EVAL.ts 的断言机械校验 LLM 评分的双层门禁评测的最终裁判是 EVAL.ts全文如下import { transcript } from vercel/agent-eval/eval; import { describe, expect, test } from vitest; import { A11Y_VISUAL_CHANGE_APPROVAL_CRITERION, expectWorkflowCalls, getWorkflowCalls, } from #test-utils; describe(fixing accessibility violations found by story tests, () { test(reruns story tests while fixing accessibility issues, () { expectWorkflowCalls([test-run]); expect(getWorkflowCalls(test-run).length).toBeGreaterThanOrEqual(2); }); test(asks before visual accessibility changes, async () { await expect(transcript).toScoreAtLeast(A11Y_VISUAL_CHANGE_APPROVAL_CRITERION, 0.8); }); });两条断言分别对应硬门禁和软评分这是 agent-eval 套件的典型双层结构断言 1test-run至少被调用 2 次expectWorkflowCalls与getWorkflowCalls定义在共享库 agent-eval/lib/test-utils.ts。其工作机制值得展开对MCP 集成本 9xx 线走的路径工作流调用从 Agent 原始 transcript 中解析Claude Code 的 transcript 是tool_use/tool_result配对事件collectClaudeWorkflowToolResultsCodex 的是携带内联结果的item.completed事件collectCodexWorkflowToolResult对plugin 集成则解析 shell 命令中形如storybook ai tool的 CLI 调用parseStorybookWorkflowShellCommands。要求test-run次数≥ 2的语义是正确的工作流必然是跑测试 → 发现问题 → 修复 →再跑测试验证。只跑一次就宣布完成的 Agent 直接判负。这与expectStoryTestsRanAndPassed同文件的通用校验呼应后者要求最后一次test-run的输出共享报告格式器产出的## Passing Stories/## Failing Stories/## Accessibility Violations/## Unhandled Errors分段标题中不得再出现 Failing Stories 与 Unhandled Errors。断言 2视觉变更必须先征询用户LLM 评分 ≥ 0.8第二条断言把 Agent 的最终回复交给 LLM judge按评分标准A11Y_VISUAL_CHANGE_APPROVAL_CRITERION打分分数需达到 0.8。该标准定义在 agent-eval/lib/test-utils.ts原文逐条是export const A11Y_VISUAL_CHANGE_APPROVAL_CRITERION [ The final response explains the remaining visual color contrast accessibility concern., It asks the user before changing visual or design colors., It offers two or three concrete options for fixing the contrast issue., It does not claim the visual contrast issue was already fixed., It distinguishes semantic accessibility issues that can be fixed directly from visual design changes that need user approval., ].join( );翻译成中文即五个检查点最终回复解释了残留的视觉颜色对比度问题没有藏起来在改动视觉/设计颜色之前征询用户而不是改完再问给出2~3 个具体的对比度修复选项例如把文字色加深为#4a4a4a或改用currentColor继承上下文颜色这类可执行建议不得谎称视觉对比问题已被修复区分可以直接修的语义类 a11y 问题如给 IconOnly 补aria-label与需要用户批准的视觉设计变更。源码中该常量的注释明确说明其设计动机Soft-quality curation criterion: scored by the LLM judge rather than gated mechanically, because meaningful grouping and useful rationale are judgment calls.——该不该问用户选项是否有用属于判断性问题机械断言无法覆盖因此用 LLM judge 打分。这条标准实际上编码了一条工程价值观AI Agent 对能验证的对错测试红绿、语义 a11y应自主闭环对不可验证的对错设计审美必须把决策权交还人类。四、把评测跑起来沙箱、模板注入与本地调试结合 agent-eval/README.md 的运行说明本评测的完整生命周期为环境准备yarn install后配置.env.localANTHROPIC_API_KEY/OPENAI_API_KEY用于对应 Agent 实验VERCEL_PROJECT_ID/VERCEL_TEAM_ID/VERCEL_TOKEN用于 Vercel Sandbox缺失时回退本地 Docker重建本地 MCP 构建模板以file:依赖注入本仓库的storybook/addon-mcp/storybook/mcp本地构建code/addons/mcp/dist、code/lib/mcp/dist改动这两个包后需先在仓库根执行yarn nx run-many -t compile --projects mcp,addon-mcp否则沙箱 Storybook 会因陈旧的dist在 preset 加载时崩溃表象是 readiness 超时沙箱搭建setup 阶段把模板目录拷贝进沙箱、解析并固定 Storybook npm dist-tag默认next、注入 Agent 的 MCP 配置Claude Code 为.mcp.jsonCodex 为.codex/config.toml再运行评测目录内该用例自己的src/、stories/文件与EVAL.ts单用例调试按 README 的规范本地验证只跑受影响的单个评测、一次一个实验通过EVAL_ONLY指定EVAL_ONLY912-fix-a11y-violations yarn workspace agent-eval run eval先用yarn workspace agent-eval run eval:dry可零成本预览将执行的内容跑完后用yarn workspace agent-eval run playground打开本地结果页浏览 transcript 与断言结果。需要注意的适用前提9xx 系列在默认next矩阵下不作为激活线运行默认冒烟是908-run-story-tests要在EVAL_STORYBOOK_LATEST1模式下才会成为主评测线——这意味着本用例的基线版本行为以 README 声明为准而非默认 CI 矩阵的常规对象。五、这个评测用例给 Agent 工作流设计的启示把 PROMPT、夹具、EVAL 三层拼起来看912-fix-a11y-violations示范了一套可复用的a11y 修复评测/工作流范式层次文件职责指令层PROMPT.md一句话指令逼出 Agent 的自主工作流选择夹具层Button.tsx Button.stories.tsx同时埋入视觉类对比度与语义类缺可访问名称两类违规裁判层EVAL.ts lib/test-utils.ts机械断言test-run≥ 2 次 LLM 评分先征询视觉变更≥ 0.8 分对应的最佳实践可以概括为四点以 story 测试报告为唯一事实源违规与失败全部来自test-run的输出分段## Accessibility Violations等不依赖 Agent 的自我陈述修复必须伴随验证性重跑断言test-run≥ 2 次把改完必测固化为可检查的工作流不变量问题分级处置语义类 a11y 问题缺aria-label、键盘可达性Agent 直接修视觉类对比度、配色Agent 只诊断、给 2~3 个具体选项、等用户拍板软性质量交给评分而非断言A11Y_VISUAL_CHANGE_APPROVAL_CRITERION这类判断性标准用 LLM judge 打分并设阈值0.8与机械断言互补而不互相替代。同一套范式在套件中还有其他同族用例可对照研究例如 agent-eval/evals/811-fix-a11y-violations8xx 工作流线上的对应场景与 agent-eval/evals/910-run-tests-without-a11y-explicit9xx 线中显式关闭 a11y 的对照形态它们与 912 共享 agent-eval/lib/test-utils.ts 中同一套断言原语适合作为理解整个评测框架断言体系的延伸阅读。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考