ZCode 问题分类指南基于 Issue Taxonomy 系统化开展 Dogfooding 质量巡检【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCodeZCode 仓库内置了一套面向 AI Agent 的 Dogfooding 技能.agents/skills/dogfood/SKILL.md用于对 Web 应用进行系统性探索与缺陷发现并产出带完整复现证据的结构化报告。本文围绕该技能的核心参考文档 Issue Taxonomy完整讲解缺陷分级体系、七大问题分类、逐项检查清单并结合仓库中agent-browser技能的真实命令与报告模板给出可直接落地的边探索、边取证、边记录的实战方案。为什么需要一份 Issue TaxonomyDogfooding自用自测与传统的脚本化测试不同它不是执行预先写好的测试用例而是像真实用户一样探索应用凭直觉发现哪里不对劲。这带来一个核心问题——如何保证探索的广度和判断的一致性Issue Taxonomy 正是为此设计的校准工具。该文档在dogfood技能中明确要求每次 Dogfooding 会话开始前先阅读它用统一的严重级别和分类口径校准该找什么。这样无论由人类还是 AI Agent 执行探索产出的问题报告都能在同一套坐标系下比较、汇总与排优先级。严重级别四级分级体系任何发现的问题首先必须定级。Taxonomy 给出四级严重度定义严重级别定义critical致命阻断核心工作流、造成数据丢失或导致应用崩溃high高主要功能损坏或不可用且没有绕行方案medium中功能可用但存在明显问题存在绕行方案low低轻微的外观或打磨类问题定级时的判断顺序建议是先问核心工作流是否被阻断 / 是否有数据丢失或崩溃critical再问主要功能是否完全不可用high然后判断是否有绕行方案来区分 medium 与 high最后才是纯打磨类问题归入 low。这套分级与报告模板中的Summary表一一对应——模板要求按 Critical / High / Medium / Low 统计数量并在收尾阶段重新阅读报告确保严重级别计数与实际 ISSUE 块完全匹配。因此定级不是写报告时的临时判断而是从发现问题那一刻起就必须遵循的纪律。七大问题分类与逐项清单Taxonomy 将问题划分为 7 大类。每个类别的完整检查点如下这也是dogfood-report-template.md中Category字段的可选值visual / functional / ux / content / performance / console / accessibility。Visual / UI视觉与界面布局破坏或元素错位文字重叠或被裁剪间距、内边距、外边距不一致图标/图片缺失或损坏深色/浅色模式渲染异常响应式布局问题不同视口尺寸下Z-index 层叠问题元素被其他元素遮挡字体渲染问题字体、字号、字重错误颜色对比度问题动画闪烁或卡顿实战提示视觉类问题大多属于加载即可见的静态缺陷按 Dogfooding 技能的取证规则SKILL.md第 5 节只需一张带标注截图即可作为证据无需录视频。可使用agent-browser screenshot --annotate生成带元素编号标注的截图配合snapshot -i获取交互元素引用agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png深色/浅色模式与响应式问题需要主动切换环境验证。agent-browser提供set media dark模拟深色模式、set viewport 375 812模拟移动宽度支持对同一页面在不同视口与配色下分别截图比对见 commands.md 的 Browser Settings 一节。Functional功能性链接失效404、跳转错误按钮或控件点击无响应表单校验拒绝合法输入或接受非法输入错误的重定向功能静默失败状态未按预期持久化刷新或导航后丢失竞态条件重复提交、陈旧数据搜索或过滤功能异常分页问题文件上传/下载失败实战提示这是典型的交互型缺陷需要完整的复现证据。按技能流程复现前先启动录像然后以人类节奏逐步操作每步截图、步骤间sleep 1agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png # 执行点击、填写等操作步骤间 sleep 1 agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png # ...直到缺陷出现 agent-browser --session {SESSION} record stop竞态条件类问题尤其值得关注技能要求先用至少一次重试验证缺陷可复现再开始采集证据——无法稳定复现的问题不算有效缺陷。UX用户体验导航混乱或语义不清操作后缺少加载指示或反馈交互缓慢或无响应感知延迟 300ms错误信息不清晰破坏性操作缺少确认死胡同无法返回或继续相似功能间交互模式不一致缺少键盘快捷键或焦点管理不直观的默认值缺失空状态或空状态无帮助实战提示UX 问题的判断基准是真实用户视角。技能指引明确像用户一样测试而不是像机器人——尝试端到端的常见工作流点击真实用户会点的东西输入真实数据。300ms 感知延迟、死胡同、空状态这类问题无法靠截图证明需要结合录像与文字描述说明交互过程。Content内容拼写或语法错误过期或不正确的文本残留占位符或 Lorem ipsum 内容文本被截断且无 tooltip 或展开能力标签缺失或错误术语使用不一致实战提示纯内容缺陷属于加载即可见的静态问题单张标注截图即可。但要注意技能中的一条硬性纪律永远不要阅读被测应用的源代码——所有发现必须来自浏览器中的可观察表现见 SKILL.md 的 Guidance 部分。Performance性能页面加载缓慢3s滚动或动画卡顿大幅布局偏移内容跳动网络请求过多通过 console/network 检查内存泄漏页面随时间变慢图片未优化文件体积过大实战提示性能问题通常UI 上看不见要靠工具佐证。agent-browser提供了network requests查看跟踪到的请求、network har start/stop录制 HAR 文件配合console/errors命令检查控制台与错误见 commands.md。技能建议每个页面例行执行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加载慢、请求多这类问题也可以在报告中附上 network / console 输出作为量化证据。Console / Errors控制台与错误控制台中的 JavaScript 异常失败的网络请求4xx、5xx弃用警告Deprecation warningsCORS 错误混合内容警告未处理的 Promise rejection实战提示这类问题在 UI 上完全不可见只能通过agent-browser console与agent-browser errors主动检查。技能多次强调检查控制台——许多问题在 UI 中不可见但会以 JS 错误或失败请求的形式暴露。若发现错误在特定操作后触发交互型按录像流程取证若是页面加载时即出现静态型单张截图加控制台输出即可。Accessibility可访问性图片缺少 alt 文本表单输入无标签键盘导航不佳无法 Tab 到元素焦点陷阱颜色对比度不足动态内容缺少 ARIA 属性屏幕阅读器不兼容的模式实战提示snapshot -i输出的正是可访问性树accessibility tree它天然暴露无标签输入框不可聚焦元素等问题。agent-browser get styles e1可获取元素的计算样式以核对颜色对比度。--color-scheme dark与set media dark同样适用于验证可访问性相关的对比度场景参考 SKILL.md 的 Color Scheme 一节。探索检查清单八个步骤逐个页面执行Taxonomy 提供了一个可复用的探索清单用于指导每个页面/功能测什么。这是文档中可直接照做的部分建议在每个目标页面依次执行视觉扫描Visual scan—— 拍摄带标注截图检查布局、对齐与渲染问题交互元素Interactive elements—— 点击每个按钮、链接和控件它们是否生效是否有反馈表单Forms—— 填写并提交测试空提交、非法输入和边界情况导航Navigation—— 走通所有导航路径检查面包屑、返回按钮、深链状态States—— 检查空状态、加载状态、错误状态、满/溢出状态控制台Console—— 检查 JS 错误、失败请求和警告响应式Responsiveness—— 如适用在不同视口尺寸下测试鉴权边界Auth boundaries—— 测试未登录时的表现以及不同角色下的差异在技能的整体流程中这八个步骤被嵌入到初始化 → 认证 → 定向 → 探索 → 记录 → 收尾的六阶段工作流里。初始化阶段需要agent-browser --session {SESSION} open {TARGET_URL}与wait --load networkidle确保页面加载完成认证阶段使用snapshot -i定位登录表单并通过fill/click完成登录成功后state save保存状态便于复用。探索策略源自 SKILL.md 第 4 节从主导航开始逐个访问每个顶级分区在每个分区内测试交互元素点击按钮、填写表单、打开下拉框/弹窗检查边界情况空状态、错误处理、边界输入尝试真实端到端工作流创建、编辑、删除流程定期检查浏览器控制台错误把时间花在核心功能上外围页面浅探即可若某个区域发现成簇的问题深入调查。取证优先让每个缺陷都可复现Taxonomy 定义了找什么而 Dogfooding 技能则定义了如何证明。其核心原则是Repro-First复现优先交互型/行为型缺陷功能、UX、操作触发的控制台错误需要完整复现——录像 分步截图。先在复现前record start启动录像再以人类节奏逐步操作每步截图最终对缺陷状态拍带标注截图record stop结束最后在报告中写编号复现步骤并逐条关联截图。加载即可见的静态缺陷错别字、占位文本、文字截断、错位、加载时的控制台错误单张带标注截图即可报告中的Repro Video字段填N/A。取证过程有几条硬性纪律值得单独强调均出自 SKILL.md 的 Guidance 部分先验证可复现性再采集证据——至少重试一次无法稳定复现就不是有效缺陷发现即记录——找到问题立即追加到报告并递增编号ISSUE-001、ISSUE-002…绝不攒到最后批量写防止会话中断丢失成果静态缺陷不录视频——录像只留给涉及交互、时序或状态变化的问题步骤与截图一一对应——报告读者应能不碰浏览器、仅凭截图走完复现流程会话内禁止删除输出文件——不清理截图、录像和报告不回退重来为人类节奏调速——录像时用type逐字符输入而非fill步骤间sleep 1、结果前sleep 2保证 1 倍速可观看。报告落地从分类到可交接的产物Taxonomy 的分类最终要落到报告模板上。每个 ISSUE 块包含以下字段字段取值Severitycritical / high / medium / lowCategoryvisual / functional / ux / content / performance / console / accessibilityURL发现问题所在页面的 URLRepro Video录像路径静态缺陷填 N/A报告结构为头部元信息日期、URL、会话名、探索范围→ Summary 严重级别计数表 → 逐条 ISSUE 块描述 编号复现步骤每步配图。收尾阶段的目标是5-10 个证据充分的缺陷技能明确指出证据深度比总量更重要——5 个带完整复现的缺陷胜过 20 个含糊的描述。完成探索后需重新核对 Summary 计数与实际 ISSUE 块一致close关闭会话最后向用户汇报总数、严重级别分布与最关键的缺陷。本文依据的仓库文件核心参考文档Issue Taxonomy本文主体内容来源Dogfooding 工作流与取证纪律dogfood 技能报告结构与字段定义dogfood-report-template.md取证工具命令全集agent-browser 技能 与 commands.md需要说明的是issue-taxonomy.md与dogfood技能源自 Vercel 开源的agent-browser项目由 ZCode 本地集成并适配文档头部有明确版权与来源标注见仓库根目录 THIRD-PARTY-NOTICES.md。实践中建议将本分类与清单作为团队内部统一的缺陷口径让每一次 Dogfooding 会话都能产出可比较、可交接、可回归的质量数据。【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ZCode 问题分类指南：基于 Issue Taxonomy 系统化开展 Dogfooding 质量巡检
ZCode 问题分类指南基于 Issue Taxonomy 系统化开展 Dogfooding 质量巡检【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCodeZCode 仓库内置了一套面向 AI Agent 的 Dogfooding 技能.agents/skills/dogfood/SKILL.md用于对 Web 应用进行系统性探索与缺陷发现并产出带完整复现证据的结构化报告。本文围绕该技能的核心参考文档 Issue Taxonomy完整讲解缺陷分级体系、七大问题分类、逐项检查清单并结合仓库中agent-browser技能的真实命令与报告模板给出可直接落地的边探索、边取证、边记录的实战方案。为什么需要一份 Issue TaxonomyDogfooding自用自测与传统的脚本化测试不同它不是执行预先写好的测试用例而是像真实用户一样探索应用凭直觉发现哪里不对劲。这带来一个核心问题——如何保证探索的广度和判断的一致性Issue Taxonomy 正是为此设计的校准工具。该文档在dogfood技能中明确要求每次 Dogfooding 会话开始前先阅读它用统一的严重级别和分类口径校准该找什么。这样无论由人类还是 AI Agent 执行探索产出的问题报告都能在同一套坐标系下比较、汇总与排优先级。严重级别四级分级体系任何发现的问题首先必须定级。Taxonomy 给出四级严重度定义严重级别定义critical致命阻断核心工作流、造成数据丢失或导致应用崩溃high高主要功能损坏或不可用且没有绕行方案medium中功能可用但存在明显问题存在绕行方案low低轻微的外观或打磨类问题定级时的判断顺序建议是先问核心工作流是否被阻断 / 是否有数据丢失或崩溃critical再问主要功能是否完全不可用high然后判断是否有绕行方案来区分 medium 与 high最后才是纯打磨类问题归入 low。这套分级与报告模板中的Summary表一一对应——模板要求按 Critical / High / Medium / Low 统计数量并在收尾阶段重新阅读报告确保严重级别计数与实际 ISSUE 块完全匹配。因此定级不是写报告时的临时判断而是从发现问题那一刻起就必须遵循的纪律。七大问题分类与逐项清单Taxonomy 将问题划分为 7 大类。每个类别的完整检查点如下这也是dogfood-report-template.md中Category字段的可选值visual / functional / ux / content / performance / console / accessibility。Visual / UI视觉与界面布局破坏或元素错位文字重叠或被裁剪间距、内边距、外边距不一致图标/图片缺失或损坏深色/浅色模式渲染异常响应式布局问题不同视口尺寸下Z-index 层叠问题元素被其他元素遮挡字体渲染问题字体、字号、字重错误颜色对比度问题动画闪烁或卡顿实战提示视觉类问题大多属于加载即可见的静态缺陷按 Dogfooding 技能的取证规则SKILL.md第 5 节只需一张带标注截图即可作为证据无需录视频。可使用agent-browser screenshot --annotate生成带元素编号标注的截图配合snapshot -i获取交互元素引用agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png深色/浅色模式与响应式问题需要主动切换环境验证。agent-browser提供set media dark模拟深色模式、set viewport 375 812模拟移动宽度支持对同一页面在不同视口与配色下分别截图比对见 commands.md 的 Browser Settings 一节。Functional功能性链接失效404、跳转错误按钮或控件点击无响应表单校验拒绝合法输入或接受非法输入错误的重定向功能静默失败状态未按预期持久化刷新或导航后丢失竞态条件重复提交、陈旧数据搜索或过滤功能异常分页问题文件上传/下载失败实战提示这是典型的交互型缺陷需要完整的复现证据。按技能流程复现前先启动录像然后以人类节奏逐步操作每步截图、步骤间sleep 1agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png # 执行点击、填写等操作步骤间 sleep 1 agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png # ...直到缺陷出现 agent-browser --session {SESSION} record stop竞态条件类问题尤其值得关注技能要求先用至少一次重试验证缺陷可复现再开始采集证据——无法稳定复现的问题不算有效缺陷。UX用户体验导航混乱或语义不清操作后缺少加载指示或反馈交互缓慢或无响应感知延迟 300ms错误信息不清晰破坏性操作缺少确认死胡同无法返回或继续相似功能间交互模式不一致缺少键盘快捷键或焦点管理不直观的默认值缺失空状态或空状态无帮助实战提示UX 问题的判断基准是真实用户视角。技能指引明确像用户一样测试而不是像机器人——尝试端到端的常见工作流点击真实用户会点的东西输入真实数据。300ms 感知延迟、死胡同、空状态这类问题无法靠截图证明需要结合录像与文字描述说明交互过程。Content内容拼写或语法错误过期或不正确的文本残留占位符或 Lorem ipsum 内容文本被截断且无 tooltip 或展开能力标签缺失或错误术语使用不一致实战提示纯内容缺陷属于加载即可见的静态问题单张标注截图即可。但要注意技能中的一条硬性纪律永远不要阅读被测应用的源代码——所有发现必须来自浏览器中的可观察表现见 SKILL.md 的 Guidance 部分。Performance性能页面加载缓慢3s滚动或动画卡顿大幅布局偏移内容跳动网络请求过多通过 console/network 检查内存泄漏页面随时间变慢图片未优化文件体积过大实战提示性能问题通常UI 上看不见要靠工具佐证。agent-browser提供了network requests查看跟踪到的请求、network har start/stop录制 HAR 文件配合console/errors命令检查控制台与错误见 commands.md。技能建议每个页面例行执行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加载慢、请求多这类问题也可以在报告中附上 network / console 输出作为量化证据。Console / Errors控制台与错误控制台中的 JavaScript 异常失败的网络请求4xx、5xx弃用警告Deprecation warningsCORS 错误混合内容警告未处理的 Promise rejection实战提示这类问题在 UI 上完全不可见只能通过agent-browser console与agent-browser errors主动检查。技能多次强调检查控制台——许多问题在 UI 中不可见但会以 JS 错误或失败请求的形式暴露。若发现错误在特定操作后触发交互型按录像流程取证若是页面加载时即出现静态型单张截图加控制台输出即可。Accessibility可访问性图片缺少 alt 文本表单输入无标签键盘导航不佳无法 Tab 到元素焦点陷阱颜色对比度不足动态内容缺少 ARIA 属性屏幕阅读器不兼容的模式实战提示snapshot -i输出的正是可访问性树accessibility tree它天然暴露无标签输入框不可聚焦元素等问题。agent-browser get styles e1可获取元素的计算样式以核对颜色对比度。--color-scheme dark与set media dark同样适用于验证可访问性相关的对比度场景参考 SKILL.md 的 Color Scheme 一节。探索检查清单八个步骤逐个页面执行Taxonomy 提供了一个可复用的探索清单用于指导每个页面/功能测什么。这是文档中可直接照做的部分建议在每个目标页面依次执行视觉扫描Visual scan—— 拍摄带标注截图检查布局、对齐与渲染问题交互元素Interactive elements—— 点击每个按钮、链接和控件它们是否生效是否有反馈表单Forms—— 填写并提交测试空提交、非法输入和边界情况导航Navigation—— 走通所有导航路径检查面包屑、返回按钮、深链状态States—— 检查空状态、加载状态、错误状态、满/溢出状态控制台Console—— 检查 JS 错误、失败请求和警告响应式Responsiveness—— 如适用在不同视口尺寸下测试鉴权边界Auth boundaries—— 测试未登录时的表现以及不同角色下的差异在技能的整体流程中这八个步骤被嵌入到初始化 → 认证 → 定向 → 探索 → 记录 → 收尾的六阶段工作流里。初始化阶段需要agent-browser --session {SESSION} open {TARGET_URL}与wait --load networkidle确保页面加载完成认证阶段使用snapshot -i定位登录表单并通过fill/click完成登录成功后state save保存状态便于复用。探索策略源自 SKILL.md 第 4 节从主导航开始逐个访问每个顶级分区在每个分区内测试交互元素点击按钮、填写表单、打开下拉框/弹窗检查边界情况空状态、错误处理、边界输入尝试真实端到端工作流创建、编辑、删除流程定期检查浏览器控制台错误把时间花在核心功能上外围页面浅探即可若某个区域发现成簇的问题深入调查。取证优先让每个缺陷都可复现Taxonomy 定义了找什么而 Dogfooding 技能则定义了如何证明。其核心原则是Repro-First复现优先交互型/行为型缺陷功能、UX、操作触发的控制台错误需要完整复现——录像 分步截图。先在复现前record start启动录像再以人类节奏逐步操作每步截图最终对缺陷状态拍带标注截图record stop结束最后在报告中写编号复现步骤并逐条关联截图。加载即可见的静态缺陷错别字、占位文本、文字截断、错位、加载时的控制台错误单张带标注截图即可报告中的Repro Video字段填N/A。取证过程有几条硬性纪律值得单独强调均出自 SKILL.md 的 Guidance 部分先验证可复现性再采集证据——至少重试一次无法稳定复现就不是有效缺陷发现即记录——找到问题立即追加到报告并递增编号ISSUE-001、ISSUE-002…绝不攒到最后批量写防止会话中断丢失成果静态缺陷不录视频——录像只留给涉及交互、时序或状态变化的问题步骤与截图一一对应——报告读者应能不碰浏览器、仅凭截图走完复现流程会话内禁止删除输出文件——不清理截图、录像和报告不回退重来为人类节奏调速——录像时用type逐字符输入而非fill步骤间sleep 1、结果前sleep 2保证 1 倍速可观看。报告落地从分类到可交接的产物Taxonomy 的分类最终要落到报告模板上。每个 ISSUE 块包含以下字段字段取值Severitycritical / high / medium / lowCategoryvisual / functional / ux / content / performance / console / accessibilityURL发现问题所在页面的 URLRepro Video录像路径静态缺陷填 N/A报告结构为头部元信息日期、URL、会话名、探索范围→ Summary 严重级别计数表 → 逐条 ISSUE 块描述 编号复现步骤每步配图。收尾阶段的目标是5-10 个证据充分的缺陷技能明确指出证据深度比总量更重要——5 个带完整复现的缺陷胜过 20 个含糊的描述。完成探索后需重新核对 Summary 计数与实际 ISSUE 块一致close关闭会话最后向用户汇报总数、严重级别分布与最关键的缺陷。本文依据的仓库文件核心参考文档Issue Taxonomy本文主体内容来源Dogfooding 工作流与取证纪律dogfood 技能报告结构与字段定义dogfood-report-template.md取证工具命令全集agent-browser 技能 与 commands.md需要说明的是issue-taxonomy.md与dogfood技能源自 Vercel 开源的agent-browser项目由 ZCode 本地集成并适配文档头部有明确版权与来源标注见仓库根目录 THIRD-PARTY-NOTICES.md。实践中建议将本分类与清单作为团队内部统一的缺陷口径让每一次 Dogfooding 会话都能产出可比较、可交接、可回归的质量数据。【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考