安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install rez-caching
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 rez-caching。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Rez 缓存是一份实用指南，介绍 Rez 3.4.0 中两种相互独立的缓存系统：由 memcached 支持的 resolve 缓存，以及本地磁盘上的 package 负载缓存。指南说明每种缓存存储的内容、配置和检查方法、条目失效的原因，以及哪些更改可能导致数据过期。
对于使用 Openclaw Skills 的开发者和流水线团队，本指南提供了精准的工作流程，用于判断缓慢的 resolve 或未生效的 package 更改是否确实由缓存导致。每次只绕过一种缓存，应用针对性修复，然后在新的 resolve 中验证结果，而不是清空所有缓存后盲目猜测。

应用场景

诊断看似没有生效的 package 更改。
判断缓慢的 resolve 使用的是 memcached resolve 缓存还是 package 负载缓存。
调查过期结果之前，检查任一缓存是否已启用。
检查缓存命中率、缓存的变体、停滞的副本和清理状态。
安全地删除过期的 package 负载，或清空 resolve 条目。
对缓存配置更改进行基准测试并比较结果。
帮助团队区分缓存问题与缺少发布版本、构建失败或 package 安装问题。

工作原理

使用 rez-config memcached_uri 和 rez-config cache_packages_path 检查启用了哪些缓存。
如果缺少某项 package 更改，使用 rez-search 确认预期版本是否可见。
使用 rez-env foo --no-cache 绕过 resolve 缓存；如果更改出现，则调查过期的 resolve 条目。
使用 rez-env foo --no-pkg-cache 绕过 package 缓存；如果更改出现，则调查过期的缓存负载。
应用针对性修复：使用 rez-memcache --flush 清空 resolve 条目，或使用 rez-pkg-cache -r 和 rez-pkg-cache --clean 取消缓存并清理 package 变体。
使用 rez-env foo -o context.rxt 和 rez-context --so 在新的上下文中验证。
如需验证性能相关的说法，分别运行更改前后的 rez-benchmark 测试并比较输出。

配置指南

在 rezconfig.py 中分别配置每种缓存。默认情况下，两者都处于关闭状态。
配置 memcached 服务器以启用 resolve 缓存；仅设置 resolve_caching 并不会启用它：

rezconfig.py

memcached_uri = ["127.0.0.1:11211"]
设置缓存目录以启用本地磁盘上的 package 负载缓存。package 还必须通过其 cachable 属性或适用的默认设置符合缓存条件：

rezconfig.py

cache_packages_path = "/path/to/local/cache"
使用以下命令检查当前生效的配置并查看缓存：
rez-config memcached_uri
rez-config cache_packages_path
rez-memcache --stats
rez-pkg-cache
要排查看似未生效的更改，请分别绕过缓存：
rez-env foo --no-cache
rez-env foo --no-pkg-cache
要删除过期条目，请使用相应的缓存专用命令：
rez-memcache --flush
rez-pkg-cache -r
rez-pkg-cache --clean
如需准确比较性能，请先创建前后两次基准测试，再进行比较：
rez-benchmark --out before
rez-benchmark --out after
rez-benchmark --out after --compare before

数据架构

Rez 将缓存分为两个独立系统，两者的存储方式、内容、控制项和检查工具各不相同。
缓存 存储的数据 位置 启用设置 检查或管理
Resolve 缓存 求解器结果、package 文件读取记录、目录列表和变体状态 Memcached 服务器 memcached_uri 加 resolve_caching rez-memcache
Package 缓存 变体负载（package 根目录），不包括 package 定义 本地磁盘 cache_packages_path 和 package 缓存资格 rez-pkg-cache
Resolve 缓存的行为受 cache_package_files、cache_listdir 和 resource_caching_maxsize 影响。缓存的求解状态包括 package 时间戳和变体状态；不会改变受监控状态的更改可能不会使条目失效。
Package 缓存由多项设置控制，包括 read_package_cache、write_package_cache、default_cachable、package_cache_async、package_cache_local 和 package_cache_same_device。清理和容量控制项包括 package_cache_max_variant_days、package_cache_clean_limit、package_cache_space_buffer 和 package_cache_used_threshold。
Package 缓存变体有三种状态：
copying：正在复制负载，尚未准备好使用。
cached：负载已可供使用。
stalled：复制失败；必须先运行 rez-pkg-cache --clean 将其删除，才能重新缓存。
缓存的 package 根目录通过 REZ_
ROOT 指向本地缓存；REZ
_ORIG_ROOT 记录原始负载位置。取消变体的缓存会移除其缓存注册信息，而 --clean 会删除未使用的文件。rez-benchmark 会生成一个包含 summary.json 的结果目录。

