# Cleanup Deprecated Artifacts

> Safely removes deprecated files, stale caches, and superseded code from a project while preserving anything still referenced. Use when the user asks to "清理", "整理", "清掉废弃", "remove deprecated", "cleanup legacy", "tidy up the repo", or when the agent spots obvious leftovers such as `tmp_*.html`, `setup_*.py` replaced by newer tooling, old prompt files, or abandoned yml references. Classifies each candidate into zero-risk / low-risk / high-risk tiers, runs a reference scan before deletion, updates cross-file links, and reports a clear before/after summary.

- Skill: `playerrch/cleanup-deprecated-artifacts` (Agent Skill)
- Install (CLI): `npx skillmds@latest add playerrch/cleanup-deprecated-artifacts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/playerrch/cleanup-deprecated-artifacts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: playerrch (https://skillmd.com/u/playerrch)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/playerrch/cleanup-deprecated-artifacts

---


# Cleanup Deprecated Artifacts

识别并清理已废弃的文件 / 代码 / 配置，保证不会误删还在被引用的内容。

## 风险三分类

| 档位 | 特征 | 处理 |
|---|---|---|
| **零风险** | 纯缓存、明确标记临时、已有 gitignore 覆盖；不被任何文件引用 | 直接删除，无需询问 |
| **低风险** | 被新版完全取代的旧脚本/旧配置；只被少数 docs 链接，引用可自动修正 | 列清单 → 引用扫描 → 同步更新 docs → 执行 |
| **高风险** | 历史日志、归档测试、用户自定义材料；或有多处强耦合引用 | 先 AskQuestion 用户确认，才执行 |

## 零风险候选（默认可删）

- `__pycache__/`、`.pytest_cache/`、`.mypy_cache/`、`.ruff_cache/`
- `*.pyc`、`*.pyo`
- `dist/`、`build/_work/`、`build/build/`、`build/Output/`（PyInstaller 产物）
- `node_modules/`（如果项目使用 npm）
- 明显调试残留：`tmp_*.html`、`tmp_*.py`、`_tmp_*.py`、`debug_*.log`
- 空目录（确认无隐藏文件后）

## 低风险典型模式

| 信号 | 大概率可删 |
|---|---|
| 文件名带 `_legacy_`、`_deprecated_`、`_old_` | 是 |
| 跟 v1 时代挂钩的 setup/install 脚本，已被 launcher / docker-compose 取代 | 是 |
| 旧版 prompt `*.md`，当前 prompt 已硬编码到工作流 yml | 是 |
| 旧版 Dify 参考 yml，实际 app 已通过 API 更新 | 是 |
| 在 README / CHANGELOG 里被明确标注"已移除"但文件还在 | 是 |

## 高风险典型模式（必须 AskQuestion）

- 归档的测试脚本（`_legacy_test_*.py`）—— 作者可能想保留作历史追溯
- `docs/` 下的历史文档、设计草稿、毕设材料
- `.verify_data/`、`backups/`、`archive/` 等以归档为目的的目录
- 生产历史日志（时间跨度超过 7 天、体积 > 10 MB）

## 标准工作流

### Phase 1 — 枚举候选

1. 扫项目树，列出"疑似废弃"的文件与目录
2. 按档位给每个候选打标签：零风险 / 低风险 / 高风险
3. 对低风险和高风险，输出一张可读表格：

   ```
   | 候选 | 档位 | 替代物 | 当前引用 |
   |---|---|---|---|
   | setup_dify.py | 低风险 | 已由自动化脚本取代 | docs/local-credentials.md |
   ```

### Phase 2 — 引用扫描（低风险必做）

```
Grep -r "<候选文件名>" --包括 Markdown/yaml/Python/PowerShell
```

对每个命中：
- 如果是"仅提及名字"，执行删除时同步修正引用
- 如果是"import/链接"的硬依赖，**降级为高风险**，必须询问用户

### Phase 3 — 用户确认（高风险必做）

用 `AskQuestion` 一次性出多选题给用户批：

```
候选 A：xxx（用途：yyy，已被 zzz 取代）
  - 删除
  - 保留
候选 B：...
```

### Phase 4 — 执行

- 零风险：直接 `Delete` / `Remove-Item`
- 低风险 / 获确认的高风险：先改引用 → 再删文件 → 再运行一次 Grep 验证没有残留引用

### Phase 5 — 后置校验

- 业务系统仍能启动（`python backend/app.py` 或对应语言的入口）
- 主要测试仍能通过（跑 unit + 快速 integration 子集）
- `ReadLints` 已修改的 Markdown / 代码
- 跑一次 `maintain-folder-readmes` skill，若删掉的文件需要从目录 README 的文件清单里移除，一并同步

### Phase 6 — 报告

给出一份清晰的"已删除 / 已保留并加备注 / 跳过"的清单，让用户一眼看懂变更：

```
已删除（零风险）：
  - tmp_signin.html    (339 KB, Dify 登录页调试残留)
  - __pycache__/       (约 120 处，Python 自动重建)

已删除（低风险）：
  - setup_dify.py      (已被脚本自动化取代)
  - setup.ps1          (已被 launcher 取代)
  同步更新了：docs/local-credentials.md

已保留（用户决定）：
  - .verify_data/      (v1.2 完整性快照，保留)
  - tests/_legacy_test_api.py  (头部加粗注释"仅历史追溯用")
```

## 关键约束

- **不动版本库状态不明的文件**：如果 `git status` 显示文件是"未追踪"且不在明确的废弃模式里，跳过
- **不动用户数据**：`*.db`、`.env*`、`secret.*`、`credentials.*`、用户上传目录一律跳过
- **不动他人代码**：第三方依赖目录（`Lib/site-packages/`、`node_modules/`）永远不碰，让包管理器管
- **不跨仓库**：只在当前项目范围内清理
- **变更必反馈**：凡是删了东西，都要生成一段汇总，不要静默

## 常见踩坑

- `/build/` 同名冲突：有的项目 `build/` 是自己的打包脚本（要保留），但又有 PyInstaller 临时产物（要删）。删前确认目录内容
- `__pycache__/` 看似无害，但 Dify docker 容器挂载的目录 `volumes/...site-packages/...__pycache__/` 也会被递归匹配到；正在运行的容器下一次启动会自动重建
- `.pytest_cache/` 有时带 `.gitignore`，删之前确认真的不在用
- venv 目录：`Include/`、`Lib/`、`Scripts/` 是扁平 venv 产物，不应误删（会破坏开发环境），应该**确保 gitignore 覆盖**而不是直接删

## 项目级记忆

如果项目已经清理过，之后再触发本 skill 时：

- 先查项目的 `docs/` 或顶层 `README.md` 是否有"已清理"记录
- 避免重复提议删除已经删过的东西
- 对于保留项（用户已明确说"保留"），下次不要再问