Agent skill · software engineering · affaan-m
content-hash-cache-pattern
使用SHA-256内容哈希缓存昂贵的文件处理结果——路径无关、自动失效、服务层分离。
Why this skill is useful
Provides a caching pattern using SHA-256 content hashes that optimizes file processing and is not commonly found in public documentation.
What it needs
About 2k tokens when loaded. Last updated 2026-08-06. 238,342 stars on the source repository.
What this skill does
内容哈希文件缓存模式 使用 SHA-256 内容哈希作为缓存键，缓存昂贵的文件处理结果（PDF 解析、文本提取、图像分析）。与基于路径的缓存不同，此方法在文件移动/重命名后仍然有效，并在内容更改时自动失效。 何时激活 构建文件处理管道时（PDF、图像、文本提取） 处理成本高且同一文件被重复处理时 需要一个 --cache/--no-cache CLI 选项时 希望在不修改现有纯函数的情况下为其添加缓存时 核心模式 1. 基于内容哈希的缓存键 使用文件内容（而非路径）作为缓存键： 为什么使用内容哈希？ 文件重命名/移动 = 缓存命中。内容更改 = 自动失效。无需索引文件。 2. 用于缓存条目的冻结数据类 3. 基于文件的缓存存储 每个缓存条目都存储为 {hash}.json —— 通过哈希实现 O(1) 查找，无需索引文件。 4. 服务层包装器（单一职责原则） 保持处理函数的纯净性。将缓存作为一个单独的服务层添加。 关键设计决策 决策 理由 ---------- ----------- SHA-256 内容哈希 与路径无关，内容更改时自动失效 {hash}.json 文件命名 O(1) 查找，无需索引文件 服务层包装器 单一职责原则：提取功能保持纯净，缓存是独立的关注点 手动 JSON 序列化 完全控制冻结数据类的序列化 损坏时返回 None 优雅降级，在下次运行时重新处理 cachedir.mkdir(parents=True) 在首次写入时惰性创建目录 最佳实践 哈希内容，而非路径 —— 路径会变，内容标识不变 对大文件进行哈希时分块处理 —— 避免将整个文件加载到内存中 保持处理函数的纯净性 —— 它们不应了解任何关于缓存的信息 记录缓存命中/未命中，并使用截断的哈希值以便调试 优雅地处理损坏 —— 将无效的缓存条目视为未命中，永不崩溃 应避免的反模式 适用场景 文件处理管道（PDF 解析、OCR、文本提取、图像分析） 受益于 --cache/--no-cache 选项的 CLI 工具 跨多次运行出现相同文件的批处理 在不修改现有纯函数的情况下为其添加缓存 不适用场景 必须始终保持最新的数据（实时数据流） 缓存条目可能极其庞大的情况（应考虑使用流式处理） 结果依赖于文件内容之外参数的情况（例如，不同的提取配置）
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills affaan-m/content-hash-cache-pattern--c87acd