Everything Claude Code 的 content-hash-cache-pattern Skill，提供了一种基于 SHA-256 内容哈希的文件处理缓存模式。它让缓存与文件路径解耦，文件重命名/移动也能命中缓存，内容变更则自动失效。适用于 PDF 解析、文本抽取、图片分析等高成本任务，支持 CLI --cache/--no-cache 切换，且可无侵入地为现有纯函数添加缓存层，大幅提升 AI 辅助编程的批量处理效率。

Everything Claude Code Content Hash Cache Pattern：SHA-256 内容哈希缓存，路径无关、自动失效

在 AI 编程助手（如 Claude Code、Codex、Cursor）驱动的自动化开发场景中，文件处理（如 PDF 解析、文本抽取、图片分析）往往是高成本、重复性强的任务。传统的缓存方式多依赖文件路径作为 key，导致文件一旦重命名或移动就会缓存失效，带来重复计算和资源浪费。Everything Claude Code 推出的 content-hash-cache-pattern Skill，通过 SHA-256 内容哈希作为缓存主键，实现了路径无关、内容变更自动失效的缓存机制，极大提升了批量处理和多 Agent 协作时的效率与稳定性。

本指南将结合实际项目场景，详细讲解如何用好 content-hash-cache-pattern Skill，包括适用场景、激活条件、分步操作流程、输出示例、常见配套 Agent 及与其他 Skill 的协作关系。你也可以参考 Everything Claude Code 完全指南 了解更多 Skill 与 Agent 的组合应用思路。

---

1. 这个 Skill 解决什么问题？

核心痛点：

• 文件处理任务（如 PDF 解析、OCR、图片分析）成本高、重复性强。
• 路径作为缓存 key，文件移动/重命名就会导致缓存失效。
• 需要支持 CLI 层面的 --cache/--no-cache 开关，且希望对现有纯函数无侵入加缓存。
• 传统做法下，缓存与业务逻辑耦合，维护困难，易出错。

content-hash-cache-pattern Skill 的优势：

• 以 SHA-256 内容哈希为缓存 key，文件路径变动不影响缓存命中。
• 内容变更自动失效，无需额外索引或手动清理。
• 缓存逻辑完全与处理函数解耦，易于维护和扩展。
• 支持大文件分块哈希，内存友好。
• 适配 CLI 工具、批量处理、Agent 自动化等多种场景。

---

2. 什么时候激活（触发条件）

• 你在构建文件处理 Pipeline（如批量 PDF 解析、图片 OCR、文本抽取）。
• 处理单个文件的成本较高，且同一文件会被重复处理（如多次运行、并行 Agent）。
• 需要为 CLI 工具或自动化流程增加 --cache 或 --no-cache 选项。
• 希望在不修改原有纯处理函数的前提下，为其加上缓存能力。
• 你的 Agent/Skill 需要在多次运行间共享处理结果，避免重复消耗算力或 API 配额。

---

3. Step by Step：实际项目中的使用流程

步骤 1：用内容哈希生成缓存 key

用 SHA-256 对文件内容分块计算哈希，确保即使文件路径变动也能唯一标识内容。

import hashlib
from pathlib import Path

def compute_file_hash(path: Path) -> str:
    """对文件内容分块计算 SHA-256 哈希，适合大文件。"""
    sha256 = hashlib.sha256()
    with open(path, "rb") as f:
        while chunk := f.read(65536):  # 64KB
            sha256.update(chunk)
    return sha256.hexdigest()

效果：

• 文件内容不变，哈希不变，移动/重命名也能命中缓存。
• 文件内容变更，哈希自动变化，缓存自动失效。

---

步骤 2：定义缓存数据结构（Frozen Dataclass）

用不可变 dataclass 存储缓存条目，便于序列化和一致性校验。

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class CacheEntry:
    file_hash: str
    source_path: str
    document: dict  # 这里以 dict 代替实际解析结果类型

---

步骤 3：实现文件级缓存存取逻辑

每个缓存条目以 {hash}.json 命名，O(1) 查找，无需维护索引文件。

import json

def write_cache(cache_dir: Path, entry: CacheEntry) -> None:
    cache_dir.mkdir(parents=True, exist_ok=True)
    cache_file = cache_dir / f"{entry.file_hash}.json"
    cache_file.write_text(json.dumps(entry.__dict__, ensure_ascii=False), encoding="utf-8")

def read_cache(cache_dir: Path, file_hash: str) -> CacheEntry | None:
    cache_file = cache_dir / f"{file_hash}.json"
    if not cache_file.is_file():
        return None
    try:
        data = json.loads(cache_file.read_text(encoding="utf-8"))
        return CacheEntry(**data)
    except (json.JSONDecodeError, ValueError, KeyError):
        return None  # 缓存损坏时自动降级为未命中

---

步骤 4：用服务层包装纯处理函数，实现缓存透明接入

保持核心处理函数纯净，无需感知缓存。缓存逻辑单独实现，便于维护和测试。

def extract_with_cache(
    file_path: Path,
    *,
    cache_enabled: bool = True,
    cache_dir: Path = Path(".cache"),
) -> dict:
    if not cache_enabled:
        return extract_text(file_path)  # 纯函数，无缓存逻辑

    file_hash = compute_file_hash(file_path)
    cached = read_cache(cache_dir, file_hash)
    if cached is not None:
        print(f"Cache hit: {file_path.name} (hash={file_hash[:12]})")
        return cached.document

    print(f"Cache miss: {file_path.name} (hash={file_hash[:12]})")
    doc = extract_text(file_path)
    entry = CacheEntry(file_hash=file_hash, source_path=str(file_path), document=doc)
    write_cache(cache_dir, entry)
    return doc

使用示例：

# 假设 extract_text 是你的 PDF/图片/文本处理主函数
result = extract_with_cache(Path("docs/sample.pdf"), cache_enabled=True)

---

步骤 5：CLI/Agent 集成与 Skill 协作

• 在 CLI 工具中加上 --cache/--no-cache 选项，控制是否启用缓存。
• 在多 Agent 协作流程中，所有 Agent 共享同一缓存目录，避免重复处理。
• 可与 Continuous Agent Loop Skill、Agent Harness Construction 等协作，实现大规模自动化批量处理时的高效缓存。

---

4. 输出示例

假设你有一批 PDF 文件，反复解析内容：

首次处理：

Cache miss: sample.pdf (hash=1a2b3c4d5e6f...)
[解析结果输出]

第二次处理（即使文件已移动或重命名）：

Cache hit: sample.pdf (hash=1a2b3c4d5e6f...)
[直接返回缓存结果，无需重新解析]

内容变更后：

Cache miss: sample.pdf (hash=7f8e9a0b1c2d...)
[内容变了，自动失效，重新处理]

---

5. 常见配套 Agent 与 Skill 协作

• 配套 Agent：
  • Doc Updater Agent：批量文档更新时避免重复解析。
  • Repo Scan Agent：大规模源码扫描时缓存解析结果。
  • E2E Runner Agent：自动化测试生成与结果缓存。
• Skill 协作：
  • Continuous Agent Loop Skill：持续循环处理时，缓存极大提升效率。
  • Agent Harness Construction Skill：为 Agent 流水线无侵入加缓存层。
  • Context Budget Skill：缓存减少 token 占用，提升上下文利用率。

---

6. 常见问题与注意事项

Q: 这种缓存模式适合哪些场景？ A: 适用于文件内容处理（如 PDF、图片、文本等）高成本、重复性强的场景，尤其适合 CLI 工具、Agent 自动化、批量处理等。

Q: 内容哈希缓存会不会误命中？ A: 只要文件内容完全一致（无论路径、文件名如何变化），哈希就一致，缓存命中。内容变动则自动失效，不会误用老结果。

Q: 如果缓存文件损坏怎么办？ A: 设计上会自动降级为“未命中”，重新处理文件，不会导致崩溃或错误传播。

---

通过 content-hash-cache-pattern Skill，你可以为 AI 编程助手和自动化流程无侵入地加上高效、健壮的缓存机制，极大提升批量处理和多 Agent 协作的效率。更多高级用法和自动化集成，可参考 Claude Code 高级技巧 和 Everything Claude Code Hooks 实战。