高级特性

rez-memcache --stats
检查 memcached 命中/未命中比例和内存使用情况；使用 --poll 、 --warm 、 --reset-stats --flush 进行运维控制。
REZ_DEBUG_MEMCACHE
、
debug_memcache
或仅适用于 resolve 的
debug_resolve_memcache
启用详细的 memcached 操作日志。
使用异步 package 缓存，在后台复制变体；如果 resolve 应等待复制完成，请使用
rez-pkg-cache --pkg-cache-mode sync
。
rez-pkg-cache --logs
检查 package 缓存活动，查看变体状态，并清理未使用或停滞的负载。
使用 package 级别的
cachable
元数据，以及存储库、package 和全局默认设置，控制 package 的缓存资格和缓存行为。
rez-benchmark
摘要和直方图衡量变化；比较时，差值的含义是 --compare 的值减去 --out 的值。
如果缓存设置可能被覆盖，请使用
rez-config --source-list resolve_caching
检查配置来源。

name: rez-caching description: "Rez's two independent caches — the memcached-backed resolve cache and the on-disk package payload cache — the five settings that turn each one on, what invalidates an entry and what silently does not, rez-memcache and rez-pkg-cache for inspecting and flushing them, and the decision tree for 'I changed the package and nothing took effect'. Use when a resolve is slow, when a package change appears to be ignored, or when you need to prove a stale cache is or is not the cause. Covers Rez 3.4.0."

Rez caching

One-sentence summary: rez has two caches that share almost nothing — a memcached resolve cache that stores solves and package file reads, and a local-disk package cache that stores variant payloads — and the single most useful move when a change seems to be ignored is to disable one at a time and see which one was lying.

Skill scope: what is cached, when it goes stale, and how to prove it. For the solver internals that a cached resolve short-circuits see rez-resolve; for the six causes of a failed resolve see rez-resolve-troubleshooting; for a package that fails to load or was left half-installed see rez-package-pitfalls; for the cachable attribute in a package.py see rez-package-definition.

The two caches

They are configured separately, live in different places, and fail in different ways. Naming the right one first is most of the work.

Resolve cache Package cache

What it stores solves, package file reads, directory listings, variant states variant payloads — the package root directory

Where a memcached server local disk

Enabled by memcached_uri (plus resolve_caching) cache_packages_path
Default off (memcached_uri = []) off (cache_packages_path = None)
Speeds up the solve the runtime — loading files off shared storage

Inspect with rez-memcache rez-pkg-cache

Disable for one run rez-env --no-cache rez-env --no-pkg-cache

Both are off out of the box, so a cache that is biting you is one somebody turned on. Check before you theorise:

rez-config memcached_uri
rez-config cache_packages_path

An empty list and None respectively mean neither cache is active.

Resolve caching

Backed by memcached. In a studio, a machine that performs a solve another machine already performed gets the cached result instead of re-solving.

# rezconfig.py

memcached_uri = ["127.0.0.1:11211"]

That one setting is all that is required. The related switches:

Setting Default Effect

memcached_uri [] memcached servers; empty means no memcaching at all
resolve_caching True cache solves, but only when memcached_uri is non-empty
cache_package_files True cache package.py / package.yaml reads
cache_listdir True cache directory traversals
resource_caching_maxsize -1 in-process resource cache size; 0 disables, -1 is unlimited

resolve_caching = True with memcached_uri = [] is not caching. The setting is a permission slip, not a switch — the URI list is what turns it on.

What invalidation actually covers

Each cached solve stores solver state, the timestamps of the packages it saw, and the variant state of every variant involved. For the filesystem repository the variant state is the last modified time of the file backing the variant. Two consequences:

Releasing a newer version that would change the result does invalidate the entry. A cached foo-1+