# Agent Branch (智能体分支)

*每次运行在写时复制的分支里工作，经审阅的合并才进入主线。*

> **Agent Branch（智能体分支）** 让每次运行在写时复制的分支里工作；变更只有通过一次经审阅的合并（Agent PR）才能进入受保护的主线；随时可以打检查点并恢复。

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

## 要解决的问题

智能体以机器的速度犯错，而共享数据没有“试一试、看差异、审阅、撤销”的机制。并行的智能体还会互相踩踏。

2026 年 4 月的一次事故里，一个智能体用一枚权限过宽的令牌，在 9 秒内删除了生产卷和同卷的备份。如果它只能写一个分支，如果删除是软删除，如果快照不在它的权限之内，这件事会小得多。

## 工作方式

- **分支创建廉价**（取决于引擎，理想情况接近 O(1)）。租约只授予**分支内**的写入，以及向目标的 `propose`。
- **受保护树。** 主线只能经合并更新：即使凭据泄露，也不能直接写。
- **Agent PR。** 差异、意图、来源（读清单摘要）、检查结果与标签摘要。检查通过且策略允许时自动合并，否则交给 [Human Gate](https://agentnas.com/zh-cn/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-cn/concepts/human-gate/)。

## 相关概念

- [Human Gate (人类闸门)](https://agentnas.com/zh-cn/concepts/human-gate/): 只在不可逆、对外或提权的动作之前出现，展示真实的差异。
- [Agent Home (智能体之家)](https://agentnas.com/zh-cn/concepts/agent-home/): 按角色划分、带历史的目录，全是普通文件，可以带走。
- [Flight Recorder (飞行记录仪)](https://agentnas.com/zh-cn/concepts/flight-recorder/): 以运行为单位、哈希链接的记录，包括这次运行读过什么。

---

规范网址: https://agentnas.com/zh-cn/concepts/agent-branch/
更新于: 2026-11-11 · 规范草案 v0.2 · CC BY 4.0