企业官网建设流程全解析

agent-browser 缺陷分类指南（Issue Taxonomy）：基于 Dogfood 技能的系统化 Web 应用质量排查方法论

【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/gh_mirrors/agen/agent-browser

本指南围绕 dogfood 技能 的配套参考文档 issue-taxonomy.md 展开，系统讲解在 agent-browser 浏览器自动化 CLI 生态中如何对被测 Web 应用进行缺陷分类、严重度定级与系统性探索。读者将掌握一套可复用的"严重度分级 → 缺陷类别 → 逐页探索清单"方法论，并了解如何借助 agent-browser 的命令行工具（截图、快照、控制台与错误追踪、录屏）将每一个发现沉淀为带完整复现证据的问题报告。

文档定位：Dogfood 会话开始前的校准基准

issue-taxonomy.md是 dogfood 技能 的一部分，位于仓库的skill-data/dogfood/references/目录。dogfood 技能（SKILL 元数据中的 description 将其定义为"Systematically explore and test a web application to find bugs, UX issues, and other problems"）用于系统化地探索并测试 Web 应用，寻找 bug、UX 问题与其他缺陷，适用于 "dogfood"、"QA"、"exploratory test"、"find issues"、"bug hunt" 等任务场景。

该参考文档在 dogfood 工作流中的位置非常明确：SKILL.md 的 "4. Explore" 步骤要求先阅读本文件以获得"需要寻找什么的完整清单"（Readreferences/issue-taxonomy.mdfor the full list of what to look for and the exploration checklist），同时在 SKILL.md 末尾的 References 表格中，它被标记为Start of session—— 即每次 dogfood 会话开始时都必须阅读，用于校准关注点（"calibrate what to look for"）。

整篇文档由三个核心部分构成：

1. Severity Levels（严重度分级）—— 四档分级标准，用于为每个发现定级；
2. Categories（缺陷类别）—— 七大类别，每类下列出具体检查项；
3. Exploration Checklist（探索清单）—— 八个维度，指导每个页面/功能的测试顺序。

这三部分与 dogfood 报告模板 形成完整闭环：报告模板中的Severity字段取值（critical/high/medium/low）与Category字段取值（visual/functional/ux/content/performance/console/accessibility）正是本文件定义的分类体系。

严重度分级（Severity Levels）

文档定义了四档严重度，每一档都对应明确的业务影响描述：

分级的关键是以影响用户的程度为准，而非以修复成本为准。critical 强调"阻断核心流程"与"数据丢失"这类不可逆后果；high 强调"无 workaround"的完全不可用；medium 与 low 的分界则在于是否存在可绕过的替代方案、以及问题是否仅停留在外观层面。在 dogfood 报告模板中，汇总表（Summary）按这四档统计数量，每个 ISSUE- 块都必须与该汇总保持一致——SKILL.md 的 Wrap Up 步骤明确要求"更新 summary 严重度计数，使它们与实际 issue 匹配，每个### ISSUE-块都必须反映在总计中"。

七大缺陷类别（Categories）

Visual / UI（视觉与界面）

布局错乱或元素错位、元素重叠或文本被裁剪、间距/内边距/外边距不一致、图标或图片缺失损坏、深色/浅色模式渲染问题、响应式布局问题（视口尺寸）、z-index 层级问题（元素被遮挡）、字体渲染问题（字体、字号、字重错误）、颜色对比度问题、动画卡顿或抖动。

Functional（功能）

• 失效链接（404、跳错目标）
• 按钮或控件点击无响应
• 表单校验误拒合法输入或误收非法输入
• 重定向错误
• 功能静默失败（无任何报错）
• 状态未按预期持久化（刷新、导航后丢失）
• 竞态条件（重复提交、陈旧数据）
• 搜索或筛选失效
• 分页问题
• 文件上传/下载失败

UX（用户体验）

• 导航混乱或不清晰
• 缺少操作后的加载指示或反馈
• 交互缓慢或无响应（感知延迟 >300ms）
• 错误信息不清晰
• 破坏性操作缺少确认
• 死胡同（无法返回或继续）
• 相似功能间模式不一致
• 缺少键盘快捷键或焦点管理
• 默认值不符合直觉
• 缺少空状态或空状态无帮助

