05 · 用 Artifacts 建立验收工作流

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 说完成了”，而是“证据能不能支撑完成”。

1. Artifact 不是日志

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

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

2. 任务开始前：Task List

Task List 要回答：

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

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

更好的 Task List 应该像这样：

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

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

3. 动手前：Implementation Plan

Implementation Plan 要审：

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

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

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

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

4. 生成后：Code Diff

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

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

Diff 审查可以按三层走：

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

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

5. UI 后：Screenshot 和 Recording

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

示例验收要求：

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

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

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

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

6. 完成后：Walkthrough

Walkthrough 应该包含：

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

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

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

7. 评论迭代

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

8. 一套完整验收顺序

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

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 - 官方定义 artifact，并说明 artifacts 与 feedback 的关系。
• Google Antigravity Task List - 官方说明 task list 以 markdown list 跟踪复杂任务。
• Google Antigravity Implementation Plan - 官方说明 plan review、Proceed、评论和重新审查流程。
• Google Antigravity Screenshots - 官方说明截图作为 image artifact 保存并支持评论。
• Google Antigravity Browser Recordings - 官方说明浏览器动作录屏和 recording artifact。
• Google Antigravity Walkthrough - 官方说明任务完成后的 walkthrough summary 和浏览器证据。

接下来去哪