# 架構

> 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-tw/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-tw/architecture/
更新於: 2026-11-11 · 規範草案 v0.2 · CC BY 4.0