metabolism-tools/workspace-metabolism

workspace-metabolism

用于治理 AI 编码代理遗留文件的 MCP 服务器和 CLI：策略驱动的审计、可逆清理、回滚以及哈希链验证。Python 3.11+，零依赖，支持 Windows / Linux / macOS。

PyPI version
Python
CI
License: MIT
Zero dependencies
Glama score

Terminal demo

workspace health

▶️ 观看 60 秒动画演示：docs/demo-terminal.html

问题所在

AI 编码代理（Claude Code、Codex、DeepSeek Harness……）有一个共同点——你的工作区——它们会留下一堆临时文件、缓存和暂存目录。没有人负责清理：手动删除不可逆，定时脚本没有审计追踪，而下一次代理运行又在上一次留下的垃圾中工作。

workspace-metabolism 就是为此而生的策略层：一个 metabolism.json 决定每条路径的价值等级（G1 永不触碰 → G4 自动处理），任何内容都不会按模式删除——条目会移动到回收区，并附带每个文件的 SHA-256 哈希，rollback 可以精确恢复它们——每个操作都会记录到哈希链日志中，verify 可以对其进行审计。

30 秒上手：

pip install workspace-metabolism
wm doctor --residue                  # what agent byproducts your policy doesn't govern yet
wm doctor --residue --apply-policy   # adopt the suggestions as policy entries (creates the file if missing)
wm audit                             # read-only checkup with health score

分发（v0.7.0）：GitHub release 和可安装 wheel。
retain 需要此 GitHub wheel/源码；PyPI 发布是独立的。
安装说明见 v0.7.0 发布说明。
已收录于 awesome-mcp-servers 的 Developer Tools 分类下（2026-09-21 合并）。
参见 Glama 工具定义评估
用于接口质量评估；它不建立生产可靠性，也不降低监督要求。
诚实地说：目前还没有大规模生产部署，策略模式在 v1.0 之前可能还会变动。
欢迎早期采用者在奇怪的目录结构上把它弄坏。

诚实的边界——这不是什么：

- 不是沙箱。 wm gate 是面向协作型 agent 的治理/审计层；被攻陷或恶意的 agent 可以绕过它，直接调用目标服务器。操作系统级沙箱是另一个层面。
- 不是启发式分类器。 它从不自行判定“这个文件是垃圾”——只有你批准的策略才能决定。doctor 只是建议条目；在你采纳之前，没有任何东西受到治理。
- 不修复 agent 的 bug。 它治理 agent 留下的副产品；它不阻止 agent 产生这些副产品。
- 本地审计，不是公证。 哈希链式日志能检测对工具自身记录的篡改；它不是分布式账本，也不是法庭级账本。

这个仓库有两个相互关联的想法：

- Agentic Metabolic Engineering 是方法：如何思考工作区生命周期。
- AI governance as code 是实现：wm 如何通过策略文件和命令应用该方法。

中文快速上手（30 秒）

v0.6.0 新增：先认领再写入、清理避让未完成认领、精确绑定 SQLite 路径及不建库的只读
检查。复用现有任务和数据入口，不另建 AI 调度系统。见接入指南、
认领使用说明和数据库检查。

AI 编程（Claude Code / Codex / Aider 等）会在工作区留下大量草稿、缓存和
废弃文件，越堆越多，下一轮 AI 还得在垃圾堆里干活。这个工具用一份策略文件
管理文件的整个生命周期：检查（只读）→ 回收（可回滚）→ 验证（防篡改记录）
→ 清理。

pip install workspace-metabolism        # 安装（零依赖）
python examples/demo.py                 # 30 秒演示：盲删 vs 回收+回滚
wm init                                 # 生成策略文件 metabolism.json
wm audit                                # 只读体检，给文件贴营养标签
wm clean --grades G4 --yes              # 回收过期项（默认 dry-run，确认后加 --yes）
wm rollback                     # 删错了？一键原样找回
wm govern write --path src/main.py      # 写文件前先问策略：允许吗？（AI 执行点拦截）
wm slim --db data/app.db --yes          # 数据库也会膨胀：策略驱动的库内瘦身（v0.3）

默认只读、绝不直接删文件；每步操作都有防篡改记录；Windows / Mac / Linux 通用。
项目处于早期，认领和受控编辑仍为实验能力；策略格式在 v1.0 前可能调整。完整英文文档见下文。

为什么需要它

