1. 项目概述为AI代理工作空间打造的安全清理工具如果你和我一样日常重度使用Codex、Claude Code或OpenClaw这类AI编程助手那你肯定对一件事深有体会工作目录用不了多久就会变得一团糟。各种临时文件、缓存数据、重复的代码片段、失败的实验快照像野草一样疯长不仅占用宝贵的磁盘空间更关键的是它们会严重干扰你的工作流。你可能只是想找一个昨天生成的某个函数结果却在几十个命名相似的trial_v1.py、trial_v2_final.py、trial_v2_final_really.py文件中迷失方向。OpenClearn就是为了解决这个痛点而生的。它不是另一个简单的rm -rf脚本而是一个为AI代理工作场景量身定制的、高度可配置的自动化清理工具集。它的核心设计哲学是“安全第一可控清理”。想象一下你有一个经验丰富的数字清洁工他不仅知道哪些是垃圾比如临时的.tmp文件、过期的日志还能识别出那些看似无用、实则可能包含重要中间结果的“灰色地带”文件比如AI生成的多个代码变体并提交一份详细的清理报告供你最终裁决。OpenClearn就是这个清洁工。这个工具特别适合以下几类人频繁使用AI辅助编程的开发者、需要管理多个实验项目的机器学习工程师、以及任何希望自动化维护其数字工作环境整洁度的技术从业者。它通过一系列精心设计的“模式”和“策略”将原本高风险、易出错的清理操作转变为可审计、可回滚、高度可控的自动化流程。2. 核心设计思路与安全哲学2.1 为何需要专门的AI工作空间清理工具通用清理工具如ccleaner或简单的脚本在处理AI工作空间时往往力不从心。原因在于AI工作流产生的“垃圾”具有其特殊性文件关系复杂一次代码生成任务可能产生主文件、多个备选方案、测试用例、依赖快照等一组关联文件盲目删除单个文件可能导致上下文丢失。价值判断模糊一个specimen_*.py文件可能是失败的实验也可能是某个成功算法的关键灵感来源需要结合项目上下文判断。清理风险高AI常在工作区根目录或项目核心区域操作误删配置文件、版本控制文件.git或源代码的后果是灾难性的。模式化垃圾AI工具会产生特征明显的垃圾如带时间戳的会话缓存、固定的临时目录结构、特定命名模式的重复文件这为模式化清理提供了可能。OpenClearn的设计正是基于对这些痛点的深刻理解。它没有采用“一刀切”的策略而是构建了一个基于策略Policy和上下文Context的清理框架。2.2 安全核心四级防护与操作模式OpenClearn的安全体系可以概括为四级防护贯穿于其所有操作模式中第一级定义安全边界Deny Roots Protected Files这是最根本的防护。在配置中你可以明确指定绝对禁止清理的目录deny_roots例如你的家目录C:\Users\YourName、系统目录、以及所有项目的.git文件夹。同时可以列出受保护的具体文件protected_files如关键的config.json、README.md等。任何清理操作都会首先尊重这些“禁区”从物理上杜绝误删核心资产的可能。注意我强烈建议将你的代码仓库根目录、文档目录以及任何包含不可再生数据的路径加入deny_roots。这是一个“安全气囊”必须最先配置。第二级策略化收集Collector Context Persona清理器Collector的行为由“上下文”和“人设”控制。上下文定义了扫描的根目录、排除的模式等。而“人设”Persona则是一组清理原则的集合例如balanced人设可能允许删除一周前的临时文件而safe人设只删除明显无用的文件类型。这确保了清理行为是符合你预设的“谨慎程度”的。第三级非破坏性操作优先Collect Review模式这是OpenClearn最精妙的设计。它不直接删除而是分步进行collect模式仅扫描并列出“候选”清理目标生成一个清单不做任何实际删除。review模式在collect基础上生成一份详细的Markdown报告对每个候选文件进行描述和分类如“重复文档”、“乱码文件”让你在决策前有充分的知情权。只有在你审查报告并将认可的条目加入“批准文件”Approval File后运行delete模式才会执行真正的删除。第四级回收站与硬删除隔离Use Trash Hard Delete即使执行删除OpenClearn也默认启用“回收站”策略use_trashtrue。文件会被移到系统回收站给你最后的挽回机会。只有当你明确使用--hard-delete参数时才会进行永久删除。我强烈建议在完全信任该工具对某个特定目录的清理逻辑前永远不要使用--hard-delete。这套“扫描 - 报告 - 批准 - 执行可恢复”的流程将一次性的危险操作拆解成了一个可监控、可中断、可复审的运维流水线极大提升了心理安全感和操作可靠性。3. 核心功能模块深度解析OpenClearn v1.5 的功能集可以看作一个工具箱每个工具解决一类特定的清理问题。我们来逐一拆解其原理和适用场景。3.1 主清理引擎scavenger.py这是工具的核心负责执行策略化的清理工作流。其强大之处在于丰富的运行模式--operation和可调节的清理强度--mode。3.1.1 模式详解从安全到激进safe模式最保守的策略。它只针对那些几乎100%可以认定为垃圾的文件例如操作系统或某些软件产生的、具有固定后缀且不在使用中的临时文件如.tmp,.bak。它不会碰任何源代码文件、文档或自定义文件。适合初次使用或对某个工作区结构不了解时进行“摸底”扫描。balanced模式默认推荐模式。在safe的基础上增加了对“疑似垃圾”的识别。例如它会识别出那些由AI助手生成的、带有_v1,_copy,old_等前缀后缀的重复或旧版本文件。它基于启发式规则准确性较高是日常维护的主力。aggressive模式更激进的策略。除了上述目标它可能还会清理较长时间未访问的缓存目录、较大的日志文件等。使用此模式前务必先用review生成报告仔细检查因为它可能清理掉一些你暂时不用但仍有保留价值的中间文件。3.1.2 操作流程四步工作法收集候选 (collect)python scavenger.py --config config.example.json --mode balanced --operation collect此命令会遍历配置中定义的collector_context.allow_roots目录应用deny_patterns排除规则并根据选择的mode和persona识别出所有符合条件的候选文件。结果会保存在一个内部状态文件中默认在state/目录下但不会进行任何删除。这是纯粹的侦察阶段。生成审查报告 (review)python scavenger.py --config config.example.json --mode balanced --operation review此命令基于上一步的收集结果生成一份人性化的Markdown报告通常命名为review_*.md。报告会按类别如“重复文件”、“临时文件”、“大文件”列出候选并包含文件路径、大小、最后修改时间和简要的清理理由。这是你做出决策的关键依据。你应该仔细阅读这份报告确认哪些文件确实可以删除。批准清理 (手动编辑批准文件) OpenClearn不会自动批准任何项目。你需要手动编辑批准文件默认state/g5_scavenger_approve.json将你在报告中确认可以删除的条目的ID或路径添加进去。这个设计强迫你进行最后一次人工确认是安全链条上的关键一环。{ approve_candidate_ids: [dup-abc123, stale-def456], approve_paths: [C:/workspace/temp/junk.tmp] }执行删除 (delete)python scavenger.py --config config.example.json --mode balanced --operation delete只有运行此命令时工具才会读取批准文件并仅删除文件中明确列出的条目。如果配置了use_trashtrue默认文件会进入回收站。3.1.3 传统清理管道 (cleanup)这是一个遗留的、更自动化的操作它一次性完成收集、筛选基于内置规则和删除或模拟删除。--dry-run参数在此模式下尤为重要它让你预览将要执行的操作而不实际执行。python scavenger.py --config config.example.json --mode balanced --operation cleanup --dry-run实操心得对于熟悉的、模式固定的目录如纯粹的构建输出目录dist/,build/使用cleanup --dry-run预览后再执行效率很高。但对于AI工作区这种混合内容区域我仍然更推荐collect-review-delete的分步工作流控制感更强。3.2 系统级扫描system_scan.pyscavenger.py专注于根据策略清理特定工作区而system_scan.py则提供了另一个视角发现磁盘空间被谁占用了。它不执行清理而是进行诊断。基础扫描运行python system_scan.py它会快速列出系统中各个磁盘或顶级目录的大小帮你快速定位是哪个盘符或哪个大文件夹在“吃空间”。深度扫描通过参数组合可以定位近期产生的大文件这对于排查突然的磁盘空间不足非常有用。python system_scan.py --include-recent-large-files --recent-hours 24 --min-file-mb 200这个命令的意思是“扫描过去24小时内大小超过200MB的文件”。如果你发现C盘一夜之间少了几个G用这个命令很可能立刻找到“元凶”比如一个忘记清理的虚拟机快照文件或录制视频。3.3 专项清理工具3.3.1 Chrome AI缓存清理 (clean_chrome_ai_cache.py)像Claude Code这样的基于浏览器的AI工具会在本地留下缓存。这个脚本专门定位并安全清理这些缓存目录。--kill-chrome参数会在清理前尝试关闭Chrome浏览器进程确保能删除被锁定的文件。python clean_chrome_ai_cache.py --kill-chrome注意事项清理浏览器缓存可能会导致一些网站需要重新登录或者AI工具的本地临时状态丢失。但这通常是无害的并且能释放出可观的空间尤其是长期使用后。3.3.2 文档质量扫描 (doc_cleanup)这是v1.5的一个亮点它引入了基于内容的智能识别乱码文档检测 (garbled_document)能识别出那些因编码错误而变成乱码的文本文件俗称“火星文”。这些文件通常已损坏或无价值可以安全清理。精确重复文档检测 (exact_duplicate_document)通过计算文件的哈希值如MD5、SHA-1精确识别内容完全相同的重复文件。对于文档、备份的代码副本这个功能非常实用能帮你删除多余的副本。这个模块展示了OpenClearn从“按名称和位置清理”向“按内容清理”的演进使其更能理解数据的语义而不仅仅是元数据。3.4 代理配置文件与API集成为了让清理策略更贴合不同的AI工作流OpenClearn引入了“代理配置文件”的概念。内置配置文件如codex,claude,openclaw它们预置了针对这些工具常见工作模式和临时文件结构的优化规则。python scavenger.py --config config.example.json --agent-profile claude --operation review自定义配置文件你可以创建自己的JSON配置文件定义独有的allow_roots、deny_patterns和cleanup_principles以适应你的团队或项目规范。python scavenger.py --config config.example.json --agent-profile custom --agent-profile-file ./my_team_profile.json --operation collectAPI密钥绑定是一个高级功能推测其未来可能用于集成AI服务来分析文件内容例如判断一个代码片段是否已过时。目前它主要通过环境变量来管理密钥为未来扩展预留了接口。# Windows PowerShell示例 $env:OPENAI_API_KEY sk-your-key-here python scavenger.py --config config.example.json --provider openai --api-key-env OPENAI_API_KEY --operation review4. 实战配置与操作指南理论说了这么多现在我们来手把手配置一个属于你自己的安全清理环境。假设你主要使用Claude Code进行Python开发工作区在D:\AI_Projects。4.1 初始化与基础配置首先克隆或下载OpenClearn项目到本地例如C:\Tools\OpenClearn。复制并修改配置文件 项目根目录下通常有一个config.example.json。复制一份并重命名为config.my.json。这个文件是你的清理“宪法”所有行为都由它定义。配置核心安全边界 打开config.my.json找到collector_context部分。这是你需要重点修改的地方。collector_context: { allow_roots: [ D:\\AI_Projects ], deny_roots: [ C:\\, D:\\System Volume Information, D:\\$Recycle.Bin, D:\\AI_Projects\\.git, D:\\AI_Projects\\*.venv, C:\\Users\\YourName\\Documents, C:\\Users\\YourName\\Desktop ], deny_patterns: [ **/*.py, // 默认保护所有Python源码可根据需要调整 **/*.ipynb, **/*.md, **/*.json, **/*.yaml, **/*.yml, **/README*, **/requirements.txt, **/.gitignore, **/.* // 保护所有以点开头的隐藏文件/文件夹 ], protected_files: [ D:\\AI_Projects\\my_secret_config.ini, D:\\AI_Projects\\project_a\\.env ] }配置解析allow_roots: 只允许清理这个目录下的文件。务必精确不要指向过大的根目录。deny_roots: 这里是你的“禁区”列表。我强烈建议将系统盘、回收站、版本控制目录.git,.svn以及你的个人文档、桌面目录加进去。deny_patterns: 通过通配符模式保护特定类型的文件。上面的示例保护了所有源代码、配置文件和文档。这是一个非常重要的安全网。初期可以设置得严格一些后续再根据实际情况放松。protected_files: 保护具体的、重要的文件即使它们可能匹配了清理规则。配置清理器行为 找到cleaner_persona和principles。初期建议使用safe或balanced人设并仔细阅读其原则。你可能需要根据你的文件命名习惯调整原则例如如果你喜欢用test_作为临时文件前缀可以将其加入清理原则。4.2 首次安全扫描流程配置完成后进行第一次“无害”扫描建立信心。运行收集模式cd C:\Tools\OpenClearn python scavenger.py --config config.my.json --mode safe --operation collect这个命令会在D:\AI_Projects下进行最安全的扫描。完成后控制台会输出扫描到的候选文件数量但不会做任何事。生成并审查报告python scavenger.py --config config.my.json --mode safe --operation review运行后在项目目录下或state/目录会生成一个review_*.md文件。用文本编辑器或Markdown阅读器打开它。仔细阅读每一个条目确认文件是否真的无用。对于safe模式大部分应该是明显的临时文件或缓存。检查是否有“误伤”查看是否有被意外扫描进来的重要文件。如果有说明你的deny_patterns或protected_files配置需要加强。可选执行首次微型清理 如果报告看起来完全正确你可以尝试批准并删除一两个文件作为测试。打开state/g5_scavenger_approve.json。从review报告中复制一两个候选的ID到approve_candidate_ids数组中。运行删除命令python scavenger.py --config config.my.json --mode safe --operation delete立即去系统回收站检查确认文件是否在里面。这一步是验证整个“回收站”安全机制是否正常工作的关键。4.3 进阶使用平衡模式进行日常维护经过几次safe模式的验证你对工具的准确性建立了信任可以开始使用更高效的balanced模式进行日常清理。定期运行审查 可以每周或每两周运行一次review。python scavenger.py --config config.my.json --mode balanced --operation reviewbalanced模式会找出更多候选如旧的日志文件、重复的下载项、IDE的临时历史文件等。审查报告会花费更多时间但收获的清理空间也更大。利用代理配置文件 如果你发现Claude Code总是在D:\AI_Projects\.claude_cache生成缓存你可以创建一个自定义的claude_profile.json将allow_roots直接指向这个缓存目录并配置更激进的清理原则专门用于快速清理这个已知的“垃圾场”。自动化巡逻 (Patrol) 对于总是产生垃圾的目录如持续集成日志目录可以使用patrol.py设置一个自动化的巡逻任务。python patrol.py --config config.my.json --mode balanced --cycles 0 --interval-seconds 3600 --auto-apply --apply-threshold-mb 1024参数解析--cycles 0: 无限循环。--interval-seconds 3600: 每1小时运行一次。--auto-apply: 自动应用清理慎用必须确保对该目录的清理规则100%安全。--apply-threshold-mb 1024: 只有当扫描到的可清理空间大于1GB时才执行自动清理。 这个命令可以放在后台运行像一个自动化的清洁机器人在满足条件时帮你保持目录整洁。我个人的经验是只对纯粹的、无价值的缓存目录如浏览器缓存、软件临时目录使用auto-apply并且阈值设置得高一些。5. 常见问题、排查技巧与实战案例即使设计再安全在复杂的真实环境中也会遇到各种边缘情况。下面是我在实际使用中遇到的一些典型问题及解决方法。5.1 问题排查速查表问题现象可能原因排查步骤与解决方案运行collect或review后无任何输出或候选文件极少。1.allow_roots配置路径错误或为空。2.deny_patterns过于严格排除了所有文件。3. 当前运行模式如safe规则太严没有匹配项。1. 检查config.my.json中allow_roots的路径是否存在格式是否正确Windows用双反斜杠或正斜杠。2. 临时注释掉deny_patterns中的几行如保护*.py的行再次运行看是否扫描到文件。3. 尝试使用balanced模式运行collect。报告 (review) 中出现了明显不应被清理的重要文件。1. 该文件类型未被deny_patterns保护。2. 该文件路径未被protected_files列出。3. 文件匹配了某个清理“原则”如文件名中包含temp。1. 将该文件的扩展名如.myext添加到deny_patterns中。2. 将该文件的完整路径添加到protected_files中。3. 审查cleaner_persona的principles调整过于宽泛的规则。这是最重要的学习过程通过“误伤”来完善你的配置。delete操作失败提示“文件被占用”或“权限不足”。1. 文件正在被其他程序如编辑器、IDE、进程使用。2. 脚本没有以管理员权限运行尝试删除系统或受保护文件时。1. 关闭可能使用该文件的程序特别是IDE和资源管理器。2. 对于非关键文件可以跳过。对于需要清理的系统文件可以尝试以管理员身份运行命令行。OpenClearn默认使用回收站被占用的文件通常无法移入回收站。patrol模式的自动清理没有按预期执行。1.--apply-threshold-mb设置过高从未达到。2. 脚本执行出错但后台运行未显示错误。3. 系统休眠或睡眠中断了定时任务。1. 降低阈值如设为100MB进行测试。2. 先在前台运行一次patrol命令不加--cycles或设为1查看控制台输出是否有错误。3. 对于需要长期运行的任务考虑使用Windows任务计划程序或系统的cron来调用脚本而不是依赖patrol的内置循环。清理后发现某个功能异常疑似文件被误删。配置文件或依赖文件被清理。立即检查回收站这是启用use_trashtrue的最大价值。从回收站恢复文件。然后分析该文件为什么会被扫描到并相应调整deny_patterns或protected_files。5.2 实战案例处理被锁定的包文件在项目自带的案例笔记docs/cases/2026-04-13-g5-virus-devour-case.md中提到了一个真实场景在进行大规模的清理“devour”模式时遇到了被版本控制系统如Git锁定的包文件packfile导致删除失败。我的处理经验识别锁定当delete操作失败并提示“进程无法访问文件”时首先怀疑文件被锁定。在Windows上可以使用Resource Monitor或handle.exeSysinternals套件工具查看是哪个进程占用了文件。温和解决如果是Git锁定的通常关闭所有Git客户端IDE中的Git、Git Bash、Git GUI即可释放。对于其他软件尝试关闭相关程序。脚本重试OpenClearn的清理操作通常是幂等的。解决锁定后重新运行delete命令即可。配置排除如果某个目录如.git下的文件经常被锁定且无需清理最根本的办法是将其父目录.git添加到deny_roots中一劳永逸。预案对于计划进行的大规模清理提前通知团队确保在维护窗口内进行并关闭所有可能锁定文件的应用程序。5.3 高级技巧利用系统扫描定位“空间怪兽”有一次我的开发机C盘突然告急。使用system_scan.py快速定位python system_scan.py --include-recent-large-files --recent-hours 48 --min-file-mb 500报告显示一个VirtualBox的.vdi磁盘镜像文件在过去两天增长了近50GB。原来是我之前做测试时虚拟机使用了动态分配磁盘但忘记清理快照。通过这个工具我几分钟内就找到了问题根源而不是手动在各个文件夹里大海捞针。个人体会是将system_scan.py与资源管理器的“按大小排序”功能结合使用。前者擅长按时间过滤大文件后者擅长可视化查看目录树中的空间占用。两者互补是管理磁盘空间的黄金组合。最后再分享一个小心得OpenClearn的配置文件本质上是你的“清理知识库”。每当你通过审查报告学习到一种新的、需要清理或需要保护的文件模式时就把它更新到配置中。久而久之这份配置文件会成为高度定制化、完全贴合你个人工作习惯的智能清理助手真正实现自动化而不失安全的 workspace 维护。