ZCode Dogfood 报告模板实战基于 agent-browser 的结构化缺陷报告写作规范【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCodeZCode 仓库内置了完整的「自产自销dogfood」质量探索流程由 AI Agent 借助agent-browser浏览器自动化工具系统化地探测 Web 应用、发现缺陷并产出带完整复现证据的结构化报告。本文以仓库中的 dogfood-report-template.md 模板为骨架结合 dogfood SKILL 工作流 与 issue-taxonomy 问题分类法讲解如何写出可直接移交开发团队、可逐步回放的缺陷报告——包括头部元信息、严重性汇总、单条 Issue 的字段规范与「Repro 优先」的证据采集原则。模板在 Dogfood 流程中的定位在 ZCode 的.agents技能体系中dogfood 技能见 SKILL.md负责「系统化探索并测试一个 Web 应用找出 bug、UX 问题及其他缺陷」它的交付物就是一份结构化的 dogfood 报告。报告模板位于 .agents/skills/dogfood/templates/dogfood-report-template.md其头部注释表明该模板源自 vercel-labs/agent-browser 项目由 ZCode 做了本地化集成与格式适配采用 Apache-2.0 许可许可证与来源详情见仓库根目录的 THIRD-PARTY-NOTICES.md。模板在设计上有三个关键定位初始化即复制流程开始时将模板复制到输出目录并改名为report.md作为后续持续追加的单一报告文件Repro 优先Repro-First每条 Issue 都必须包含可回放的证据报告读者可以不碰浏览器、仅凭截图与步骤顺序就能完整复现问题证据分级交互类问题需要视频 分步截图静态类问题错别字、视觉瑕疵只需一张标注截图避免为不必要的问题录制冗长视频。报告头部元信息与严重性汇总模板要求每个报告文件以# Dogfood Report: {APP_NAME}开头紧接一张头部元信息表四个字段是必填的FieldValue含义Date{DATE}测试执行日期App URL{URL}被测应用地址如vercel.com或http://localhost:3000Session{SESSION_NAME}agent-browser 命名会话默认取域名的 slug 化形式如vercel-comScope{SCOPE}本次探索范围默认是「全应用」也可以聚焦如「计费页面」其中 Session 与agent-browser --session {SESSION}命令一一对应——通过命名会话可以在多个命令之间保持同一个浏览器实例与登录态详见 agent-browser 技能文档 的 Session Management 部分。紧接着是 Summary 严重性汇总表。模板中的占位值均为 0收尾阶段必须回填为与正文每条### ISSUE-块严格一致的计数SeverityCountCritical0High0Medium0Low0Total0严重性等级的定义在 issue-taxonomy.md 中有明确标准critical阻断核心工作流、造成数据丢失或应用崩溃high主要功能损坏且无变通方案medium功能可用但有明显问题、存在变通方案low属于轻微的外观或打磨问题。SKILL.md 同时强调5 个证据完备的 Issue 胜过 20 个描述含糊的 Issue探索目标是5–10 条记录良好的问题。单条 Issue 块的字段规范每条发现对应一个### ISSUE-{NNN}: {Short title}块编号从ISSUE-001开始递增且必须边发现边追加Append to the report immediately不能攒到最后批量补写以防会话中断丢失成果。Issue 块本身是一张字段表FieldValueSeveritycritical / high / medium / lowCategoryvisual / functional / ux / content / performance / console / accessibilityURL{page URL where issue was found}Repro Video{path to video, or N/A for static issues}Category 的取值对应 issue-taxonomy.md 中的七大问题类别visual布局错乱、元素重叠/文字截断、间距不一致、图标缺失、明暗主题渲染问题、响应式布局缺陷、z-index 层级遮挡、字体渲染问题、对比度不足、动画卡顿functional死链、点击无响应、表单校验过严/过松、重定向错误、静默失败、状态未持久化、竞态条件重复提交、脏数据、搜索/筛选损坏、分页问题、上传下载失败ux导航混乱、缺少加载反馈、感知延迟 300ms、错误提示不清、破坏性操作缺少确认、死胡同、同类功能模式不一致、缺少快捷键与焦点管理、默认值不直观、空状态缺失或无帮助content错别字与语法错误、过期文案、残留占位符/lorem ipsum、无 tooltip 的截断文本、标签缺失或错误、术语不一致performance页面加载 3s、滚动/动画掉帧、大布局偏移内容跳动、过多网络请求、内存泄漏、未优化的超大图片console / errors控制台 JS 异常、4xx/5xx 请求失败、弃用警告、CORS 错误、混合内容警告、未处理的 Promise rejectionaccessibility图片缺 alt、表单输入无标签、键盘无法 Tab 到达、焦点陷阱、对比度不足、动态内容缺 ARIA、不兼容屏幕阅读器。Repro Video字段是证据分级的落点交互类问题填视频文件路径相对输出目录如videos/issue-001-repro.webm静态类问题错别字、占位文本、加载即见的视觉瑕疵直接填N/A——模板注释明确说明静态问题只需一张截图无需视频与多步复现。Description 与 Repro Steps可回放的分步复现每条 Issue 由两个自由文本小节构成**Description**描述「什么错了、期望是什么、实际发生了什么」**Repro Steps**则给出编号步骤每一步都对应一张截图让读者可以纯视觉跟随。模板给出的骨架如下占位符含义已标注### ISSUE-001: {Short title} | Field | Value | | --------------- | ------------------------------------------ | | **Severity** | critical / high / medium / low | | **Category** | visual / functional / ux / content / performance / console / accessibility | | **URL** | {page URL where issue was found} | | **Repro Video** | {path to video, or N/A for static issues} | **Description** {What is wrong, what was expected, and what actually happened.} **Repro Steps** 1. Navigate to {URL} Step 1 2. {Action -- e.g., click Settings in the sidebar} Step 2 3. {Action -- e.g., type test in the search field and press Enter} Step 3 4. **Observe:** {what goes wrong -- e.g., the page shows a blank white screen instead of search results} Result注意截图路径是相对输出目录的模板约定截图统一放在{OUTPUT_DIR}/screenshots/下视频放在{OUTPUT_DIR}/videos/下初始化阶段即用mkdir -p创建这两个目录。报告的截图命名遵循issue-{NNN}-step-{N}.png、issue-{NNN}-result.png、issue-{NNN}.png静态问题以及视频issue-{NNN}-repro.webm的约定保证报告与证据文件一一对应。证据采集从 SKILL 工作流到模板落地模板本身是静态产物但要让每个字段都有内容可填需要遵循 SKILL.md 的六步工作流1. Initialize Set up session, output dirs, report file 2. Authenticate Sign in if needed, save state 3. Orient Navigate to starting point, take initial snapshot 4. Explore Systematically visit pages and test features 5. Document Screenshot record each issue as found 6. Wrap up Update summary counts, close session与模板字段直接相关的关键命令包括初始化cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md并agent-browser --session {SESSION} open {TARGET_URL}后wait --load networkidle定向Orientagent-browser screenshot --annotate {OUTPUT_DIR}/screenshots/initial.png与snapshot -i建立应用结构认知——snapshot -i用于发现可点击/可填写的元素返回e1、e2等引用不带-i的snapshot用于阅读页面文本内容每页例行检查snapshot -i、screenshot --annotate、errors、console四连其中console检查能发现 UI 上看不见的 JS 报错与失败请求静态问题单张screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png即可Repro Video 填N/A交互问题先record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm再复现每步截图之间sleep 1最终结果截图前sleep 2停顿最后record stop——视频必须能按 1x 速度观看因此录制时要用type逐字符输入而非fill一次性填充收尾重读报告确保 Summary 计数与每条 Issue 块严格一致然后agent-browser --session {SESSION} close关闭会话。采集证据前还有一条硬性前置校验必须先至少重试一次确认问题可复现无法稳定复现的现象不能记为有效 Issue详见 SKILL.md 的 Guidance 章节。实战示例一份填充完整的 Issue 块将模板要素、严重性定义与证据规范组合起来一个完整的交互类问题条目大致如下### ISSUE-001: 搜索后页面白屏未展示结果列表 | Field | Value | | --------------- | ------------------------------------------------------ | | **Severity** | high | | **Category** | functional | | **URL** | http://localhost:3000/search | | **Repro Video** | videos/issue-001-repro.webm | **Description** 在搜索框输入 test 并回车后期望展示结果列表实际页面渲染为空白白屏控制台报 TypeError: Cannot read properties of undefined。 **Repro Steps** 1. Navigate to http://localhost:3000/search Step 1 2. Click the search field in the sidebar Step 2 3. Type test in the search field and press Enter Step 3 4. **Observe:** the page shows a blank white screen instead of search results Result静态问题如某按钮文案拼写错误则可大幅简化Repro Video 填N/ARepro Steps 简化为「加载页面并截图」单步附一张screenshots/issue-002.png即可——模板注释明确允许这一做法避免为视觉瑕疵录制无意义的视频。编写要点与常见误区结合模板注释与 SKILL.md 的 Guidance编写报告时应把握以下要点Repro 就是一切但证据要匹配问题类型交互类functional、ux、操作触发的 console 错误需要视频 分步截图静态类错别字、占位文本、加载即见的视觉瑕疵单张标注截图即可涉及交互、时序或状态变化的问题才值得录视频步骤与截图一一对应每条编号步骤都应引用对应截图读者能纯视觉跟随交互问题要截出「动作前、动作中、动作后」的完整序列从探索到记录在同一趟完成发现问题的当下立即停止探索并写报告而不是全应用探索完再回头补文档绝不删除产物会话中途不得删除截图、视频或报告文件也不得关闭会话重启只能向前推进只测不读作为用户测试而非代码审计不得读取被测应用的 HTML、JS 或配置文件所有发现必须来自浏览器内的观察以用户视角探索按真实用户习惯走端到端流程、输入真实数据发现问题的密集区域应深入挖掘核心功能投入更多时间控制台不可忽视许多 UI 上看不见的问题表现为 JS 异常或失败请求每页例行执行errors与console检查视频按人类节奏录制动作间sleep 1、结果前sleep 2录制时用type而非fill命令批量化相互独立的命令可用在单次 shell 调用中串联如screenshot ... console滚动页面用scroll down 300不要用key或evaluate替代。小结ZCode 的 dogfood-report-template.md 不是一张普通的缺陷记录表而是一套「Repro 优先」的质量交付约定头部元信息表锁定测试上下文Summary 计数表与严重性定义见 issue-taxonomy.md让结论可量化单条 Issue 块的字段表强制证据分级分步截图让每条问题可回放、可移交。配合 dogfood SKILL 的六步工作流与 agent-browser 的命令体系任何 Agent 或测试人员都能产出一份开发团队可以直接上手修复的高质量缺陷报告。【免费下载链接】ZCodeZ.ais coding agent harness. Powerful, intelligent, extensible.项目地址: https://gitcode.com/gh_mirrors/zco/ZCode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考