企业官网建设流程全解析

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI

OpenRig 仓库中的 dogfood-report-template.md 是一个专为"agent 驱动的 Web 应用内测（dogfood）"设计的结构化报告模板。本文以该模板为主体，逐字段讲解报告头、严重度汇总和单条 Issue 块的编写规范，并结合 dogfood SKILL.md 的六步工作流与 issue-taxonomy.md 的分级分类体系，说明这份报告如何在真实测试会话中被初始化、逐条追加并最终定稿，帮助读者掌握一套可直接落地的可复现证据型 QA 报告写法。

模板在 OpenRig 技能体系中的定位

OpenRig 的技能（skill）是"渐进式上下文注入"的原语：frontmatter 中的description作为触发器常驻，正文在触发时加载，附属参考资料按需加载（见 skills/README.md）。dogfood 技能正是这样一个"当用户说 dogfood、QA、exploratory test、find issues、bug hunt 时触发"的技能，它系统性地探索一个 Web 应用、找出问题，并产出对每个发现都附带完整复现证据的报告——"so findings can be hand directly to the responsible teams"。

模板文件位于该技能目录的templates/子目录下，与参考资料references/并列：

• 仓库根镜像：skills/_canonical/process/dogfood/templates/dogfood-report-template.md
• 产品源（daemon 随包分发的真源）：packages/daemon/specs/agents/shared/skills/process/dogfood/templates/dogfood-report-template.md

从源码结构看，skills/_canonical/是通过 scripts/mirror-skills.mjs 从packages/daemon/specs/agents/shared/skills/单向镜像而来的副本，两者内容一致；npm run test:repo会执行mirror-skills --check检测漂移。此外，scripts/skill-edge-digests.generated.json 中对process/dogfood/templates/dogfood-report-template.md记录了固定 sha256 摘要，说明该模板文件本身也处于摘要校验的治理范围之内。

模板的 frontmatter 溯源元数据显示它 vendored 自 Vercel agent-browser 生态（vendoring_pattern: vendored-as-is），即模板内容与上游保持逐字一致，依赖的浏览器操作 CLI 就是 dogfood 技能配套的 agent-browser 技能 所使用的agent-browser命令行工具。

模板总体结构：三段式

整个模板由三个部分组成，对应一次 dogfood 会话"开始 → 过程中 → 结束"的信息沉淀：

1. 报告头（Header Fields）：Date、App URL、Session、Scope 四个元数据；
2. Summary 汇总：按严重度（Critical/High/Medium/Low）统计 Issue 数量的表格；
3. Issues 明细区：以ISSUE-001为编号、可无限复制追加的单条问题块。

这种结构的关键设计是汇总与明细分离：Summary 表是最后一步（Wrap up）统一回填的，而 Issues 区在探索过程中边发现边追加，因此即使会话中途被中断，已记录的发现也不会丢失——这与 SKILL.md 中"Append to the report immediately. Do not batch issues for later"的指导直接对应。

报告头：四个字段与默认值

模板开头是一张待填的元数据表：

# Dogfood Report: {APP_NAME} | Field | Value | |-------|-------| | **Date** | {DATE} | | **App URL** | {URL} | | **Session** | {SESSION_NAME} | | **Scope** | {SCOPE} |

这四个字段与 dogfood 技能 Setup 阶段的参数表一一对应。SKILL.md 规定：只有 Target URL 是必填项，其余参数都有默认值，除非用户显式覆盖：

SKILL.md 强调：当用户说 "dogfood vercel.com" 时应当立即用默认值开工，不要追问澄清问题（除非提到了认证但没给凭据）。Session 名之所以重要，是因为后续所有agent-browser --session {SESSION}命令都依赖它来隔离浏览器上下文；Scope 则决定了探索的边界，例如用户限定"只看账单页"时，报告头里的 Scope 字段应如实记录这一点，让读者知道汇总数字覆盖的范围。

模板在工作流第 1 步（Initialize）中被复制到输出目录成为实际的报告文件：

mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md agent-browser --session {SESSION} open {TARGET_URL} agent-browser --session {SESSION} wait --load networkidle

注意输出目录同时建立了screenshots/和videos/两个子目录——这正与后面单条 Issue 块中引用截图路径、视频路径的约定相配套。

Summary：严重度汇总表与收尾回填

模板的 Summary 区是一张零初始化的计数表：

## Summary | Severity | Count | |----------|-------| | Critical | 0 | | High | 0 | | Medium | 0 | | Low | 0 | | **Total** | **0** |

四个严重度等级的判定标准定义在 issue-taxonomy.md 中，dogfood 技能要求在每次会话开始时阅读该参考资料来校准"看什么"：

汇总数字不是随手填的：SKILL.md 第 6 步（Wrap up）明确要求"Re-read the report and update the summary severity counts so they match the actual issues. Every### ISSUE-block must be reflected in the totals"——即报告中每一个### ISSUE-块都必须在 Total 中有对应体现。这一设计保证汇总区与明细区强一致，读者仅看 Summary 就能对风险面形成判断。

单条 Issue 块：字段、描述与分步复现

模板 Issues 区给出了可复制的问题块样板（原模板中的 HTML 注释指明了两种证据等级的选择规则）：

## Issues <!-- Copy this block for each issue found. Interactive issues need video + step-by-step screenshots. Static issues (typos, visual glitches) only need a single screenshot -- set Repro Video to N/A. --> ### 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** <!-- Each step has a screenshot. A reader should be able to follow along visually. --> 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

逐字段拆解如下。

编号与标题

### ISSUE-001: {Short title}采用三位递增编号（ISSUE-001、ISSUE-002……）。SKILL.md 要求每发现一个问题就立即递增计数器并追加，而不是攒到最后统一写。标题用一句话概括问题，方便报告被搜索和引用。

元数据表四个字段

• Severity：取critical / high / medium / low四值之一，按上述 taxonomy 判定；
• Category：取七值之一——visual / functional / ux / content / performance / console / accessibility，与 taxonomy 文档中的七个分类章节一一对应（详见下节）；
• URL：发现该问题的页面地址，读者可据此快速跳转；
• Repro Video：交互类问题填录屏文件路径；静态问题（错别字、视觉瑕疵）填N/A。

Description 的三段式

模板注释给出了 Description 的写法："What is wrong, what was expected, and what actually happened"——即问题是什么、期望行为、实际行为三要素齐备，避免"页面坏了"这类无法定位的模糊描述。

Repro Steps：与截图一一映射

模板内注释点明设计意图："Each step has a screenshot. A reader should be able to follow along visually." 每个编号步骤后紧跟一张screenshots/issue-{NNN}-step-{K}.png截图，最后一步固定以Observe:开头描述出错状态，并附一张标注过的结果截图issue-{NNN}-result.png。这样读者无需打开浏览器，仅凭图文就能完整重放问题——这正是 dogfood 技能"Repro is everything"宗旨的体现：

Every issue must be reproducible. When you find something wrong, do not just note it -- prove it with evidence. The goal is that someone reading the report can see exactly what happened and replay it.

两类问题的证据分级

模板 HTML 注释中的关键规则——"Interactive issues need video + step-by-step screenshots. Static issues only need a single screenshot"——在 SKILL.md 中被展开为两套具体操作规程。

交互 / 行为类问题（functional、ux、操作触发的 console 报错）

需要录屏 + 分步截图的完整复现，操作序列如下（其中{OUTPUT_DIR}、{SESSION}、{NNN}为占位符）：

1. 复现前先开始录像：

agent-browser --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.webm

2. 以人的节奏走完每一步，动作之间sleep 1停顿，每步截图：

agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png sleep 1 # Perform action (click, fill, etc.) sleep 1 agent-browser --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png

3. 捕获出错状态：停顿让观众看清，再拍一张标注截图：

sleep 2 agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png

