# 接口

> 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