# Budgeted Reads (预算化读取)

*同一个文件可以用轮廓、章节、行范围或全文来读，按预算降级。*

> **Budgeted Reads（预算化读取）** 是以 token 预算为单位的读取：同一个文件可以用不同的细节来读，从轮廓、章节、行范围到全文；智能体要的是“能装进 N 个 token 的最佳视图”，并附带指回精确来源的证据指针。

**AN-08** · 符合性等级: L2 Memory · 概念簇: 知识

## 要解决的问题

智能体把上下文耗在整文件和重复读取上；朴素的 RAG 切块会丢掉结构。而模型本来就很擅长 `grep`、`tail` 和按行读取：Cursor 把过长的工具输出写成文件让智能体按需读取，在调用了 MCP 工具的运行里，[动态发现](https://cursor.com/blog/dynamic-context-discovery)工具描述让总 token 下降了 46.9%。

所以问题不是“再造一个检索系统”，而是在文件之上给读取一个**有预算、可核对**的契约。

## 工作方式

- **文件优先。** 标准读取（含行范围）永远可用；Budgeted Reads 是它之上的可选扩展，不替代文件系统。
- **确定性轮廓（免费）：** Markdown 标题树、代码符号（tree-sitter）、JSON 与 YAML 的键、CSV 的表头与行数，不需要 LLM。
- **预算与降级。** 请求带 `budget_tokens`；放不下就降级到更粗的视图，**而不是静默截断**；响应声明实际视图、token 数，以及是否 `generated`。
- **搜索返回片段加指针，** 而不是整个文件。
- **证据指针：** `nas://<node>/<tree>/<path>@<commit>#L12-L18`，针对某个提交稳定、可校验；`dereference` 返回精确内容。
- **自上次以来的变化：** 返回两个提交之间的差异，而不是整个文件。
- **可选的 LLM 摘要层：** 作为缓存，标记 `generated: true` 与陈旧标记。

## 从小处开始

- 除了 `nas_read` 什么都不加：让智能体用 `rg`、`sed -n` 这样的老办法读。
- 然后加一个针对 Markdown 与代码的小型轮廓工具。
- 证据指针先用“路径@提交#行号”，不需要新的服务。

## 接口草图

仅作示意。字段名在规范 v0.3 之前可能调整。

*POST /v1/files/read*

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

## 规范的要求

- 响应**必须**声明实际返回的视图与 token 数；生成式视图**必须**标注。
- 预算不足时，NAS **必须**降级到更粗的视图，**不得**静默截断。
- 标准的文件读取（含范围）**必须**保持可用。
- 证据指针**必须**可以对照提交校验。
- 搜索默认**必须**返回片段与指针，而不是整个文件。

## 借鉴与区别

渐进披露和 grep 本身都不新。**真正新的部分：** 把预算与证据指针做成**存储层的读取契约**，让答案可以被核对：你能从一句话回到它来自哪个提交的哪几行。

- [Cursor: dynamic context discovery](https://cursor.com/blog/dynamic-context-discovery)
- [Agent Skills (progressive disclosure)](https://agentskills.io/specification)
- [Letta Context Repositories](https://www.letta.com/blog/context-repositories/)
- [RAPTOR](https://arxiv.org/abs/2401.18059)

## 坦诚的局限

- 不同模型的分词器不同，token 数只是估算。
- 只有客户端采用才有效。
- 摘要会陈旧，也可能出错，所以只作缓存、一律标注。

## 开放问题

- 跨模型分词器的预算误差怎么处理？
- 摘要质量如何评估？

## 常见问题

### 它和 RAG 有什么不同？

RAG 返回与问题最接近的片段。Budgeted Reads 让读者对一个已知的对象选择细节层级，预算不足就降级并如实声明，并给出可校验的指针。两者可以叠加：搜索结果也可以以预算视图返回。

### 必须用它才能读文件吗？

不必。挂载与 Git 读到的永远是普通文件；Budgeted Reads 是给在乎 token 的智能体用的可选读取。

### 证据指针能防止“编造出处”吗？

它让出处可以被核对：指针指向某个提交里的具体行，可以校验内容哈希。它不会阻止模型编造，但让“它引用的那一段是否真实存在”变成一次机器检查。

## 相关概念

- [Agent Memory (智能体记忆)](https://agentnas.com/zh-cn/concepts/agent-memory/): 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
- [Agent Home (智能体之家)](https://agentnas.com/zh-cn/concepts/agent-home/): 按角色划分、带历史的目录，全是普通文件，可以带走。
- [Flight Recorder (飞行记录仪)](https://agentnas.com/zh-cn/concepts/flight-recorder/): 以运行为单位、哈希链接的记录，包括这次运行读过什么。

---

规范网址: https://agentnas.com/zh-cn/concepts/budgeted-reads/
更新于: 2026-11-11 · 规范草案 v0.2 · CC BY 4.0