---
title: "Agent 接口设计 (Agent Interface Design)"
created: 2026-07-04
updated: 2026-07-04
type: concept
tags: [agent, interface, design, token-efficiency, workspace]
sources: ["https://nokv.io/blog/agents-want-filesystems"]
---

# Agent 接口设计 (Agent Interface Design)

面向 AI Agent 的工具和数据接口设计方法论。核心主张：决定 Agent 效率的变量不只有模型和提示词，还包括 Agent 面对的操作界面（Interface/Surface）。

## 核心原则

1. **[[progressive-disclosure|渐进式披露]]**：先发现 → 再按需读取，不要预加载全部
2. **路径是稳定句柄**：语义化路径（如 `/runs/abc/stdout.log`）既是名称也是地址
3. **[[pushdown-in-agent-interface|下推]]**：过滤/排序/limit/投影一次完成
4. **限定范围搜索**：全局发现 + 局部精确提取
5. **引用原生性**：行号、偏移量等引用形式天然适合审计和 debug

## 为什么文件系统语义特别匹配

LLM 被训练在大量 shell、Unix、Git、日志排查语料上——「进入目录 → 列文件 → 搜关键词 → 打开局部内容 → 引用行号」是模型内在熟练的工作模式。接口设计与模型能力对齐，比强行适配更能发挥模型效能。

## 外部收敛信号

- Anthropic MCP code execution：TypeScript 文件树 → 150k → 2k token
- OpenAI tool search：建议 namespace/MCP server 按需加载
- Letta memory benchmark：文件组织对话历史 → 竞争力结果

## 参考

- [[agent-workspace-filesystem|Agent 工作空间文件系统]]
- [[agents-want-filesystems-nokv-2026|新智元报道]]
- [[token-efficiency|Token 效率]]
- [[workspace-first-architecture|Workspace-first 架构]]
- [[harness-engineering|Harness Engineering]]