cc-clean

# cc-clean：Claude Code 环境检查与清理 版本 v0.2.2。Codex 使用 `$cc-clean`；Claude Code 使用 `/cc-clean`。 把指定环境中的旧账号状态处理清楚，并证明保留项没有被误改。适用于账号封禁、无法访问、账号切换和独立网关迁移。账号问题本身走官方恢复或申诉；本地操作不改变服务端记录，也不保证新账号状态。 默认从只读检查开始。用户已明确给出目标与保留范围时直接推进；不重复索要已有授权。删除文件、清空历史、变更凭据等操作，必须对应用户确认的具体清单。读库文件不等于执行数据库操作；不要打开、查询或修改 SQLite / Keychain 数据库，使用平台的凭据工具。 ## 先确定环境 识别当前任务属于哪种场景，选择所需步骤： | 场景 | 目标与处理重点 | |---|---| | 被封、旧账号无法访问 | 先列账号缓存和凭据的实际位置；按范围移除本机旧状态，保留工作资产。缓存身份不能证明封禁原因。 | | 普通账号切换 | 可正常访问时优先官方退出/重新认证流程；先说明退出会修改状态并可能撤销凭据。希望同时保留多个账号时使用独立配置目录。 | | 官方登录转网关、网关换模型 | 查清配置目录、实际认证来源和共享依赖；只清已确认的旧 Claude 凭据，供应商密钥和路由设置按用户范围保留。 | | 清本地遥测或保护历史 | 遥测按文件清单处理；历史里的密钥按记录定点脱敏，默认保留其余行。后续采集开关另行决定。 | | 恢复、迁移到新机器 | 先验证备份内容和凭据影响；恢复会带回旧身份或密钥。复制工作配置时排除用户不想迁移的账号状态。 | 定位实际 `CLAUDE_CONFIG_DIR`、主状态 JSON 和凭据存储。默认目录与默认 `~/.claude.json` 是两个位置；自定义目录下主状态文件若已位于该目录内，只传目录 `--root` 并配合 `--state-file`，避免父子根重叠报错。工作目录与输出路径不得包含符号链接祖先（macOS 的 `/tmp`、`/var` 需解析为 `/private/...` 或选主目录外侧私有目录）。用户排除的环境完全不查不改。 检查启动入口、当前相关进程、shell 配置和 settings 中的环境变量时，只输出配置目录、经过脱敏的 endpoint、凭据变量是否存在。不要打印完整进程环境、shell 配置或 `.env`。不要启动 Claude 来探测版本、退出或登录，除非用户已授权该动作。 复杂的账号/网关或平台凭据问题，读 [references/credentials.md](references/credentials.md)。上游清理器的适用范围和本技能的设计依据见 [references/sources.md](references/sources.md)，无需每次全读。 ## 只读检查与清单 检查五类位置：遥测/调试、主配置与旧备份、平台凭据、用户指定的独立配置目录、输入历史。按用户范围选择，不做全盘密钥搜索。 默认保留：项目设置与会话、`projects/*/memory`、`settings*.json`、`CLAUDE.md`、Skills、commands、agents、plugins、rules、hooks、MCP 配置/凭据，以及网关路由和正在使用的 API Key。`file-history`、shell snapshots、transcripts、tasks、plans 也属于工作数据；不要按文件年龄或“原项目路径不存在”就判定可删。 账号字段以本机版本为准。`oauthAccount`、`userID`、`machineID` 和权益缓存是检查线索，不是固定删除表。先确认关联性；必要的同值比对在本地内存中完成，只回报是否一致或脱敏信息。Device ID 精确识别 `deviceId`、`device_id`、`deviceID`，覆盖显式主状态 JSON 中的嵌套对象与数组；没有相关字段时不新造字段，不把 `machineID` / `userID` 与 device ID 自动等同。用户未授权读取凭据内容时，只查存在性和元数据。 本地工具（Python 3.10+，无第三方依赖）可生成文件元数据报告，**不哈希/读取凭据正文、不解析历史正文、不删除源文件**。主状态 JSON 仅在提供 `--state-file` 时读取：账号/缓存输出存在性和数量，device ID 另输出字段名、结构位置、JSON 类型及默认保留标记，**不记录原值、原值哈希或祖先键名**。位置用从 0 开始的对象键序号与数组下标，防止路径本身泄露邮箱或 ID。发现字段不证明它非空、有效或属于旧账号；清理前仍须核实真实字段路径与当前文件指纹，验证备份并取得具体确认，不将报告直接当执行清单。缓存字段提示不等于可删除；未分类顶层字段计数非零时，按本机版本在本地内存补充核查，对外仅记录结构序号、类型与计数，不输出可能携带身份信息的原始键名，不能称账号状态已完整覆盖。报告写在指定环境之外，权限 0600： ```bash python3 -B <skill目录>/scripts/local_state.py audit \ --root default="$HOME/.claude" \ --root state="$HOME/.claude.json" \ --state-file "$HOME/.claude.json" \ --output /已选择的工作目录/audit.json ``` 缺失位置列为未找到；无权限、无效 JSON、符号链接或未完成检查列为未验证。不要把工具错误当作“不存在”。符号链接只记录链接，永不顺着它清目标；涉及共享链接先处理保留关系。 Device ID 递归检查只覆盖已选主状态文件里的 JSON 对象/数组，不展开字符串或 Base64 内容，不读取其他日志、遥测、历史、凭据正文，不获取或重置系统硬件 ID。重复 JSON 键或无法完成解析时拒绝给出完成结论；旧报告没有递归摘要时也不解释为未发现 ID。字段结构与覆盖边界见 [references/review.md](references/review.md#device-id-字段摘要)。 `audit.json` 同时包含项目会话、`session-env`、`file-history`、debug 和 todos 的**路径元数据关联**。同根 UUID 一致仅证明标识关联，跨根不合并；目录编码不反向解码成项目路径。缺少 `session-env`、项目路径不存在或文件年龄都不能单独成为清理依据。关联项记录证据来源、置信类型、未验证原因和保留理由，清理授权固定为 false。 需要可视化审阅时，从已生成的审计文件制作只读 HTML： ```bash python3 -B <skill目录>/scripts/local_state.py report \ --audit /已选择的工作目录/audit.json \ --output /已选择的工作目录/report.html ``` 报告只读取提供的审计文件，不重新访问环境；可搜索、筛选类别/关联并导出遮罩后的审阅清单。HTML 没有删除、应用、恢复按钮或网络接口，导出清单不含操作、不代表批准。常见邮箱、UUID、home 路径与密钥格式默认遮罩；不能保证任意文件名无私有信息，分享前复核。原始 JSON 清单权限 0600，仍是私密材料。关联和报告字段/边界见 [references/review.md](references/review.md)。 形成可审阅的计划后再请求最终执行确认。先完成可逆的备份与验证；如果用户只要只读检查，就交检查结果，不额外备份或修改配置。计划写法及执行要点见 [references/operations.md](references/operations.md)。 ## 备份、执行与验收 备份应覆盖会改动的配置目录、目录外主配置和批准处理的旧备份；网关、路由器或其他环境明确排除时，不把它们悄悄加入。用户已做好备份时优先验证复用，避免重复复制。Keychain 的恢复材料单独处理，文件备份不能冒称包含钥匙串凭据。 `backup` 只向新目录复制，逐文件校验 SHA-256、权限/属主和符号链接，并验证复制前后源内容一致，产生恢复样本。macOS 使用 `ditto` 请求保留 ACL 和扩展属性；其他 POSIX 平台仅承诺工具实际核验的文件内容与基础元数据： ```bash python3 -B <skill目录>/scripts/local_state.py backup \ --root default="$HOME/.claude" --root state="$HOME/.claude.json" \ --output /已选择的私有备份目录/本次备份 python3 -B <skill目录>/scripts/local_state.py verify \ --backup-dir /已选择的私有备份目录/本次备份 --check-source ``` 辅助工具不包含删除/应用命令。实际清理由 agent 根据已确认清单生成并检查本机操作，执行前验证备份、文件指纹和写入状态；这一层不能用通用批量清理器替代。对每个目标使用明确路径和字段，防止通配符扩展、符号链接和临时文件误删。保持 JSON 中未选字段语义不变；修改 history 时保持其他原始行逐字节不变。macOS 原位替换前用原文件克隆元数据，保留权限和 ACL。 恢复同样先验证旧备份，再对当前状态生成独立且已验证的备份（若待恢复的单文件根已被移除，用 `backup --allow-missing` 记录缺失前态）。`prepare-restore` 只产出逐文件计划；`record-restore` 只观察随后由 agent 根据真实用户批准执行的恢复。回执比较所选文件与旧备份、全部未选项与恢复前备份，异常结果不会退出为成功。工具不执行恢复，也不验证人的授权；操作前仍须核对授权与指纹。用法及限制见 [references/review.md](references/review.md#恢复计划与回执)。 如果目标环境的会话仍在写入（包括在目标环境的 Claude Code 会话内直接调用 `/cc-clean`），宿主会话每次工具调用都会追加 `projects/` 与 `debug/` 日志，导致全树静止校验失败；此时在当前会话内只做只读 `audit` / `report` 与计划确认，备份、`verify --check-source`、清理和恢复须在退出目标 Claude 会话后从外部环境（如 Codex `$cc-clean` 或独立配置目录）执行。不要杀进程或关闭无关 IDE。源文件新增/改变就重新核对并更新备份，原批准范围仍有效时无需重新批准相同操作；新目标必须补确认。出现中途失败则保存完成清单与未完成清单，不扩大清理范围或擅自回滚。 实际操作后验收：删除目标确实消失；JSON 仅移除了批准字段；凭据只变更指定 namespace/子项；受保护文件、共享依赖和路由配置未改变；历史行数和未选行一致。在线模型/登录测试只有用户已授权时才执行，说明目的地、测试内容及预计最小用量，不发送原始历史或私有文档。一次路由成功仅代表那次调用。 交付备份位置与验证范围、实际变更清单、保留项对比、未验证项和恢复方式。清理本地文件、停止未来采集、服务器记录和账号申诉分别说明。发现历史密钥时说明原始备份仍保留密钥；是否轮换由实际暴露情况与用户范围决定，不能用脱敏结果证明未外泄。