# Agent NAS: 完整文档

> Agent NAS 是围绕“一次运行”设计的网络附加存储：智能体的每次运行都在隔离的分支里工作，凭一张短时、窄域的租约访问数据；每个改动都能追溯、能撤销；记忆是带来源的普通文件。对外，它说智能体早已会说的话：文件、Git、S3 和 MCP。

状态：概念与规范草案 v0.2，2026 年 11 月。尚无参考实现。 内容采用 CC BY 4.0 许可。

---

# Agent NAS：为 AI 智能体而生的网络附加存储

> Agent NAS 是围绕“一次运行”设计的网络附加存储：智能体的每次运行都在隔离的分支里工作，凭一张短时、窄域的租约访问数据；每个改动都能追溯、能撤销；记忆是带来源的普通文件。对外，它说智能体早已会说的话：文件、Git、S3 和 MCP。

**智能体在这里工作，你始终掌控。** 一台把“运行”当作基本单位的 NAS：每次运行有自己的分支和租约，每个改动可追溯、可撤销，记忆是你能读、能改、能带走的笔记。

## 一览

- **类别**: 为 AI 智能体而生的网络附加存储，也称智能体原生存储（agent-native storage）。
- **核心理念**: 访问的单位是**运行**，不是账号：运行在分支上工作，凭租约访问，留下记录。
- **四个承诺**: 有界、可恢复、可追责、可检视。
- **核心名词**: Tree、Commit、Principal、Run、Lease 和 Record。
- **概念**: 九个命名概念，分为三簇：工作、权限与知识。
- **接口**: 数据面：挂载、Git、S3、WebDAV；控制面：MCP、HTTP、CLI。
- **规范**: 草案 v0.2，符合性等级从 L0 Files 到 L4 Sync，每一级都有可执行的验收测试。
- **状态**: 概念与规范阶段，尚无参考实现。L0 与 L1 可以用现成零件今天搭出来。
- **许可**: 内容采用 CC BY 4.0。

## 为什么是现在

过去一年里，四件事已经发生。

