接口

准则 #

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。