Skip to content

README.zh-CN.md

Latest commit

 

History

History
311 lines (200 loc) · 13.2 KB

README.zh-CN.md

File metadata and controls

311 lines (200 loc) · 13.2 KB
Raw
Vole mascot

Vole

给 macOS 用的清理与监控命令行工具
先看再清 · 默认进废纸篓 · 一个命令装好就能用

License: GPL-3.0 Version Platform Download Stars

多语言： English · 简体中文 · 繁體中文 · 日本語 · 한국어

缓存、日志、卸载残留、安装包、构建垃圾……Vole 帮你找出来，先预览再清理。默认进废纸篓，删错还能找回。

快捷导航 界面预览 · 能做什么 · 安装 · 使用 · 安全说明 · 常见问题 · 桌面版 · 关于我 · 鸣谢 · 许可证

界面预览

Vole 交互式首页（七项：清理到 Agent）

终端运行 vole 即可打开交互式首页：方向键移动，Enter 进入。

交互首页目前七项：前五项文案对齐 Mole（清理 / 卸载 / 优化 / 分析 / 状态），第六项 Worktree 与第 7 项 Agent（Remove leftover agent data，数字键 7）是 Vole 自己的增值入口，不是 Mole 命令面缺口。1–6 含义不变。

能做什么

功能 你能得到什么
清理 扫出缓存、日志、残留，确认后再清理
卸载 卸掉 App，并尽量清掉残留文件
优化 做一组安全范围内的系统维护（如刷新缓存等）
净化 清理陈旧项目构建物等占空间的大件
安装包 找出磁盘上落灰的 .dmg / .pkg
分析 看哪个文件夹、哪些大文件最占空间
历史 回看做过的清理与删除记录
状态 实时看 CPU、内存、磁盘健康情况
Worktree 列出遗留 Git worktree，确认后移入废纸篓
Agent 列出 Agent 容器 / 会话 / 缓存残留，确认后移入废纸篓

打开终端输入 vole，会进入交互式首页，用方向键选功能即可。内置约 540 条清理规则，不必再单独安装其他小工具。

适合：会开终端、想安全清理 Mac，又不喜欢「一键全删」的人。想要窗口界面请看下方「桌面版」。

安装

需要 macOS 12 或更高。

当前已发布版本：v2.20.0（Developer ID 签名并经 Apple 公证）。Apple Silicon 与 Intel 均有对应安装包。

产品话术里的「v3」指 CLI 代际。包版本继续 2.x MINOR（当前 2.20.0），不是 3.0.0，也不会因为「v3」发 3.0.0。请用本仓 tap 安装，我们不会把 vole 送进 Homebrew core。下一份 MINOR 由已合入的用户可见行为触发，是否打 tag 另问。

方式一：发给 AI 安装

把下面这段提示词复制发给 Cursor、Claude Code、Codex、ChatGPT 等 AI 助手，它会帮你完成安装。

请在这台 Mac 上安装 Vole（macOS 清理与监控命令行工具）。

官方仓库：https://github.com/wukongnotnull/vole
需要 macOS 12+。只负责安装，不要运行 clean / uninstall / optimize / purge / worktree / agent 等会改动系统的命令。不要往 Homebrew core 提交或从 core 安装 vole。

按顺序尝试，前一步成功就停：
1. 若已有 Homebrew：
   brew tap wukongnotnull/vole https://github.com/wukongnotnull/vole
   brew install vole
2. 否则从 GitHub Releases 下载最新公证包
   （Apple Silicon 用 aarch64-apple-darwin，Intel 用 x86_64-apple-darwin），
   把 bin/vole 装到 ~/.local/bin，并把 share/vole/rules 复制到 ~/.local/share/vole/rules。
   如需要，把 ~/.local/bin 写入 ~/.zshrc 的 PATH。
3. 不要从源码编译，除非上面两种方式都失败。

装完后执行 `vole --version`，告诉我安装路径和版本。

也可以直接说：帮我按 https://github.com/wukongnotnull/vole 的官方说明安装 Vole

方式二：Homebrew

brew tap wukongnotnull/vole https://github.com/wukongnotnull/vole
brew install vole

装好后直接运行 vole。若 brew 安装失败或版本对不上，请改用下方「下载安装包」。

方式三：下载安装包

  1. 打开 最新 Release
  2. 下载对应芯片的压缩包：
  • Apple Silicon（M 系列）：…-aarch64-apple-darwin.tar.gz
  • Intel：…-x86_64-apple-darwin.tar.gz
  1. 解压后，把 bin/vole 放到你 PATH 里的目录（例如 ~/.local/bin），并保留同包里的 share/vole/rules 目录

示例（Apple Silicon / v2.20.0；请以 Release 页实际文件名为准）：

curl -LO https://github.com/wukongnotnull/vole/releases/download/v2.20.0/vole-2.20.0-aarch64-apple-darwin.tar.gz
tar xzf vole-2.20.0-aarch64-apple-darwin.tar.gz
mkdir -p ~/.local/bin ~/.local/share/vole
install -m 755 vole-2.20.0-aarch64-apple-darwin/bin/vole ~/.local/bin/vole
cp -R vole-2.20.0-aarch64-apple-darwin/share/vole/rules ~/.local/share/vole/

