用途
Code Purge 是一个用于深度代码分析与自动化清理的技能，目标是从任意代码库中安全、彻底地移除废弃物，包括死代码、未使用的导入、未被引用的文件和重复逻辑，并对复杂代码进行简化。
主要能力
该技能围绕五阶段工作流展开：
-
Phase 1 — Analyze：运行捆绑的分析脚本
python3 scripts/analyze.py <project_root> --summary获取快速概览，或--json获取完整机器可读报告。脚本自动检测语言并分派到已安装工具：Python 使用 vulture（死代码）和 pyflakes（未使用导入）；JS/TS 使用 knip（未使用的导出、依赖、文件）；所有语言使用 jscpd（重复块）。同时进行手动分析：扫描 package.json / pyproject.toml / Cargo.toml 中的未使用依赖；检查 TODO、FIXME、HACK 注释；检查超过 12 个月未被触碰且无外部调用者的文件/函数；运行radon cc . -nb（Python）或lizard . --CCN 10（多语言）审查复杂度。 -
Phase 2 — Report & Confirm：在触碰任何文件前呈现结构化报告，按类别列出发现（死代码、重复、未使用文件、未使用导入、复杂度），每个类别列出带 file:line 的顶部发现，并询问用户清理范围。未经用户明确确认，不进入 Phase 3。
-
Phase 3 — Backup：通过
bash scripts/backup.sh <project_root>创建备份。脚本生成 Git 状态和二进制补丁（若在 git 仓库内），并在${XDG_STATE_HOME:-$HOME/.local/state}/code-purge/下创建包含未跟踪文件的 .tar.gz 归档。可通过CODE_PURGE_BACKUP_ROOT覆盖备份位置。脚本不会写入、暂存、贮藏、重置或以其他方式修改目标仓库。回滚命令为tar -xzf <backup-directory>/project.tar.gz -C <project_root>。 -
Phase 4 — Clean：按顺序执行移除以最小化级联错误：4a 未使用导入（Python 用 autoflake，JS/TS 用 ESLint fix）；4b 死代码（先移除高置信度发现，每次移除后 grep 检查引用，每批 5–10 个后验证编译/导入）；4c 未使用文件（删除前确认无字符串引用，删除后清理空目录，保留可能影响包结构的 init.py 和按名称加载的配置文件）；4d 重复合并（提取共享逻辑，更新调用点，删除副本，每组一个提交）；4e 复杂度重构（应用守卫子句/提前返回、提取子函数、用字典分派或替换长 if/elif 链）。
-
Phase 5 — Verify：运行
bash scripts/run_tests.sh <project_root>，脚本自动检测 pytest、jest/vitest/mocha、go test、cargo test、rspec 和 maven。退出码 0 表示至少一个套件通过，1 表示某套件失败，2 表示无法执行任何套件（视为未验证，而非成功）。测试通过后以类似chore: remove dead code, unused imports, and 5 unreferenced files的消息提交；测试失败则定位导致失败的具体移除，从备份归档恢复该文件，重新运行测试确认，并调查“死”代码是否被动态调用（反射、配置），将相关项加入跳过列表后继续。
使用方式
工具安装：Python 侧 pip install vulture pyflakes autoflake radon lizard；JS/TS 侧 npm i -g knip jscpd，或使用 npm exec --offline knip 与 npm exec --offline jscpd -- .。分析阶段优先使用项目固定版本的工具可执行文件，避免让 npx 在分析期间下载并执行未固定版本的包。
适用场景
适用于需要从代码库中清理死代码、未使用导入、未引用文件和重复逻辑的维护工作，尤其适合长期未清理的历史项目。
限制与安全规则
该技能强调若干安全规则：永远不要跳过备份（即使“快速”清理）；永远不要在同一提交中混入死代码移除与功能变更；删除文件或函数前始终 grep 字符串引用；框架魔法（装饰器、信号、动态分派）对静态分析不可见，需要手动验证；公共 API 表面（已发布包、共享库）需额外谨慎，检查外部消费者；每次移除批次前阅读安全移除清单。分析依赖工具链与语言检测，若某语言无对应安装工具则无法自动处理。