Purrge

基于 AI 的磁盘空间管理工具（macOS / Windows）：低空间预警、智能识别可清理项、经用户审批后执行清理。

名称取自 purr（猫咪呼噜）与 purge（清除）· by RabbittuX

  

Mac 应用 · 命令行版 · 工作原理 · 安全机制 · 常见问题 · 更新日志

✨ 核心功能

🔔 低空间预警

后台服务定时检测磁盘剩余空间，低于设定阈值时发出提醒。检测过程不调用 AI，不消耗额度。

🧠 AI 智能分析

调用本机的 Claude Code、Codex、WorkBuddy 或 DeepSeek Harness，对缓存、安装包、媒体文件及历史项目逐项评估，说明其用途、闲置时长及清理影响。

✅ 用户审批

可重建的缓存默认选中，用户文件默认不选。仅执行用户勾选并确认的清理项，AI 不具备删除权限。

Purrge 有两个版本，核心功能相同：

	🍎 Mac 应用	💻 命令行版
适合	不想用终端，想要图形界面	习惯终端，或者在用 Windows
系统	macOS 13 及以上（Apple 芯片与 Intel）	macOS、Windows 10 / 11
界面	菜单栏、桌面悬浮球、应用窗口	终端命令 + 浏览器里的审查页
安装	官网下载	Homebrew、一键脚本、PowerShell Gallery
源码	暂未开源	本仓库（非商业许可）

🍎 Mac 应用

1.0 新发布

不想用终端？Purrge for Mac 把命令行版的功能做成了图形界面应用，下载打开就能用：

界面预览

下载

macOS 13 及以上 · Apple 芯片与 Intel 通用 · 不收费

[!NOTE]

• 安装包只在官网发布，GitHub 上不提供下载；其他地方的同名安装包请不要安装。
• Mac 应用目前没有开源，本仓库是命令行版（macOS / Windows）的源码。
• 第一次打开时 macOS 会提示「无法验证开发者」，下载时官网会显示「安装必读」，按步骤允许一次即可。

💻 命令行版

终端里运行的版本，审查页在浏览器里打开；支持 macOS 和 Windows，源码就在本仓库。

📸 界面预览

🚀 安装

[!WARNING] 请认准官方来源。 Purrge 只有两个官方仓库：RabbittuX/purrge 和 RabbittuX/homebrew-tap（作者名 RabbittuX，两个 t、结尾大写 X）。

• GitHub 上另有多个同名的 purrge 项目，与本项目无关，其中部分自称"清理垃圾"的项目来源不明，请勿安装。
• Homebrew 中的 purge（单个 r）是另一款软件；请使用完整名称 rabbittux/tap/purrge。
• PowerShell Gallery 中的官方模块名为 Purrge（作者 RabbittuX，发布账号 yin），页面地址 powershellgallery.com/packages/Purrge。
• 安装开始时会显示「Purrge 版本号 by RabbittuX　官方来源：GitHub RabbittuX/purrge」，可据此核对；也可随时运行 purrge version 查看。

macOS

方式一：Homebrew（推荐）

brew install rabbittux/tap/purrge
purrge install

方式二：一键脚本

curl -fsSL https://raw.githubusercontent.com/RabbittuX/purrge/master/install.sh | bash

# 国内网络：改从 codeload 下载完整代码再安装
curl -fsSL https://codeload.github.com/RabbittuX/purrge/tar.gz/refs/heads/master | tar -xz -C /tmp && bash /tmp/purrge-master/install.sh

# 从源码安装
git clone https://github.com/RabbittuX/purrge.git
cd purrge && bash install.sh

# 非交互式安装（engine 可选 claude / codex / workbuddy / deepseek）
bash install.sh --engine codex --threshold 20 --yes

Windows

打开「Windows PowerShell」（不需要管理员权限），执行：

Install-Module Purrge -Scope CurrentUser
Install-Purrge

• 第一次使用 Install-Module 时，Windows 会询问是否安装 NuGet 组件、是否信任 PSGallery 仓库，输入 Y 回车即可。
• 没有 Python 时会询问并自动安装（只装给当前用户）。安装完成后重新打开一个 PowerShell 窗口即可使用 purrge 命令。
• 模块里自带完整代码，安装过程不访问 GitHub。

# 一行脚本（从 GitHub 下载）
[Net.ServicePointManager]::SecurityProtocol = 'Tls12'; irm https://raw.githubusercontent.com/RabbittuX/purrge/master/install.ps1 | iex

上面这条报错「基础连接已经关闭」或「连接被重置」时（国内网络经常拦截 raw.githubusercontent.com），改用下面这条，从 codeload.github.com 下载完整代码后安装：

[Net.ServicePointManager]::SecurityProtocol='Tls12'; $ProgressPreference='SilentlyContinue'; $t="$env:TEMP\purrge-dl"; Remove-Item $t -Recurse -Force -ErrorAction SilentlyContinue; New-Item -ItemType Directory $t | Out-Null; Invoke-WebRequest https://codeload.github.com/RabbittuX/purrge/zip/refs/heads/master -OutFile "$t\p.zip" -UseBasicParsing; Expand-Archive "$t\p.zip" $t; iex (Get-Content -Raw -Encoding UTF8 (Get-ChildItem $t -Recurse -Filter install.ps1 | Select-Object -First 1).FullName)

