# Agent Branch (智能體分支)

*每次執行在寫時複製的分支裡工作，經審閱的合併才進入主線。*

> **Agent Branch（智能體分支）** 讓每次執行在寫時複製的分支裡工作；變更只有透過一次經審閱的合併（Agent PR）才能進入受保護的主線；隨時可以打檢查點並恢復。

**AN-02** · 符合性等級: L0 Files · 概念組: 工作

## 要解決的問題

智能體以機器的速度犯錯，而共享資料沒有「試一試、看差異、審閱、撤銷」的機制。並行的智能體還會互相踩踏。

2026 年 4 月的一次事故裡，一個智能體用一枚權限過寬的權杖，在 9 秒內刪除了生產卷和同卷的備份。如果它只能寫一個分支，如果刪除是軟刪除，如果快照不在它的權限之內，這件事會小得多。

## 工作方式

- **分支建立廉價**（取決於引擎，理想情況接近 O(1)）。租約只授予**分支內**的寫入，以及向目標的 `propose`。
- **受保護樹。** 主線只能經合併更新：即使憑據洩露，也不能直接寫。
- **Agent PR。** 差異、意圖、來源（讀清單摘要）、檢查結果與標籤摘要。檢查通過且策略允許時自動合併，否則交給 [Human Gate](https://agentnas.com/zh-tw/concepts/human-gate/)。
- **軟刪除。** 受保護樹中的刪除進入回收區，預設保留 7 天；快照由所有者持有，**不在任何租約的權限之內**。
- **檢查點。** 命名的快照；`restore` 把檔案回退到檢查點。
- **合併。** 文本用三方合併，其他檔案按檔案粒度。有衝突就停下，**絕不靜默覆蓋**；結構化資料需要註冊的合併器，或者交給人。
- **TTL 與配額，** 防止「分支炸彈」。
- **並行嘗試。** 同一個任務可以開 N 個分支，擇優合併，其餘回收。

## 從小處開始

- Git 分支加 worktree，再加上 Forgejo、Gitea 或 GitHub 的**受保護 main**。
- 大目錄用 btrfs 或 ZFS 的快照與複製；物件儲存可以用 Tigris 或 lakeFS 的分叉。
- 先把「刪除進回收區」和「快照歸所有者」做對。這兩條最便宜，也最能防住事故。

## 介面草圖

僅作示意。欄位名在規範 v0.3 之前可能調整。

*nas cli*

```bash
nas branch create cleo/release-notes --from main --ttl 48h
nas checkpoint create before-refactor
nas propose --into main --checks links,schema
nas restore before-refactor
nas trash list                    # recycle area, kept 7 days by default
nas trash restore <path>
```

## 規範的要求

- 受保護樹**必須**只能經合併更新，任何憑據都不能直接寫入。
- 合併**必須**產生帶來源（執行、租約、主體）的提交。
- 任何租約**不得**允許刪除快照或備份。
- 受保護樹中的刪除**必須**是軟刪除，並在配置的視窗內（預設 7 天）可恢復。
- 衝突**不得**被靜默解決；合併**必須**停止並報告。
- 分支**必須**有 TTL 與配額。

## 借鑑與區別

下面這些都是現成的做法。**真正新的部分：** 把分支綁定到**執行與租約**，讓分支成為授權的單位，合併成為審閱的單位。分支和快照本身並不新。

- [Git worktree](https://git-scm.com/docs/git-worktree)
- [lakeFS for agents](https://lakefs.io/agentic-ai/)
- [Tigris Agent Kit](https://www.tigrisdata.com/docs/ai/agent-kit/)
- [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/)

## 坦誠的侷限

- 分支只保護 NAS 裡的資料，**不會撤銷外部副作用**：已經發出的郵件、已經呼叫的介面。
- 大型二進位檔檔案和資料庫檔案很難合併。
- 審閱疲勞仍可能發生，所以低風險的路徑允許自動合併，並度量批准率。

## 開放問題

- 語義合併器如何註冊並被信任？
- 二進位檔衝突的互動應當怎麼做？

## 常見問題

### 這和 Git 分支有什麼不同？

機制上並不神奇：在 Git 上就能搭出來。不同的是它把分支與一次執行、一張租約綁在一起，讓「只能寫自己的分支」成為授權規則，而合併成為唯一的審閱點。

### 分支能防住所有事故嗎？

不能。它只保護 NAS 裡的資料：智能體已經發出的郵件、已經呼叫的外部介面，不會因為回滾分支而撤銷。這類動作應當經過租約裡的 `egress` 和 Human Gate。

### 每次合併都要人批准嗎？

不是。檢查通過、沒有讀過外部內容、不涉及刪除或共享的合併可以自動進行；需要人的只有少數情形，見 [Human Gate](https://agentnas.com/zh-tw/concepts/human-gate/)。

## 相關概念

- [Human Gate (人類閘門)](https://agentnas.com/zh-tw/concepts/human-gate/): 只在不可逆、對外或提權的動作之前出現，展示真實的差異。
- [Agent Home (智能體之家)](https://agentnas.com/zh-tw/concepts/agent-home/): 按角色劃分、帶歷史的目錄，全是普通檔案，可以帶走。
- [Flight Recorder (飛行記錄器)](https://agentnas.com/zh-tw/concepts/flight-recorder/): 以執行為單位、雜湊連結的記錄，包括這次執行讀過什麼。

---

標準網址: https://agentnas.com/zh-tw/concepts/agent-branch/
更新於: 2026-11-11 · 規範草案 v0.2 · CC BY 4.0