Budgeted Reads 预算化读取

要解决的问题 #

智能体把上下文耗在整文件和重复读取上；朴素的 RAG 切块会丢掉结构。而模型本来就很擅长 grep、tail 和按行读取：Cursor 把过长的工具输出写成文件让智能体按需读取，在调用了 MCP 工具的运行里，动态发现工具描述让总 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
{ "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
• Agent Skills (progressive disclosure)
• Letta Context Repositories
• RAPTOR

坦诚的局限 #

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

开放问题 #

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

常见问题 #

相关概念 #

• Agent Memory (智能体记忆) 笔记是你能读能改的真相，索引只是可以丢弃的缓存。
• Agent Home (智能体之家) 按角色划分、带历史的目录，全是普通文件，可以带走。
• Flight Recorder (飞行记录仪) 以运行为单位、哈希链接的记录，包括这次运行读过什么。