大多数磁盘工具要么向你展示空间占用（ncdu、duf），要么删除东西
（rmlint）。workspace-metabolism 不同：一份策略文件定义了每条路径
的价值等级（G1–G4），而工具只做策略允许的事——绝不多做。它是多 agent 工作区的
策略层：Claude Code、Codex、Aider、OpenClaw 以及其他所有 agent 共享同一件事——
你的工作区——而策略治理它们所有人留下的副产品，无论这些副产品由哪个工具创建。它不绑定任何厂商，也不评判任何文件；在你评判它之前，请先看这不是什么。

- G1 绝不触碰 / G2 保留 / G3 批准 + 引用检查 / G4 自动
- 删除从不直接进行：条目先移动到回收区，然后 rollback
- 在逐文件 SHA-256 完整性检查后恢复它们
- 每个操作都会写入一个哈希链式日志；verify 可检测任何编辑
- 只读的 audit 会报告候选项、未注册路径、磁盘警报、增长趋势和可能的重复项——以及内存支持挂载（tmpfs/ramfs：它消耗的是 RAM，而不仅仅是磁盘）上的残留
- 可选的保护窗口（例如交易时段、营业时间），在此期间标记的条目绝不会被触碰
- 通过 examples/ 中的模板，Windows（任务计划程序）和 Linux/macOS（cron）开箱即支持计划运行

为什么不只是计划清理？

一个计划任务——或者让 Codex 按定时器“清理旧文件”——带给你的只是在某个时刻，文件被删除。workspace-metabolism 带给你的是：

- 存放在仓库中的规则（metabolism.json），可版本化、可审查
- 从不直接删除的清理：回收区、逐文件 SHA-256、精确的 rollback
- 可检测篡改的哈希链式日志
- 在每台机器、每次运行中行为一致，不涉及 AI 判断

调度与代谢是互补的，而不是对立的：本仓库提供运行 wm 本身的 cron、Windows 任务计划程序和 CI 模板。调度器回答何时；策略回答什么、如何，以及如何撤销。

这不是什么

有四种反对意见出现得如此频繁，值得拥有自己的页面（docs/positioning.md）。简短版本如下：

- 不是供应商 bug 的修复方案——Claude Code 的 /tmp 泄漏、OpenClaw 的暂存目录残留：这些属于上游。我们治理的是工作区，而这是每个 agent 都共享的一件事。
- 不是启发式分类器——不猜测，不做 AI 判断。只有你编写的策略文件才能决定任何事情；wm explain  会显示规则。
- 不是 agent 自我清理的对手——agent 应该自己清理；wm mcp + 会话结束钩子让这件事安全且可审计。
- 不是盲目删除脚本——绝不会按模式删除任何内容：条目会移动到带有逐文件哈希的回收区，并且 rollback 会恢复它们。purge 删除文件回收批次。显式的 retain 策略可以在写入完整恢复导出后删除未被引用的数据库行。

实际效果

本仓库附带一个可复现的基准测试：两个相同的工作区运行 30 个模拟 agent 循环；一个在每个循环结束时执行 wm clean，另一个从不清理。结果是——2 个活动文件 vs 242 个——这是一个你可以自己复现的数字：

python examples/metabolism_benchmark.py

一次记录的运行（2026-08-16，wm 0.2.0）位于 docs/publish/benchmark-run-20260816.json（原始日志：docs/publish/benchmark-run-20260816.txt）。

案例研究：一个 20.7 GB 的数据库拖垮了一个研究引擎

wm slim 诞生于一次生产事故，而 dogfooding 轮次产生了该工具迄今为止最诚实的评审。阅读
docs/case-studies/research-engine-db-rot.md：
三种故障模式（失效工作单元、数据库腐化、静默死亡任务）、
修复方案，以及我们使用 wm slim 验证它们时的发现——一条策略剥离了错误的字段、
两个路径匹配缺陷、一个 CLI 标志顺序陷阱导致首次定时运行失败，
以及首次成功运行回收了 10.15 GB（21.7 GB → 11.3 GB），随后又发现了第三个真实问题：
死位置排除规则在“干净”纪元稀释其学习窗口后忘记了自身。真实使用才是最终考验。

🧬 理念

workspace-metabolism 将你的 AI 生成工作区视为一个有限系统：
审计 → 清理 → 验证 → 回滚，并带有可回收清理和哈希链式审计追踪。清理是手段；代谢是框架。一句话概括：
循环让智能体持续运行；代谢让工作区保持可用。 我们将这一框架称为 Agentic Metabolic Engineering——管理智能体驱动软件工作区的副产品。完整论述：
docs/philosophy.md · 故事 ·
竞品分析 ·
学术锚点。

