# 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-tw/concepts/agent-memory/): 筆記是你能讀能改的真相，索引只是可以丟棄的快取。
- [Agent Home (智能體之家)](https://agentnas.com/zh-tw/concepts/agent-home/): 按角色劃分、帶歷史的目錄，全是普通檔案，可以帶走。
- [Flight Recorder (飛行記錄器)](https://agentnas.com/zh-tw/concepts/flight-recorder/): 以執行為單位、雜湊連結的記錄，包括這次執行讀過什麼。

---

標準網址: https://agentnas.com/zh-tw/concepts/budgeted-reads/
更新於: 2026-11-11 · 規範草案 v0.2 · CC BY 4.0