由 AI 代为安装（macOS / Windows）

在 Claude Code、Codex 或 WorkBuddy 中输入：

帮我安装 GitHub 上的 RabbittuX/purrge，只认作者 RabbittuX，找不到就先问我，不要安装同名的其他项目

AI 会读取本仓库的安装指引完成安装，并自动选用当前的 AI 作为分析引擎。

安装过程

1. 选择 AI 引擎：Claude Code、Codex、WorkBuddy 或 DeepSeek Harness（由 AI 代为安装时自动选择当前 AI）。
2. 设置提醒阈值：剩余空间低于该值时发出提醒，默认 15 GB。
3. 配置 AI 引擎：未安装时自动安装最新版本（需要 Node.js 时先询问并自动安装）；未登录时引导登录；最后进行连接测试，确认引擎可正常响应。
4. 启用后台监控：安装完成后，Purrge 以后台服务形式独立运行，无需保持 AI 软件处于打开状态。

支持的 AI 引擎

引擎	调用方式	说明
Claude Code	claude -p --tools ""	关闭全部工具
Codex	codex exec --sandbox read-only	只读沙箱，支持免费账号
WorkBuddy	CodeBuddy 命令行 codebuddy -p --tools ""	关闭全部工具；与 WorkBuddy 同一账号、同一积分；首次需运行 codebuddy 并输入 /login 登录
DeepSeek Harness	dsh --profile headless + 关工具补丁	关闭全部工具，补丁未生效时拒绝调用；需要 DeepSeek API Key，只保存在本机

随时切换：purrge engine claude | codex | workbuddy | deepseek。

🔄 更新

purrge update

自动识别安装方式（Homebrew / 脚本），先备份再更新，设置、扫描记录和 AI 引擎都保留；新版本自检不通过会自动换回旧版本。有新版本时，purrge status 和审查页会提示。

[!NOTE] 从 0.2.x 升级：0.2.x 还没有 purrge update 命令，需要手动更新这一次，之后就可以用 purrge update 了。

• Homebrew 安装的：brew upgrade rabbittux/tap/purrge && purrge update（设置和 AI 引擎都保留）
• 脚本安装的：重新运行一遍上面的安装命令

🐾 使用方法

操作	终端命令	在 Claude Code / Codex / WorkBuddy 中说
立即扫描	purrge scan	"磁盘快满了，帮我清理一下"
重新打开上次的审查页	purrge review	—
查看状态	purrge status	"硬盘还剩多少"
修改阈值	purrge config thresholdGB 20	"阈值改成 20G"
额外扫描其他目录 / 分区	purrge config scanDirs add D:\项目（remove 移除、clear 清空）	"把 D 盘的项目文件夹也扫一下"
查看 / 切换 AI 引擎	purrge engine、purrge engine workbuddy	—
更新到最新版	purrge update	"帮我更新 Purrge"
停用提醒	purrge uninstall	"关掉磁盘提醒"
查看版本	purrge version	—

• 扫描完成后会自动在浏览器打开审查页面：勾选要清理的项目，点「清理」后才会执行。
• 阈值、检查频率等参数也可在审查页面右上角的「设置」中修改。

🗑️ 卸载

purrge uninstall           # 关闭后台监控，移除 purrge 命令和 AI 里的说明文件（保留设置和扫描记录）
purrge uninstall --purge   # 同时删除设置、扫描记录以及 Purrge 自带的 Node.js

• Homebrew 安装的：再运行 brew uninstall purrge。
• 通过 PowerShell Gallery 安装的：再运行 Uninstall-Module Purrge。
• Windows：在 PowerShell 中执行上面的命令即可，后台的「任务计划程序」任务、通知登记会一并清除。
• 安装时自动装上的 Python、Node.js（系统里原本没有的）不会被删除；不再需要时可在系统中自行卸载。

📋 系统要求

• macOS 或 Windows 10/11
• Python 3.8 及以上（没有时安装程序会自动安装：Mac 用苹果官方命令行开发者工具，Windows 用 python.org 官方安装包，无需管理员权限）
• 使用 WorkBuddy / DeepSeek（以及 Windows 上的 Codex）时需要 Node.js；没有时自动下载官方 LTS 版本到 Purrge 自己的目录，不改动系统
• Claude Code、Codex、WorkBuddy 或 DeepSeek Harness 任一可用账号（AI 分析使用用户自己的额度，支持 Codex 免费账号；DeepSeek 使用自己的 API Key）。AI 暂时不可用时自动切换为规则判断，基础功能不受影响
• 可选（macOS）：为「终端」授予「完全磁盘访问权限」，以扩大系统缓存的扫描范围

🤖 AI 助手安装指引

本节供 Claude Code、Codex 等 AI 助手阅读。用户请求安装 Purrge 时，请按以下步骤执行。

This is the beginning of the README. Read the rest at the original. Read the full README ↗