快速开始

install the release that includes retain (PyPI is a separate channel)
pip install https://github.com/metabolism-tools/workspace-metabolism/releases/download/v0.7.0/workspace_metabolism-0.7.0-py3-none-any.whl

or run without installing anything:
PYTHONPATH=src python -m workspace_metabolism --help

try it on a throwaway workspace (builds demo files; shows the usual
blind-delete fix vs the wm way: recycle + rollback + journal)
python examples/demo.py

将工具指向你自己的的工作区：

cd /path/to/workspace
wm init            # scaffold metabolism.json (like git init)
wm doctor          # check readiness before the first audit or cleanup
wm audit           # first checkup (read-only)
wm health          # workspace health score (0-100)
wm explain logs    # why a path is graded the way it is
wm clean --grades G4 --yes   # recycle expired G4 items (dry-run without --yes)
wm rollback

wm init 会扫描你的工作区并注册常见目录（源代码和文档作为 G2 保留，logs/tmp/cache 作为 G4 自动处理，archive/staging 作为 G3 需批准）。
编辑 metabolism.json 并像任何源文件一样提交它。该工具会自动发现工作区根目录下的 metabolism.json（或 .wm.json），因此 --registry 是可选的。除非在策略文件中注册，否则不会清理任何内容。高级用户可以从
examples/registry.example.json 开始。

命令

| 命令 | 作用 |
| --- | --- |
| audit | 只读健康检查；写入报告和日志条目（同时标记敏感文件和 git 跟踪的内容） |
| clean --grades G4 | 将过期项目移动到回收区（默认试运行） |
| clean --grades G3 | 相同，但需要 --approve + --approver |
| rollback  | 在完整性检查后恢复一次清理运行 |
| purge --older-than 30 | 删除过期的文件回收批次 |
| retain --db data/objects.db | 在显式策略下预览删除多余的、未被引用的行版本 |
| retain --db data/objects.db --restore RUN_ID | 预览已验证的行恢复；添加 --yes 以执行 |
| verify | 检查日志哈希链和运行清单 |
| status | 工作区、回收区和待处理候选对象的概览 |
| init | 搭建 metabolism.json 策略文件（类似 git init） |
| explain  | 显示策略对某个路径的规定（营养成分标签） |
| health | 工作区健康评分（0-100），支持 --json 和 --badge 输出 |
| doctor | 只读就绪检查（工作区、策略、状态、锁）；--residue 还会列出策略尚未管控的常见代理副产物（.cursor、.claude、缓存、日志）——每项都附有将管控它的确切策略条目，--apply-policy 会采纳它们 |
| govern  | 检查某个 AI 操作是否被策略允许并记录该决定 |
| gate --target ... | MCP 治理代理：被包装服务器的每次工具调用都会先根据策略进行检查 |
| slim --db PATH | 策略驱动的就地裁剪 SQLite 数据库中的重型 JSON 字段（有日志记录；默认试运行） |
| mcp | MCP stdio 服务器，使代理可以自行运行微代谢 |

全局标志：

| 标志 | 含义 |
| --- | --- |
| --root PATH | 要管控的工作区（默认：当前目录） |
| --state-dir PATH | 日志 / 回收 / 运行 / 报告（默认：系统缓存目录，位于工作区之外） |
| --registry PATH | 策略 JSON（可选；自动发现 metabolism.json / .wm.json） |
| --protected-window HH:MM-HH:MM | 工作日时间窗口；标记为 protected 的条目在窗口激活期间会被跳过 |

默认状态目录有意位于工作区之外——这样在你的项目中执行
git add . 就永远不会把审计日志扫进版本控制。

wm doctor 是只读的预检检查。它会报告工作区和状态目录是否可写、
策略是否存在且有效，以及另一个 wm 操作当前是否持有状态锁。该锁
会串行化审计、清理、回滚和清除操作，因此并发的计划任务或
代理触发的运行不会交错执行日志和回收操作。

作为代码的 AI 治理

可选的 ai_governance 部分是本仓库 AI 治理层的具体实现。它使用
同一个策略文件在 AI 操作发生之前对其进行检查。未知操作默认被拒绝；
写操作可以要求预览，而执行、删除和网络操作可以要求指定审批人。
wm govern 只做出并记录决定；它不会替调用者执行该操作。

