---
title: "05 · 用 Artifacts 建立验收工作流"
description: "Antigravity Artifacts 的商业级验收方法：task list、implementation plan、diff、screenshot、browser recording、walkthrough 和评论迭代。"
verifiedAt: "2026-05-07"
---

Artifacts 的价值不是“输出更漂亮”，而是把 agent 工作从黑盒变成可审阅证据。官方 Artifacts 文档把 artifact 定义成 agent 为完成工作或向用户沟通工作与思考而创建的内容，类型可以包括 rich markdown、diff view、architecture diagram、image、browser recording、code diff 等。官方还明确：artifacts 在 agent 处于 **Planning 模式**时产生，并同时出现在 Agent Manager 与 Editor 中（前者对 artifacts 的显示和管理做了优化）。这意味着如果你在 Fast 模式下跑任务，agent 不会主动产出可审阅的 artifacts。

这意味着你不需要盯着每个工具调用，但你必须能看懂计划、diff、截图、录屏和 walkthrough。商业级验收的核心不是“agent 说完成了”，而是“证据能不能支撑完成”。

> [!NOTE]
> **一句话标准**：没有 artifact 的完成，只是口头完成；有 artifact 的完成，才可能进入商业验收。

> [!TIP]
> **阅读目标**：读完本章，你应该能按 Task List（任务清单）→ Implementation Plan（实现计划）→ Diff（代码差异）→ Screenshot / Recording（截图 / 录屏）→ Walkthrough（任务总结）的顺序验收一次 agent 任务。

## 1. Artifact 不是日志

日志记录过程，artifact 承担验收。两者差别很大：

| 类型 | 目的 | 谁来读 |
| --- | --- | --- |
| Tool logs | 调试 agent 过程 | 排障时才读 |
| Task List | 看步骤是否合理 | 任务负责人 |
| Implementation Plan | 看方案和范围 | 工程负责人 |
| Screenshot / Recording | 看用户路径是否通过 | 产品和设计 |
| Walkthrough | 看完成内容和验证方法 | 交付接收人 |

官方 Task List 文档说明，它是一个 markdown list，用于复杂任务的研究、实现、验证等进度跟踪。你通常不需要直接编辑它，但需要看它是否真的覆盖了任务闭环。

## 2. 任务开始前：Task List

Task List 要回答：

1. 分几步做？
2. 哪些步骤会改文件？
3. 哪些步骤会跑命令？
4. 哪些步骤会打开浏览器？
5. 最后怎么验收？

如果 task list 只有“implement feature / test feature / finish”，太粗。让 agent 重写。

更好的 Task List 应该像这样：

```text
- 研究当前设置页结构。
- 定位保存动作和持久化层。
- 编辑前先输出 implementation plan。
- 只修改设置页文件和对应测试。
- 运行定向测试 + 浏览器验证。
- 输出 walkthrough，含 diff 摘要和剩余风险。
```

这个列表不是为了好看，而是为了防止任务中途变形。只要它缺少 research、implementation、verification 其中任何一环，就要求补齐。

## 3. 动手前：Implementation Plan

Implementation Plan 要审：

```mermaid
flowchart LR
    Plan["Implementation Plan"] --> Scope["修改范围"]
    Plan --> Design["技术路线"]
    Plan --> Risk["风险点"]
    Plan --> Verify["验证方式"]
    Plan --> Rollback["回退方式"]
```

> [!IMPORTANT]
> 商业级任务至少要有验证方式和回退方式。没有这两项，不要批准复杂改动。

官方 Implementation Plan 文档强调，plan 是用来架构代码库变更的 artifact，并且通常会在修改前请求用户 review。你可以点 `Proceed` 继续，也可以在 artifact 上评论，让 agent 缩小范围、改技术路线或修正理解偏差。

建议把评论写得像工程约束，而不是像主观意见：

```text
这个 plan 范围过大。
请保留第一步分析，但不要改全局 layout。
只允许修改 settings form 和对应测试。
验证命令限定为 pnpm test settings 和一次 mobile browser 截图。
```

## 4. 生成后：Code Diff

看 diff 不要平均用力，先扫红线：

| 红线 | 为什么 |
| --- | --- |
| 改 `.env`、token、凭据 | 可能泄露或破坏环境 |
| 改部署配置 | 影响生产 |
| 大范围格式化 | 淹没真实改动 |
| 加无关依赖 | 增加维护和安全风险 |
| 删除测试 | 降低验证可信度 |

如果 diff 变大，让 agent 解释每个文件为什么必须改。

Diff 审查可以按三层走：

1. 文件层：是否只改授权路径。
2. 行为层：是否真的解决目标问题。
3. 维护层：是否引入不必要依赖、格式化或隐式副作用。

不要把 walkthrough 当成 diff 的替代品。Walkthrough 是索引，diff 才是事实。

