Skip to content

38-read-file-state-and-context-cache-mechanics.md

Latest commit

 

History

History
128 lines (83 loc) · 5.03 KB

38-read-file-state-and-context-cache-mechanics.md

File metadata and controls

128 lines (83 loc) · 5.03 KB

38. ReadFileState、Context Cache 与 Partial View 机制

所属专题簇：记忆与上下文算法深挖

建议前读：07. QueryEngine 与上下文

建议后读：35. CLAUDE.md 加载算法与指令装配 或 32. Harness 与 Eval Runtime

研究问题

readFileState、context memoize cache 和 partial view 到底只是性能优化，还是 Claude Code 长会话治理的一部分？

一句话结论

它们不只是优化。Claude Code 用 readFileState 跟踪“模型到底看过哪个文件视图”，用 context cache 固定跨轮注入内容，再通过 cache invalidation 和 partial view 标记维持上下文一致性与安全边界。

这篇讲什么

这一章解释文件读取状态、上下文缓存与 partial view 如何共同构成 Claude Code 的会话记忆卫生机制。

如果你不看源码，只看这一章，应该记住什么

  • readFileState 记录的不是“磁盘上有什么”，而是“模型看过什么视图”。
  • partial view 表示模型看过的是处理后的文件视图，不等于磁盘原文。
  • context cache 的清理是显式的，尤其在 cache breaking injection 场景下。

源码依据

Mermaid 图：文件视图与上下文缓存流程图

flowchart TD
    A["磁盘文件"] --> B["Read / auto-injection"]
    B --> C["readFileState"]
    C --> D["content + timestamp + offset/limit + isPartialView"]
    D --> E["QueryEngine 跨轮共享"]
    E --> F["去重 / 变更检测 / memory path 汇总"]
    G["getSystemContext / getUserContext memoize"] --> H["会话级固定上下文"]
    I["systemPromptInjection 变化"] --> J["clear caches"]
    J --> G
Loading

readFileState 的语义比缓存更强

src/utils/fileStateCache.ts 里 FileState 至少包含：

  • content
  • timestamp
  • offset
  • limit
  • isPartialView

特别是 isPartialView 的注释很关键：如果 auto-injection 只让模型看到 stripped / truncated 版本，那么 Edit/Write 仍然要求显式 Read。也就是说，这不是纯性能缓存，而是模型视图的记录。

partial view 是安全与一致性边界

同一注释明确举了 partial view 的来源：

  • stripped HTML comments
  • stripped frontmatter
  • truncated MEMORY.md

这说明 Claude Code 明确知道“模型看到的并不是磁盘全文”，因此后续编辑权限不能假装它已经完整读过该文件。

QueryEngine 把 readFileState 当长期会话状态持有

src/QueryEngine.ts 里：

  • readFileState 是成员变量
  • 通过 readFileCache 注入
  • 跨 submitMessage() 持续存在

这表明 Claude Code 不是每轮都忘记“模型之前读过什么文件”，而是在维护一份跨轮文件认知状态。

context cache 也是会话级的

src/context.ts 里 getSystemContext 和 getUserContext 都是 memoize 的，注释还明确说：

  • context is prepended to each conversation
  • cached for the duration of the conversation

所以这里缓存的不是某个函数结果，而是“这次会话的固定上下文切片”。

cache invalidation 是显式设计的

同一文件中的 setSystemPromptInjection() 会：

  • 更新 systemPromptInjection
  • 立即清空 getUserContext.cache
  • 立即清空 getSystemContext.cache

这说明 Anthropic 已经意识到 context cache 不是“永远安全可复用”，而是在某些 debug / cache-break 路径下必须强制失效。

claudemd.ts 会从 readFileState 反向汇总 memory paths

getMemoryFilesFromReadFileState() 之类逻辑说明：

  • 自动注入或读过的 memory 文件，会被纳入 path 汇总
  • readFileState 不只服务 Read tool，也服务 memory 装配与 dedup

这让它更像“会话文件知识库”，而不是工具内部缓存。

为什么这层对研究很重要

很多上下文系统的问题，不在“怎么读文件”，而在：

  • 模型到底看过什么
  • 它看的是原文还是变形视图
  • 下一轮还能不能假设之前读过的视图仍然有效

Claude Code 在这层给出了明确回答，这也是它比普通 CLI agent 更工程化的地方。

你真正应该记住的点

  • readFileState 是模型视图状态，不只是 I/O cache。
  • partial view 是 Claude Code 在自动注入和安全边界之间做的显式标记。
  • context cache 与 cache invalidation 共同构成会话级上下文卫生机制。

延伸阅读