wm govern write --path src/main.pybash
wm govern write --path src/main.py --preview
wm govern execute --path scripts/release.ps1 --approve-by "name"
wm govern network --approve-by "name" --json

wm gate 将决策转化为强制执行。 它包装任何 MCP stdio 服务器，
并在转发每个 tools/call 之前根据策略进行检查；
被拒绝的调用永远不会到达目标，每个决策都会记录到日志中：
bash
wm gate --target "python -m my_mcp_server"

使用 tool_patterns（glob）将工具名称映射到操作，例如
"fs_write": "write"、"shell": "execute"。未匹配的工具默认使用
execute 操作。对于调用携带预览模式的工具，在调用参数中传入
"preview": true 以满足 requires_preview。

每个决策都包含策略哈希，并写入同一个哈希链日志；
govern 返回一个 decision_id，clean / rollback / slim 通过
--decision-id 接受它，因此日志显示了完整的
意图 → 决策 → 执行链。审批者值是一种可审计的声明，而非身份验证机制。

诚实的边界： wm gate 是一个治理与审计层，而非沙箱。
被攻陷或恶意的代理可以绕过代理直接与目标通信。Gate 治理的是
合作的代理；操作系统级沙箱治理的是敌对的代理。

首次运行，引导式： wm doctor --residue 扫描代理通常留下的
副产品（.cursor、.claude、node_modules/.cache、
__pycache__、日志……），这些尚未被你的策略治理。每个命中项都会显示
将治理它的确切策略条目；--apply-policy 将这些建议采纳到
metabolism.json（如需要则创建它）。任何内容都不会被删除——这些建议
成为策略，之后策略仍然决定一切：
bash
wm doctor --residue               # 哪些未被治理，以及建议的条目
wm doctor --residue --apply-policy  # 将它们采纳为策略条目，然后审计

策略文件
json
{
"version": 1,
"defaults": {
"recycle_retention_days": 30,
"max_item_mb": 2560,
"disk_alert_free_gb": 20,
"disk_alert_free_pct": 15,
"dupe_scan_dirs": ["tmp", "cache"]
},
"never_clean": [".git", "README.md", "src"],
"entries": [
{"path": "logs", "grade": "G4", "cleanup": "auto", "retention_days": 30},
{"path": "archive", "grade": "G3", "cleanup": "approve", "retention_days": 60},
{"path": "/__pycache__", "grade": "G4", "cleanup": "auto", "retention_days": 30}
]
}

| 字段 | 含义 |
| --- | --- |
| path | 相对于 --root 的路径或 glob（、/） |
| grade | G1 从不 / G2 保留 / G3 批准 / G4 自动 |
| cleanup | never、auto 或 approve |
| retention_days | 条目成为候选前的空闲天数（除非 cleanup=never，否则必填） |
| scope | 可选：files_only（目录的顶层文件） |
| protected | 可选：当 --protected-window 处于活动状态时跳过 |
| remote_authoritative | 可选：为具有远程事实来源的数据显示标记 |
| category | 可选：用于你自己的分类的自由格式标签 |
| owner | 可选：谁对该规则负责 |
| intent | 可选：该规则存在的原因 |
| review_after | 可选：该规则应何时重新审视 |

策略格式已版本化，并依据
schema/metabolism.schema.json 进行校验，因此编辑器和
代理可以在工具检查你的文件之前先行检查。

健康评分

wm health 将审计摘要合并为一个 0 到 100 的单一数字：25
分用于日志可审计性，25 分用于治理（未注册路径、磁盘
告警），35 分用于腐化负担（过期候选），15 分用于回收
就绪度。等级：A（90+）、B（75+）、C（60+）、D（低于）。
bash
wm health --json
wm health --badge   # 用于 README 徽章的 shields.io 端点 JSON

上方的徽章由 docs/health.json 生成。一个当评分低于阈值时
失败的 CI 模板位于
examples/ci-audit.yml。

代理

wm mcp 运行一个零依赖的 MCP stdio 服务器。代理可以自行初始化策略、
审计、解释、验证和试运行清理计划；clean 仅在
调用方显式传入 execute=true 时执行，rollback 从回收区恢复
上一次运行（经 SHA-256 验证），并且策略文件
仍然决定一切。循环结束仪式已在
examples/micro_metabolism.py 中自动化——将其接入
会话结束钩子，让每个循环都以一次检查收尾。

DeepSeek Harness (DSH)

