常用工具、保护清单与事务#

先用现成的小工具#

这些工具使用 Python 3.10+ 标准库，面向 POSIX/macOS。它们只读生产来源，输出写入私有目录；不判断旧账号归属、不退出应用、不清登录，也不发布或回滚生产文件。先核验本机解释器版本，将 Python 3.10+ 的实际路径设为 CLEANUP_PYTHON，不能假定命令 python3 已满足版本要求。以下 SKILL_DIR、PRIVATE_DIR、源路径及 SHA 均由本轮实际发现，不能照搬历史值。私有工作目录必须在应用管理根之外，使用无软链接祖先的真实绝对路径。

精确 JSON 候选#

私有 targets.json 是一个 0600 的 JSON 文件，父目录由当前用户所有且权限为 0700。内容是精确对象键路径，例如 [["account", "oldToken"], ["oldPreference"]]；这些只是语法示例，不是 Claude 的固定字段或删除清单。先核实字段、旧身份归属与本轮授权。

# 预览不写来源或候选，只输出状态、目标数量及前后 SHA。
"$CLEANUP_PYTHON" -B "$SKILL_DIR/scripts/json_candidate.py" \
  --source "$CONFIG_FILE" --targets "$PRIVATE_DIR/targets.json"

# SOURCE_SHA256 取自刚才的预览；candidate.json 必须不存在。
"$CLEANUP_PYTHON" -B "$SKILL_DIR/scripts/json_candidate.py" \
  --source "$CONFIG_FILE" --targets "$PRIVATE_DIR/targets.json" \
  --expected-sha256 "$SOURCE_SHA256" --candidate "$PRIVATE_DIR/candidate.json"

只支持严格 UTF-8 JSON 中的对象成员删除，不支持 JSONC、根替换、通配符、数组元素或穿过数组寻址。重复键、缺失目标、重复或祖先/后代重叠路径、非有限数值及来源变化均拒绝；限制为 8 MiB、64 层、100,000 节点、256 个目标。候选不能覆盖已有文件或写在来源的同一父目录；完整应用根仍由代理核对。工具核验剩余结构/token并回读候选，但它不知道某字段是否属于旧账号。

成功退出 0，拒绝/错误退出 2；stdout 无原值，stderr 只给固定错误码。SOURCE_HASH_MISMATCH / SOURCE_CHANGED 要重新核对来源；TARGET_MISSING / DUPLICATE_KEY / OVERLAPPING_TARGETS 要修正目标或改用匹配格式的方法，不能放宽为全局删键。CLEANUP_INCOMPLETE 表示失败候选仍需核对处理，不能当成功交付。

SQLite 私有检查副本#

# PRIVATE_DIR 已是当前用户所有的 0700 目录；db-inspection 必须不存在。
"$CLEANUP_PYTHON" -B "$SKILL_DIR/scripts/sqlite_snapshot.py" \
  --source "$DATABASE_FILE" --out-dir "$PRIVATE_DIR/db-inspection"

输出为 0700 目录中的 source.sqlite、存在时的 source.sqlite-wal、副本引擎可能生成的 SHM，以及 0600 report.json。需要绑定预先已确认的 DB 字节时可加 --expected-sha256；该 SHA 只绑定 DB，WAL 仍由本次实际成员及哈希检查覆盖。只处理 SQLite 引擎能读取的格式，不提供解密；总源成员上限 256 MiB，副本检查设有 15 秒进度中止条件。

源 DB/WAL/SHM/journal 按实际存在性核验，不把无 SHM 当无 WAL。非空 rollback journal 报 ROLLBACK_JOURNAL_PRESENT，先调查或等待冷态；来源变动报 SOURCE_CHANGED，不得把失败副本继续当有效输入。非空 WAL 仅按 SQLite WAL 头部格式 检查长度、magic、版本及页大小，不支持的头部报 WAL_HEADER_UNSUPPORTED。报告明确不验证 WAL 帧语义，quick_check 不能证明所有原始 WAL 帧或事务都被引擎采纳。