Content（内容）

• 拼写或语法错误
• 过时或不正确的文本
• 遗留的占位符或 lorem ipsum 内容
• 文本被截断且无 tooltip 或展开方式
• 标签缺失或错误
• 术语不一致

Performance（性能）

• 页面加载缓慢（>3s）
• 滚动或动画卡顿
• 大幅布局偏移（内容跳动）
• 过多网络请求（通过 console/network 检查）
• 内存泄漏（页面随时间变慢）
• 图片未优化（文件体积过大）

Console / Errors（控制台与错误）

• 控制台中的 JavaScript 异常
• 失败的网络请求（4xx、5xx）
• 弃用警告（deprecation warnings）
• CORS 错误
• Mixed content 警告
• 未处理的 Promise rejection

Accessibility（无障碍）

• 图片缺少 alt 文本
• 表单输入无标签
• 键盘导航体验差（无法 Tab 到元素）
• 焦点陷阱（focus traps）
• 颜色对比度不足
• 动态内容缺少 ARIA 属性
• 与屏幕阅读器不兼容的模式

探索清单（Exploration Checklist）

文档将每个页面/功能上的测试动作归纳为八步，按顺序执行即可做到覆盖全面：

1. Visual scan（视觉扫描）—— 截图并标注（annotated screenshot），检查布局、对齐与渲染问题；
2. Interactive elements（交互元素）—— 点击每个按钮、链接与控件，验证是否生效、是否有反馈；
3. Forms（表单）—— 填写并提交，测试空提交、非法输入与边界情况；
4. Navigation（导航）—— 走遍所有导航路径，检查面包屑、返回按钮、深链接；
5. States（状态）—— 检查空状态、加载状态、错误状态与满/溢出状态；
6. Console（控制台）—— 检查 JS 错误、失败请求与警告；
7. Responsiveness（响应式）—— 如相关，在不同视口尺寸下测试；
8. Auth boundaries（认证边界）—— 测试未登录时的表现，以及不同角色（如适用）下的表现。

与 agent-browser 工具链的结合：如何实际执行这份清单

issue-taxonomy 定义了"找什么"，而 agent-browser CLI 则提供了"怎么找"。dogfood SKILL.md 给出了与上述清单一一对应的命令组合，这些命令在 cli/src/commands.rs 中有完整的解析逻辑，在 cli/src/native/actions.rs 中有对应的底层实现。

快照与截图：覆盖清单第 1 步

探索每个页面时的标准动作组合（对应清单的 Visual scan 与 Interactive elements）：

agent-browser --session {SESSION} snapshot -i agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/{page-name}.png agent-browser --session {SESSION} errors agent-browser --session {SESSION} console

其中snapshot -i用于查找可点击/可填写的元素（按钮、输入框、链接），snapshot（不带标志）用于阅读页面内容（文本、标题、数据列表）。screenshot --annotate会在截图上叠加元素标注，便于在报告中指向具体元素——该行为在 actions.rs 的截图处理逻辑中实现，annotate标志决定是否在渲染后叠加标注层。

控制台与错误追踪：覆盖清单第 6 步

console与errors两个命令在 commands.rs 中被解析为对应的 action（支持--clear标志清空已收集的条目），实际处理则在 actions.rs。底层数据由 network.rs 中的EventTracker维护：

• ConsoleEntry记录日志级别（level）、文本（text）与格式化参数（args）；
• ErrorEntry记录错误文本、URL 与行列号（line/column）——这正是报告模板中定位代码问题所需的精确坐标；
• 两类条目均有max_entries: 1000的环形缓冲上限，超出后丢弃最旧的条目，避免长时间会话中内存无限增长。

这一设计直接支撑了探索清单第 6 步"检查 JS 错误、失败请求与警告"：许多问题在 UI 上不可见，但会以控制台异常或失败请求的形式暴露——SKILL.md 的 Guidance 中也强调"Many issues are invisible in the UI but show up as JS errors or failed requests"。

录屏与逐步截图：覆盖"Repro-First"证据要求

dogfood 方法论的核心原则是repro-first（复现优先）——发现问题时立即停下探索并记录证据，而不是先探索完再补文档。issue-taxonomy 的类别直接决定了证据等级：

