# 介面

> 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-tw/concepts/budgeted-reads/) |
| `nas_search` | 搜尋（全文，可選向量），返回片段與指標 | `read` | 預設不返回隔離區。 |
| `nas_write` | 寫入分支內的檔案，可附 `intent` | `write` | 多數執行環境直接用掛載，不需要它。 |
| `nas_branch` | 建立、檢查點、恢復、列出分支 | `write` | [Agent Branch](https://agentnas.com/zh-tw/concepts/agent-branch/) |
| `nas_propose` | 生成 Agent PR | `propose` | 可能觸發閘門。 |
| `nas_lease` | 申請更窄的子租約；查詢當前租約與預算；請求擴權（走閘門） | 無 | [Capability Lease](https://agentnas.com/zh-tw/concepts/capability-lease/) |
| `nas_remember` | 寫入筆記，含來源與型別 | `write` | [Agent Memory](https://agentnas.com/zh-tw/concepts/agent-memory/) |
| `nas_recall` | 召回筆記：預算化，含來源與審閱狀態 | `read` | [Agent Memory](https://agentnas.com/zh-tw/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-tw/interfaces/
更新於: 2026-11-11 · 規範草案 v0.2 · CC BY 4.0