- **智能体在文件里工作。** [AGENTS.md](https://agents.md)、[Agent Skills](https://agentskills.io/specification)、以 Git 为后端的记忆（[Letta Context Repositories](https://www.letta.com/blog/context-repositories/)），以及把长输出写成文件的[动态上下文发现](https://cursor.com/blog/dynamic-context-discovery)，让文件成了智能体的工作介质。
- **错误来得又快又贵。** 2026 年 4 月，一个编码智能体用在无关文件里翻到的、权限过宽的令牌，[9 秒内删掉了一家公司的生产数据库和同卷备份](https://www.theregister.com/software/2026/04/27/cursor-opus-agent-snuffs-out-startups-production-database/5224442)。
- **人审不了每一步。** Anthropic 披露，用户批准了 [93% 到 97% 的权限提示](https://claude.com/resources/articles/auto-mode-default-in-claude-code)；在它的受控实验里，人只拦住了 13.6% 被植入的危险命令。
- **记忆成了攻击面。** 2026 年的[多项研究](https://arxiv.org/abs/2606.04329)表明，恶意指令一旦写进持久记忆就能跨会话存活，只在输入或检索处设防，效果有限。

存储厂商也动了：[QNAP QuAgent](https://www.qnap.com/en/software/quagent)、[Synology DSM Agent](https://www.synology.com/en-us/beta/2026_DSM_Agent_1_0_Beta/release_note) 和 [TrueNAS MCP](https://truenas.github.io/truenas-research-labs/) 都让智能体来管理这台盒子。可是别的智能体怎样在盒子里的数据上安全地工作，据我们所见还没有一份自托管、开放、可验收的契约。参见 [Agent NAS 与现有做法的比较](https://agentnas.com/zh-cn/compare/)。

## 四个承诺

| 承诺 | 含义 | 由哪些概念兑现 |
| --- | --- | --- |
| 有界 | 一次运行只能碰租约点名的数据，到点即失效；读过不可信内容的会话，不能同时再拥有敏感数据与对外通道。 | [Capability Lease](https://agentnas.com/zh-cn/concepts/capability-lease/)、[Trust Labels](https://agentnas.com/zh-cn/concepts/trust-labels/) |
| 可恢复 | 写入先落在分支；受保护的数据只能经审阅的合并更新；删除是软删除；快照不在任何租约的权限之内。 | [Agent Branch](https://agentnas.com/zh-cn/concepts/agent-branch/)、[Human Gate](https://agentnas.com/zh-cn/concepts/human-gate/) |
| 可追责 | 每个改动都能回答：谁做的、代表谁、凭哪张租约、读过什么。 | [Flight Recorder](https://agentnas.com/zh-cn/concepts/flight-recorder/) |
| 可检视 | 记忆是带来源的普通笔记，索引随时可以丢弃重建；全部数据都可以导出带走。 | [Agent Home](https://agentnas.com/zh-cn/concepts/agent-home/)、[Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/)、[Budgeted Reads](https://agentnas.com/zh-cn/concepts/budgeted-reads/)、[Cascade Forget](https://agentnas.com/zh-cn/concepts/cascade-forget/) |

## 九个概念，三个问题

Agent NAS 提出九个命名概念。每个概念都有独立页面：一句可以直接引用的定义、一套机制、一条“从小处开始”的路径、一份接口草图、规范对它提出的要求，以及它坦诚的局限。

### 工作

工作在哪里进行，发生了什么？

- AN-01 [Agent Home (智能体之家)](https://agentnas.com/zh-cn/concepts/agent-home/): 按角色划分、带历史的目录，全是普通文件，可以带走。
- AN-02 [Agent Branch (智能体分支)](https://agentnas.com/zh-cn/concepts/agent-branch/): 每次运行在写时复制的分支里工作，经审阅的合并才进入主线。
- AN-03 [Flight Recorder (飞行记录仪)](https://agentnas.com/zh-cn/concepts/flight-recorder/): 以运行为单位、哈希链接的记录，包括这次运行读过什么。

### 权限

谁可以做什么，凭谁的许可？

- AN-04 [Capability Lease (能力租约)](https://agentnas.com/zh-cn/concepts/capability-lease/): 发给一次运行的、有期限与预算的窄域授权；子租约只能更窄。
- AN-05 [Human Gate (人类闸门)](https://agentnas.com/zh-cn/concepts/human-gate/): 只在不可逆、对外或提权的动作之前出现，展示真实的差异。
- AN-06 [Trust Labels (信任标签)](https://agentnas.com/zh-cn/concepts/trust-labels/): 来源与敏感度两个小标签，加上会话污点，强制执行 Rule of Two。

### 知识

智能体知道什么，怎样读，怎样忘？

- AN-07 [Agent Memory (智能体记忆)](https://agentnas.com/zh-cn/concepts/agent-memory/): 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
- AN-08 [Budgeted Reads (预算化读取)](https://agentnas.com/zh-cn/concepts/budgeted-reads/): 同一个文件可以用轮廓、章节、行范围或全文来读，按预算降级。
- AN-09 [Cascade Forget (级联遗忘)](https://agentnas.com/zh-cn/concepts/cascade-forget/): 沿血缘删除派生物，按保留类处理历史，并如实报告做不到的部分。

## 四层，六个名词

Store 层直接使用成熟的存储。其余各层都可以从它重建，核心只有六个名词：Tree、Commit、Principal、Run、Lease 和 Record。我们不发明存储引擎，创新放在契约上。

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

[阅读架构](https://agentnas.com/zh-cn/architecture/)。

## 一次运行的旅程

1. **申请租约。** 研究智能体 Cleo 的编排器为这次运行申请一张 [Capability Lease（能力租约）](https://agentnas.com/zh-cn/concepts/capability-lease/)：读取 `/shared/launch`、提议修改、有效四小时。所有者预先设定的策略包络自动批准了这次申请。
2. **开工。** NAS 创建这次运行和它的分支 `cleo/run_91ab`；沙箱把分支当作普通目录挂载。Cleo 从自己的 [Agent Home（智能体之家）](https://agentnas.com/zh-cn/concepts/agent-home/)读到 `AGENTS.md` 和已审阅的记忆。
3. **在预算内阅读。** 它用 [Budgeted Reads（预算化读取）](https://agentnas.com/zh-cn/concepts/budgeted-reads/)读一份长报告：先看 400 token 的轮廓，再按需读具体的行范围。每次读取都记进这次运行的读清单。
4. **在分支上工作。** 修改落在 [Agent Branch（智能体分支）](https://agentnas.com/zh-cn/concepts/agent-branch/)上。共享的 `main` 此刻没有任何变化。
5. **遇到闸门。** Cleo 读过一个网页，所以 [Trust Labels（信任标签）](https://agentnas.com/zh-cn/concepts/trust-labels/)让它的会话带上 `external` 污点。向 `main` 提议合并时，策略要求经过 [Human Gate（人类闸门）](https://agentnas.com/zh-cn/concepts/human-gate/)：所有者在手机上看到由 NAS 计算的真实差异和不可信的来源，然后批准。
6. **留下记录。** 合并产生一个带来源的提交。读过什么、写过什么、谁批准了什么，都写进 [Flight Recorder（飞行记录仪）](https://agentnas.com/zh-cn/concepts/flight-recorder/)，以哈希串联。
7. **沉淀记忆。** Cleo 顺手记下几条新事实。因为这次会话读过外部内容，这些 [Agent Memory（智能体记忆）](https://agentnas.com/zh-cn/concepts/agent-memory/)笔记先进入隔离区：可以被召回，但在人审阅之前不会自动加载。
8. **遗忘。** 几周后，一位客户要求被遗忘。[Cascade Forget（级联遗忘）](https://agentnas.com/zh-cn/concepts/cascade-forget/)沿血缘删除相关的摘要与索引，并出具一份写明覆盖不到范围的报告。

## 它说智能体早已会说的语言

起步不需要新的 SDK。只要智能体能读写文件、用 Git 或 S3，或者调用 MCP 工具，就能使用 Agent NAS。下面这段会话只是对计划中命令行的示意。

*示意会话*

```bash
$ nas lease create --role cleo --paths "/shared/launch/**" --actions read,write,propose --ttl 4h
lease lse_7Qk3 · run run_91ab · branch cleo/run_91ab · expires 16:00
$ nas mount --lease lse_7Qk3 ~/work       # plain files, on a branch
$ ./draft-release-notes.sh                # the agent works with ordinary tools
$ nas propose --into main
gate gt_2Mx4 waiting for approval: merge cleo/run_91ab into main (4 files)
$ nas gate approve gt_2Mx4                # the owner, from another terminal or a phone
merged · commit 91ce3a7 · record 18211
```

[查看全部接口](https://agentnas.com/zh-cn/interfaces/)。

## 我们押注什么

一份希望几年后仍然成立的设计，应当说明自己押注了什么，以及押错时会怎样。

- **智能体会继续把文件系统和 Git 当作主要的工作介质。** 如果不是，Agent Home 退化为一种导出格式，其余概念仍然成立。
- **“一次运行”仍是自然的授权与追责单位。** 如果出现长期常驻的自治进程，租约就改为滚动续期加预算。
- **提示词注入在可预见的将来不会在模型层被根除。** 如果被根除了，Trust Labels 就成为纵深防御里便宜的一层。
- **人的注意力仍然稀缺。** 如果全自动足够可靠，Human Gate 由策略预授权取代，审计仍然保留。

全部七个赌注见[设计原则](https://agentnas.com/zh-cn/principles/)。

## 本站同样可以被智能体读取

每个页面都有 Markdown 孪生版本，本站发布 `llms.txt`，并运行一个小型的只读 MCP 服务器。在终端里试试：

*终端*

```bash
curl -H "Accept: text/markdown" https://agentnas.com/what-is-agent-nas/
curl https://agentnas.com/llms.txt
curl -X POST https://agentnas.com/api/search \
  -H "content-type: application/json" \
  -d '{"query": "capability lease", "limit": 5}'
```

把文档服务器加入 MCP 客户端：

*mcp.json*

```json
{
  "mcpServers": {
    "agentnas-docs": { "url": "https://agentnas.com/mcp" }
  }
}
```

## 人们最先会问的问题

### 用一句话说，Agent NAS 是什么？

围绕“一次运行”设计的网络附加存储：智能体的每次运行都在隔离的分支里工作，凭一张短时、窄域的租约访问数据；每个改动都能追溯、能撤销；记忆是带来源的普通文件。

### 有可以下载的软件吗？

还没有。Agent NAS 目前是一个概念和一份规范草案（v0.2）。L0 与 L1 可以用 Git、文件系统快照和一个小网关今天搭出来；参考实现 v0 的目标是 2027 年上半年，见[路线图](https://agentnas.com/zh-cn/roadmap/)。

### 它和 NAS 厂商推出的 AI 智能体有什么不同？

那些智能体用来管理这台盒子。Agent NAS 规定的是别的智能体怎样在盒子里的数据上工作：分支、租约、记忆与遗忘。两者互补，厂商的盒子可以成为 Overlay 形态的底座。

### 它会取代我现有的存储吗？

不会。Overlay 部署形态架在现有的 NAS、对象存储或 Git 托管之前，只管理其中的一个目录或桶。

### 它能防住提示词注入吗？

不能。它限制注入之后的后果，并让后果可见、可撤销。坦诚的局限见[安全](https://agentnas.com/zh-cn/security/)。

### 我可以随时离开吗？

随时可以。所有内容都能导出为普通文件和 Git 历史。这是设计上的保证，而不是可选功能。

[全部问答](https://agentnas.com/zh-cn/faq/)。

## 目前进展

> **状态.** Agent NAS 处于概念与规范草案阶段（v0.2，2026 年 11 月）。v0.2 是一次落地修订：十三个概念收敛为九个，每个概念都写明了“从小处开始”和“坦诚的局限”。目前还没有参考实现。

- [规范草案](https://agentnas.com/zh-cn/spec/): 符合性等级与可执行的验收测试。
- [路线图](https://agentnas.com/zh-cn/roadmap/): 现在、下一步、以后，以及不做什么。
- [关于本项目](https://agentnas.com/zh-cn/about/): 许可、如何引用，以及如何参与。

---

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

---

# 什么是 Agent NAS？

> Agent NAS 是围绕“一次运行”设计的网络附加存储：智能体的每次运行都在隔离的分支里工作，凭一张短时、窄域的租约访问数据；每个改动都能追溯、能撤销；记忆是带来源的普通文件。对外，它说智能体早已会说的话：文件、Git、S3 和 MCP。

## 一段话说清

Agent NAS 存放智能体长期工作所需的一切：指令、技能、记忆、进行中的工作和历史。它回答传统 NAS 不关心的几个问题：这次运行能碰什么，改错了能不能撤销，谁批准了什么，记忆来自哪里。它不是新的存储引擎，而是搭在成熟存储（文件系统、Git、对象存储）之上的一份**契约**：规定智能体与数据之间的权限、隔离、追溯与记忆应当如何运作，以及怎样验收。

## 拆开读这个名字

- **Agent（智能体）**: 代表某人行事的 AI 系统：它在多个步骤里阅读、决策并使用工具。在 Agent NAS 里，智能体属于一个**角色**，每一次工作则是一次**运行**。
- **Network-attached（网络附加）**: 通过网络被许多客户端同时访问，无论是家庭局域网、团队服务器还是云区域。不绑定某一个沙箱或某一台机器。
- **Storage（存储）**: 持久、带历史、可导出。存储是真相的来源，一切“智能”的东西都由它派生，并且可以丢弃重建。

## 怎样才算 Agent NAS

1. **访问的单位是运行。** 每次运行拥有自己的[租约](https://agentnas.com/zh-cn/concepts/capability-lease/)，而不是共享密钥或人类账号。
2. **默认隔离、可撤销。** 写入先落在[分支](https://agentnas.com/zh-cn/concepts/agent-branch/)；受保护的数据只经合并更新；删除是软删除。
3. **每个改动可追溯。** 谁做的、代表谁、凭哪张租约、读过什么（[Flight Recorder](https://agentnas.com/zh-cn/concepts/flight-recorder/)）。
4. **记忆是带来源的文件，索引可丢弃**（[Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/)）。
5. **通过已有的接口服务：** 挂载、Git、S3、MCP，而不是一套新协议。
6. **去掉 AI 层后，它仍是一台合格的通用 NAS，** 全部数据可以完整导出。

## 它不是什么

- **不是新的存储引擎、文件系统或向量数据库。** 它们都以现成零件的形式被使用。
- **不是沙箱。** 它不隔离计算，只约束智能体与数据之间的关系；应当与沙箱一起使用。
- **不是提示词注入的解药。** 它限制后果，不阻止注入发生。参见[安全](https://agentnas.com/zh-cn/security/)。
- **不是智能体框架。** 它不规定智能体怎样推理、规划或调用模型。

## 适合谁，谁不需要它

- **已经在用 `AGENTS.md` 加 Git 的开发者：** 想要受保护的主线、可撤销的运行，以及一份可追溯的记录。
- **运行多个智能体的团队：** 需要共享的树、对智能体改动的审阅，以及“它到底读过什么”的答案。
- **拥有个人智能体的个人：** 希望这份记忆留在自己手里，可以读、可以改、可以带走。
- **处理客户数据的组织：** 需要把保留与遗忘当作写入时的显式选择，并拿到一份诚实的遗忘报告。

> **谁不需要它.** 如果你只有一个智能体、一份可以随意重来的数据，**不需要** Agent NAS：一个 Git 仓库加 `AGENTS.md` 就够了。当数据开始值钱、智能体开始变多、你开始想知道“它到底读过什么、改过什么”时，才是它的位置。更多情形见[用例](https://agentnas.com/zh-cn/use-cases/)。

## Agent NAS 与厂商的管理智能体

| 问题 | NAS 厂商的管理智能体 | Agent NAS |
| --- | --- | --- |
| 智能体做什么？ | 用自然语言管理这台 NAS，把对话变成操作。 | 在盒子里的数据上工作：读、写、记忆，并留下记录。 |
| 如何授予访问权？ | 沿用用户的权限，危险操作二次确认。 | 绑定一次运行的短时租约：路径、动作、期限、预算。 |
| 出错怎么办？ | 依靠确认和日志。 | 写入先落在分支；删除是软删除；快照不在任何租约之内。 |
| 记忆放在哪里？ | 助手或厂商的服务端。 | 作为带来源的笔记放在智能体的 Home 里，索引可以丢弃。 |
| 不可信的内容？ | 像其他文本一样进入模型。 | 带 `external` 标签；读过之后，有后果的动作要过闸门。 |
| 想离开怎么办？ | 取决于厂商。 | 一切都能导出为普通文件和 Git 历史。 |

## 接下来读什么

- [九个概念](https://agentnas.com/zh-cn/concepts/): 每个概念各有一页，写明从小处怎么开始。
- [架构](https://agentnas.com/zh-cn/architecture/): 四层、六个名词与一次运行的旅程。
- [安全](https://agentnas.com/zh-cn/security/): 威胁模型、控制措施与坦诚的局限。
- [常见问题](https://agentnas.com/zh-cn/faq/): 常见问题的简短回答。

---

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

---

# 九个概念

> Agent NAS 建立在九个命名概念之上。它们回答三个问题：工作在哪里进行、发生了什么；谁可以做什么、凭谁的许可；智能体知道什么、怎样读、怎样忘。

概念名称是自造术语，在所有语言中都保持英文，并在中文版里附上释义。每个页面开头都是一句可以单独引用的定义，随后依次说明要解决的问题、机制、从小处开始的做法、接口草图、规范的要求，以及借鉴与区别和坦诚的局限。符合性等级表示实现方应当在何时支持该概念；参见[规范](https://agentnas.com/zh-cn/spec/)。

> **关于“新”.** 九个概念里，多数是把成熟的零件组合起来。每个概念页都写明了借鉴了什么，以及真正新的部分是什么。汇总的清单见[比较](https://agentnas.com/zh-cn/compare/)。

## 三个概念簇

### 工作

工作在哪里进行，发生了什么？

- AN-01 [Agent Home (智能体之家)](https://agentnas.com/zh-cn/concepts/agent-home/): 按角色划分、带历史的目录，全是普通文件，可以带走。
- AN-02 [Agent Branch (智能体分支)](https://agentnas.com/zh-cn/concepts/agent-branch/): 每次运行在写时复制的分支里工作，经审阅的合并才进入主线。
- AN-03 [Flight Recorder (飞行记录仪)](https://agentnas.com/zh-cn/concepts/flight-recorder/): 以运行为单位、哈希链接的记录，包括这次运行读过什么。

### 权限

谁可以做什么，凭谁的许可？

- AN-04 [Capability Lease (能力租约)](https://agentnas.com/zh-cn/concepts/capability-lease/): 发给一次运行的、有期限与预算的窄域授权；子租约只能更窄。
- AN-05 [Human Gate (人类闸门)](https://agentnas.com/zh-cn/concepts/human-gate/): 只在不可逆、对外或提权的动作之前出现，展示真实的差异。
- AN-06 [Trust Labels (信任标签)](https://agentnas.com/zh-cn/concepts/trust-labels/): 来源与敏感度两个小标签，加上会话污点，强制执行 Rule of Two。

### 知识

智能体知道什么，怎样读，怎样忘？

- AN-07 [Agent Memory (智能体记忆)](https://agentnas.com/zh-cn/concepts/agent-memory/): 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
- AN-08 [Budgeted Reads (预算化读取)](https://agentnas.com/zh-cn/concepts/budgeted-reads/): 同一个文件可以用轮廓、章节、行范围或全文来读，按预算降级。
- AN-09 [Cascade Forget (级联遗忘)](https://agentnas.com/zh-cn/concepts/cascade-forget/): 沿血缘删除派生物，按保留类处理历史，并如实报告做不到的部分。

---

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

---

# 架构

> 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

---

# 接口

> Agent NAS 的数据面用文件，控制面用工具：字节走挂载、Git 和 S3；授权、审批、记忆、搜索与解释走 MCP、HTTP 和 CLI。每个接口都是同一份数据的投影，语义差异用明确的错误表达，而不是假装不存在。

## 准则

1. **数据面用文件，控制面用工具。** 字节走挂载、Git、S3；授权、审批、记忆、搜索与解释走 MCP、HTTP 与 CLI。
2. **网关无状态。** 授权只发生在 Trust 层的一个点上。
3. **每个接口都是投影。** 语义差异用明确的错误映射表达（例如“闸门待处理”映射成一个带说明文件的 `EACCES`），不假装 S3 有分支。
4. **窄工具面。** 面向智能体的 MCP 工具不超过 10 个；人与运营者的动作放在单独的操作员接口里。
5. **适配器隔离协议变化。** MCP、A2A 的版本演进只影响适配器。

## 接口矩阵

| 接口 | 面 | 面向 | 映射 | 等级 |
| --- | --- | --- | --- | --- |
| 挂载（FUSE、NFS、SMB） | 数据 | 智能体、人、任何程序 | 分支视图；错误映射见下文 | L0 |
| Git（SSH、HTTPS） | 数据 | 智能体、人、CI | 运行分支即 Git 分支；Agent PR 即合并请求 | L0 |
| S3 兼容 | 数据 | 数据管线、批处理 | 桶对应某棵树的某个分支视图；版本 ID 即提交 | L0（可选） |
| WebDAV | 数据 | 人（Finder、资源管理器） | 只读的活动视图 | L0（可选） |
| CLI `nas` | 控制 | 人、脚本 | 与 HTTP API 一一对应 | L0 |
| HTTP API | 控制 | 编排器、控制室 | 全部 `POST` 加 JSON；字段使用 `snake_case` | L1 |
| MCP | 控制 | 智能体 | 九个工具（见下文） | L1、L2 |
| A2A | 控制 | 其他智能体 | 任务对应 `inbox/` 与 `outbox/` | L4（可选） |

## MCP 工具面

面向智能体的只有九个工具：

| 工具 | 作用 | 所需的租约动作 | 备注 |
| --- | --- | --- | --- |
| `nas_list` | 列目录，含标签与审阅状态 | `list` | 租约之外的路径不可见。 |
| `nas_read` | 预算化读取：视图、范围、预算 | `read` | [Budgeted Reads](https://agentnas.com/zh-cn/concepts/budgeted-reads/) |
| `nas_search` | 搜索（全文，可选向量），返回片段与指针 | `read` | 默认不返回隔离区。 |
| `nas_write` | 写入分支内的文件，可附 `intent` | `write` | 多数运行时直接用挂载，不需要它。 |
| `nas_branch` | 创建、检查点、恢复、列出分支 | `write` | [Agent Branch](https://agentnas.com/zh-cn/concepts/agent-branch/) |
| `nas_propose` | 生成 Agent PR | `propose` | 可能触发闸门。 |
| `nas_lease` | 申请更窄的子租约；查询当前租约与预算；请求扩权（走闸门） | 无 | [Capability Lease](https://agentnas.com/zh-cn/concepts/capability-lease/) |
| `nas_remember` | 写入笔记，含来源与类型 | `write` | [Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/) |
| `nas_recall` | 召回笔记：预算化，含来源与审阅状态 | `read` | [Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/) |

> **只面向人与运营者的操作.** `explain`、`gate approve/deny`、`forget`、`trash restore`、`label admin`、`lease revoke` 和 `policy edit` **不暴露**给智能体。这些动作改变的是保证本身，不应该由被约束者来调用。智能体可以**请求**其中一部分（扩权、遗忘），但不能执行。

## 挂载语义

- 挂载绑定**一个分支和一张租约**；租约到期后挂载变为只读，随后卸载。
- 自动提交（防抖，例如静默 5 秒）；`fsync` 会触发一次提交。
- 租约之外的路径**不出现在目录列表里**：这减少信息泄露，也缩小了提示注入的攻击面。
- 对沙箱友好：不需要 root；FUSE 与 NFS 二选一，不需要内核模块；可以只读挂载。

| 情况 | POSIX 错误 | 说明 |
| --- | --- | --- |
| 租约之外的路径 | `ENOENT`（可见但被拒时为 `EACCES`） | 拒绝被记录。 |
| 配额或预算用尽 | `EDQUOT` | 运行可以据此自我节制。 |
| 闸门待处理 | `EACCES`，并在 `/.nas/pending` 给出说明 | 避免智能体无限重试。 |
| 租约过期 | `ESTALE`，随后只读 | 分支保留到它自己的 TTL 到期。 |

## Git

- 运行分支名为 `<role>/<run_id>`；`main` 是受保护的，服务器端的 `pre-receive` 钩子会拒绝直接推送。
- `nas propose` 创建 Agent PR。
- 提交自动附带 `Run:`、`Lease:`、`Principal:` 等 trailer。

## S3

- 一个桶对应一棵树的某个分支视图；对象版本 ID 即提交。
- 分支这类 S3 没有的语义，用桶前缀或请求头（`x-nas-branch`）表达。这是一种**降级的投影**：数据管线能读写，但拿不到完整的分支体验。
- 租约通过 STS 风格的临时凭据传递。

## A2A（可选）

- 收到的任务落在 `inbox/` 里的任务文件；产物放进 `outbox/`。
- Agent Card 声明角色的技能与所需的租约。
- **NAS 不是 A2A 的参与者，** 代表角色的运行时才是。NAS 只负责任务与产物的存放、交接包与租约。

## HTTP API 约定

- **全部接口使用 `POST`，参数放在 JSON 请求体里；** 响应字段一律 `snake_case`。
- 路径带版本：`/v1/...`。
- 幂等：写操作接受 `idempotency_key`。
- 分页：`cursor` 加 `limit`。
- 预算与限流通过响应头反馈（剩余字节、剩余请求数），便于运行时自我节制。

预算化读取的请求与响应大致如下：

*预算化读取*

```http
POST /v1/files/read
{ "path": "/agents/cleo/memory/notes/customer-acme.md",
  "view": "outline", "budget_tokens": 400 }

200 OK
{ "view": "outline", "tokens": 212, "generated": false, "truncated": false,
  "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)",
  "evidence": [
    { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" }
  ] }
```

错误使用统一的结构：

*错误响应*

```json
{
  "error": {
    "code": "gate_required",
    "message": "This merge requires human approval.",
    "retryable": false,
    "request_id": "req_01JB7W2X4N",
    "details": { "gate_id": "gt_2Mx4" }
  }
}
```

## 发现

- 机器可读的入口与本站相同：`/.well-known/ai-catalog.json`、MCP Server Card、`llms.txt`。
- `nas://` 证据指针的解析与校验端点。
- MCP 的 `server/discover`。

---

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

---

# 安全

> Agent NAS 不阻止提示词注入，它限制注入之后的后果：用窄域租约限定一次运行能碰什么，用分支让错误可撤销，用 Rule of Two 阻止读过不可信内容的会话再同时拥有敏感数据与对外通道，并留下可追溯的记录。

## 范围与信任假设

- **我们保护：** NAS 里的数据与历史；授权的边界；记录的完整性；记忆的可追溯性。
- **我们不保护：** 智能体在 NAS 之外的行为；运行计算本身的隔离（那是沙箱的工作）；模型提供商那一侧发生的事。
- **信任假设：** 可信计算基（TCB）是 NAS 网关、策略引擎与记录服务；主机没有被攻陷；沙箱负责隔离计算。TCB 被攻陷，本页的保证就失效。

## Rule of Two：会话不变量

三个性质：**[A]** 会话读过不可信内容，**[B]** 租约允许读敏感数据，**[C]** 租约允许改变受保护的状态或对外通信。同一会话里三者同时成立时，触发 C 的那次调用不会被自动放行。

| 场景 | A | B | C | 结果 |
| --- | --- | --- | --- | --- |
| 总结一个网页，写成分支里的笔记 | 是 | 是 | 否（只写分支） | 自动：分支内的写入不算 C。 |
| 读过网页之后，向 `main` 提议合并 | 是 | 是 | 是 | Human Gate。 |
| 只读公开数据，写临时区 | 是 | 否 | 否 | 自动。 |
| 读过外部邮件之后发出邮件（出口） | 是 | 是 | 是 | 闸门；涉及 `secret` 则拒绝。 |

这是 Meta 的 [Agents Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/) 在**存储边界**上的实现。Meta 自己强调，它是减轻风险的启发式，不是终点，也不替代最小权限；我们的用法也是如此。机制见 [Trust Labels](https://agentnas.com/zh-cn/concepts/trust-labels/)。

## 威胁模型

| 威胁 | NAS 能强制的 | NAS 做不到的 | 残余风险 |
| --- | --- | --- | --- |
| T1 间接提示注入（经文件、网页、邮件） | Rule of Two；租约限定；分支；闸门。 | 阻止注入发生；阻止注入之后在租约内的恶意行为。 | 租约之内的误用。 |
| T2 凭据泄露（智能体读到长期密钥） | 长期凭据不在运行手里；密钥扫描器标记 `secret`；短 TTL。 | 防止智能体把租约内的数据发往已授权的出口。 | 租约内的数据外发。 |
| T3 过宽权限与误操作 | 窄域租约；分支；软删除；快照不在任何租约之内。 | 撤销外部副作用。 | NAS 之外的后果。 |
| T4 记忆投毒（含跨角色传播） | 来源与污点；隔离区；已审阅才自动加载；回滚。 | 识别“看起来合理”的错误事实。 | 被审阅者放过的投毒。 |
| T5 租约被窃取或重放 | 短 TTL；可撤销；可选的持有者绑定（DPoP、mTLS）。 | 阻止 TTL 内的滥用。 | TTL 窗口。 |
| T6 审批疲劳与橡皮图章 | 闸门稀少；NAS 渲染差异；批准绑定摘要；监控批准率。 | 让人认真看。 | 人为失误。 |
| T7 日志篡改 | 哈希链；可选的外部锚定。 | 没有锚定时，防止 root 毁掉日志。 | 恶意的管理员。 |
| T8 数据外泄（出口、共享、搜索结果） | 出口需要租约动作与闸门；`secret` 禁止出口；派生物继承标签。 | 防止人批准之后的泄露；隐蔽信道。 | 批准后的泄露。 |
| T9 供应链（技能、MCP 服务器、插件、模型） | 技能与外部 MCP 的内容视为 `external`；技能目录可以固定到某个提交；运行时清单写入记录。 | 保证第三方代码无害。 | 被固定下来的恶意版本。 |
| T10 资源耗尽（分支炸弹、预算耗尽、循环读取） | 配额；TTL；预算；熔断。 | 区分合法的大任务与失控。 | 局部的拒绝服务。 |

## 控制措施

- **策略引擎：** 确定性（Cedar 或 Rego 风格），默认拒绝，拒绝时给出可读的原因与命中的规则；**不调用 LLM**。
- **凭据代理：** 长期密钥只在代理手里；仅在获批的出口动作里为运行铸造短时的下游令牌。
- **隔离与密钥：** 每个角色一个 Home 与路径空间；`sensitive` 保留类使用单独的密钥域。
- **供应链：** 技能、MCP 服务器与插件的内容视为 `external`；运行开始时，把使用的技能与版本写入记录。

## 坦诚的局限

1. 这**不是**提示词注入的防御。它限制后果，并让后果可见。
2. 租约之内的合法权限仍可能被误用。
3. 对 NAS 之外的副作用无能为力：已经发出的邮件、已经调用的接口。
4. 隐蔽信道与侧信道不在范围内。
5. TCB 被攻陷，则保证失效。
6. 人会犯错：闸门降低但不能消除这种风险。
7. 污点是保守的，会带来摩擦与误报；需要调参，也需要可见的拒绝原因。
8. 加密粉碎只保护我们能控制的副本。

## 事件应对

- **熔断：** `revoke_run` 与 `revoke_role` 立即撤销租约并冻结分支。
- **回滚：** 把受影响的树恢复到某个提交。
- **溯源：** 用读清单和记录链找出“这次运行读过什么、写过什么、影响了哪些笔记”。
- **清理：** 用 [Cascade Forget](https://agentnas.com/zh-cn/concepts/cascade-forget/) 删除受影响的派生物，并出具报告。

## 可观测性与审计

- **三类数据：** 记录（事件）、读清单（输入集合）、指标与 trace。
- **`explain(commit)`：** 返回这个提交由哪次运行、哪张租约产生，经过了哪些闸门，读过什么，以及依赖的输入。
- **与现有观测栈集成：** 一次运行对应一个 OpenTelemetry GenAI span，租约与闸门以事件的形式挂在上面；记录可以导出为 JSON Lines，或接入 SIEM。
- **指标：** 租约发放与拒绝率；闸门队列长度、批准率与批准耗时；分支数量与年龄；索引新鲜度；预算消耗；记录链校验结果。
- **隐私与保留：** 默认只记元数据，不记内容；记录的保留与内容的删除各自独立；读取记录本身也需要租约。

---

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

---

# 用例

> 这些场景都从“已经有人这样做”出发，说明 Agent NAS 在哪一步改变了结果、需要哪一级符合性，以及今天就能用什么搭出来。

## 夜间运行的智能体

睡前，你给智能体一个任务：整理发布说明。它在自己的分支里工作；早上，你在手机上看到一张 Gate Card：4 个文件、真实的差异、它读过的来源。批准就合并；拒绝就丢弃分支，主线毫发无损。

- **用到的概念：** [Agent Branch](https://agentnas.com/zh-cn/concepts/agent-branch/)、[Capability Lease](https://agentnas.com/zh-cn/concepts/capability-lease/)、[Human Gate](https://agentnas.com/zh-cn/concepts/human-gate/)。
- **符合性：** L0 到 L1。
- **今天就能搭：** Git worktree、受保护的 `main` 和一条推送通知。

## 换框架，不丢记忆

你把智能体从一个运行时迁到另一个。Home 是遵循开放约定的目录：`AGENTS.md`、`skills/`、`memory/notes/`。新的运行时读同一个目录；映射有损的部分，在导入时标记为未审阅。

- **用到的概念：** [Agent Home](https://agentnas.com/zh-cn/concepts/agent-home/)、[Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/)。
- **符合性：** L0 到 L2。
- **今天就能搭：** 一个带 `AGENTS.md` 的 Git 目录。

## 一个团队，多个智能体，一份共享知识

三个智能体写同一个知识库。每个都在自己的分支里工作，合并经过审阅；读过外部网页的运行写下的笔记进入隔离区，不会被别的智能体自动加载。共享的是笔记，不是索引。

- **用到的概念：** [Trust Labels](https://agentnas.com/zh-cn/concepts/trust-labels/)、[Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/)、[Agent Branch](https://agentnas.com/zh-cn/concepts/agent-branch/)。
- **符合性：** L0 到 L3。
- **今天就能搭：** 受保护的主线，加导入目录的 `external` 标记，加一个只自动加载已审阅笔记的规则。

## 事故复盘

一次合并之后，你发现某页内容不对劲。`explain(commit)` 告诉你是哪次运行、哪张租约、哪个闸门决定；读清单显示那次运行读过一个外部网页。你顺着来源找到受影响的笔记，回滚，并把它们隔离。

- **用到的概念：** [Flight Recorder](https://agentnas.com/zh-cn/concepts/flight-recorder/)、[Agent Branch](https://agentnas.com/zh-cn/concepts/agent-branch/)。
- **符合性：** L1。
- **今天就能搭：** 提交里的 Git trailer，加一张追加写的 SQLite 表。

## 客户要求被遗忘

客户的数据在写入时就被标为 `sensitive` 保留类。收到请求后，Cascade Forget 沿血缘找到摘要、嵌入与引用它的笔记，销毁该密钥域，并出具报告：做了什么，哪些做不到（NAS 之外的副本、模型提供商的日志、模型权重）。

- **用到的概念：** [Cascade Forget](https://agentnas.com/zh-cn/concepts/cascade-forget/)、[Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/)。
- **符合性：** L3。
- **今天就能搭：** 保留类、软删除，以及为每个派生物记录输入。

## 给已有的盒子加一道门

你已经有一台 NAS。Overlay 形态在它前面放一个网关，只管理其中的一个目录。智能体通过挂载或 S3 视图进出；所有者的备份和快照仍在智能体够不着的地方。

- **用到的概念：** [Capability Lease](https://agentnas.com/zh-cn/concepts/capability-lease/)、[Agent Branch](https://agentnas.com/zh-cn/concepts/agent-branch/)。
- **符合性：** L0 到 L1。
- **今天就能搭：** NFS 或 SMB 加一个小网关，按路径前缀与动作校验令牌。

## 什么时候不该用 Agent NAS

| 你的情况 | 更简单的做法 |
| --- | --- |
| 一个智能体，数据可以随意重来 | 一个 Git 仓库加 `AGENTS.md`。 |
| 只想让智能体帮你管理 NAS | 厂商自带的管理智能体。 |
| 只需要可分叉的数据集 | lakeFS 或 Tigris。 |
| 只需要记忆检索 | 任何一个记忆库。 |
| 需要隔离计算 | 沙箱。 |

---

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

---

# 比较

> Agent NAS 不是要取代这些方案。多数相邻的做法在各自的位置上做得很好，可以直接成为它的零件。我们尽量诚实地列出借鉴了什么，以及真正新的只有哪几点。

## 现状地图

| 类别 | 代表 | 已经做到 | 止步之处 |
| --- | --- | --- | --- |
| NAS 厂商的管理智能体 | QNAP QuAgent、Synology DSM Agent、TrueNAS MCP | 用自然语言管理盒子；沿用用户权限；危险操作二次确认；日志。 | 面向“管理”而不是“在数据里工作”；没有运行级租约、分支与记忆契约。 |
| 智能体文件系统与 Git | Turso AgentFS、Letta Context Repositories、Cloudflare Artifacts、Redis Agent Filesystem | 把文件、状态与工具调用审计放进可移植的存储；用 Git 做版本化记忆；面向智能体的 Git。 | 各自绑定一个运行时或平台；授权、审批、污点、遗忘大多在其外。 |
| 可分叉对象存储与数据版本控制 | Tigris Agent Kit、lakeFS | 写时复制的分叉、检查点、受保护分支、限域凭据、合并前钩子。 | 面向数据湖与云对象存储；不规定记忆和租约的语义，也没有人的审批体验。 |
| 记忆框架 | Letta、Mem0、Zep/Graphiti、OpenClaw 记忆架构 | 检索、整合、时间图；OpenClaw 已经有来源标签与隔离。 | 多数绑在某个框架里；索引与真相不分；迁移与删除困难。 |
| 沙箱与运行时 | E2B、Daytona、Vercel Sandbox | 隔离的计算与快照。 | 存储不是重点；状态随沙箱消失。 |
| 通用存储 | S3 与 S3 Files、NFS、SMB、Git | 耐久、成熟、生态完整。 | 不认识“运行”“租约”“污点”。 |

**空白。** 每个部件都有人做出来了。我们没有看到的是：把它们编成一份**自托管、开放、可验收**的契约，以运行为单位，把分支、租约、审批、记录、记忆与遗忘绑在一起，并附带符合性测试。我们不声称没有人做过其中任何一件事；这正是我们大量借鉴的原因。

## 与相邻方案的关系

| 方案 | 擅长 | 与 Agent NAS 的关系 |
| --- | --- | --- |
| QNAP QuAgent、Synology DSM Agent、TrueNAS MCP | 用自然语言管理 NAS | 互补；它们的盒子可以成为 Overlay 的底座。 |
| Turso AgentFS、Redis Agent Filesystem、LayerFS | 智能体文件系统 | 可以作为 Store 引擎；Agent NAS 在上面加契约。 |
| Letta Context Repositories | Git 支撑的记忆 | Agent Home 沿用其布局思想；Letta 可以是 Agent Memory 的运行时。 |
| Cloudflare Artifacts、Tigris、lakeFS | 可分叉、可版本化的存储 | 可以直接作为 Store 引擎。 |
| Mem0、Zep/Graphiti | 记忆检索与整合 | 可以作为索引器，即派生物的生产者。 |
| OpenClaw 记忆架构 | 来源标签与隔离 | 先行者；我们把同样的想法放到共享的存储层。 |
| S3、S3 Files、NFS、SMB | 通用存储 | 可以作为 Store；它们不认识运行、租约与污点。 |
| E2B、Daytona、Vercel Sandbox | 隔离的计算 | 互补；应当一起使用。 |

## 我们借鉴了什么

- 从 **Git 与 lakeFS**：分支、受保护分支、合并前钩子。
- 从 **Letta 与 Cursor**：文件是智能体最熟悉的接口，上下文要渐进披露。
- 从 **OpenClaw 与记忆安全研究**：来源不可伪造，不可信的记忆要隔离。
- 从 **Meta 的 Rule of Two、CaMeL 与 Fides**：在模型之外限定后果。
- 从 **OAuth（RFC 8693、RFC 9396）、Biscuit 与 UCAN**：令牌交换与衰减式授权。
- 从 **OpenTelemetry 与 Certificate Transparency**：可导出的追踪与可发现的篡改。
- 从 **Anthropic 的自动模式研究**：审批要少，要放在计划与合并上。

## 真正新的东西

我们尽量诚实地列出来。这份清单很短：

1. 以**运行**为单位，把分支、租约、预算与记录绑在一起。
2. **读清单**与会话污点：在存储边界执行 Rule of Two。
3. 记忆写入的**来源与污点**，以及“已审阅才自动加载”的信任边界。
4. **保留类**：把“可恢复”与“可遗忘”变成显式的选择。
5. **符合性阶梯与可执行的验收测试。**

> **一个需要被证明的判断.** 其余的一切，包括分支、令牌、日志和检索，都是已有技术的组合。我们认为，把它们组合成一份开放、可验收的契约，本身就有价值；但这是一个**需要被证明的判断**，不是已经成立的事实。

---

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

---

# 规范

> 规范草案 v0.2 定义五个累积的符合性等级，从 L0 Files 到 L4 Sync。每一级都对应一组概念和一组可执行的验收测试；没有 `conformance.json` 的“兼容”声明不被接受。

> **草案.** 目前没有参考实现，也没有可运行的符合性测试套件。下面的验收测试是规范的一部分：它们的作用，是让“兼容”这个词可以被检验。

## 规范的组成

| 组件 | 内容 | 目标版本 |
| --- | --- | --- |
| Core | 六个名词、Store 契约、分支与受保护树、合并、软删除。 | v0.3 草案 |
| Lease & Record | 租约格式（`authorization_details` 档案）、记录与读清单的格式、`explain`。 | v0.3 草案 |
| Interfaces | 挂载语义、Git 与 S3 的投影、HTTP API、MCP 工具面。 | v0.4 草案 |
| Memory | 笔记约定、派生物与配方、预算读取、证据指针。 | v0.4 草案 |
| Guard | 标签、会话污点、策略档案、Gate Card、遗忘报告。 | v0.5 草案 |
| Sync | 交接包、标签门槛、墓碑。 | 之后 |
| Conformance Suite | 每个等级的可执行验收测试。 | 与各版本同步 |

## 符合性等级

等级是累积的：声明 L2，就必须同时满足 L0 和 L1。

| 等级 | 名称 | 覆盖的概念 | 一句话 |
| --- | --- | --- | --- |
| L0 | Files | Agent Home、Agent Branch | 带历史的目录。 |
| L1 | Authority | Flight Recorder、Capability Lease、Human Gate | 谁、凭什么、做了什么。 |
| L2 | Memory | Agent Memory、Budgeted Reads | 记忆可读、可迁移。 |
| L3 | Guard | Trust Labels、Cascade Forget | 限制后果。 |
| L4 | Sync | 无（可选） | 多节点。 |

## L0 Files：带历史的目录

1. 在运行分支里改文件，受保护的主线保持不变。
2. 直接写受保护树（即使凭据有效）被拒绝。
3. 删除受保护树里的文件之后，可以从回收区恢复。
4. 导出再导入，得到字节一致的树与历史。
5. 至少提供两种标准视图：挂载与 Git，或者其中一种加 S3。

## L1 Authority：谁、凭什么、做了什么

1. 没有租约的请求被拒绝，并且拒绝被记录。
2. 申请超出父租约的子租约被拒绝。
3. 租约到期后挂载变为只读；撤销在实现所声明的时限内生效。
4. 没有任何租约能删除快照。
5. 任一提交都可以 `explain` 到运行、租约与读清单。
6. 记录链校验通过；篡改一条记录后，校验失败。
7. 合并进受保护树时，Gate Card 展示由 NAS 计算的差异，且批准绑定摘要：差异一改，批准即失效。

## L2 Memory：记忆可读、可迁移

1. 删除全部索引并重建后，黄金召回测试通过。
2. 不经 Memory 层，笔记就可以被读取。
3. 每个派生物都带配方与输入。
4. 预算读取在预算不足时降级，并声明实际的视图。
5. 证据指针可以校验：提交变化后，指针仍然指向原来的内容。

## L3 Guard：限制后果

1. 在具备 B 与 C 的租约下，读过 `external` 的会话触发 C 类动作时，被拒绝或转交闸门。
2. 派生物继承其输入标签的并集。
3. 受污染会话写入的笔记不会被自动加载。
4. 遗忘请求产出含“覆盖不到的范围”的报告；法律保留能阻止遗忘。
5. 策略求值不调用 LLM：策略引擎没有对模型的出站调用，可以审计。

## L4 Sync：多节点

1. 两个节点同步之后，树一致。
2. 不向许可级别更低的节点发送高敏感的对象。
3. 遗忘的墓碑传播到对端。
4. 交接包可以在对端被执行，并且租约只会更窄。

## 声明格式

实现必须发布一个 `conformance.json`：声明符合的等级、各项测试的结果与已知的偏差。没有这份文件的“兼容”声明不被接受。

*conformance.json*

```json
{
  "implementation": "example-nas",
  "version": "0.1.0",
  "spec": "0.2",
  "level": "L1",
  "tests": { "L0.1": "pass", "L0.2": "pass", "L0.3": "pass", "L0.4": "pass", "L0.5": "pass",
             "L1.1": "pass", "L1.2": "pass", "L1.3": "pass", "L1.4": "pass",
             "L1.5": "pass", "L1.6": "pass", "L1.7": "pass" },
  "deviations": ["L1.3: revocation takes effect within 60 seconds"]
}
```

## 版本与兼容

- 语义化版本。0.x 期间不保证兼容。
- 新增字段向后兼容。
- 废弃的字段至少保留一个版本的警告期。

## 规范暂不规定

传输协议的版本细节、具体的策略语言、令牌的签名算法、具体的存储引擎，以及用户界面。

---

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

---

# 路线图

> 路线图按“现在、下一步、以后、不做”排列，不写具体年份的承诺：一份在 2026 年写下的三年时间表，大概率会在第一年就被事实改写。

## 现在、下一步、以后

- **现在（2026 年第四季度）** · 进行中 · **概念、规范草案与官网**: 概念与规范草案 v0.2，官网（8 种语言）。收集反馈：找 3 到 5 位已经在用 `AGENTS.md` 加 Git 的真实使用者做访谈，验证赌注 B1 到 B7。
- **下一步（目标：2027 年上半年）** · 下一步 · **参考实现 v0 与规范 v0.3**: 参考实现 v0（Lite 与 Overlay）：Git 与文件系统快照后端、租约签发、记录与读清单、CLI，以及 L0 到 L1 的符合性测试套件；规范 v0.3（Core、Lease & Record）。一个可演示的场景：夜间运行的智能体在分支里工作，早上在 Gate Card 上批准合并。
- **以后（视反馈而定）** · 之后 · **Memory、Guard、控制室与 Sync**: Memory 层与 MCP 工具面（L2）；Guard：标签、污点、级联遗忘（L3）；控制室；Team 与 Cloud 形态；Sync（L4）。

> **不具约束力.** 这是意图，而不是承诺。定义“兼容”含义的是符合性等级，而不是日历。

## 阶段门槛（证伪条件）

“下一步”完成的标准**不是**功能清单，而是：在至少三个真实工作流里连续运行一周；闸门的批准率低于 95%；至少拦下过一次真实的问题。做不到，就回头修改概念，而不是继续往前堆功能。

## 不做

- 自研存储引擎。
- 自研向量数据库。
- 模型托管。
- 技能市场。
- 代币与区块链。
- 专用硬件。

## 有意留白的问题

- 租约里自由文本的 `purpose`，如何走向可以被机器检查的结构化意图？
- 语义合并器如何注册并被信任？
- 标签的粒度应当是文件，还是段落？
- 多租户场景下，标签词汇表如何治理？
- 撤销在多节点之间的传播延迟，如何对外表述？
- 如何度量记忆质量？模型或嵌入变化时，回归的标准是什么？
- 对由多个来源混合推断出的事实，Cascade Forget 如何界定受影响的范围？
- 高吞吐下，读清单的存储成本与粒度如何取舍？
- 批量与分级审阅的最佳界面是什么？自动合并的门槛如何度量与调整？
- 跨组织的信任根如何分发与撤销？

---

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

---

# 设计原则

> 八个论点指导 Agent NAS 的每一项取舍；七个赌注说明它押了什么、押错了会怎样。一份希望几年后仍然成立的设计，应当说明自己什么时候会错。

## 1. 访问的单位是运行，不是账号

现在的做法是给智能体一个长期令牌，或者一个人类账号：2026 年 4 月那次事故里的令牌，“为管理域名而建，却能做任何事”。一次运行有开始、结束、目的和责任人，是天然的授权与追责单位。

*排除：* 共享密钥、长期令牌和借来的人类账号。

## 2. 撤销比预防便宜

预防（审批、分类器、提示里的规则）一定会漏：分类器有漏报，人更差，模型也会违背写在提示里的原则。让错误**可撤销**（分支、软删除、快照），比让每个动作都正确容易得多，也更容易验证。附带一条：**恢复路径必须在被保护对象的爆炸半径之外**，所以快照由所有者持有，不在任何租约的权限之内。

*排除：* 把“在提示里写一句要人确认”当作控制措施。

## 3. 权限按任务出借，不按身份授予

一次运行拿到的是一张窄域、有期限、有预算的租约；长期钥匙只留在编排器或所有者手里，模型永远看不到。

*排除：* 长期、宽泛、常驻的权限。

## 4. 笔记是真相，智能是缓存

记忆应当是人能读能改的文件；索引、嵌入和摘要都是可丢弃、可重建的派生物。这样检索算法可以换，记忆不会丢；投毒与删除也变得可以处理。

*排除：* 无法检查、无法迁移的不透明记忆库。

## 5. 来源是贯穿一切的主线

每条记忆、每个派生物、每次合并，都能回答“它从哪来、被什么影响过”。来源既是审计的基础，也是投毒治理、信任标签和遗忘的基础。

*排除：* 没有来源的记忆。

## 6. 策略是确定性的，模型只能收紧

授权决定由代码做出，不由模型的“意见”做出。分类器或 LLM 可以建议“这一步需要审批”，但永远不能批准。

*排除：* 让模型自己判断某件事能否放行。

## 7. 存储保持无聊，创新放在契约上

不造引擎；文件优先，因为模型最熟悉的接口就是文件；协议会换，六个名词不会。

*排除：* 以 AI 为由发明新的存储引擎。

## 8. 稀缺的是 token 与人的注意力

读取要有预算；审批要少而具体，并放在人真会判断的地方：计划与合并，而不是每个动作。

*排除：* 默认返回整个文件；每个动作弹一次窗。

## 七个赌注与证伪

一份希望几年后仍然成立的设计，应当说明自己押注了什么、什么情况下会错。

| 赌注 | 依据 | 如果错了 |
| --- | --- | --- |
| B1 智能体会继续把文件系统与 Git 当作主要的工作介质 | 多个主流运行时已经转向文件。 | 若转向专用的“记忆 API”，Agent Home 退化为导出格式；其余概念不依赖文件，仍然成立。 |
| B2 “一次运行”仍是自然的授权与追责单位 | 编排器普遍按任务或会话启动沙箱。 | 若出现长期常驻的自治进程，租约改为滚动续期加预算，概念保留。 |
| B3 提示词注入在可预见的将来不会在模型层被根除 | Meta 的表述；分类器的漏报率；多项攻击研究。 | 若被根除，Trust Labels 变成纵深防御里的一层，成本很低。 |
| B4 人的注意力仍是稀缺资源 | Anthropic 披露的数据。 | 若全自动足够可靠，Human Gate 由策略预授权取代，审计仍然保留。 |
| B5 存储层是执行来源与污点的合适位置 | 记忆安全研究强调写入时的来源；OpenClaw 在运行时内部做过同样的事。 | 若各运行时都自己做好，NAS 只需保存标签，角色变薄。 |
| B6 跨运行时、跨智能体共享的记忆会成为真实需求 | 多智能体协作；框架迁移的成本。 | 若记忆继续是各框架的私有功能，Agent Memory 的价值主要在个人与小团队的可迁移性。 |
| B7 协议会换，但“文件加工具”两个口会稳定 | MCP 的版本迁移；A2A 1.0。 | 换适配器即可；这也是适配器隔离的原因。 |

## 预期保持稳定的，与预期会变的

| 预期保持稳定 | 预期会变化 |
| --- | --- |
| 六个名词 | 具体的协议与传输 |
| Home 的目录约定 | 嵌入模型与检索算法 |
| 四个承诺 | 令牌格式 |
| “导出即退出”的保证 | 智能体框架与人机交互界面 |

---

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

---

# 常见问题

> 回答人们对 Agent NAS 最先会问的问题：它是什么，与现有的存储和记忆工具有何不同，如何处理安全与隐私，以及项目进展到哪里。

## 基础问题

### Agent NAS 是什么？

Agent NAS 是围绕“一次运行”设计的网络附加存储：智能体的每次运行都在隔离的分支里工作，凭一张短时、窄域的租约访问数据；每个改动都能追溯、能撤销；记忆是带来源的普通文件。它通过挂载、Git、S3 和 MCP 提供服务。

### Agent NAS 是可以购买或下载的产品吗？

还不是。它目前是一个带规范草案的概念（v0.2，2026 年 11 月）。L0 与 L1 可以用现成零件今天搭出来；参考实现 v0 的目标是 2027 年上半年，之后的安排见[路线图](https://agentnas.com/zh-cn/roadmap/)。

### 它和 NAS 厂商推出的 AI 智能体有什么不同？

QNAP、Synology 和 TrueNAS 等厂商推出的智能体，用来管理这台盒子。Agent NAS 规定的是别的智能体怎样在盒子里的数据上工作：分支、租约、记忆与遗忘。两者互补，参见[比较](https://agentnas.com/zh-cn/compare/)。

### 它和向量数据库或记忆框架有什么不同？

它们是检索与整合的工具，而 Agent NAS 的真相是带来源的普通笔记。向量库和记忆框架可以作为索引器挂在 [Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/) 之下，索引随时可以丢弃重建。

### 它是开源的吗？

规范和本站内容采用 CC BY 4.0 许可。参考实现计划以 Apache-2.0 开源。

## 设计与安全

### 为什么用文件和 Git，而不是数据库？

智能体正在向文件收敛：指令在 `AGENTS.md` 里，技能在 `SKILL.md` 里，记忆是 Markdown，历史在 Git 里。文件任何工具、任何模型都能读，容易对比，也容易带走。数据库和索引仍然会用，但它们是可以重建的派生层。

### 一次运行出了错，最坏会怎样？

最坏的情况是丢掉一个可丢弃的分支：受保护的主线只能经审阅的合并更新，删除是软删除，快照不在任何租约之内。前提是错误发生在 NAS 之内；已经发出的邮件和已经调用的外部接口，NAS 无法撤销。

### 租约和 OAuth 令牌是什么关系？

租约就是一枚 OAuth 访问令牌：靠令牌交换（RFC 8693）申请，用富授权请求（RFC 9396）描述路径与动作。Agent NAS 补上的是以运行为单位的约定，包括分支、预算与 Rule of Two 属性。详见 [Capability Lease](https://agentnas.com/zh-cn/concepts/capability-lease/)。

### 为什么说记忆是“笔记加缓存”？

这样它才能被检视、更正、迁移和遗忘。笔记是文件；索引、嵌入和摘要都由它们按记录在案的配方计算而来。换嵌入模型，系统就在后台重算。受污染会话写的笔记先进入隔离区，在审阅之前不会自动加载。

### Agent NAS 能阻止提示词注入吗？

不能。模型之外的任何东西都无法完全阻止它。Agent NAS 限制的是被注入的智能体能做什么：[Trust Labels](https://agentnas.com/zh-cn/concepts/trust-labels/) 让读过外部内容的会话，无法再同时拥有敏感数据与对外通道，有后果的动作需要 [Human Gate](https://agentnas.com/zh-cn/concepts/human-gate/)。坦诚的局限见[安全](https://agentnas.com/zh-cn/security/)。

### 它如何处理“被遗忘权”？

通过 [Cascade Forget](https://agentnas.com/zh-cn/concepts/cascade-forget/)：沿血缘删除由来源派生的摘要、嵌入与笔记，按保留类处理历史，并对 `sensitive` 类销毁密钥（加密粉碎）。它出具的报告会明确列出覆盖不到的范围：NAS 之外的副本、模型提供商的日志、模型权重。它无法让模型忘记任何东西。

### 我必须使用 MCP 吗？

不必。MCP 只是控制面的接口之一，文件、Git 和 S3 不需要它；协议层本来就设计为可以替换。

## 采用与未来

### 它会取代我现有的 NAS 或云存储吗？

不会。Overlay 部署形态在现有的 NAS、对象存储或 Git 托管之前放一个网关，只管理其中的一个目录或桶。云存储也可以充当 Store。

### 哪些智能体框架和运行时可以配合使用？

任何能挂载目录，或者会用 Git、S3 或 MCP 的运行时。Agent Home 的布局遵循开放约定（`AGENTS.md`、Agent Skills、带 YAML frontmatter 的 Markdown），所以 Claude Code、Cursor、Codex、OpenHands、LangGraph 以及自研的框架都是候选。

### 我可以随时离开吗？

随时可以。所有内容都能导出为普通文件和 Git 历史。这是四个承诺之一，而不是一个功能。

### 什么时候不该用 Agent NAS？

只有一个智能体、数据可以随意重来的时候：一个 Git 仓库加 `AGENTS.md` 就够了。更多情形见[用例](https://agentnas.com/zh-cn/use-cases/)。

### 我怎样引用或参与贡献？

每个页面都列出了规范网址和建议的引用格式。要参与贡献，请在 GitHub 上提交 issue 或发起讨论。详情见[关于页面](https://agentnas.com/zh-cn/about/)。

---

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

---

# 术语表

> 本术语表定义 Agent NAS 使用的每个术语：九个命名概念与配套词汇。概念名称是自造术语，在所有语言中都保持英文，并在中文版里附上释义。

## 九个概念

- **[Agent Home (智能体之家)](https://agentnas.com/zh-cn/concepts/agent-home/)**: **Agent Home（智能体之家）** 是按角色划分、带历史的目录：指令、技能、记忆、日志和工作区，全是普通文件。任何运行时都能进入，离开时可以整个带走。
- **[Agent Branch (智能体分支)](https://agentnas.com/zh-cn/concepts/agent-branch/)**: **Agent Branch（智能体分支）** 让每次运行在写时复制的分支里工作；变更只有通过一次经审阅的合并（Agent PR）才能进入受保护的主线；随时可以打检查点并恢复。
- **[Flight Recorder (飞行记录仪)](https://agentnas.com/zh-cn/concepts/flight-recorder/)**: **Flight Recorder（飞行记录仪）** 是以运行为单位、只追加、哈希链接的记录：这次运行读了什么（读清单）、写了什么、被允许或拒绝了什么、谁批准了什么。它存放在数据旁边，用来回答“这个改动可能受到了什么影响”。
- **[Capability Lease (能力租约)](https://agentnas.com/zh-cn/concepts/capability-lease/)**: **Capability Lease（能力租约）** 是对特定数据、特定操作、有明确期限与预算的授权，发给**一次运行**，也是运行接触 NAS 的唯一途径。子租约只能比父租约更窄。
- **[Human Gate (人类闸门)](https://agentnas.com/zh-cn/concepts/human-gate/)**: **Human Gate（人类闸门）** 是由策略触发的检查点：在**不可逆、对外或提权**的动作生效之前，由人（或指定的审批主体）批准一个被完整渲染的具体动作。它被设计成稀少、具体、难以橡皮图章。
- **[Trust Labels (信任标签)](https://agentnas.com/zh-cn/concepts/trust-labels/)**: **Trust Labels（信任标签）** 是附在数据上的两个很小的标签集，**来源**（`owner`、`agent`、`external`）与**敏感度**（`public`、`private`、`secret`），再加上**会话污点**。NAS 把 Rule of Two 当作会话不变量来强制：一次会话不能同时拥有 [A] 读过外部内容、[B] 接触敏感数据、[C] 改变受保护状态或对外通信；要补全第三项，就走 [Human Gate](https://agentnas.com/zh-cn/concepts/human-gate/)。
- **[Agent Memory (智能体记忆)](https://agentnas.com/zh-cn/concepts/agent-memory/)**: **Agent Memory（智能体记忆）** = **你能读、能改的笔记** + **可以随时丢弃的索引**。每条笔记都引用它的来源；索引（全文、向量、图、轮廓）只是笔记的派生物；后台维护作业只**提议**修改，绝不改写原始日志。
- **[Budgeted Reads (预算化读取)](https://agentnas.com/zh-cn/concepts/budgeted-reads/)**: **Budgeted Reads（预算化读取）** 是以 token 预算为单位的读取：同一个文件可以用不同的细节来读，从轮廓、章节、行范围到全文；智能体要的是“能装进 N 个 token 的最佳视图”，并附带指回精确来源的证据指针。
- **[Cascade Forget (级联遗忘)](https://agentnas.com/zh-cn/concepts/cascade-forget/)**: **Cascade Forget（级联遗忘）** 是沿血缘的删除：当一个来源被删除，或有人要求被遗忘时，NAS 找出由它派生的一切，包括摘要、嵌入、引用它的笔记、缓存和共享链接，删除它们，或在不含该来源的情况下重新派生，并出具**报告**：做了什么，哪些做不到。

## 配套术语

- **Principal（主体）**: 可以被认证并被追责的实体：人、智能体、服务或节点。
- **Run（运行）**: 一次有开始、结束、目的和责任人的执行。一次运行持有一张根租约，并拥有一个分支。
- **Protected tree（受保护树）**: 只能经审阅的合并更新、不接受直接写入的树，例如 `main`。
- **Read manifest（读清单）**: 一次运行读过的路径、提交、范围与内容哈希的聚合记录，不含内容本身。
- **Evidence pointer（证据指针）**: 形如 `nas://<node>/<tree>/<path>@<commit>#L12-L18` 的可校验引用，指向某个提交里的确切行。
- **Derived data（派生数据）**: 由笔记按配方计算出来的数据，例如索引、嵌入或摘要。可以丢弃，也可以重建。
- **Recipe（配方）**: 产生一个派生物所需的全部参数：模型及其版本、切块器和各项设置。
- **Lineage（血缘）**: 派生物与计算它们所用输入之间的依赖关系图。
- **Session taint（会话污点）**: 一次会话读过的全部内容的标签汇总。它在会话内只增不减，并决定会话接下来可以做什么。
- **Rule of Two**: Meta 提出的启发式：在注入问题被可靠解决之前，一次会话最多只应同时具备三项中的两项：[A] 处理不可信输入，[B] 访问敏感数据，[C] 改变状态或对外通信。
- **Declassification（降级）**: 降低数据的敏感度，或抬高其来源的可信度。只能经 Human Gate，或经模式校验的结构化交接。
- **Policy envelope（策略包络）**: 所有者预先设定的、允许自动发放租约的范围。超出范围的申请交给 Human Gate。
- **Credential Broker（凭据代理）**: 保管长期密钥，并且只为获批的出口动作铸造短时下游令牌的组件。模型和运行看不到长期密钥。
- **Agent PR**: 把一个分支合并进目标的结构化提案，附带差异、来源、检查结果与标签摘要。
- **Retention class（保留类）**: 写入时指定的 `scratch`、`normal`、`sensitive` 三类之一，决定备份、历史和能否粉碎。
- **Crypto-shredding（加密粉碎）**: 通过销毁密钥，让所有用它加密的副本变得不可读。
- **Conformance level（符合性等级）**: 从 L0 到 L4 的等级，每一级对应一组概念和一组可执行的验收测试。
- **MCP**: Model Context Protocol：智能体与工具或数据源之间的开放协议。
- **A2A**: Agent2Agent 协议：智能体之间进行任务协作的开放协议。

---

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

---

# 关于

> agentnas.com 是 Agent NAS 概念及其规范草案的家。这是一个开放项目，目标是给人和智能体一套共同的词汇，以及一份可以让多个独立实现共同遵循、并且可以被验收的契约。

## 状态

截至 2026 年 11 月，Agent NAS 是一个带规范草案（v0.2）的概念。目前还没有参考实现，也没有可运行的符合性测试套件。v0.2 是一次落地修订：十三个概念收敛为九个，每个概念都写明了“从小处开始”和“坦诚的局限”。本网站是项目发布的第一件成品。计划见[路线图](https://agentnas.com/zh-cn/roadmap/)。

## 许可

本站与规范的文字和图示采用 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可：只要署名，你就可以分享和改编。参考实现计划以 Apache-2.0 发布。

## 如何引用

请引用你使用的那个页面，并尽量逐字引用它的定义。每个页面底部都有规范网址和建议的引用格式。引用整个项目时：

*引用格式*

```text
Agent NAS 项目。《Agent NAS：为 AI 智能体而生的网络附加存储》。规范 v0.2（草案），2026 年 11 月。https://agentnas.com/zh-cn/what-is-agent-nas/
```

*BibTeX*

```bibtex
@misc{agentnas2026,
  title        = {Agent NAS: network-attached storage for AI agents},
  author       = {{Agent NAS project}},
  year         = {2026},
  howpublished = {Specification v0.2 (draft)},
  url          = {https://agentnas.com/what-is-agent-nas/}
}
```

## 治理

- **规范与实现分离。** 欢迎有许多实现；定义“兼容”的是符合性测试和 `conformance.json`，而不是品牌。
- **过程。** 公开的提案（issue 与 PR）；重大变更需要写明动机、证据和反例。
- **命名。** “Agent NAS”是描述性的概念名称；声明符合某一等级，需要发布 `conformance.json`。
- **欢迎反驳。** 对任何论点的质疑都有价值，尤其是[七个赌注](https://agentnas.com/zh-cn/principles/)。

## 参与

欢迎勘误、批评和实现笔记。请在[项目仓库](https://github.com/xwzy/agentnas.com)中提交 issue 或发起讨论。本站不公布电子邮箱；关于规范的安全报告也走同一渠道。

## 面向智能体与爬虫

- 每个页面都有 Markdown 孪生版本：在网址后加上 `index.md`，或发送 `Accept: text/markdown`。
- [/zh-cn/llms.txt](https://agentnas.com/zh-cn/llms.txt) 是精选索引，[/zh-cn/llms-full.txt](https://agentnas.com/zh-cn/llms-full.txt) 是全文。
- 本文档的 MCP 服务器运行在 `https://agentnas.com/mcp`，由它的[服务器卡片](https://agentnas.com/mcp/server-card)描述。
- 搜索端点 `POST /api/search` 在 [/openapi.json](https://agentnas.com/openapi.json) 中描述。
- [AI Catalog](https://agentnas.com/.well-known/ai-catalog.json) 和[站点地图](https://agentnas.com/sitemap.xml)列出了全部内容。
- 内容可以自由索引、引用，并用作回答的输入。参见 [/robots.txt](https://agentnas.com/robots.txt)。

---

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

---

# Agent Home (智能体之家)

*按角色划分、带历史的目录，全是普通文件，可以带走。*

> **Agent Home（智能体之家）** 是按角色划分、带历史的目录：指令、技能、记忆、日志和工作区，全是普通文件。任何运行时都能进入，离开时可以整个带走。

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

## 要解决的问题

智能体的状态散落在框架的数据库、厂商托管的记忆接口和随时会消失的沙箱磁盘里。换一个框架或厂商，状态就丢；出了问题，也没有一个地方可以“看一眼它到底知道什么”。

与此同时，主流智能体已经在向文件收敛：`AGENTS.md`、Agent Skills、以 Git 为后端的记忆仓库。缺的不是新格式，而是一个**有归属、有历史、有配额、可导出**的地方来放它们。

## 工作方式

- **布局遵循开放约定。** `AGENTS.md`、Agent Skills 的 `SKILL.md`、带 YAML frontmatter 的 Markdown，如下面的草图所示。我们不发明新格式。
- **Home 属于角色，不属于某一次运行。** 运行通过[分支](https://agentnas.com/zh-cn/concepts/agent-branch/)使用它：改动先落在分支上，再经审阅合并回 Home。
- **带历史。** 每次改动都是一次提交。`nas export` 或 `git clone` 就能带走整个 Home，包括 `.nas/` 里的纯文本元数据。
- **启动上下文就是读几个文件：** `AGENTS.md`、`memory/MEMORY.md`、收件箱摘要。没有专门的“醒来协议”；NAS 可以提供一个有 token 上限的 `briefing` 视图作为便利，但不是必需。
- **已审阅才自动加载。** 只有被标记为 `reviewed` 的笔记才会进入 `MEMORY.md` 和自动加载的上下文，见 [Trust Labels](https://agentnas.com/zh-cn/concepts/trust-labels/) 与 [Agent Memory](https://agentnas.com/zh-cn/concepts/agent-memory/)。
- **生命周期。** 从模板创建、配额、归档、退役，退役时可以指定继承者。

## 从小处开始

- 建一个目录，放 `AGENTS.md`、`skills/` 和 `memory/`，`git init`。用符号链接让 `CLAUDE.md` 等文件指向 `AGENTS.md`。
- 每次运行前执行 `git worktree add`，让运行在自己的工作树里干活。
- 这就是 L0：不需要任何 Agent NAS 软件，你已经拥有一个带历史、可带走的 Home。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*layout*

```text
/agents/cleo/                    # a role's Home: it belongs to the role, not to one run
├── AGENTS.md                    # instructions (open convention)
├── skills/                      # Agent Skills: one directory per skill
│   └── release-notes/SKILL.md
├── memory/
│   ├── MEMORY.md                # reviewed core memory: auto-loaded, token-capped
│   ├── notes/                   # notes: Markdown + YAML frontmatter
│   ├── journal/                 # raw log: append-only
│   └── quarantine/              # unreviewed notes: recallable, never auto-loaded
├── inbox/                       # tasks and messages received
├── outbox/                      # deliverables and replies
├── workspace/                   # scratch space (retention class: scratch)
└── .nas/                        # plain-text metadata: role.yaml, limits.yaml, maintenance.yaml
```

## 规范的要求

- Home **必须**仅凭 Store 就能重建；读取它**不得**依赖任何派生数据。
- `.nas/` 元数据**必须**是纯文本，并随 Home 一起导出。
- 自动加载的上下文**必须**有 token 上限，并且**只能**来自已审阅的笔记。
- 布局**应当**遵循开放约定：`AGENTS.md`、`SKILL.md`、带 YAML frontmatter 的 Markdown。
- 运行**必须**通过分支使用 Home。

## 借鉴与区别

下面这些都是现成的做法，**真正新的部分很少**：布局和 Git 都已经存在。新的只是把 Home 当作带配额、继承者和导出保证的一等对象，并规定“已审阅才自动加载”这条信任边界。

- [AGENTS.md](https://agents.md)
- [Agent Skills](https://agentskills.io/specification)
- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [Turso AgentFS](https://github.com/tursodatabase/agentfs)
- [Cloudflare Artifacts](https://blog.cloudflare.com/artifacts-git-for-agents-beta/)

## 坦诚的局限

- 各框架的原生记忆格式并不一致，映射到 Home 的约定是有损的。
- 只有运行时愿意读写这些文件才有用。
- 厂商侧的隐藏状态（例如云端托管的记忆）无法纳入。

## 开放问题

- 各框架的格式如何双向映射？
- 一个很大的 Home 怎样控制启动时的加载量与延迟？

## 常见问题

### Agent Home 只是一个 Git 仓库吗？

大体上是，而且这是有意的：你可以直接 `git clone` 它。区别在于它还有归属（属于一个角色）、配额、继承者、导出保证，以及“已审阅才自动加载”的规则；这些由 NAS 保证，而不只是约定。

### 换一个智能体框架，记忆会丢吗？

不会，只要新的运行时愿意读这些文件。Home 用的是开放约定，`AGENTS.md`、`SKILL.md` 与 Markdown 笔记不依赖任何一个框架。映射有损的部分，应当在导入时标记为未审阅。

### 我需要先装 Agent NAS 才能用 Home 吗？

不需要。一个带 `AGENTS.md` 的 Git 目录就是 L0 的 Home。NAS 提供的是配额、受保护的合并、租约与审计，而不是文件格式。

## 相关概念

- [Agent Branch (智能体分支)](https://agentnas.com/zh-cn/concepts/agent-branch/): 每次运行在写时复制的分支里工作，经审阅的合并才进入主线。
- [Agent Memory (智能体记忆)](https://agentnas.com/zh-cn/concepts/agent-memory/): 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
- [Capability Lease (能力租约)](https://agentnas.com/zh-cn/concepts/capability-lease/): 发给一次运行的、有期限与预算的窄域授权；子租约只能更窄。

---

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

---

# 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

---

# Flight Recorder (飞行记录仪)

*以运行为单位、哈希链接的记录，包括这次运行读过什么。*

> **Flight Recorder（飞行记录仪）** 是以运行为单位、只追加、哈希链接的记录：这次运行读了什么（读清单）、写了什么、被允许或拒绝了什么、谁批准了什么。它存放在数据旁边，用来回答“这个改动可能受到了什么影响”。

**AN-03** · 符合性等级: L1 Authority · 概念簇: 工作

## 要解决的问题

事故复盘时，日志散落各处；“读取”与随后的动作之间没有关联；日志可以被同一位管理员，甚至同一个智能体修改。

更根本的是：当一次合并或一条记忆被怀疑受到污染时，没有办法回答“那次运行读过什么”。

## 工作方式

- **两类内容。** *事件*逐条记录：提交、租约签发与撤销、闸门请求与决定、策略拒绝、派生、遗忘。*读清单*（read manifest）按运行聚合：读过哪些路径@提交、哪些范围、内容哈希；不记每一次读取调用，也不记内容。
- **每个提交带来源元数据：** `principal`、`on_behalf_of`、`run`、`lease`、`purpose` 和读清单引用。
- **哈希链**（按天），可选签名与外部锚定（第二个节点、带对象锁的桶）。目标是“**篡改可以被发现**”，而不是“无法篡改”。
- **导出：** OpenTelemetry GenAI spans、JSON Lines，或接入 SIEM。
- **隐私：** 默认只记元数据，不记内容；记录的保留与内容的删除互相独立；记录本身受访问控制。
- **`explain(commit)`：** 返回这次提交对应的运行、租约、闸门决定、读清单与输入。
- **先记录，后生效：** 有后果的操作必须先写入意图记录。

## 从小处开始

- 一张追加写的 SQLite 表，加上每日哈希。
- 在每个提交信息里写 `Run:`、`Lease:` 之类的 Git trailer。
- 导出 OpenTelemetry spans，接入你已有的观测栈。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*record.json*

```json
{
  "seq": 18211,
  "time": "2026-11-12T09:14:22Z",
  "kind": "commit",
  "run": "run_91ab",
  "principal": "agt_cleo",
  "on_behalf_of": "usr_wei",
  "lease": "lse_7Qk3",
  "purpose": "Draft the Q4 release notes",
  "subject": { "path": "/shared/launch/notes.md", "commit": "91ce3a7" },
  "read_manifest": "rm_5d2e",
  "decision": { "effect": "allow", "rule": "r-17" },
  "taint": { "external": true, "sensitivity": "private" },
  "prev_hash": "sha256:b3a0..."
}
```

## 规范的要求

- 有后果的操作**必须**在生效之前写入意图记录；写入失败时，操作**必须**失败。
- 每次运行**必须**有读清单，记录读过的路径、提交与范围（不含内容）。
- 记录**必须**哈希链接，并且**必须**能用公开的命令校验。
- `explain(commit)` **必须**返回运行、租约、闸门决定与读清单引用。
- 记录的保留**必须**独立于内容的删除。

## 借鉴与区别

下面这些都是现成的零件。**真正新的部分是读清单：** 把“读”变成一个可追溯的输入集合，使“被污染的合并”和“被投毒的记忆”可以复盘。

- [OpenTelemetry GenAI conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/)
- [Certificate Transparency](https://certificate.transparency.dev)
- [Sigstore Rekor](https://docs.sigstore.dev/logging/overview/)
- [Git trailers](https://git-scm.com/docs/git-interpret-trailers)

## 坦诚的局限

- 没有外部锚定时，拥有 root 的管理员仍然可以毁掉日志。
- 记录本身含有敏感的元数据，必须受控。
- 读清单的粒度是存储成本与可追溯性之间的折中。

## 开放问题

- 高吞吐下读清单的存储成本如何控制？
- 跨节点的记录如何合并与校验？

## 常见问题

### 它会记录智能体读到的内容吗？

默认不会。记录里只有路径、提交、范围与内容哈希，足以指回原始数据，又不会把敏感内容复制进日志。内容仍然在 Store 里，受租约与标签保护。

### “防篡改”是什么意思？

我们只承诺**篡改可以被发现**：记录是哈希链接的，改一条就会让链校验失败；配合外部锚定（第二个节点或带对象锁的桶），可以抵御拥有 root 的管理员。没有锚定时，管理员仍可整体销毁日志。

### 为什么要记“读”？

因为风险常常来自读取：一次读了网页的会话，随后写进的笔记就可能被污染。读清单让你事后能回答“这个改动受到了什么影响”。

## 相关概念

- [Capability Lease (能力租约)](https://agentnas.com/zh-cn/concepts/capability-lease/): 发给一次运行的、有期限与预算的窄域授权；子租约只能更窄。
- [Trust Labels (信任标签)](https://agentnas.com/zh-cn/concepts/trust-labels/): 来源与敏感度两个小标签，加上会话污点，强制执行 Rule of Two。
- [Cascade Forget (级联遗忘)](https://agentnas.com/zh-cn/concepts/cascade-forget/): 沿血缘删除派生物，按保留类处理历史，并如实报告做不到的部分。

---

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

---

# Capability Lease (能力租约)

*发给一次运行的、有期限与预算的窄域授权；子租约只能更窄。*

> **Capability Lease（能力租约）** 是对特定数据、特定操作、有明确期限与预算的授权，发给**一次运行**，也是运行接触 NAS 的唯一途径。子租约只能比父租约更窄。

**AN-04** · 符合性等级: L1 Authority · 概念簇: 权限

## 要解决的问题

RBAC 与 ACL 假设用户长期稳定、权限宽而持久；智能体需要的是按任务裁剪、到点失效的权限。更糟的是，长期凭据常常放在智能体够得着的地方：2026 年 4 月那次事故里的令牌，就躺在一个无关的文件里，名义上用来管理域名，实际上能做任何事。

## 工作方式

- **谁拿着钥匙。** 长期凭据只在编排器或所有者手里；运行拿到的是租约，不是钥匙。模型永远看不到长期凭据。
- **租约是一枚访问令牌，** 它的 `authorization_details`（[RFC 9396](https://www.rfc-editor.org/rfc/rfc9396)）描述路径、动作与分支；由所有者或编排器通过[令牌交换（RFC 8693）](https://www.rfc-editor.org/rfc/rfc8693)申请，`act` 声明记录委托链；NAS 端保存状态，用于撤销与预算计数。
- **只能收窄。** 子租约必须是父租约的子集，铸造时由 NAS 校验。
- **预算。** 读写字节数、请求数，以及可选的出口字节与花费上限，由网关计数。它是**熔断器**，不是精确计费。
- **策略包络（policy envelope）。** 所有者预先设定一个范围，范围内的租约自动发放，超出就交给 [Human Gate](https://agentnas.com/zh-cn/concepts/human-gate/)。长期的访问用包络表达，而不是做成长期租约。
- **显式声明 B 与 C。** 租约写明最高敏感级别，以及是否允许受保护写入或出口，它们是 [Trust Labels](https://agentnas.com/zh-cn/concepts/trust-labels/) 的输入。
- **撤销。** 短 TTL（默认 4 小时，上限 24 小时）加即时撤销，撤销会级联到子租约。
- **`purpose` 只记录，不强制：** 自由文本无法被机器检查。

## 从小处开始

- 写一个 `nas lease create` 命令：为每个角色签发一枚带路径前缀、动作和 TTL 的令牌，用环境变量交给沙箱；NAS 一侧按前缀和动作强制。
- 这已经能挡住那类事故的前半段：令牌无法做租约之外的任何事。
- 预算、委托链与策略包络可以以后再加。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*lease.json*

```json
{
  "lease_id": "lse_7Qk3",
  "run": "run_91ab",
  "principal": "agt_cleo",
  "on_behalf_of": "usr_wei",
  "parent": null,
  "purpose": "Draft the Q4 release notes",
  "paths": ["/shared/launch/**", "/agents/cleo/workspace/**"],
  "actions": ["read", "write", "propose"],
  "branch": "cleo/run_91ab",
  "sensitivity_max": "private",
  "egress": false,
  "requires_gate": ["merge", "delete", "share"],
  "budgets": { "bytes_read": 200000000, "bytes_written": 5000000, "requests": 5000 },
  "expires_at": "2026-11-12T16:00:00Z"
}
```

## 规范的要求

- 租约**必须**有到期时间，并且**不得**在最大 TTL 之后续期；续期需要新的发放。
- 子租约**必须**是父租约的子集，NAS **必须**在铸造时校验。
- 撤销租约**必须**级联撤销它的全部子租约。
- 长期访问**必须**以策略包络表达，**不得**做成长期租约。
- 租约**必须**声明敏感级别上限，以及是否允许出口与受保护写入。
- 长期凭据**不得**暴露给模型或运行。

## 借鉴与区别

下面这些都是现成的部件。**真正新的部分：** 以**运行与任务的形状**为单位，把分支、预算与 Rule of Two 的属性放进同一张租约。令牌与能力模型本身都是现成的。

- [OAuth Token Exchange (RFC 8693)](https://www.rfc-editor.org/rfc/rfc8693)
- [OAuth Rich Authorization Requests (RFC 9396)](https://www.rfc-editor.org/rfc/rfc9396)
- [Biscuit](https://github.com/biscuit-auth/biscuit)
- [UCAN](https://ucan.xyz/specification/)
- [IETF attenuating agent tokens draft](https://datatracker.ietf.org/doc/draft-niyikiza-oauth-attenuating-agent-tokens/)

## 坦诚的局限

- 只覆盖 NAS 内的操作，管不到智能体在别处的行为。
- `purpose` 不可强制；预算是近似的。
- 租约不能阻止**合法权限之内**的误用，那是分支和闸门的工作。

## 开放问题

- `purpose` 如何从自由文本走向可机检的结构化意图？
- 预算在联邦下怎样记账？

## 常见问题

### 租约和 API 密钥有什么不同？

API 密钥是长期共享的秘密，持有者能做账号能做的一切。租约绑定一次运行，限定路径、动作和期限，并且只能被收窄；到期即失效，可以随时撤销。

### 为什么不直接用 OAuth？

用的就是 OAuth：租约是访问令牌，靠令牌交换（RFC 8693）申请，用富授权请求（RFC 9396）描述范围。Agent NAS 只补上 OAuth 没有规定的部分：以运行为单位，把分支、预算与 Rule of Two 属性放进同一张授权。

### 租约过期后运行会怎样？

挂载变为只读并随后卸载，新的请求被拒绝并记录。分支保留到它自己的 TTL 到期，所以已完成的工作不会丢，仍然可以经审阅合并。

## 相关概念

- [Human Gate (人类闸门)](https://agentnas.com/zh-cn/concepts/human-gate/): 只在不可逆、对外或提权的动作之前出现，展示真实的差异。
- [Trust Labels (信任标签)](https://agentnas.com/zh-cn/concepts/trust-labels/): 来源与敏感度两个小标签，加上会话污点，强制执行 Rule of Two。
- [Flight Recorder (飞行记录仪)](https://agentnas.com/zh-cn/concepts/flight-recorder/): 以运行为单位、哈希链接的记录，包括这次运行读过什么。

---

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

---

# Human Gate (人类闸门)

*只在不可逆、对外或提权的动作之前出现，展示真实的差异。*

> **Human Gate（人类闸门）** 是由策略触发的检查点：在**不可逆、对外或提权**的动作生效之前，由人（或指定的审批主体）批准一个被完整渲染的具体动作。它被设计成稀少、具体、难以橡皮图章。

**AN-05** · 符合性等级: L1 Authority · 概念簇: 权限

## 要解决的问题

今天的“人在回路”要么是无休止的弹窗，要么什么都没有。Anthropic 披露，Claude Code 用户批准了 93%–97% 的权限提示；在它的受控实验里，人只拦住了 13.6% 被植入的危险命令，会话越长越差。这是厂商为推广自动模式做的研究，测的是识别被植入的提示，不是生产事故率，但方向很清楚。

同一份数据里还有另一个数字：用户对“计划”的拒绝率是 39%，对单个权限请求只有 3%。人会认真判断的，是计划和合并，不是每一次工具调用。

## 工作方式

- **只在少数地方出现：** 合并进受保护树、受保护树中的删除、对外共享或发布、出口、租约扩权、标签降级。分支上的写入不需要审批。
- **粒度是计划或合并。** 评审一个 PR，而不是五十个弹窗。
- **Gate Card 由 NAS 渲染：** 真实的差异、读清单摘要、租约、会话污点，绝不使用智能体的自述。选项：批准、收窄后批准、拒绝；超时默认拒绝。
- **批准绑定动作摘要：** 绑定差异哈希与租约，不能重放。
- **交付：** 推送、聊天、邮件或 CLI；可以委派；passkey 作为可选的强认证。
- **只升不降。** 可选的风险分类器（包括 LLM）只能把动作**升级**到闸门，永远不能**批准**。模型只能收紧，不能放宽。
- **疲劳度量：** 批准率与批准耗时；批准率异常高时，提示合并闸门或收紧策略。

## 从小处开始

- 受保护 main 加 PR 审阅（任何 Git 平台都行），再加一条推送通知。
- 或者一个 CLI：`nas gate approve <gate_id>`。
- 先把 Gate Card 做成“真实的差异”，别急着做花哨的界面。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*gate-card.json*

```json
{
  "gate_id": "gt_2Mx4",
  "run": "run_91ab",
  "action": {
    "op": "merge",
    "from": "cleo/run_91ab",
    "into": "main",
    "files_changed": 4,
    "diff_sha256": "7d2a..."
  },
  "why": "Release notes are ready for review",
  "risk": {
    "session_taint": ["external"],
    "sources": ["web:example.com/changelog"],
    "destructive": false,
    "egress": false
  },
  "options": ["approve", "approve_narrowed", "deny"],
  "default": "deny",
  "expires_at": "2026-11-12T12:00:00Z"
}
```

## 规范的要求

- Gate Card **必须**展示由 NAS 计算出的真实差异，而不是智能体对它的描述。
- 批准**必须**绑定动作摘要与租约，**不得**可重放。
- 超时的默认结果**必须**是拒绝。
- 分类器或 LLM **不得**授予批准；**可以**把动作升级到闸门。
- 合并进受保护树、受保护树中的删除、对外共享、出口、租约扩权、标签降级，**必须**经过闸门。
- NAS **应当**报告批准率与批准耗时。

## 借鉴与区别

下面这些都是现成的做法。**真正新的部分：** 把审批锚定在**存储层的合并**上，并由 NAS（而不是智能体）渲染内容。审批与 PR 本身都是现成的。

- [How we built Claude Code auto mode](https://www.anthropic.com/research/claude-code-auto-mode)
- [Anthropic: approval data behind auto mode](https://claude.com/resources/articles/auto-mode-default-in-claude-code)
- [CaMeL](https://arxiv.org/abs/2503.18813)
- [WebAuthn](https://www.w3.org/TR/webauthn-3/)
- [OpenID CIBA](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html)

## 坦诚的局限

- 人仍然可能批准错误的动作；成批的审阅也会疲劳。
- 通知渠道可能被钓鱼。
- 审批无法阻止它**批准范围之外**的事，那是租约的工作。

## 开放问题

- 批量与分级审阅的最佳界面是什么？
- 自动合并的门槛如何度量与调整？

## 常见问题

### 这不就是又一个“确认”弹窗吗？

刻意不是。弹窗针对每次工具调用，人很快就会点“批准”。闸门只出现在少数不可逆或对外的动作前，展示 NAS 计算出的真实差异，批准还绑定了差异的哈希：差异变了，批准即失效。

### 可以让 LLM 来决定要不要放行吗？

可以让它建议“这一步需要人看”，不能让它批准。放行的决定必须是确定性的规则或人的批准。这条规则让安全性不依赖某个模型的判断。

### 超时会怎样？

默认拒绝。运行会收到一个明确的被拒绝结果，可以改走别的路径，或把提议留在分支里等人处理。

## 相关概念

- [Capability Lease (能力租约)](https://agentnas.com/zh-cn/concepts/capability-lease/): 发给一次运行的、有期限与预算的窄域授权；子租约只能更窄。
- [Trust Labels (信任标签)](https://agentnas.com/zh-cn/concepts/trust-labels/): 来源与敏感度两个小标签，加上会话污点，强制执行 Rule of Two。
- [Agent Branch (智能体分支)](https://agentnas.com/zh-cn/concepts/agent-branch/): 每次运行在写时复制的分支里工作，经审阅的合并才进入主线。

---

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

---

# Trust Labels (信任标签)

*来源与敏感度两个小标签，加上会话污点，强制执行 Rule of Two。*

> **Trust Labels（信任标签）** 是附在数据上的两个很小的标签集，**来源**（`owner`、`agent`、`external`）与**敏感度**（`public`、`private`、`secret`），再加上**会话污点**。NAS 把 Rule of Two 当作会话不变量来强制：一次会话不能同时拥有 [A] 读过外部内容、[B] 接触敏感数据、[C] 改变受保护状态或对外通信；要补全第三项，就走 [Human Gate](https://agentnas.com/zh-cn/concepts/human-gate/)。

**AN-06** · 符合性等级: L3 Guard · 概念簇: 权限

## 要解决的问题

提示词注入之所以奏效，是因为模型分不清“指令”和“数据”。模型层的防御（分类器、提示加固）会漏，攻击者还可以自适应。Meta 在 2025 年 10 月底提出 [Agents Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/)：在注入问题被可靠解决之前，一次会话最多只应同时具备三个性质中的两个。

更可靠的做法是在模型**之外**限定后果。存储恰好是“读”和“写”的必经之地，所以适合把这条规则变成可以测试的不变量。

## 工作方式

- **标签。** 来源 3 档、敏感度 3 档，外加 `reviewed` 标记（由闸门批准设置）。导入点（网页、邮件、上传）默认标为 `external`；密钥扫描器发现凭据时，自动标为 `secret`。
- **会话污点。** 一次运行读过的一切的汇总（来自读清单）；在一个会话内只增不减，新会话重置。
- **不变量。** A = 会话读过 `external`；B = 租约允许读 `private` 或以上（阈值可配置）；C = 租约允许向受保护树提议合并、共享、删除或出口。三者在同一会话里同时成立时，触发 C 的那次调用被拒绝或转交闸门。
- **实际效果：** 在同时具备 B 和 C 的租约下，会话一旦读过外部内容，之后的 C 类动作都要经过人。想避免这种摩擦，就把“读外部内容”放到另一个没有 B 的会话里，只通过结构化交接传递结果。
- **传播。** NAS 自己的派生（索引、摘要）确定性地继承输入标签的并集；运行写入的文件继承该运行的会话污点（保守做法）。
- **降级。** 只能经由 Human Gate，或**结构化交接：** 把受污染会话的输出限定为经 JSON Schema 校验的字段（枚举、ID、有界字符串），校验通过后才允许被特权会话读取。能被确定性校验的，才可能被信任。
- **强制点在网关与挂载层**（它们知道租约与会话），不在模型内部。

## 从小处开始

- 只做两件事：给导入目录里的文件打上 `external`；读过 `external` 的运行默认没有出口和受保护合并的权限，需要闸门。
- 策略用 Cedar 或 Rego 写成确定性的规则，拒绝时给出可读的原因。
- 先用“仅记录”模式跑一周，看看会误拦什么，再打开强制。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*policy.yaml*

```yaml
# Deterministic policy (Cedar- or Rego-style rules can express the same thing)
session_invariant: rule_of_two
properties:
  A: session.read_origin includes "external"
  B: lease.sensitivity_max >= "private"
  C: lease allows propose_protected | share | delete | egress
on_would_complete_ABC: gate        # never "allow"
rules:
  - id: r-merge-1
    when: session.A and op == "merge" and target.protected
    then: gate
  - id: r-secret-1
    when: session.read_sensitivity == "secret" and op == "egress"
    then: deny
```

## 规范的要求

- 每个导入点**必须**赋予默认标签；外部内容**必须**标为 `external`。
- 会话污点**必须**在会话内只增不减。
- 策略求值**必须**是确定的，**不得**调用 LLM。
- 会让同一会话补全 A+B+C 的调用**必须**被拒绝或转交闸门。
- 降级**必须**经过闸门或经模式校验的结构化交接。
- 派生数据**必须**继承其输入标签的并集。

## 借鉴与区别

下面这些都是现成的思路。**真正新的部分：** 在**存储边界**用读清单实现会话污点，并把标签用到记忆写入和派生数据上。我们刻意把标签格缩小到 3×3，因为细粒度的格在实践中会导致标签膨胀。OpenClaw 已经在单个运行时里做了来源标签与隔离，我们的区别只是把它放到共享的存储中。

- [Agents Rule of Two (Meta)](https://ai.meta.com/blog/practical-ai-agent-security/)
- [The lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/)
- [CaMeL](https://arxiv.org/abs/2503.18813)
- [Fides](https://arxiv.org/abs/2505.23643)
- [Design Patterns for Securing LLM Agents against Prompt Injections](https://arxiv.org/abs/2506.08837)
- [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture)

## 坦诚的局限

- 这**不是**提示词注入的防御，它限制的是后果。
- NAS 看不到它之外的工具（浏览器、邮件），需要运行时配合。
- 污点是保守的，会带来摩擦与误报；结构化模式之外的自由文本仍然可以携带攻击者的话。
- 隐蔽信道无法消除。

## 开放问题

- 标签的粒度应当是文件还是段落？
- 多租户下标签词汇表如何治理？
- 如何降低误报？

## 常见问题

### Rule of Two 能防住提示词注入吗？

不能阻止注入发生。它让一次被注入的会话**无法同时**拥有“读过不可信内容、接触敏感数据、能改变受保护状态或对外发送”三项，从而限制后果。Meta 自己也强调它是减轻风险的启发式，不替代最小权限。

### 为什么只有三个来源和三个敏感度？

因为细粒度的标签格在实践中会膨胀、会被关掉。3×3 足够表达“谁写的、有多敏感”，也容易让人理解拒绝的原因。更细的分区可以靠路径与租约来做。

### 会话污点会不会让智能体什么都干不了？

只会限制三类动作：改动受保护树、共享或删除、对外发送。分支内的读写不受影响。需要避开摩擦时，可以把读外部内容的工作放进一个没有敏感数据的会话，只传回经模式校验的结果。

## 相关概念

- [Human Gate (人类闸门)](https://agentnas.com/zh-cn/concepts/human-gate/): 只在不可逆、对外或提权的动作之前出现，展示真实的差异。
- [Agent Memory (智能体记忆)](https://agentnas.com/zh-cn/concepts/agent-memory/): 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
- [Capability Lease (能力租约)](https://agentnas.com/zh-cn/concepts/capability-lease/): 发给一次运行的、有期限与预算的窄域授权；子租约只能更窄。

---

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

---

# Agent Memory (智能体记忆)

*笔记是你能读能改的真相，索引只是可以丢弃的缓存。*

> **Agent Memory（智能体记忆）** = **你能读、能改的笔记** + **可以随时丢弃的索引**。每条笔记都引用它的来源；索引（全文、向量、图、轮廓）只是笔记的派生物；后台维护作业只**提议**修改，绝不改写原始日志。

**AN-07** · 符合性等级: L2 Memory · 概念簇: 知识

## 要解决的问题

记忆框架把记忆放进不透明的数据库：无法检查、对比、迁移、纠正，也难以可靠删除；索引和嵌入模型被绑死。而记忆本身就是攻击面：2026 年的[一项研究](https://arxiv.org/abs/2606.04329)里，持久记忆投毒在两个智能体上的平均攻击成功率达 50.46%；[另一项研究](https://arxiv.org/abs/2607.05189)用一封精心构造的邮件，在文件系统和向量两种记忆后端上都得了手。

同时，“哪种记忆架构最好”远没有定论：基准互相矛盾。一份不押注任何检索算法的设计，才扛得住三年的变化。

## 工作方式

- **笔记是真相。** Markdown 加 YAML frontmatter：`kind`（情景、语义、程序、偏好）、`subject`、`sources`、`confidence`、`valid_from`、`valid_to`、`supersedes`、`origin`、`reviewed`。
- **更新而非覆盖。** 新事实 `supersedes` 旧事实；区分有效时间与记录时间，因为事实会变，而常见基准几乎不测这一点。
- **索引是缓存。** BM25（如 SQLite FTS5）、向量（可以多套并存）、可选的图；每个派生物带**配方**与**输入**。换嵌入模型就是后台重算，旧索引保留到新索引的黄金召回测试达标为止。
- **两类派生。** 确定性的（切块、BM25、固定模型的嵌入）可复现；生成式的（LLM 摘要、抽取出的事实）只能“再生成并比对”，因此标记 `generated: true`，并且从不作为唯一副本。
- **写入路径。** `nas_remember` 把笔记（含来源）写到当前分支；污点随之继承。来自 `external` 污点会话的笔记进入**隔离区**，标记为未审阅：可以被召回，但**不自动加载**，也不会进入 `MEMORY.md`。
- **读取路径。** `nas_recall` = 搜索、候选、预算视图加证据指针，并显示笔记的来源与审阅状态。
- **维护作业**（夜间或空闲时）：去重、把情景整合成语义事实、标记矛盾、让过期的事实失效、重建索引。作业在分支上产出提案，由人或智能体审阅；**绝不删除原始日志**；度量“后悔率”（被回滚的提案比例）。
- **黄金召回测试。** 每个 Home 一组“问题、期望笔记”，换模型或索引器时自动回归。

## 从小处开始

- `memory/notes/*.md` 加 frontmatter；用 SQLite FTS5 做检索。
- 在 CI 里跑十条黄金问题。
- 向量索引和维护作业都可以以后再加；先把“来源”和“已审阅才自动加载”做对。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*memory/notes/customer-acme.md*

```markdown
---
id: mem_4kq2
kind: semantic
subject: customer/acme
valid_from: 2026-10-02
valid_to: null
confidence: 0.8
origin: agent
reviewed: true
sources:
  - nas://home-box/agents/cleo/journal/2026-10-02.md@9f2c1de#L12-L18
supersedes: [mem_1xa9]
---
Acme renewed for 24 months; the champion moved from Dana to Luis.
```

## 规范的要求

- 笔记**必须**能脱离 Memory 层被读取（它们是 Store 里的普通文件）。
- 每个派生物**必须**带配方与输入；索引**必须**可丢弃并可重建。
- 由受污染会话写入的笔记，在被审阅之前**不得**自动加载。
- 新事实**必须**以 `supersedes` 取代旧事实，而不是覆盖。
- 维护作业**必须**在分支上工作并只提议；**不得**删除原始日志。
- 每个 Home **应当**带黄金召回测试，在模型或索引器变化时运行。

## 借鉴与区别

下面这些都是现成的思路，OpenClaw 的记忆架构已经做了来源标签、按层隔离和整合时的污点传播。**真正新的部分：** OpenClaw 在**单个运行时内部**做；我们提议在**共享的存储里**做，让任何运行时都受益；并把索引降为可丢弃的缓存，使检索算法可以更换而记忆不丢。

- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [Letta: is a filesystem all you need?](https://www.letta.com/blog/benchmarking-ai-agent-memory/)
- [OpenClaw memory architecture](https://docs.openclaw.ai/concepts/memory-architecture)
- [Long-term memory security survey](https://arxiv.org/abs/2604.16548)
- [Graphiti](https://github.com/getzep/graphiti)
- [MemGPT](https://arxiv.org/abs/2310.08560)

## 坦诚的局限

- 生成式派生物不可能逐位重现。
- 维护作业可能把错误“固化”成事实，所以它只提议，不直接改。
- 哪种记忆架构最好，目前没有定论。

## 开放问题

- 何时由智能体自己写，何时交给维护作业？
- 跨模型版本的回归标准是什么？

## 常见问题

### 为什么用文件，不用向量数据库？

文件是你能读、能改、能 diff、能带走的真相；向量索引是它的派生缓存，可以并存多套、随时重建。Letta 的基准说明，只给智能体 `grep` 和文件工具就有竞争力，但各家基准互相矛盾，所以设计不押注某一种检索算法。

### 怎样防止记忆被投毒？

无法保证绝不被写入，但可以限制后果：外部来源的内容带着 `external` 标签；受污染会话写的笔记进入隔离区，不自动加载；合并要经过审阅；出了问题可以顺着来源链找到受影响的笔记并回滚。

### 换嵌入模型要迁移记忆吗？

不需要。笔记不变，只是在后台用新的配方重算索引；旧索引保留到新索引的黄金召回测试达标为止。

## 相关概念

- [Budgeted Reads (预算化读取)](https://agentnas.com/zh-cn/concepts/budgeted-reads/): 同一个文件可以用轮廓、章节、行范围或全文来读，按预算降级。
- [Cascade Forget (级联遗忘)](https://agentnas.com/zh-cn/concepts/cascade-forget/): 沿血缘删除派生物，按保留类处理历史，并如实报告做不到的部分。
- [Trust Labels (信任标签)](https://agentnas.com/zh-cn/concepts/trust-labels/): 来源与敏感度两个小标签，加上会话污点，强制执行 Rule of Two。

---

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

---

# Budgeted Reads (预算化读取)

*同一个文件可以用轮廓、章节、行范围或全文来读，按预算降级。*

> **Budgeted Reads（预算化读取）** 是以 token 预算为单位的读取：同一个文件可以用不同的细节来读，从轮廓、章节、行范围到全文；智能体要的是“能装进 N 个 token 的最佳视图”，并附带指回精确来源的证据指针。

**AN-08** · 符合性等级: L2 Memory · 概念簇: 知识

## 要解决的问题

智能体把上下文耗在整文件和重复读取上；朴素的 RAG 切块会丢掉结构。而模型本来就很擅长 `grep`、`tail` 和按行读取：Cursor 把过长的工具输出写成文件让智能体按需读取，在调用了 MCP 工具的运行里，[动态发现](https://cursor.com/blog/dynamic-context-discovery)工具描述让总 token 下降了 46.9%。

所以问题不是“再造一个检索系统”，而是在文件之上给读取一个**有预算、可核对**的契约。

## 工作方式

- **文件优先。** 标准读取（含行范围）永远可用；Budgeted Reads 是它之上的可选扩展，不替代文件系统。
- **确定性轮廓（免费）：** Markdown 标题树、代码符号（tree-sitter）、JSON 与 YAML 的键、CSV 的表头与行数，不需要 LLM。
- **预算与降级。** 请求带 `budget_tokens`；放不下就降级到更粗的视图，**而不是静默截断**；响应声明实际视图、token 数，以及是否 `generated`。
- **搜索返回片段加指针，** 而不是整个文件。
- **证据指针：** `nas://<node>/<tree>/<path>@<commit>#L12-L18`，针对某个提交稳定、可校验；`dereference` 返回精确内容。
- **自上次以来的变化：** 返回两个提交之间的差异，而不是整个文件。
- **可选的 LLM 摘要层：** 作为缓存，标记 `generated: true` 与陈旧标记。

## 从小处开始

- 除了 `nas_read` 什么都不加：让智能体用 `rg`、`sed -n` 这样的老办法读。
- 然后加一个针对 Markdown 与代码的小型轮廓工具。
- 证据指针先用“路径@提交#行号”，不需要新的服务。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*POST /v1/files/read*

```http
POST /v1/files/read
{ "path": "/agents/cleo/memory/notes/customer-acme.md",
  "view": "outline", "budget_tokens": 400 }

200 OK
{ "view": "outline", "tokens": 212, "generated": false, "truncated": false,
  "content": "# Acme\n## Renewal (L12-L18)\n## Contacts (L19-L31)\n## Open issues (L32-L40)",
  "evidence": [
    { "pointer": "nas://home-box/agents/cleo/memory/notes/customer-acme.md@9f2c1de#L1-L40" }
  ] }
```

## 规范的要求

- 响应**必须**声明实际返回的视图与 token 数；生成式视图**必须**标注。
- 预算不足时，NAS **必须**降级到更粗的视图，**不得**静默截断。
- 标准的文件读取（含范围）**必须**保持可用。
- 证据指针**必须**可以对照提交校验。
- 搜索默认**必须**返回片段与指针，而不是整个文件。

## 借鉴与区别

渐进披露和 grep 本身都不新。**真正新的部分：** 把预算与证据指针做成**存储层的读取契约**，让答案可以被核对：你能从一句话回到它来自哪个提交的哪几行。

- [Cursor: dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery)
- [Agent Skills (progressive disclosure)](https://agentskills.io/specification)
- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [RAPTOR](https://arxiv.org/abs/2401.18059)

## 坦诚的局限

- 不同模型的分词器不同，token 数只是估算。
- 只有客户端采用才有效。
- 摘要会陈旧，也可能出错，所以只作缓存、一律标注。

## 开放问题

- 跨模型分词器的预算误差怎么处理？
- 摘要质量如何评估？

## 常见问题

### 它和 RAG 有什么不同？

RAG 返回与问题最接近的片段。Budgeted Reads 让读者对一个已知的对象选择细节层级，预算不足就降级并如实声明，并给出可校验的指针。两者可以叠加：搜索结果也可以以预算视图返回。

### 必须用它才能读文件吗？

不必。挂载与 Git 读到的永远是普通文件；Budgeted Reads 是给在乎 token 的智能体用的可选读取。

### 证据指针能防止“编造出处”吗？

它让出处可以被核对：指针指向某个提交里的具体行，可以校验内容哈希。它不会阻止模型编造，但让“它引用的那一段是否真实存在”变成一次机器检查。

## 相关概念

- [Agent Memory (智能体记忆)](https://agentnas.com/zh-cn/concepts/agent-memory/): 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
- [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/budgeted-reads/
更新于: 2026-11-11 · 规范草案 v0.2 · CC BY 4.0

---

# Cascade Forget (级联遗忘)

*沿血缘删除派生物，按保留类处理历史，并如实报告做不到的部分。*

> **Cascade Forget（级联遗忘）** 是沿血缘的删除：当一个来源被删除，或有人要求被遗忘时，NAS 找出由它派生的一切，包括摘要、嵌入、引用它的笔记、缓存和共享链接，删除它们，或在不含该来源的情况下重新派生，并出具**报告**：做了什么，哪些做不到。

**AN-09** · 符合性等级: L3 Guard · 概念簇: 知识

## 要解决的问题

删除一个文件，并不会删除它的嵌入、摘要，或记忆里据此推出的事实；快照与备份还在；版本历史里内容依然存在。

“可恢复”与“可遗忘”是同一条轴的两端，多数系统没有把这个选择交给人。如果在写入之后才想起要忘，通常已经太晚。

## 工作方式

- **血缘。** 每个派生物记录自己的输入；反向索引回答“X 的所有依赖物”；笔记的 `sources` 字段也是血缘。
- **保留类，在写入时决定**（因为历史无法事后改写）：`scratch`（短 TTL，不进备份，运行结束即可清理）、`normal`（版本化，可恢复）、`sensitive`（独立密钥域，可以通过销毁密钥来粉碎）。
- **恢复与遗忘的张力。** 软删除窗口内可恢复；窗口过后才硬删除；遗忘请求可以跳过窗口。
- **流程。** 请求（由人或运营者发起；智能体只能提出请求，不能执行），血缘遍历，删除派生物并对混合来源的事实重新派生，对 `normal` 类重写受影响路径的历史并清理快照，对 `sensitive` 类销毁密钥，最后出具报告。
- **报告：** 删除的文件数、被移除的派生物、历史是否重写、被销毁的密钥、尚未过期的快照，以及**明确列出覆盖不到的范围**：NAS 之外的副本、模型提供商的日志、模型权重。
- 总是经过 [Human Gate](https://agentnas.com/zh-cn/concepts/human-gate/)（或策略预授权）；**法律保留**会阻止遗忘并被记录。

## 从小处开始

- 先做保留类和软删除，并为每个派生物记录它的输入。
- 先做到“删除源文件时，列出并删除它的全部派生物”。
- 加密粉碎留给 `sensitive` 类，不必一开始就全量做。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*forget-report.json*

```json
{
  "forget_id": "fgt_3b7c",
  "selector": { "paths": ["/shared/crm/acme/**"], "subject": "customer/acme" },
  "retention_class": "sensitive",
  "report": {
    "files_removed": 142,
    "derived_removed": { "embeddings": 3621, "summaries": 210, "notes_rewritten": 6 },
    "history": "rewritten (3 commits)",
    "keys_destroyed": ["key_acme"],
    "snapshots_pending": ["nightly-2026-11-10 (expires 2026-11-17)"],
    "not_covered": ["copies outside the NAS", "model provider logs", "model weights"]
  },
  "state": "pending_expiry"
}
```

## 规范的要求

- 遗忘**必须**沿血缘从来源传播到每一个派生物。
- 保留类**必须**在写入时指定（默认 `normal`）。
- 遗忘报告**必须**列出覆盖不到的范围：NAS 之外的副本、提供商日志、模型权重。
- 法律保留**必须**阻止遗忘，并且**必须**被记录。
- 智能体**可以**请求遗忘，但**不得**执行。
- 报告**不得**声称模型已经“遗忘”了什么。

## 借鉴与区别

下面这些都是现成的。**真正新的部分：** 把**保留类**当作存储的显式属性，并承认“能恢复”与“能遗忘”是同一条轴上的取舍。

- [OpenLineage](https://openlineage.io)
- [GDPR Article 17](https://gdpr-info.eu/art-17-gdpr/)
- [Long-term memory security survey (forget and rollback)](https://arxiv.org/abs/2604.16548)

## 坦诚的局限

- 备份、NAS 之外的副本、模型提供商的日志都不在范围内。
- 对由多个来源混合推断出的事实，“受影响范围”很难界定。
- 重写历史的代价很高，也有风险。

## 开放问题

- 混合来源事实的受影响范围怎么界定？
- 法律保留与遗忘请求冲突时，流程应当怎样走？

## 常见问题

### 它能让模型忘记吗？

不能，也不会这么声称。它能做的是删除 NAS 里的文件、派生物，以及（在 `sensitive` 类下）历史与密钥；模型提供商的日志与模型权重不在范围内，报告里会明确列出来。

### 为什么要在写入时选保留类？

因为历史难以事后改写：已经进了备份和历史的内容，只能重写或等过期。写入时决定它是 `scratch`、`normal` 还是 `sensitive`，是之后能删得干净的前提。

### 智能体可以自己要求遗忘吗？

可以提出请求，不能执行。遗忘不可逆，必须经过人或预授权的策略，而且法律保留会阻止它。

## 相关概念

- [Agent Memory (智能体记忆)](https://agentnas.com/zh-cn/concepts/agent-memory/): 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
- [Flight Recorder (飞行记录仪)](https://agentnas.com/zh-cn/concepts/flight-recorder/): 以运行为单位、哈希链接的记录，包括这次运行读过什么。
- [Agent Branch (智能体分支)](https://agentnas.com/zh-cn/concepts/agent-branch/): 每次运行在写时复制的分支里工作，经审阅的合并才进入主线。

---

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