本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文
本機證據快取
狀態：記憶體預設啟用；RocksDB 須自行啟用
範圍：現行狀態
上次審閱：2026-09-13
負責人：ax-code runtime
AX Code 預設使用有界限的記憶體內證據快取，並可選擇以 RocksDB 持久化，與其既有的 SQLite 儲存並存。SQLite 保留完整的工作階段歷史與驗證記錄。快取含有可丟棄的已呈現文字與語法符號；它不會改變權限，也不算新的驗證。
預設的記憶體模式不會開啟 RocksDB 資料庫。若要在原始碼安裝中選擇持久化，請組建其原生支援並明確選取 RocksDB：
pnpm build:native fs
AX_CODE_EVIDENCE_CACHE=rocksdb pnpm run devAX_CODE_EVIDENCE_CACHE=memory 明確選取預設的、有界限的處理程序內重用，不含持久儲存。在 RocksDB 模式中，缺少原生支援、資料庫鎖被另一個執行環境持有，或快取失敗，都會退回記憶體並附診斷。標準檔案系統附加元件組建包含 RocksDB，供明確選擇啟用。發行組建會驗證已封裝的附加元件可以寫入並重新開啟其快取。原生操作在 JavaScript 事件迴圈之外執行。
最多 1 MiB 的文字讀取會驗證目前的原始碼位元組，並在內容、路徑、範圍與格式相符時重用已呈現的範圍。較大的檔案、外部讀取、目錄與附件不會進入讀取快取。儲存庫指示與檔案讀取戳記保持即時。語法擷取可以為相同的原始碼與語言重用符號；這些符號不建立語意引用或呼叫者。
無論哪種快取模式，目前模型請求中已經可見的重複完整文字讀取結果，會使用指向第一個結果的短引用。原始的完整工具輸出仍留在工作階段歷史中。壓縮會重建可見性；若較早的複本不存在，稍後的讀取會完整呈現。重複且位元組相同的分頁讀取、grep 與 glob 檢視，也可以引用第一個完整回傳的檢視。每個引用都保留原本的截斷頁尾與續讀指引；被省略的原始碼內容仍然不可用。帶有指示、媒體、錯誤、被截斷行，以及無法辨識的部分結果，都保持逐字。這改變的是模型輸入，不是標準歷史或工具執行，也不構成供應商計費減少。
快取命中省下呈現或剖析；它們不會省掉原始碼驗證讀取，也不會省掉模型要求的工具呼叫。若要把相依的探索併成較少的模型往返，請明確啟用既有的 experimental.read_only_recipes 選項，並以有界限的選取使用 read_recipe。若要有界限的結構概觀，請使用 code_intelligence，並帶上 operation: "buildContext"。快取不會自動啟用這兩個選項。
選取之後，持久快取位於一般 AX Code 快取目錄中的 evidence-v1，每個專案執行個體目錄有各自的資料庫。RocksDB 准入上限為 1024 個項目與 32 MiB 的邏輯值；實體磁碟用量還包括編碼、日誌與壓縮負擔。兩種模式都把記憶體內重用限制為每個處理程序、每個專案執行個體 128 個項目與 4 MiB 的序列化值；這不是整個處理程序的 RAM 上限。記憶體項目在執行個體處置時清除，處理程序結束後不會留下。項目在 24 小時後過期，並在查詢時驗證。容量淘汰可能整批清除可丟棄的原生項目。既有的 SQLite 資料不會被遷移或回填。
若要同時停用儲存重用與模型輸入去重，請設定 AX_CODE_EVIDENCE_CACHE=off 並重新啟動 AX Code。未設定或空白值使用記憶體；無法辨識的非空白值會停用快取。請重新啟動既有執行環境以套用新的預設，並移除任何明確的 rocksdb 覆寫以使用記憶體。既有的持久快取檔案會保留。不需要 SQLite 回滾。手動移除 evidence-v1 之前請先停止執行環境；執行環境正在使用快取時，不要移除 RocksDB 鎖定檔。
組建此功能之後，若要做本機原生資格確認：
cd packages/ax-code
AX_TEST_EVIDENCE_NATIVE=1 AX_TEST_FILES=test/evidence/cache-native.test.ts,test/evidence/cache-eval.test.ts pnpm exec vitest run --retry 0固定治具評估會分別報告要求的讀取、呈現命中、省略的輸出位元組與經過時間。它不是即時模型基準，也不是關於供應商 token 計費的主張。
回報問題時，請附上 AX Code 版本、作業系統／架構、ax-code doctor 輸出、off 或 memory 是否改變行為，以及若有的可重現工作。Doctor 會報告要求的模式與原生能力；它無法判斷是否有另一個執行中的處理程序擁有專案快取。專案鎖定／I/O 退回會出現在執行環境日誌中。回饋或快取的原始碼內容不會自動上傳。既有已發布的二進位檔只有在安裝更新的發行版本之後，才會取得這些預設。