1. 项目概述为AI智能体打造的安全工作空间清理工具如果你和我一样日常工作中深度依赖Codex、Claude Code或OpenClaw这类AI编程助手那你肯定也遇到过这个头疼的问题项目目录里不知不觉就塞满了各种临时文件、重复的代码片段、过时的快照还有那些AI生成的、编码混乱到根本没法看的文档。这些“数字垃圾”不仅占用宝贵的磁盘空间更关键的是它们会拖慢你的开发工具干扰你的思路甚至让你在关键时刻找不到真正需要的文件。手动清理太费时而且风险极高一不小心就可能误删了还在迭代中的关键版本。OpenClearn正是为了解决这个痛点而生的。它不是一个简单的rm -rf脚本而是一个高度可配置、安全第一的AI智能体工作空间自动化清理工具包。你可以把它理解为你项目目录的“智能管家”它懂得AI工作流的独特模式能精准识别哪些是“垃圾”哪些是“宝藏”并在你的严格监督下执行清理动作。从v1.5版本开始它的能力得到了显著扩展新增了仅收集候选文件、生成审查报告、系统级磁盘扫描以及对乱码文档、重复文档的专项清理功能让清理工作从“凭感觉”变成了“有数据、有策略”的标准化操作。无论你是独立开发者还是团队中负责维护基础设施的工程师OpenClearn都能帮你建立起一个干净、高效、可预测的工作环境。接下来我将带你深入拆解它的设计思路、核心功能并分享一套从零开始上手到定制化高级策略的完整实操指南。2. 核心设计理念与工作模式解析OpenClearn的设计哲学非常明确安全可控高于一切自动化服务于决策而非替代决策。它没有采用“一键清理”这种高风险的黑盒模式而是设计了一套清晰、分阶段的工作流将“发现”、“审查”、“决策”、“执行”四个环节彻底分离。这种设计让你在享受自动化便利的同时始终牢牢掌握着最终的生杀大权。2.1 四大核心操作模式详解工具的核心通过--operation参数来切换不同的工作模式理解每种模式的用途和适用场景是安全使用的第一步。collect收集模式这是所有清理工作的起点也是最安全的模式。在此模式下OpenClearn会根据你的配置扫描指定的工作空间目录识别出所有符合清理条件的“候选文件”但不会进行任何删除操作。它只是将这些候选文件的路径、类型、大小、识别原因等信息以结构化的方式通常是JSON格式保存到一个中间状态文件中。这个模式相当于“侦察兵”只负责汇报敌情不发动攻击。我强烈建议在任何实质性清理前都先运行一次collect模式亲眼看看它到底找到了什么。review审查模式这是collect模式的增强版。它除了完成收集工作还会基于收集到的候选文件列表生成一份详细的Markdown格式审查报告。这份报告会按文件类型、清理原因如重复文件、过期快照、乱码文档等进行分类并列出每个文件的绝对路径、大小和简要说明。你可以把这份报告当作一个待办事项清单在文本编辑器或Markdown阅读器中仔细审阅决定哪些可以删除哪些需要保留。对于团队协作或需要留下审计记录的场景这个模式尤其有用。delete删除模式这是执行最终清理动作的模式。重要它不会直接读取扫描结果进行删除delete模式依赖于一个“批准文件”默认是state/g5_scavenger_approve.json。你需要手动或通过其他自动化审批流程将collect或review模式生成的候选文件ID或路径填入这个批准文件中。只有当文件明确出现在批准列表里时delete模式才会对它执行删除操作。这种设计彻底杜绝了误删因为每一次删除都对应着你的一次明确授权。cleanup传统清理模式这是v1.5之前版本的主要模式我们称之为“传统模式”。它在一个流程内完成了扫描、匹配基于内置规则和执行删除或移至回收站的动作。虽然效率高但可控性相对较弱。在v1.5中它被保留主要是为了向后兼容以及执行一些经过充分验证的、非常确定的清理规则例如清理超过30天的、特定命名模式的临时目录。对于新手或不熟悉的项目建议优先使用collectreviewdelete的新流程。实操心得模式选择策略我的经验是将review模式作为日常巡检工具。每周或每完成一个大特性后运行一次review生成报告快速浏览。对于明确无误的垃圾如node_modules的备份压缩包、.log临时文件可以直接批准删除。对于不确定的文件如一些命名奇怪的.tmp文件则保留。cleanup模式我仅用于处理那些我百分之百信任的规则比如定期清理Chrome的AI本地缓存。2.2 安全机制的深度剖析OpenClearn在安全方面做了多层防护理解这些机制能让你用得更放心。1. 回收站优先策略 (use_trashtrue)这是最重要的安全网。在配置中默认将use_trash设置为true。这意味着无论是cleanup模式还是delete模式文件都不会被永久删除而是被移动到操作系统的回收站在Windows上是$Recycle.Bin在macOS/Linux上是~/.Trash。这样即使发生了误操作你也有充足的机会从回收站中恢复文件。只有在进行大规模、确认无误的清理且磁盘空间极度紧张时才考虑使用--hard-delete参数进行硬删除。2. 保护名单与拒绝列表这是防御性配置的核心。protected_files: 这是一个绝对路径列表。列入此列表的文件或目录任何清理规则都会对其失效。我通常会把项目关键的配置文件如.env、docker-compose.yml、版本控制目录.git、以及正在编写的核心文档放在这里。collector_context.deny_roots: 定义扫描的禁区。任何位于这些路径下的内容都不会被扫描更不会被清理。我习惯把系统盘根目录如C:\、/、用户主目录、以及存放重要资料的外部驱动器挂载点加入拒绝列表从源头上避免工具误入“雷区”。collector_context.deny_patterns: 使用通配符或正则表达式来匹配需要跳过的路径模式。例如**/.git/**可以跳过所有Git仓库内部文件**/*.pem可以跳过所有密钥文件。3. 审批文件机制如前所述delete模式强制依赖审批文件。这个文件就像一份“处决令”必须由你亲手签署填写。工具本身不会自动往里面添加任何内容。这种“权责分离”的设计是避免自动化工具失控的关键。4. 模拟运行 (--dry-run)在cleanup模式下强烈建议首次运行时加上--dry-run参数。该参数会让工具完整走一遍扫描和决策流程并打印出“如果执行将会删除哪些文件”但不会实际执行任何文件系统操作。这是验证你的配置规则是否准确预期的完美试金石。3. 环境配置与核心功能实战要玩转OpenClearn光理解概念不够必须动手配置和运行。下面我将从最基础的快速开始逐步深入到各项高级功能的配置与使用。3.1 基础环境搭建与首次运行假设你已经将OpenClearn项目克隆到了本地。它的核心工具位于tools/g5_scavenger/目录下。第一步配置文件解读与定制工具的行为几乎完全由配置文件驱动。项目提供了一个config.example.json范例我们的首要任务就是复制它并修改成适合自己的版本。cd tools/g5_scavenger cp config.example.json config.my_workspace.json用编辑器打开config.my_workspace.json以下几个部分是必须关注的{ workspace_root: C:/Users/YourName/Projects, // 你的AI项目工作空间根目录 state_dir: state, // 状态文件如审批文件存储目录 use_trash: true, // 是否使用回收站务必为true collector_context: { allow_roots: [${workspace_root}/ai_experiments], // 允许扫描的根目录 deny_roots: [C:/Windows, /System, ${workspace_root}/archive], // 禁止扫描的目录 deny_patterns: [**/node_modules/**, **/.git/**, **/*.pem], // 禁止扫描的模式 protected_files: [ // 受保护的文件绝对路径 C:/Users/YourName/Projects/ai_experiments/.env, C:/Users/YourName/Projects/ai_experiments/current_important_draft.md ] }, cleaner_persona: balanced // 清理策略人格可选 safe/balanced/aggressive }workspace_root: 这是扫描的起点。请将其设置为你的AI编码项目集中存放的父目录。allow_roots和deny_roots: 这是白名单和黑名单的逻辑。allow_roots定义了在workspace_root下哪些子目录是允许工具进入扫描的。通常你可以设置为具体的项目文件夹。deny_roots则是全局性的任何匹配的路径都会被无视。合理设置这两项可以极大提升扫描效率和安全性。cleaner_persona: 这定义了工具的“清理性格”。safe: 极度保守只清理确凿无疑的垃圾如系统临时文件.tmp误报率极低但清理范围小。balanced(推荐): 平衡模式会清理常见的中间产物如构建目录dist/、日志文件、重复文件以及疑似乱码的文档。这是日常使用的首选。aggressive: 激进模式会应用所有清理规则包括清理较旧的文件版本、较大的缓存等。仅在磁盘空间告急且你非常了解项目结构时使用。第二步执行首次安全扫描收集模式配置好后我们就可以进行第一次实战了。打开终端PowerShell或CMD进入工具目录cd tools\g5_scavenger python scavenger.py --config config.my_workspace.json --operation collect运行后工具会开始扫描。完成后它会在state_dir指定的目录默认为state下生成一个JSON文件文件名通常包含时间戳和模式例如g5_scavenger_collect_20250415_102030.json。这个文件里就包含了所有被识别出的候选清理目标。第三步生成并审阅报告审查模式直接看JSON文件不直观我们用review模式生成报告。python scavenger.py --config config.my_workspace.json --operation review运行后除了生成候选JSON还会在相同目录下生成一个同名的.md文件。用你喜欢的Markdown编辑器打开它报告结构清晰类似下面这样# OpenClearn 清理审查报告 **生成时间:** 2025-04-15 10:20:30 **模式:** balanced **扫描目录:** C:/Users/YourName/Projects/ai_experiments ## 1. 重复文档 (exact_duplicate_document) * **文件A:** C:/.../draft_v1.py (大小: 4.2 KB) * **文件B:** C:/.../draft_v1_backup.py (大小: 4.2 KB) * **原因:** 内容哈希值完全一致。 ## 2. 乱码文档 (garbled_document) * C:/.../notes.txt (大小: 15 KB) * **原因:** 文件内容中非ASCII字符占比过高且无法用常见编码正常解码疑似编码错误或二进制文件误存为文本。 ## 3. 陈旧快照 (stale_snapshot) * C:/.../snapshots/old_session_20240301/ (大小: 150 MB) * **原因:** 目录最后修改时间超过30天且符合快照命名模式。现在你可以仔细阅读这份报告判断每一项是否真的可以删除。将你决定删除的项记录下来。3.2 高级功能实战系统扫描与文档清理v1.5版本引入了两个非常实用的独立脚本它们不依赖于主配置可以单独运行。系统级磁盘增长扫描 (system_scan.py)这个脚本用于快速定位磁盘空间被谁占用了。它不进行清理只做分析。# 基本扫描列出指定目录下体积最大的前20个文件夹 python system_scan.py --target-path C:/Users/YourName/Projects --top-n 20 # 高级扫描找出最近24小时内产生的、大于200MB的大文件 python system_scan.py --target-path C:/Users/YourName/Projects --include-recent-large-files --recent-hours 24 --min-file-mb 200后一个命令在排查“磁盘突然满了”的问题时极其有效。它能帮你迅速定位到是哪个进程或操作产生了巨型临时文件。安全清理Chrome本地AI缓存 (clean_chrome_ai_cache.py)像Claude Code这样的工具有时会在Chrome的用户数据目录下留下较大的缓存。这个脚本专门用于定位和清理这些缓存。# 安全模式只列出要清理的缓存路径不实际删除 python clean_chrome_ai_cache.py # 执行清理并关闭Chrome浏览器确保所有工作已保存 python clean_chrome_ai_cache.py --kill-chrome注意事项Chrome缓存清理使用--kill-chrome参数前务必保存所有Chrome标签页的工作状态。该操作会强制关闭Chrome进程。清理的缓存主要是AI模型相关的临时数据一般不会影响你的书签、密码等用户数据但为防万一首次使用建议在不--kill-chrome的模式下先查看它会清理哪些路径。文档质量清理 (doc_cleanup)这是v1.5的亮点功能集成在主工具的collect和review模式中。它主要识别两类问题文档乱码文档 (garbled_document): 通常是因编码问题导致打开后全是乱码的文本文件或者错误地将二进制文件如图片以文本形式保存。这些文件没有阅读价值。精确重复文档 (exact_duplicate_document): 通过计算文件的哈希值如SHA-256内容完全一致的文件会被识别为重复。保留一份即可。要启用这个功能你需要在配置文件的cleaner_persona为balanced或aggressive时它才会被激活。在review报告里你会看到独立的章节来展示这些候选文件。3.3 代理配置文件与API集成OpenClearn支持为不同的AI智能体如Codex, Claude Code, OpenClaw预定义清理策略这通过“代理配置文件”实现。使用内置代理配置工具内置了几种常见的配置预设python scavenger.py --config config.my_workspace.json --agent-profile claude --operation review不同的agent-profile可能会调整deny_patterns例如Claude Code可能产生特定格式的临时文件或清理规则的敏感度。创建自定义代理配置你可以创建一个JSON文件来定义自己的清理人格。例如创建一个my_agent.json{ name: my_python_agent, description: 针对Python AI项目的清理策略, deny_patterns_add: [**/__pycache__/**, **/*.pyc], // 在基础配置上追加 clean_rules: { stale_snapshot_max_age_days: 7, // 将快照过期时间设为7天 ignore_files_smaller_than_kb: 2 // 忽略小于2KB的文件 } }然后运行python scavenger.py --config config.my_workspace.json --agent-profile custom --agent-profile-file .\my_agent.json --operation collectAPI密钥绑定用于增强报告v1.3以后版本支持在报告中集成AI提供商状态。这本身不用于清理决策但可以在报告头部显示当前配置的AI服务是否可用。你需要设置环境变量并指定提供商。在PowerShell中$env:OPENAI_API_KEY 你的真实API密钥 python scavenger.py --config config.my_workspace.json --provider openai --api-key-env OPENAI_API_KEY --operation review报告生成时会在开头部分多出一行类似Provider Status: OpenAI (Configured)的信息。请注意切勿将真实的API密钥提交到版本控制系统或配置文件中务必使用环境变量。4. 审批与执行完成清理闭环经过review模式下的仔细审阅你已经确定了一批需要清理的文件。现在我们来执行最终的删除操作。第一步准备批准文件工具默认的批准文件路径是state/g5_scavenger_approve.json。如果该文件不存在你需要创建它如果存在则编辑它。文件格式如下{ approve_candidate_ids: [ dup-abc123def456, stale-789ghi012jkl ], approve_paths: [ C:/Users/YourName/Projects/ai_experiments/useless.tmp, C:/Users/YourName/Projects/ai_experiments/old_logs/debug.log ] }approve_candidate_ids: 这里填写review报告或collect生成的JSON文件中每个候选条目唯一的candidate_id。这是最精准的方式。approve_paths: 你也可以直接填写你知道的、需要删除的文件或目录的绝对路径。如何找到candidate_id在review模式生成的Markdown报告中每个候选条目通常都会列出其ID。在collect模式生成的JSON文件中每个候选对象都有一个id字段。复制它们即可。第二步执行删除确保批准文件已保存然后运行python scavenger.py --config config.my_workspace.json --operation delete工具会读取批准文件逐一处理列表中的条目。如果配置中use_trash为true文件会被移到回收站如果为false或使用了--hard-delete则会被永久删除。处理过程中工具会输出日志告知你每个文件是被“移动到回收站”还是“已永久删除”。第三步验证与恢复操作完成后建议再次快速扫描一下工作空间或者直接去系统回收站查看确认文件已按预期处理。如果发生误操作立即从回收站还原文件。5. 高级场景巡逻模式与实战案例对于需要长期维护的服务器或持续集成的开发环境OpenClearn提供了patrol巡逻模式可以实现定时自动扫描与清理。5.1 配置与运行巡逻模式巡逻模式由patrol.py脚本实现。一个典型的用法是设置一个定时任务如cron job或Windows计划任务让它每隔一段时间自动运行review并在垃圾文件总大小超过某个阈值时自动应用清理或只是发送通知。python patrol.py --config config.my_workspace.json --mode balanced --cycles 0 --interval-seconds 1800 --auto-apply --apply-threshold-mb 1024参数解析--cycles 0: 表示无限循环运行。如果设为5则运行5个周期后停止。--interval-seconds 1800: 每个周期之间的间隔秒数这里是30分钟。--auto-apply: 如果启用当满足条件时会自动执行delete操作。慎用建议在充分测试后再启用。--apply-threshold-mb 1024: 自动应用的阈值。当本次扫描识别出的可清理文件总大小超过1024MB1GB时才会触发auto-apply。一个更安全的做法是不启用--auto-apply而是结合脚本的退出码和通知工具如发送邮件、Slack消息仅做报告和预警。5.2 实战案例与故障排查案例处理被锁定的包文件在项目的案例笔记docs/cases/2026-04-13-g5-virus-devour-case.md中记录了一个真实场景在清理一个由AI生成大量临时文件的目录时遇到了被系统进程锁定的文件例如某些IDE或进程正在写入的.pack文件。直接删除会导致“PermissionError”或“文件正在被使用”的错误。解决方案与排查步骤识别锁定进程在Windows上可以使用Resource Monitor或handle.exeSysinternals套件工具。在Linux/macOS上可以使用lsof命令如lsof /path/to/locked.file来查看是哪个进程占用了文件。调整清理策略将频繁被锁定的文件模式如**/*.pack添加到配置文件的deny_patterns中避免扫描它们。错峰清理通过巡逻模式的--interval-seconds设置将清理任务安排在系统负载低、相关进程如IDE、构建工具不太可能活跃的时间段执行。优雅重试在自定义脚本或巡逻逻辑中可以为删除操作添加异常捕获和重试逻辑。如果遇到权限错误先记录日志等待下一个周期再尝试。常见问题速查表问题现象可能原因解决方案运行时报JSONDecodeError配置文件config.my_workspace.json格式错误如缺少逗号、引号不匹配。使用JSON验证工具如在线JSON校验网站检查并修正配置文件。collect模式找不到任何文件1.workspace_root路径错误。2.allow_roots设置过窄或路径错误。3.deny_roots或deny_patterns设置过宽排除了所有目标。1. 检查workspace_root是否为有效绝对路径。2. 暂时将allow_roots设置为[${workspace_root}]进行测试。3. 暂时注释掉deny_*配置进行测试。delete模式未删除任何文件1. 批准文件路径错误或格式不对。2. 批准文件中的candidate_id或path与状态文件中的记录不匹配。3. 文件已被手动删除或移动。1. 检查delete命令输出的日志确认它读取的批准文件路径。2. 核对批准文件中的ID/路径与collect/review生成的状态文件是否一致。3. 手动检查文件是否还存在。工具运行缓慢1. 扫描的目录树非常庞大如包含node_modules。2. 硬盘速度慢。3. 启用了计算哈希值的重复文件检测。1. 通过deny_patterns排除已知的大型第三方库目录。2. 考虑在SSD上运行。3. 对于初次扫描可以先禁用文档重复检测如果配置允许。误删了重要文件1. 保护名单protected_files未配置。2. 批准文件审查不仔细。3. 使用了--hard-delete。立即检查系统回收站这是use_trashtrue的第一道防线。恢复文件后复盘原因将重要文件路径加入protected_files。个人经验与技巧配置版本化将你的config.my_workspace.json和自定义的代理配置文件my_agent.json纳入版本控制如Git。这样可以在不同机器间同步你的清理策略也方便回滚。从小处开始首次使用时将allow_roots设置在一个较小的、不重要的子项目目录上。运行review并仔细检查报告确认工具的行为符合预期后再逐步扩大扫描范围。利用批处理文件项目提供的run_system_scan.bat和run_clean_chrome_ai_cache.bat是很好的例子。你可以创建自己的批处理或Shell脚本将常用的命令组合如collect后自动打开报告固化下来提升效率。定期审查规则随着你使用的AI工具和项目类型的变化产生的“垃圾”模式也可能变化。每隔几个月回顾一下你的deny_patterns和清理规则看是否需要调整。