Agent NAS v0.2
简体中文

架构

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

v0.2 规范草案 更新于

四层与可选的同步

  1. Interface（接口）

    把能力投影成智能体、人和工具已经会用的接口。网关无状态，从不决定谁可以做什么。

    • 挂载（FUSE、NFS、SMB）
    • Git
    • S3 兼容
    • WebDAV
    • MCP
    • HTTP API
    • CLI
    • A2A（可选）
  2. Trust（信任）

    唯一的授权点。确定性的策略引擎，决策环节没有模型参与；先记录，后生效。

    • 主体与运行
    • Capability Lease
    • 策略引擎
    • Human Gate
    • Trust Labels
    • Credential Broker
    • Flight Recorder
  3. Memory（记忆）

    把笔记变成可检索、可预算读取的知识。全部可以从下一层重建。

    • 笔记约定
    • 索引（全文、向量、图）
    • Budgeted Reads
    • 维护作业
    • 血缘
    • Cascade Forget
  4. 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 不需要任何新发明。 新的是把它们组合起来的契约，以及验收它的测试，见规范。

运维

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

控制室

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

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

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

引用本页

为读者、搜索引擎和智能体提供稳定的网址与建议的引用格式。

建议引用格式
Agent NAS project. “架构.” agentnas.com, 2026-11-11. https://agentnas.com/zh-cn/architecture/