若终端提示找不到 vole，把下面这行写进 ~/.zshrc 后执行 source ~/.zshrc：

export PATH="$HOME/.local/bin:$PATH"

使用

常用命令

# 日常
vole                           # 交互式首页（最省事）
vole status                    # 看机器状态
vole analyze                   # 谁占了磁盘
vole clean                     # 扫描 → 确认 → 清理（默认废纸篓）
vole uninstall                 # 交互式卸载 App
vole optimize                  # 系统维护
vole history                   # 回看做过什么

# 只预览、先不删（适合不放心时）
vole clean --plan
vole uninstall --plan
vole optimize --plan
vole purge --plan
vole installer --plan
vole worktree --plan
vole agent --plan

# 看过候选后再执行
vole clean --apply <plan.json>
vole uninstall --apply <plan.json>

# 其他常用
vole touchid status            # 查看 sudo Touch ID
vole update                    # 升级到新版本
vole remove --plan             # 卸载 Vole 自身（仅预览）
vole --help
vole --version

默认进废纸篓。只有你主动加上「永久删除」相关选项时，才会不可从废纸篓恢复。

全部命令

不带子命令时，在终端运行 vole 会打开交互式首页。

命令 别名 说明
vole — 交互式首页（清理 / 卸载 / 优化 / 分析 / 状态 / Worktree / Agent）
vole clean — 清理缓存与残留
vole uninstall — 卸载应用及残留
vole optimize optimise 系统优化与维护
vole status — 实时健康面板（CPU / 内存 / 磁盘）
vole analyze analyse 目录体积分析（默认从个人主目录开始）
vole history — 操作历史与删除记录
vole purge — 清理陈旧项目构建物
vole worktree — 列出遗留 Git worktree，确认后移入废纸篓
vole agent — 列出 Agent 残留，确认后移入废纸篓（不是 git checkout 清理，那是 worktree）
vole installer — 查找并清理安装包
vole touchid — 配置 sudo 的 Touch ID（status / enable / disable）
vole update — 自更新（只有你主动执行才会联网）
vole remove — 卸载 Vole 自己
vole completions completion 生成终端自动补全
vole help — 帮助（也可用 -h / --help）
vole --version -V 打印版本

安全说明

你        ❯ vole clean → 查看候选 → 确认

Vole      ❯ ✓ 先列出候选，不直接动手
            ✓ 默认进废纸篓（可恢复）
            ✓ 执行前再检查保护路径
            ✓ 不确定就跳过——不会悄悄扩大删除范围
原则 含义
先预览再执行 终端里会询问确认；也可用 --plan 只看不删
默认可恢复 个人文件默认进废纸篓
报告清楚 会区分「进废纸篓」和「永久删除」
可追溯 用 vole history 回看

日常清理在本地完成。只有执行 vole update 时才会联网下载更新。

常见问题

Q：会不会不询问就删除？
A：在终端里直接运行 clean / optimize 时，会问你是否继续（默认否）。不放心可以先用 --plan 只看列表。

Q：删错了怎么办？
A：默认进废纸篓，打开废纸篓还原即可。若你当时选了永久删除，则无法从废纸篓找回。

Q：App 已经卸了，还是还装着？
A：卸干净后的残留 → vole clean。App 还在 → vole uninstall。

Q：提示找不到命令 vole？
A：确认安装路径已加入 PATH（见上方 ~/.local/bin 示例），新开一个终端窗口再试。

Q：更想用图形界面？
A：请用 Vole for macOS——同一套清理能力，窗口操作，支持 Apple Silicon 与 Intel。

Q：和 Mole 是什么关系？
A：清理规则与安全思路受到 Mole 启发；Vole 是独立开源项目，不隶属于 Mole。

更喜欢图形界面？

Vole for macOS 是配套桌面版：侧栏提供清理、卸载、优化、净化、安装包、分析、历史、状态；可授予完全磁盘访问，并可选启用 Root 特权助手清理部分系统路径。

最新桌面版见 vole-macos Releases（当前为 Universal DMG）。

同一套清理能力 · 同一套安全习惯 · 终端或窗口任选

关于我

悟空非空也 — AI之道创始人，独立开发者，Up主。

平台 链接
🌐 官网 AI之道官网
𝕏 Twitter 悟空非空也
📺 B站 悟空非空也
▶️ YouTube 悟空非空也
📕 小红书 悟空非空也
💬 公众号 微信搜「悟空非空也」

鸣谢

感谢这些产品与开源项目在 macOS 清理体验上的探索与积累，Vole 从中获益良多：

  • Mole — 开源清理工具；规则与安全思路的重要启发
  • CleanMyMac — 成熟的桌面清理产品体验参考
  • 腾讯柠檬清理 — 中文用户熟悉的系统清理产品参考

Vole 是独立开源项目，与上述产品无隶属或商业关系。

许可证

Vole 遵循 GPL-3.0。
清理规则与安全思路受到 Mole 启发；Vole 是独立开源项目，不隶属于 Mole。
如需基于本项目做自有产品，请更换名称以避免混淆，并注明来源于 Mole / Vole。

GPL-3.0 license © 悟空非空也