DSH 是一个代理框架，其中一切皆插件（Cordis）。其官方
第三方工具通道是 MCP，而 wm mcp 已经支持它——一行
cordis.yml 即可将全部九个 wm 工具暴露给 DSH 代理（audit、health、
explain、verify、wm_db_check 已注册 SQLite 检查、wm_govern 操作前
策略检查、clean、init、rollback）：
yaml
- insert:
- id: workspace-metabolism
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: wm
transport: stdio
command: wm
args: [mcp]
cwd: !!js process.cwd()

完整演练（项目 cordis.yml 与 --patch 覆盖层、固定的
--root/--state-dir、安全注意事项）：
docs/dsh-integration.md。一份为
DSH 风格工作区（.agents/notes、临时插件、生成产物）调优的策略：
examples/registry.dsh.example.json。

可选的 Metabolic Maintenance 技能插件
为 DSH 的技能目录添加了后果感知的维护规则和下游恢复验证。
它按需加载指令，并可与上述 MCP
工具配合使用。下载该插件。
发布版本也会镜像到插件的分发仓库，
metabolism-tools/dsh-metabolic-maintenance，
该仓库带有 dsh-plugin 主题，因此插件目录可以将其索引为插件。

安全模型

- 除非给出 --yes，否则 clean 为试运行。
- G4 需要 --yes；G3 需要 --approve 和 --approver（审计追踪）。
- 敏感文件绝不会被自动清理：audit 会在专门报告部分标记密钥/密钥文件/凭据
（.env、.pem、.key、token、secret、credential、id_rsa、……），
策略验证器拒绝将敏感路径注册为 G4 自动清理，并且 clean 会跳过任何包含敏感文件的候选对象。
- Git 感知分类：在 git 仓库中，已跟踪文件计为受 git 控制
（实际上为 G2）——它们会从审计的未注册列表中排除，并且 clean
会跳过包含 git 已跟踪文件的候选对象。非 git 工作区回退到纯
策略匹配。（Git 是可选的；wm 从不依赖它。）
- 项目会以逐文件 SHA-256 哈希移动到回收区；rollback
会在恢复前验证它们，并拒绝覆盖现有路径。
- purge 仅在保留期后删除回收区内的文件批次。
- 日志是哈希链；verify 可检测任何篡改。

计划运行

带有 {{PLACEHOLDERS}} 的模板位于 examples/：

- Windows — register_schedule.template.ps1：每日只读审计（20:30），
每周 G4 清理（周六 10:00），每月清除（1 日，10:30）。
- Linux/macOS — register_cron.template.sh：通过 cron 实现相同计划。

将 {{WM_CMD}}、{{ROOT}}、{{REGISTRY}}、{{STATE_DIR}}（以及
cron 中的 {{USER}}）替换为你的值。这些脚本有意不
自动检测你的环境——你的路径，由你决定。

开发
bash
python -m pip install -e . pytest
python -m pytest

CI 在 Ubuntu、Windows 和 macOS 上使用 Python 3.11 和
3.12 运行完整测试套件。问题在周末处理；欢迎提交拉取请求。

项目家族

姊妹组织：Holdout —— 一个
对抗定量研究中自欺的工具链：

- falsification-ledger —— 预注册与证伪账本
- factor-qc —— 故障关闭式回测质量门禁
- pit-adjuster —— 带漂移检测的 PIT 后复权
- lookahead-free —— 可验证的前视偏差自由检查
- ashare-data-immunity —— A 股日线数据免疫
- lesson-book —— 交易者的学费记忆

如果 workspace-metabolism 让工作区保持活力，那么 Holdout 让
研究保持诚实。

许可证

MIT
SQLite 行保留

retain 为每个 JSON 组保留最新的 N 个版本，外加所有被引用的版本，包括来自旧载荷的引用。它从不更改 blob 内容。
最具体的相对于工作区的条目必须显式允许在 G2 数据库上执行 db_retain；G1、never_clean、活动声明和 --protected-window 会阻止执行。没有任何 CLI 覆盖可以削弱该策略。
json
{
"path": "data/objects.db", "grade": "G2", "cleanup": "never",
"db_retain": {
"table": "objects", "id_column": "hash", "blob_column": "body",
"group_by": ["code", "month"], "order_column": "captured_at", "keep": 2,
"blob_encoding": "gzip", "verify_sha256": true,
"reference_paths": ["objects//"]
}
}

