本页译自英文文档。命令、标识符和示例保持原样。运行时 7.24.4 · SDK 2.6.7。 英文原文
本地证据缓存
状态：默认启用内存；RocksDB 为可选加入
范围：当前状态
最近审阅：2026-09-13
负责人：ax-code 运行时
AX Code 默认使用有界的内存证据缓存，并可在现有 SQLite 存储旁选择 RocksDB 持久化。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 回退出现在运行时日志中。不会自动上传反馈或缓存的源内容。现有已发布二进制文件只有在安装更新后的发行版之后才会获得这些默认值。