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 (飛行記錄器) 以執行為單位、雜湊連結的記錄，包括這次執行讀過什麼。