Skip to content
sixiaozhePublic

About

给任意 Linux 命令加一层结果缓存:自动用 ptrace 追踪文件读写,输入未变时命中缓存、逐字节还原输出而不运行命令。

Topics

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

cmdcache

给任意命令加一层结果缓存:输入没变,就不重跑。

自动追踪文件读写 · 零配置可用 · 命中时逐字节还原输出

Rust Platform License


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 通过。

About

给任意 Linux 命令加一层结果缓存:自动用 ptrace 追踪文件读写,输入未变时命中缓存、逐字节还原输出而不运行命令。

Topics

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages