cachemiss

cachemiss

缓存本应让 CI 更快，可为什么这次运行还是没命中？cachemiss 会获取工作流中原样写出的缓存键模板，以及每次运行的实际情况，并判断哪些未命中不可避免，哪些原因无人能解释：

• 哈希输入 — 从模板的 hashFiles('...') / hashFiles("...") 片段中提取的 glob 模式，按出现顺序排列并去重
• 结果计数 — 精确命中的运行次数、回退到恢复键的次数、完全未命中的次数，以及命中率（命中次数除以总运行次数，四舍五入到小数点后 4 位）
• 每次未命中运行的原因 — 部分运行的原因是 exact_key_miss_restore_hit；未命中运行中，若更改的文件涉及哈希输入，原因是 hashed_input_changed，并会列出匹配的文件；其他情况的原因为 unexplained_miss
• 原因统计 — 按原因统计次数，按频率从高到低排列（次数相同则按字母顺序排列），用于生成报告中的 most_common_cause 和整体 diagnosis；如果所有运行都命中，则诊断为 cache_healthy，且最常见原因为空值
• 更改的哈希文件 — 汇总所有未命中运行中发生更改的哈希输入并排序，让你一眼看出是哪个锁文件或清单文件导致缓存不断失效

glob 匹配遵循三条规则：文件与模式完全相同时即视为匹配；模式以 **/ 开头时，文件与模式剩余部分相同，或以 / 加上该剩余部分结尾时即视为匹配；模式包含 * 时，按段匹配（以 / 分割），其中 * 恰好匹配一个段，且段数必须相同。匹配区分大小写。

所有计算均在本地根据你提供的输入完成：不联网、不抓取日志，也不需要配置。无效输入——例如空的键模板、缺少结果的运行、结果不属于 hit / partial / miss，或非字符串类型的更改文件——都会被拒绝，并报错指出有问题的路径；不会生成不完整的报告。

CLI

npx @reneturcios/cachemiss analyze --input args.json
npx @reneturcios/cachemiss --version

args.json 包含完整的参数对象：

{
  "key_template": "${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}",
  "runs": [
    { "run_id": "run-201", "outcome": "hit" },
    {
      "run_id": "run-202",
      "outcome": "miss",
      "changed_files": ["apps/web/package-lock.json", "src/index.ts"]
    },
    { "run_id": "run-203", "outcome": "partial" }
  ],
  "restore_keys": ["linux-node-"]
}

每次运行的 changed_files 都是可选的，整体的 restore_keys 也是可选的（会原样写入报告）。报告以 JSON 格式输出。

退出代码：成功时为 0，运行时错误时为 1（包括输入文件无法读取或无效，以及输入无效），用法错误时为 2。

MCP 服务

npx -y @reneturcios/cachemiss mcp

MCP 客户端配置：

{
  "mcpServers": {
    "cachemiss": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cachemiss", "mcp"]
    }
  }
}

工具

• analyze_cache_miss — 根据键模板和每次运行的结果，诊断 CI 缓存未命中。

  • key_template（字符串，必填且不能为空）— 工作流中原样写出的缓存键
  • runs（数组，必填且至少包含一项）— 由 {run_id, outcome, changed_files?} 对象组成的运行记录，其中 outcome 为 hit、partial 或 miss 之一
  • restore_keys（字符串数组，可选）— 工作流中配置的恢复键前缀

  返回 {run_count, hits, partials, misses, hit_rate, hashed_inputs, restore_keys, cause_counts, misses_detail, changed_hashed_files, most_common_cause, diagnosis}。

Docker

docker run -i ghcr.io/cloudcorprecords/cachemiss
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/cachemiss analyze --input /w/args.json

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios