介面

準則 #

1. 資料面用檔案，控制面用工具。 位元組走掛載、Git、S3；授權、審批、記憶、搜尋與解釋走 MCP、HTTP 與 CLI。
2. 閘道器無狀態。 授權只發生在 Trust 層的一個點上。
3. 每個介面都是投影。 語義差異用明確的錯誤對映表達（例如「閘門待處理」對映成一個帶說明檔案的 EACCES），不假裝 S3 有分支。
4. 窄工具面。 面向智能體的 MCP 工具不超過 10 個；人與運營者的動作放在單獨的操作員介面裡。
5. 轉接器隔離協定變化。 MCP、A2A 的版本演進隻影響轉接器。

介面矩陣 #

MCP 工具面 #

面向智能體的只有九個工具：

掛載語義 #

• 掛載綁定一個分支和一張租約；租約到期後掛載變為只讀，隨後解除安裝。
• 自動提交（防抖，例如靜默 5 秒）；fsync 會觸發一次提交。
• 租約之外的路徑不出現在目錄列表裡：這減少資訊洩露，也縮小了提示注入的攻擊面。
• 對沙箱友好：不需要 root；FUSE 與 NFS 二選一，不需要核心模組；可以只讀掛載。

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。
• 預算與限流透過回應標頭回饋（剩餘位元組、剩餘請求數），便於執行環境自我節制。

預算化讀取的請求與回應大致如下：

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" }
  ] }

錯誤使用統一的結構：

{
  "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。