SQLITE_CHECK_FAILED 包含不可读取格式、损坏或检查未完成，不能据此断言原库损坏。输出不得位于源数据库父目录或其子目录，工具拒绝覆写已有目标及软链接路径。

成功退出 0，拒绝/错误退出 2。成功只证明本次观察期间来源稳定且副本 quick_check 通过，不证明在线多文件原子一致、账号归属、删除效果或可用登录。副本含原始私有数据；失败时工具清退自己的输出，CLEANUP_INCOMPLETE 或进程被中断时须单独核对残留。完成调查后按保留决定清退副本，不能把它遗留为另一套日常来源。

文件保护 helper#

scripts/file_guard.py 只使用 Python 3.10+ 标准库。它读指定源、写私有清单/报告，不复制源文件、不删除源文件、不停止进程、不解析 Claude 数据库。哈希清单不能当回滚备份。

根输入只接受目录。先选择准确的保护根，避开本来获准变更的混合库；混合库另做逻辑非目标比较，单个配置文件可另作哈希验证。每个根取唯一中性标签，根之间不能嵌套/重叠。它会记录空目录和软链接本身，不跟随链接；外部目标需要单独列为根才在保护范围内。使用核实过的真实绝对路径，macOS /var 等软链接别名不能直接作为输入。

# SKILL_DIR 指向安装的 claude-local-cleanup 目录；PRIVATE_DIR 是本次私有证据目录。
# TRANSCRIPT_ROOT / WORKSPACE_ROOT 来自本轮实际发现，勿直接套默认父目录。
umask 077
mkdir -p "$PRIVATE_DIR"
"$CLEANUP_PYTHON" "$SKILL_DIR/scripts/file_guard.py" snapshot \
  --root "transcripts=$TRANSCRIPT_ROOT" \
  --root "projects=$WORKSPACE_ROOT" \
  --out "$PRIVATE_DIR/before.json"

# 实际获准变更完成后，使用完全相同的标签和路径重新生成清单。
"$CLEANUP_PYTHON" "$SKILL_DIR/scripts/file_guard.py" snapshot \
  --root "transcripts=$TRANSCRIPT_ROOT" \
  --root "projects=$WORKSPACE_ROOT" \
  --out "$PRIVATE_DIR/after.json"
"$CLEANUP_PYTHON" "$SKILL_DIR/scripts/file_guard.py" compare \
  --before "$PRIVATE_DIR/before.json" \
  --after "$PRIVATE_DIR/after.json" \
  --out "$PRIVATE_DIR/comparison.json"

snapshot 拒绝不稳定/不可读/异常类型的来源、带软链接祖先的根、覆盖已有输出或在源内写输出。清单对文件记录 SHA-256、大小和 mode，对链接记录目标文字，对目录记录 mode；目录时间不作为内容等价要求。读取期间做变化检测，但不是跨目录原子快照，更不能证明没有其他进程。

读取自身可能改变 atime，不把它作为用户内容被修改的证明。需要校验缓存索引的新鲜度时另按实际格式维护元数据；不能事后修改 mtime/ctime 来掩盖业务差异或让检查通过。

若用户后来明确要求删除保护集合里的特定记忆，单独提供 JSON 数组，内容为精确的 标签/相对路径 键，包括实际被删除的目录项：

["transcripts/example/memory", "transcripts/example/memory/MEMORY.md"]

给 compare 添加 --allow-removed "$PRIVATE_DIR/authorized-removals.json"。每项都必须原先存在、现在缺失；未知、重复、未使用例外应报错。例外不允许内容改变、额外新增或按目录前缀跳过；这份文件只是验证输入，不能代替用户授权。清单键从真实基线读取，示例不是实际路径。

退出码：0 为快照成功或比较通过，1 为存在未获准差异，2 为参数/格式/不稳定来源错误。stdout 只给汇总；清单和比较报告含私有路径，应留在 0700 目录，文件为 0600。不会保存源文件内容。输出 I/O 失败可能留不完整文件，不能拿它当有效基线；检查后只处理本次输出，不覆盖任何原件。可用 "$CLEANUP_PYTHON" -B "$SKILL_DIR/scripts/test_file_guard.py" 运行纯合成回归。