此处 objects// 遍历所有行中对象 ID 列表的 JSON 字典。缺失的可选字段不包含任何引用；格式错误的容器、缺失的被引用行、无效 JSON、哈希不匹配、不支持的 schema 或超出预算都会停止操作。未分组的载荷行始终保留。
空的 reference_paths 明确断言行没有表内引用。WM 无法发现未声明的或外部消费者；策略作者必须在授权删除之前确立该边界。不支持触发器、外键关系、生成列和复合主键。
bash
wm --root /workspace --registry policy.json retain --db data/objects.db
wm --root /workspace --registry policy.json retain --db data/objects.db --yes
wm --root /workspace --registry policy.json retain --db data/objects.db --restore retain-RUN_ID
wm --root /workspace --registry policy.json retain --db data/objects.db --restore retain-RUN_ID --yes

使用已执行命令返回的实际 run_id。预览不会写入任何维护状态。执行会在一个 SQLite 写事务内进行规划，导出所有列及其类型，持久化并读回该导出，然后执行删除。
恢复数据位于 /retention//，在文件 purge 的范围之外，且不会自动过期。请保留它，直到下游验收和恢复要求得到满足；不要仅按时间回收这些备份。
被中断的 prepared 批次会阻止另一次保留运行；请检查它并使用 --restore 进行协调。恢复会验证导出、原始数据库身份和 schema，并拒绝覆盖已更改的行。已经完全相同的行会保持不变，从而使被中断的恢复可以重试。哈希检测的是意外更改，而不是对导出和清单两者的恶意替换。

默认将扫描限制为 1,000,000 行 / 512 MiB 编码内容 / 120 秒，解码行限制为 32 MiB，恢复导出限制为 64 MiB。策略可以降低这些限制。没有自动 VACUUM，因此报告声称磁盘回收为零；已删除的数据库页在 SQLite 内部仍可重用，而恢复文件会占用空间。存储检查并不能确立下游业务正确性。
参考 tests/test_retain.py，了解引用保护、故障注入、并发写入者排除、精确恢复以及拒绝损坏的恢复材料。

受信任的主机集成可以向 Python 的 retain 函数提供一个声明后端，该后端实现 transaction() 和 cleanup_claims()。该后端必须复用主机的权威锁，并保留活动/未解决的 scope；CLI 绝不会忽略外部注册表。eligible_ids 只能缩小 WM 自身的安全候选范围，而 expected_ids_sha256 会在持有 SQLite 事务期间拒绝过期的调用方快照。

维护证据（0.5.1）

wm --state-dir /path/to/state evidence 会打印 journal.jsonl 的有界、只读 JSON 摘要。可选地添加 --observation check.json，以读取一个现有检查，其中包含带时区的 checked_at 和布尔值 ok。不需要任何策略。每个输入限制为 8 MiB；不会写入任何文件。

退出码 0 表示存在非空且内部一致的日志，并且在请求时，表示存在可读且有效的检查。这并不意味着系统是健康的。缺失、为空、损坏、不受支持或过大的证据会返回退出码 1。时间关联并不能确立匹配的 scope、新鲜度、因果关系或业务恢复。人工监督、Token 成本和净节省仍然未知。参见案例收集指南。

安全的近期行保留（0.5.2）

slim 现在可以匹配真实的数据库关系，而不是假设排序时间戳嵌入在每个 JSON 负载中：
json
"db_slim": {
"table": "work_units",
"blob_column": "payload_json",
"strip_keys": ["regenerable_detail"],
"protected_keys": ["consumer_evidence", "failure_reason"],
"keep_recent": {
"table": "epochs", "column": "created_at", "n": 3,
"key_column": "epoch_id", "row_column": "epoch_id"
},
"vacuum_min_gb": 1.0
}

column 对引用表进行排序；key_column 连接到工作表（work table）的 row_column。引用键必须唯一且非空。对于将要更改的行，如果缺少关系，则会在任何更新之前停止整个计划。报告中的 rows_kept_recent 统计了原本可修改但因时间而被保护的行。省略这两个新列的策略会保留旧版 JSON 匹配行为，但缺失或未知的引用现在会停止，而不是静默剥离该行。请在计划使用前迁移此类策略。受保护的键是顶层 JSON 键；冲突的 CLI 剥离请求会被拒绝。这不是递归字段匹配。

执行会在规划和更新期间持有 wm 状态锁和 SQLite 写事务。预览以只读方式打开数据库，但仍会写入现有的 wm 日志。外部写入者仍必须遵守应用程序的维护窗口；这些锁不会验证消费者正确性，也不会协调其他系统。备份/恢复和维护后的消费者检查仍然是必需的。