4. 停止录像：agent-browser --session {SESSION} record stop

5. 在报告模板的 Repro Steps 区写入编号步骤，每步引用对应截图。

SKILL.md 还强调：录制视频中填写表单要用type（逐字符输入）而不是fill，让人能看到输入过程；录像节奏要"watchable at 1x speed"。

静态 / 加载即可见的问题（错别字、占位文本、文字被裁切、布局错位、加载即报的 console 错误）

无需录屏，一张标注截图即可，然后"SetRepro VideotoN/A"：

agent-browser --session {SESSION} screenshot --annotate {OUTPUT_DIR}/screenshots/issue-{NNN}.png

这条规则直接对应模板字段表中 Repro Video 的取值约定。SKILL.md 的 Guidance 部分补充了两条纪律：收集证据前先验证可复现性（至少重试一次，无法稳定复现的"不算有效 issue"）以及不要为静态问题录视频——错别字或文字裁切从视频里得不到任何额外信息。

Category 七分类：与 taxonomy 的完整映射

Issue 块中Category字段的七个取值，在 issue-taxonomy.md 中各有详细清单，dogfood 时按此校准观察重点：

taxonomy 文档同时提供了一份每页探索检查单（视觉扫描 → 交互元素 → 表单 → 导航 → 状态（空/加载/错误/溢出）→ console → 响应式 → 认证边界），供 agent 在每个页面系统化地过一遍。

完整填写流程：模板在工作流六步中的位置

把模板放回 SKILL.md 定义的六步工作流，可以看到模板字段是在不同步骤被填充的：

1. Initialize 设置会话、输出目录、报告文件（拷贝模板并填报告头） 2. Authenticate 如需登录则登录并保存 state 3. Orient 导航到起点，拍初始标注截图 4. Explore 系统化访问页面并测试功能 5. Document 发现即截图 + 录像 + 追加 Issue 块 6. Wrap up 回填 Summary 计数，关闭会话

• 步骤 1中执行cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md，报告头的 Date、App URL、Session、Scope 在此填写；
• 步骤 4/5 是同一遍完成的（"Steps 4 and 5 happen together -- explore and document in a single pass"）：每到一个页面执行snapshot -i（找可交互元素）、screenshot --annotate（留视觉证据）、errors和console（抓不可见的 JS 错误），发现问题就停下来先按上节流程取证、再按模板追加 Issue 块并递增编号；
• 步骤 6先重读报告把 Summary 的严重度计数与明细对齐，再agent-browser --session {SESSION} close关闭会话，最后向用户汇报：问题总数、严重度分布、最关键的条目。SKILL.md 给出的量化目标是"5-10 个带完整证据的问题，深度优先于数量——5 个带完整复现胜过 20 个描述模糊的"。

配套的硬性纪律（Guidance 节）对模板的可用性至关重要：绝不删除输出文件（不要rm截图/视频/报告、不要中途关闭会话重来）；绝不阅读被测应用的源码（以用户视角测试，所有发现来自浏览器观察）；独立命令尽量用&&批量执行以提高效率。

小结

dogfood-report-template.md 虽然只有几十行，却承载了 dogfood 技能"证据先行"（Repro-First）的完整契约：报告头四字段锚定测试范围与上下文，Summary 表与明细区通过收尾回填保持强一致，单条 Issue 块用 Severity/Category/URL/Repro Video 四个元数据加"三段式描述 + 每步一截图"的复现步骤，让报告可以直接移交给责任团队而无需二次询问。配合 issue-taxonomy.md 的七类分级标准和 agent-browser 技能 提供的浏览器自动化命令，这套模板构成了一条从探索、取证到交付的完整 QA 流水线。由于该文件处于镜像与 sha256 摘要双重治理之下（见 skills/README.md 的 Drift detection 说明），在 OpenRig 生态中升级技能包时，报告格式可以预期保持稳定。

• 人工智能
• AI Agent
• 多智能体
• Agent 编排
• 代码智能体
• CLI