---
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="/zh-Hant/docs/antigravity/understanding/06-browser-subagent-ui-testing" />
  <Card title="Browser 與 Artifacts 查詢" description="查 Browser Subagent 和 Artifacts 的官方能力邊界。" href="/zh-Hant/docs/antigravity/official/03-browser-artifacts" />
</Cards>