• 交互/行为类问题（functional、ux、操作触发的 console 错误）需要完整复现：record start启动录屏 → 按人类可观看的节奏逐步操作（步骤间sleep 1）→ 每一步截图 → 最终screenshot --annotate捕获损坏状态 →record stop停止；
• 静态/加载即见问题（拼写错误、占位符文本、文本裁剪、对齐错位、加载时的 console 错误）只需一张带标注的截图，报告中的Repro Video字段填写N/A。

record命令支持start/stop/restart三个子命令，输出格式支持.webm与.mp4，并可配合--fps、--cursor、--contact-sheet等选项（commands.rs）。记录完成后，报告中的每个复现步骤都必须引用对应截图，使读者无需打开浏览器即可按图复述整个流程——这正是 dogfood-report-template.md 中每个 ISSUE- 块的结构要求。

会话、状态与效率：贯穿整个工作流

• 命名会话：agent-browser --session {SESSION} open {TARGET_URL}启动，wait --load domcontentloaded等待加载，close在 wrap up 阶段关闭；
• 认证状态复用：登录成功后state save {OUTPUT_DIR}/auth-state.json保存状态，对应探索清单第 8 步"认证边界"的测试前提；
• 滚动方式：SKILL.md 明确要求使用scroll down 300进行滚动，而不要使用key或evaluate模拟滚动；
• 命令批量执行：相互独立的命令可在同一条 shell 调用中用&&连接（如screenshot与console），减少往返开销；
• 人类节奏：录屏时步骤间sleep 1、最终结果截图前sleep 2，保证视频以 1x 速度可观看。

报告结构与质量闭环

dogfood-report-template.md 将 issue-taxonomy 的分类体系落成结构化文档：

• 头部字段：Date、App URL、Session、Scope；
• Summary 表：按 critical/high/medium/low 四档统计数量（与严重度分级一一对应）；
• ISSUE- 块：每块包含 Severity、Category（visual/functional/ux/content/performance/console/accessibility 七选一）、URL、Repro Video，以及 Description 与逐步的 Repro Steps（每步引用一张截图）。

dogfood 技能对会话质量有明确要求：目标是5-10 个文档完善的 issue，且"证据深度比总数更重要——5 个完整复现的 issue 优于 20 个含糊描述"。Wrap up 阶段需要重读报告、校正严重度统计，然后关闭会话并向用户汇报：issue 总数、按严重度的分布、以及最关键的条目。

此外，dogfood 技能还规定了若干纪律性约束，与 issue-taxonomy 的分类视角互为补充：

• 先验证可复现性再收集证据：录制视频或截图前，至少重试一次确认 issue 能稳定复现，否则不算有效发现；
• 绝不删除输出文件：会话中途不得删除截图、视频或报告，不得关闭会话后重启，只向前推进；
• 绝不阅读被测应用的源码：以用户身份测试而非审计代码，不读取被测应用的 HTML、JS 或配置文件——所有发现必须来自浏览器中的可观察行为；
• 像人类一样输入：录屏期间使用type（逐字符输入）而非fill（一次性填充），仅在非录屏、追求速度时使用fill。

结语：从"找问题"到"可交付的证据链"

issue-taxonomy 的价值在于把"发现缺陷"这一模糊的 QA 行为，拆解为一套可执行、可量化、可交接的工程方法：四档严重度让团队能按优先级排布修复工作，七大类别覆盖从像素级视觉问题到深层次竞态条件的完整缺陷光谱，八步探索清单则保证了逐页测试的系统性与可重复性。当它与 agent-browser 的截图标注、快照引用、控制台/错误追踪（network.rs）和视频录制能力结合后，每一个发现都能沉淀为带完整复现证据的 ISSUE- 记录，直接交付给负责团队。这套方法论不仅适用于 agent-browser 自身的 dogfood 会话，也为任何希望以"真实用户视角"系统化排查 Web 应用质量的工程团队提供了一份可复用的参考框架。

【免费下载链接】agent-browserBrowser automation CLI for AI agents项目地址: https://gitcode.com/gh_mirrors/agen/agent-browser