工作区清理器（Workspace Cleaner）

专为 OpenClaw 工作区设计的安全、自动化清理工具。可识别临时文件、重复内容与无用文件，同时严格保护重要数据。

快速开始

# 预览将被删除的文件（安全模式，不执行任何更改）
python3 {{SKILL_DIR}}/scripts/cleanup.py

# 执行实际清理（使用系统回收站，支持恢复）
python3 {{SKILL_DIR}}/scripts/cleanup.py --execute

# 指定自定义工作区路径
python3 {{SKILL_DIR}}/scripts/cleanup.py --workspace /path/to/workspace

功能特性

• 默认启用模拟运行（dry-run） —— 始终先预览，再删除
• 基于回收站操作 —— 文件移入系统回收站，可随时恢复
• 尺寸感知能力 —— 显示各文件大小，支持按阈值过滤
• 按修改时间过滤 —— 仅匹配早于 N 天的文件
• 模式高度可定制 —— 编辑配置文件以适配您的工作流
• 支持 JSON 输出 —— 提供机器可读格式，便于自动化集成
• 安全的默认策略 —— 绝不触碰 .git 目录、memory/ 目录及核心配置文件

命令说明

预览（默认行为）

python3 {{SKILL_DIR}}/scripts/cleanup.py

显示将被删除的文件及其大小，不执行任何实际更改。

执行清理

python3 {{SKILL_DIR}}/scripts/cleanup.py --execute

将匹配项移入系统回收站，可通过系统回收站恢复。

按大小过滤

# 仅显示大于 100MB 的文件
python3 {{SKILL_DIR}}/scripts/cleanup.py --min-size 100

按修改时间过滤

# 仅显示修改时间早于 30 天的文件
python3 {{SKILL_DIR}}/scripts/cleanup.py --min-age 30

JSON 格式输出

# 适用于自动化脚本或结构化解析
python3 {{SKILL_DIR}}/scripts/cleanup.py --json

使用自定义配置

# 指定自定义模式配置文件
python3 {{SKILL_DIR}}/scripts/cleanup.py --config /path/to/patterns.json

默认清理范围

默认匹配规则（可通过配置文件自定义）：

受保护的内容

无论配置如何，以下内容均永不删除：

• .git/ 目录
• memory/ 目录
• MEMORY.md、SOUL.md、USER.md、AGENTS.md
• projects/ 目录下的全部内容
• skills/ 目录下的全部内容
• 最近 24 小时内被修改过的文件（除非显式指定 --include-recent）

配置方式

编辑 {{SKILL_DIR}}/config/patterns.json 文件来自定义清理行为：

{
  "temp_extensions": [".tmp", ".bak", ".log", ".skill"],
  "temp_patterns": ["*~", "#*#"],
  "image_extensions": [".png", ".jpg", ".jpeg", ".gif"],
  "protected_dirs": ["memory", "skills", "projects", ".git"],
  "protected_files": ["MEMORY.md", "SOUL.md", "USER.md", "AGENTS.md"],
  "known_venvs": [".venv-skill-scanner"]
}

HEARTBEAT 集成

在您的 HEARTBEAT.md 中添加如下条目，实现周期性清理检查：

## 每周清理检查
- 以预览模式运行 workspace cleaner
- 若发现超过 500MB 的冗余文件则发出告警
- 自动清理修改时间早于 30 天且体积小于 10MB 的文件

安全须知

1. 务必先执行预览 —— 不加 --execute 参数运行，确认将要删除的内容
2. 检查回收站 —— 所有文件均进入系统回收站，而非永久删除
3. 使用排除模式 —— 对疑似冗余但实际需保留的文件，使用 --exclude 参数跳过
4. 大规模清理前建议备份 —— 特别是在执行大范围清理前，请考虑先行备份

使用示例

常规维护

# 每周清理明显冗余文件
python3 {{SKILL_DIR}}/scripts/cleanup.py --min-age 7 --execute

定位空间占用大户

# 查看哪些文件占用了大量磁盘空间？
python3 {{SKILL_DIR}}/scripts/cleanup.py --min-size 50 --json | jq '.items | sort_by(.size_mb) | reverse'

提交前清理

# 提交代码前自动清理
python3 {{SKILL_DIR}}/scripts/cleanup.py --execute && git status

运行依赖

• Python 3.8 或更高版本
• trash 命令（macOS：运行 brew install trash；Linux：安装 trash-cli）