## 5. UI 后：Screenshot 和 Recording

UI 任务至少交截图。涉及交互的任务要交浏览器录屏或可复查 walkthrough。

示例验收要求：

```text
请在 1440px desktop 和 390px mobile 两个 viewport 截图。
请录制从打开页面、点击保存、看到成功提示的完整流程。
```

截图看静态结果，录屏看交互路径。两者不是替代关系。

官方 Screenshots 文档说明，browser subagent 可以截取页面或元素，截图会保存为 image artifacts 并支持评论。官方 Browser Recordings 文档说明，浏览器动作录屏也会作为 artifact 保存，适合回看 agent 实际操作路径。

所以前端任务最低证据标准应该是：

| 任务类型 | 必须证据 |
| --- | --- |
| 静态样式 | desktop + mobile screenshot |
| 表单交互 | screenshot + walkthrough |
| 多步流程 | browser recording + console 结果 |
| 响应式问题 | 至少 390、768、1440 三档截图 |
| 线上风险任务 | 人工复核，不让 agent 自动提交 |

## 6. 完成后：Walkthrough

Walkthrough 应该包含：

1. 做了什么。
2. 改了哪些文件。
3. 怎么验证。
4. 验证结果。
5. 未覆盖风险。
6. 如何回退。

差的 walkthrough 只写“已完成”。好的 walkthrough 能让另一个人不看聊天记录也能接手验收。

官方 Walkthrough 文档说明，它通常在任务实现完成后生成，用简短 summary 帮用户回到代码库当前状态；如果是浏览器任务，walkthrough 里经常包含截图和录屏。你要把它当作验收索引，而不是最终验收本身。

## 7. 评论迭代

对 artifact 评论时，尽量绑定具体证据：

| 评论对象 | 好反馈 |
| --- | --- |
| Task List | “第 3 步先不要改 API，先复现 bug。” |
| Plan | “不要引入新依赖，用现有 form helper。” |
| Diff | “这个工具函数影响全站，改成页面内局部逻辑。” |
| Screenshot | “移动端按钮遮挡图标，只修 spacing。” |
| Recording | “录屏没有覆盖失败提示，请补异常路径。” |

## 8. 一套完整验收顺序

真实项目里，可以固定成这条流程：

```mermaid
flowchart TD
    Start["收到任务"] --> Task["看 Task List"]
    Task --> Plan["审 Implementation Plan"]
    Plan --> Proceed{"范围和验证可接受?"}
    Proceed -->|否| Comment["在 artifact 上评论要求重写"]
    Comment --> Plan
    Proceed -->|是| Diff["看 Code Diff"]
    Diff --> Evidence["看 Screenshot / Recording"]
    Evidence --> Walk["读 Walkthrough"]
    Walk --> Verify["跑测试 / 构建 / 手动路径"]
    Verify --> Accept{"证据一致?"}
    Accept -->|否| Comment
    Accept -->|是| Done["接受结果"]
```

这个顺序的好处是清晰：先批准方向，再审实现，再看用户路径，最后跑工程验证。任何一个环节证据不成立，都回到 artifact 评论，而不是让 agent 无边界重做。

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. Task List、Implementation Plan、Walkthrough 分别解决什么问题？
2. 为什么截图和录屏不能互相替代？
3. 点击 Proceed 前，至少要确认哪几类风险？

通过标准：你能拿到一次 Antigravity 交付后，按 artifacts 逐项判断它是否可以被接受。

## 官方来源

- [Google Antigravity Artifacts](https://antigravity.google/docs/artifacts) - 官方定义 artifact，并说明 artifacts 与 feedback 的关系。
- [Google Antigravity Task List](https://antigravity.google/docs/task-list) - 官方说明 task list 以 markdown list 跟踪复杂任务。
- [Google Antigravity Implementation Plan](https://antigravity.google/docs/implementation-plan) - 官方说明 plan review、Proceed、评论和重新审查流程。
- [Google Antigravity Screenshots](https://antigravity.google/docs/screenshots) - 官方说明截图作为 image artifact 保存并支持评论。
- [Google Antigravity Browser Recordings](https://antigravity.google/docs/browser-recordings) - 官方说明浏览器动作录屏和 recording artifact。
- [Google Antigravity Walkthrough](https://antigravity.google/docs/walkthrough) - 官方说明任务完成后的 walkthrough summary 和浏览器证据。

## 接下来去哪

<Cards>
  <Card title="Browser Subagent UI 测试" description="继续看如何让浏览器验证成为 UI 任务默认交付。" href="/docs/antigravity/understanding/06-browser-subagent-ui-testing" />
  <Card title="Browser 与 Artifacts 查询" description="查 Browser Subagent 和 Artifacts 的官方能力边界。" href="/docs/antigravity/official/03-browser-artifacts" />
</Cards>
