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-tw/architecture/