stderr 仅给固定错误类别：PATH_NOT_REAL_DIRECTORY 指向非真实目录/软链接路径，SOURCE_CHANGED 表示观察到源变化，INVALID_MANIFEST / INVALID_REMOVAL_LIST 表示输入清单无效，OUTPUT_EXISTS 表示拒绝覆盖。按失败阶段核对，不为绕过拒绝自动跟随用户目录软链接；类别不包含私有路径，也不能证明是谁改了文件。

会话索引到正文的关联、外部 workdir、数据库语义、磁盘锁及 UI 恢复仍需另行验证。基线一旦退役，就不能再声称后续检查与它逐字节一致。

最小事务清单#

为每批保存：当前版本、授权范围、source 路径/UID/类型/links/哈希、精确操作、变更后的预期、非目标验证方式、保护集合、回滚位置、内容分类状态。摘要不携带秘密；原路径和原件私有保存。

计划默认只读。没有误解授权时直接准备并执行，不额外造审批仪式；缺少对某项副作用的授权时，先准备到具体可审阅，再只问该项。

外部文件写入前与每个步骤的条件#

此冷态约束针对外部替换、移动或重写应用数据文件。受支持的应用原生操作由应用管理写入，不套用停机前置；但仍须验证目标范围、保全与结果，不能为省事使用会伤害新登录/他站数据的整站清除。

• 相关应用、CLI、helper 和数据库写入者确已停止，且没有未知文件占用；核对完整可执行路径，不能按模糊 claude 字符串杀进程。
• 来源与计划一致；目标在允许根内、owner 合理、无未评估 symlink/hardlink/特殊文件；不跟随路径意外写到根外。
• 原件备份可核验且必要用户内容已保全。原件和暂存文件均有唯一事务 ID；禁止将上次失败临时文件当本次输入。
• 每次 move/replace 与每次 rollback 前再次判断冷态及来源条件。该守卫有检查到写入的竞争窗口，不能冒称系统级防启动锁；捕获变化即停止并留恢复材料。

执行与恢复#

先在私有副本完成变换、校验格式和所有非目标；生产安装用同卷暂存原件与单文件原子替换，保留每步 journal。跨多个文件的操作可部分完成，所以 journal 必须足以恢复任意已执行前缀。

同一目标分多批清理时，区分“最初封存版本”和“本批修改前版本”。本批暂存/回滚必须能精确恢复当前基线；不能把已做过其他清理的文件替换为更早的原件。提交前保留当前原件至来源内容、派生元数据、索引和使用者验证通过。

失败只处理本事务确切创建/替换的项目。回滚前校验当前内容等于本事务预期写入值，拒绝覆盖后来变化。若应用中途启动，停止一切恢复写入，报告 rollback_pending_cold_state；重新冷态后才继续。不得无声强杀应用以使流程通过。

需要新写适配器时，对实际故障风险做少量有意义的私有 fixture 验证：移走一半失败、替换后失败、回滚中重新启动、非目标值不变、内容保全未通过时不永久删除。只读审查或简单可逆文字修改无需套用这套故障测试。

结果状态应能追溯#

可用状态为 audited_no_action、planned、applied_verified、partial、rollback_pending_cold_state、rolled_back_verified。副本生命周期另记 rollback_available 和退役验证，不要用一个“完成”掩盖部分失败。

最终摘要包含 scope、checked_at、目标计数、读取错误、非目标比较、保护基线及关联验证、归档验证、启动验收是否完成、保留与未知项。只陈述实际运行过的验证；当前文件为零与“这个脚本会检查”不是一回事。

证据注明采用的方法：原始字节、有效记录、内容语义、来源哈希、真实读取与人工归属确认各自有证明范围。未查与明确受阻分开记录，受阻项列具体失败及最小下一步；继续/停止条件以技能入口为准。

后续小批改动可复用已通过基线，以 前一已验证状态 → 本批精确变换与非目标比较 → 当前状态 连成证据链；同时更新当前来源哈希和依赖闭包（包括附件/图库引用）。不要拿旧报告的哈希冒充当前文件，也不要在无新风险时重复整库验收。