cmdcache 是一个加在命令前面的轻量包装器。首次执行时它真实运行命令并记录输入、输出、stdout/stderr 与退出码;之后再执行同一条命令时,若输入未变,就直接把缓存结果物化回去,完全不运行命令。
$ time cmdcache -- ./gen.sh in.txt out.txt # 首次:真实执行
real 0m1.01s
$ time cmdcache -- ./gen.sh in.txt out.txt # 再次:直接回放
real 0m0.07s
它不只是 ccache 那种编译器专用缓存:任何确定性命令都能用,且默认通过 ptrace 自动识别输入与输出——大多数情况下连参数都不用配。
- 自动追踪:未命中时用
ptrace观测被包裹命令及其整个进程树的文件访问,自动得出输入(只读打开)与输出(写 / 创建 / rename / unlink)。子进程、fork/exec都能跟随。 - 零配置即可用:不用声明任何参数,第二次执行就会命中。
- 显式声明兜底:
--in/--out/--outlistparam/--inlistparam始终优先,并可补充自动追踪的结果。 - 逐字节正确:命中 = 已观测输入完全相同时,逐字节还原输出文件、stdout/stderr 与退出码。
- 内容寻址存储:输出以 SHA-256 blob 去重保存,多个缓存条目共享同一份数据;物化优先 reflink,否则普通拷贝。
- 拒绝不可信缓存:检测到网络调用默认不缓存;网络依赖不可信。
- 可验证:
--check真实重跑并与缓存逐字节对比,用于确认追踪没有漏判。 - 低开销追踪:默认用 seccomp 过滤,只对文件/网络相关 syscall 触发停顿;seccomp 不可用时自动回退到全 syscall 追踪。
- 空间安全:磁盘空闲不足或输出过大时,命令照常完成,只是跳过本次缓存——绝不会因为缓存而让命令失败。
- 并发安全:按索引 key 加
flock,并发命中与 GC 互不破坏;写库原子提交。
需要 Rust 1.75+(edition 2021)。
git clone https://github.com/sixiaozhe/CmdCache.git
cd cmdcache
cargo build --release
# 产物:target/release/cmdcache放进 PATH:
install -m755 target/release/cmdcache ~/.local/bin/cmdcache# 1) 无需任何声明:首次真实执行,之后同输入直接回放
cmdcache -- ./gen.sh in.txt out.txt
# 2) 显式声明输入/输出(最可控)
cmdcache --in in.txt --out out.txt -- ./gen.sh in.txt out.txt
# 3) 声明 “-o 后面那个 token 是输出”(支持 -o foo / -ofoo / --output=foo)
cmdcache --outlistparam o -- mytool param -o outfile看一眼缓存效果:
cmdcache --stats可运行的完整演示(会创建独立的临时缓存,不污染你的环境):
./examples/demo.sh target/release/cmdcache适合确定性、输入是文件、输出是文件的命令:
- 代码生成器、parser 生成、模板渲染、文档站构建
- 数据转换:
pandoc、ffmpeg转码、图片缩放、CSV/Parquet 转换 - 无网络依赖的编译 / 打包步骤
- 为测试生成大夹具文件
- CI 增量:同一提交重复跑同一条生成命令时秒回
不适合:依赖时间、随机数、网络、环境变量间接状态,或输出本身不可重现的命令(见下方「正确性边界」)。
cmdcache [OPTIONS] -- <COMMAND> [ARGS]...
--outlistparam <FLAG> 声明 <FLAG> 后紧跟的 token 是输出路径;可重复
--inlistparam <FLAG> 声明 <FLAG> 后紧跟的 token 是输入路径;可重复
--in <FILE> 显式输入文件;可重复
--out <FILE> 显式输出文件;可重复
--no-trace 关闭自动追踪,仅使用显式声明的输入/输出
--no-cache 执行但不读写缓存
--check 真实重跑并与缓存结果对比(一致退出 0,不一致 1,无缓存 2)
--gc 全量清理:TTL、损坏 entry、孤儿 blob、tmp 残留
--clear 清空缓存后退出
--stats 打印缓存统计后退出
-h, --help
-V, --version
解析规则:
- 所有
cmdcache选项必须写在--之前;--之后全部属于被包裹命令。 - 被包裹命令直接
exec,不经 shell。需要 shell 内建命令时自己写-- sh -c '...'。 - 输出参数支持
-o foo、-ofoo、--output=foo三种写法;构建缓存 key 时输出值被替换为哨兵<OUT:n>,因此改输出路径仍能命中。
cmdcache [opts] -- <cmd> [args...]
│
├─ 1. 切分 cmdcache 选项 与 被包裹命令的 argv
├─ 2. 索引 key = H(schema + 工具版本 + 规范化 argv + cwd + 过滤后 env)
├─ 3. 取出 manifest → 重新哈希记录的输入文件 → 全部匹配才命中
├─ 4a. 命中:物化输出 + 回放 stdout/stderr + 返回退出码(不执行命令)
└─ 4b. 未命中:ptrace 追踪执行 → 记录输入/输出 → 写库
两级 key + manifest 的设计解决了"要判断命中得先知道输入,但输入要执行后才知道"的先有鸡还是先有蛋问题:索引 key 不含输入内容,只映射到若干 manifest;命中的最终判定是重新哈希 manifest 记录的每一个输入文件并比对。
未命中时默认用 ptrace 观测被包裹命令及其子进程:
- 只读打开 → 候选输入;写 / 创建 / rename / unlink → 候选输出。
- 相对路径按子进程 cwd 与
openat的 dirfd 解析为绝对路径。 - 忽略
/proc、/sys、/dev、系统库与缓存自身目录。 - 检测到 socket/connect 等网络调用时默认拒绝缓存该次执行。
- 显式
--in/--out/--outlistparam/--inlistparam始终优先并可补充追踪结果。 - 默认启用 seccomp 过滤,仅对文件/网络 syscall 触发停顿以降低开销;不可用时自动回退到全 syscall 追踪。
追踪仅实现于 x86_64;不可用(如受限容器)时自动回退到仅显式声明模式。
$XDG_CONFIG_HOME/cmdcache/config.toml(默认 ~/.config/cmdcache/config.toml)。所有字段可选,缺省取默认值:
env_blacklist = ["_", "SHLVL", "OLDPWD", "PWD", "RANDOM", "SECONDS", "EPOCHSECONDS", "EPOCHREALTIME"]
path_filters = ["/proc", "/sys", "/dev", "/usr/lib", "/usr/local/lib", "/lib", "/lib32", "/lib64", "/libx32", "/etc/ld.so.cache"]
max_cache_size = 5368709120 # 5 GiB
high_watermark = 0.9
max_entry_age = 0 # 秒;0 表示不过期
tmp_grace = 3600 # 秒
evict_largest_first = false
cache_network = false
use_seccomp = true
max_stream_cache = 16777216 # 16 MiB;stdout/stderr 捕获上限,超出则不缓存该次执行
min_free_space = 67108864 # 64 MiB;磁盘保留空闲量,不足则不缓存
max_output_blob = 1073741824 # 1 GiB;追踪输出超过此大小则不缓存该文件逃生开关:CMDCACHE_DISABLE=1 等价 --no-cache。
缓存命中的含义是:在已观测输入完全相同的前提下,逐字节还原上次执行产生的输出。 它不是对所有命令的正确性保证。已知无法覆盖:
- 通过已打开 fd 传入的输入(非路径打开)。
- 时间、随机数、硬件状态、主机名等非文件输入。
- 网络读取(默认拒绝缓存)。
- 环境变量的间接依赖(
getenv不是 syscall,用全环境哈希近似)。 - 追踪漏判(动态加载、子进程边界、
mmap之外的隐式读取等)。
因此:缓存是加速假设,不是正确性保证;关键场景请用 --check 验证。
- 目标平台:Linux。
- 自动追踪(ptrace/seccomp):仅 x86_64。其他架构与受限容器会自动回退到"仅显式声明"模式。
cargo build --release
cargo test -- --test-threads=1
cargo clippy --all-targets -- -D warnings测试覆盖:key 构建、argv 规范化、env 过滤、manifest 序列化、路径解析、空间安全、GC、--check、seccomp BPF 构建,以及端到端(未命中→命中、输入/env 变化、输出路径变化、fork+exec 追踪、网络拒绝缓存),另有一个性质测试断言"缓存回放 == 全新执行"。
采用 MIT 或 Apache-2.0 双许可,任选其一(LICENSE-MIT / LICENSE-APACHE)。
欢迎 issue 与 PR。提交前请确保 cargo test 与 cargo clippy --all-targets -- -D warnings 通过。