# 架构

> Agent NAS 分为四层加一个可选的同步层：Interface 把能力投影成已有的接口，Trust 是唯一的授权点，Memory 把笔记变成可检索的知识，Store 保存带历史的树。Memory 层可以整体删除再重建，Store 则直接使用成熟的存储。

## 四层与可选的同步

- **Interface（接口）**: 把能力投影成智能体、人和工具已经会用的接口。网关无状态，从不决定谁可以做什么。 (挂载（FUSE、NFS、SMB）, Git, S3 兼容, WebDAV, MCP, HTTP API, CLI, A2A（可选）)
- **Trust（信任）**: 唯一的授权点。确定性的策略引擎，决策环节没有模型参与；先记录，后生效。 (主体与运行, Capability Lease, 策略引擎, Human Gate, Trust Labels, Credential Broker, Flight Recorder)
- **Memory（记忆）**: 把笔记变成可检索、可预算读取的知识。全部可以从下一层重建。 (笔记约定, 索引（全文、向量、图）, Budgeted Reads, 维护作业, 血缘, Cascade Forget)
- **Store（存储）**: 带历史的树：用现成的文件系统快照、Git 或版本化对象存储。它不理解记忆与标签的语义。 (Tree, Commit, Agent Branch, 文件系统快照, Git, 对象存储)
- **Sync（同步，可选）**: 节点之间的复制与共享，放在最后：先把单节点做对。 (Git 远端, 快照传输, 租约链接, 交接包)

- **Memory 层可重建。** 删掉全部索引再重建，Store 里的笔记依然完整可读。
- **网关无状态。** 持久状态都在 Store 与 Trust 的记录里；网关可以随意重启，也可以水平扩展。
- **Trust 是唯一的授权点。** 包括 NAS 自己的后台作业（索引、维护）：它们也以 `svc:*` 主体的身份持租约运行。
- **Store 不理解记忆与标签的语义。** 它只保存带元数据的树。
- **先记录，后生效。** 有后果的操作必须先写入意图记录。

## 窄腰：六个名词

整套设计只依赖六个名词；标签、闸门、记忆和读清单都是建立在它们之上的约定。

| 名词 | 含义 | 关键不变量 |
| --- | --- | --- |
| Tree | 带历史的目录树。 | 任一提交可以重现；有内容哈希或等价的变更检测。 |
| Commit | 一次不可变的变更。 | 带来源元数据：`principal`、`on_behalf_of`、`run`、`lease`。 |
| Principal | 可被认证、可被追责的实体。 | 类型为 `human`、`agent`、`service`、`node`；`agent` 属于某个角色，而不是某一次运行。 |
| Run | 一次运行：有开始、结束、目的和责任人。 | 持有一张根租约；拥有一个分支。 |
| Lease | 运行的授权。 | 有到期时间；只能收窄；可撤销；含预算。 |
| Record | 只追加的记录。 | 哈希链接；先记录，后生效。 |

## Store 层：契约与可选引擎

Store 契约由引擎提供，或者由网关模拟。一个实现可以组合多种引擎，例如文本走 Git，大文件走快照；契约不规定引擎、哈希函数或磁盘格式。

1. 原子提交。
2. 廉价分叉：理想情况接近 O(1)；最差退化为复制，此时必须有配额与 TTL。
3. 不可变的快照。
4. 变更检测：内容哈希或等价的手段。
5. 两个提交之间的差异。
6. 完整导出，使用标准格式：目录、Git 历史和 `.nas/` 文本元数据。

| 引擎 | 适合 | 分叉成本 | 注意 |
| --- | --- | --- | --- |
| Git（含 worktree） | 文本、记忆、技能、小型代码库 | 低 | 大文件需要 LFS 或外置；二进制合并差。 |
| 文件系统快照与克隆（ZFS、btrfs、APFS） | 大目录、混合文件 | 近似 O(1) | 依赖文件系统；跨机器复制要用 send/receive。 |
| 版本化对象存储（Tigris 分叉、lakeFS、S3 加清单） | 数据集、大文件 | 近似 O(1) | 需要网关提供文件视图。 |
| 普通目录加复制 | Lite 的起步 | O(n) | 只适合小数据；必须有配额与 TTL。 |

> **恢复路径在爆炸半径之外.** 快照与备份由所有者主体持有，任何租约都不能包含“删除快照”或“删除备份”。这是 2026 年 4 月那次事故给出的最直接的教训：恢复路径必须在被保护对象的爆炸半径之外。

- 静态加密由底层提供；`sensitive` 保留类使用独立的密钥域，所以可以通过销毁密钥来粉碎。
- 去重与粉碎互相冲突：`sensitive` 类不跨密钥域去重。

## 一次运行的旅程

1. **申请。** 编排器（或所有者）为一次运行申请租约：路径、动作、期限、目的。在**策略包络**内自动发放；超出则交给 Human Gate。
2. **开工。** NAS 创建 `run` 与分支 `<role>/<run_id>`，把租约交给运行；沙箱挂载该分支（或 `git clone`）。
3. **工作。** 智能体用普通的文件工具读写。读取累积成**读清单**，会话污点随之更新；越权访问被拒绝并记录。
4. **提交。** 变更自动（防抖）或显式提交，每个提交都带来源元数据。
5. **提议。** `propose` 生成 **Agent PR**：差异、意图、读清单摘要、检查结果与标签摘要。
6. **裁决。** 策略引擎判断：检查通过且低风险就自动合并；涉及受保护数据、对外动作或违反 Rule of Two 就交给 Human Gate；明显违规就拒绝。
7. **合并与记录。** 合并产生一个带来源的提交，并写入 Record。
8. **收尾。** 租约到期；分支在 TTL 之后回收；读清单与 Record 按保留策略保留。

**读路径：** 请求、租约校验、标签检查（当前会话污点是否允许这次读取）、预算计数、读 Store、记入读清单、返回内容与证据指针。

> **先记录，后生效.** 有后果的操作（合并、删除、共享、出口、租约变更）必须先写入意图记录；写不进去，操作就失败（fail closed）。读操作进入读清单，批量落盘，不要求逐条同步。

## 部署形态

| 形态 | 说明 | 适合 |
| --- | --- | --- |
| Lite | 单机、单用户：一个网关进程加本地存储（Git 或文件系统快照）；L0 到 L1。 | 个人与开发者，先试用。 |
| Overlay | 不动现有的 NAS 或对象存储：在前面放一个网关，只管理其中的一个目录或桶；挂载与 S3 视图经网关出入。 | **最现实的起点：** 已经有一台盒子的人。 |
| Team | 多用户、多智能体，一台服务器或小集群；L0 到 L3；闸门通知与控制室。 | 小团队。 |
| Cloud | 托管的多租户服务，强隔离；L0 到 L3。 | 没有自有硬件的人。 |

原则：不要求专用硬件，任何常开的机器都可以；推理加速器是可选的，嵌入与摘要用小模型即可，也可以调用外部服务。

## 用现成零件搭一个 v0

| 能力 | 今天就能用的零件 |
| --- | --- |
| Store 与分支 | Git 与 worktree；btrfs 或 ZFS 的快照；或者 Tigris、lakeFS（对象存储）。 |
| 受保护的主线 | Forgejo、Gitea、GitHub 的分支保护；或者 lakeFS 的受保护分支。 |
| 租约 | OAuth 授权服务器（例如 Keycloak）加令牌交换，资源服务器按路径前缀与动作校验；或者一个几百行的签发服务。 |
| 记录 | 追加写的 SQLite 表加每日哈希；提交里的 Git trailer；OpenTelemetry 导出。 |
| 闸门 | PR 审阅加一条推送通知；CLI 的 `nas gate approve`。 |
| 记忆 | `memory/` 下的 Markdown 加 SQLite FTS5；向量库以后再加。 |
| 标签 | 导入目录自动标记为 `external`；运行级的会话污点放在网关里。 |
| 接口 | NFS、SMB 或 FUSE 挂载；Git over SSH 或 HTTPS；S3 网关；一个小型 MCP 服务器。 |

这张表想说的是：**L0 与 L1 不需要任何新发明。** 新的是把它们组合起来的契约，以及验收它的测试，见[规范](https://agentnas.com/zh-cn/spec/)。

## 运维

- **备份：** 3-2-1；快照与备份属于所有者主体，任何租约都不能触及；每季度做一次恢复演练并留下记录。
- **升级：** 网关无状态，可以滚动升级；Store 格式变更必须附带迁移与回滚方案；Memory 层可以整体重建。
- **监控：** 租约发放与拒绝率；闸门队列长度与批准率（批准率长期高于 95%，说明闸门太频繁，该合并或收紧策略）；分支数量与年龄；索引新鲜度；记录链校验；配额。
- **容量：** 分支有 TTL 与配额；回收区有保留期；派生数据有预算。

## 控制室

给人使用的界面，可以是网页、CLI 或聊天机器人。它不是必需品：L0 到 L1 完全可以只用 CLI 和现有的 Git 平台。

- **活动时间线：** 按运行聚合，谁做了什么、读了什么。
- **闸门收件箱：** 待批准的动作，显示 Gate Card。
- **角色目录：** 每个角色的 Home、租约、预算与近期运行。
- **记忆浏览器：** 笔记与来源、未审阅的隔离区、维护提案。
- **分支与 PR：** 未合并的分支、回收区。
- **遗忘控制台：** 请求、血缘预览、报告。

人也可以直接用 SMB 或 WebDAV 查看：`/humans/<user>/Agent Activity/` 是一个只读的活动视图，里面都是普通文件。

---

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