macOS MENU BAR · SWIFTUI · MACOS 14+

The Pool Problem is a free-space guard for developers. It watches the cheap signal first — available disk capacity — and analyzes known regenerable caches only when space approaches the configured waterline. Unattended cleanup is reserved for explicitly authorized caches; everything else stays manual and recoverable.

The Pool Problem 是面向开发者的可用空间守护器：平时只读取低成本的磁盘余量；接近水线时才分析已知的可再生缓存。无人值守清理只作用于明确授权的缓存，其余项目始终保留为手动、可恢复操作。

Feature 功能	What it does 说明
Pressure states · 空间压力	Healthy: capacity probe only; warning: analyze; critical: consider cleanup. 健康时只探测余量；接近水线时分析；低于水线时才考虑清理。
Safe automation · 安全自动化	Automatic permanent deletion requires explicit recipe authorization plus age and process guards. 自动永久删除必须同时具备配方明确授权、年龄保护与进程保护。
Growth priority · 增长优先	Among equally safe candidates, measured fast-growing caches are handled first. 仅在同等安全级别内，优先处理实测快速增长的缓存。
Recoverable manual cleanup · 可恢复手动清理	Projects, user-added paths, broad caches, and archives remain manual and go to Trash when applicable. 项目、用户添加路径、宽泛缓存和归档保持手动；适用时进入废纸篓。
Honest metering · 诚实计量	APFS clone-aware scanning reports real reclaimable space, not surface size. 感知 APFS 克隆与稀疏文件，报告真实可释放空间而非表面大小。
Three-level safety · 三级安全分级	safeWhileRunning / requiresQuit / userConfirm, with dry-run previews before any deletion. safeWhileRunning / requiresQuit / userConfirm 三级安全，一切删除先 dry-run 预览。
Scriptable CLI · 可脚本化 CLI	scan / suggest / clean / status with stable JSON output. scan / suggest / clean / status 命令，稳定 JSON 输出。

Milestone 里程碑	Status 状态	Scope 范围
M1 Core · 核心库	✅ Done 完成	DiskReservoirCore — recipe registry, clone-aware scanner, snapshot storage, flow analysis (attribution / rebound / growth alerts), fill prediction, rule evaluation, process detection, file deletion, and a waterline cleaning engine with measured actualFreedBytes. DiskReservoirCore——配方库、扫描器（含硬链接去重）、快照存储、流量分析（归因 / 回涨 / 增长警报）、满盘预测、规则评估、进程检测、文件删除、水线清理引擎（含量规实测 actualFreedBytes）。
M2 CLI · 命令行	✅ Done 完成	poolproblem — scan / suggest / clean / status / mcp with stable JSON and MCP tools. poolproblem——scan / suggest / clean / status / mcp，稳定 JSON 输出并提供 MCP tools。
M3 App · 应用	✅ Done 完成	SwiftUI menu-bar app — water-level panel (E-shaped gauge, sky-primary reading, layered levels), smart cleanup, novice / expert settings, notifications, Full Disk Access onboarding, launch at login, custom status-bar water icon, spring animations, accessibility. SwiftUI 菜单栏应用——蓄水池水位面板（E 字型水位标尺、天空主读数、分层水位）、智能清理、傻瓜 / 专家设置、通知、完全磁盘访问引导、开机自启、自定义状态栏水位图标、弹簧动效与无障碍适配。
M4 Widget · 小组件	⏳ Paused 暂缓	macOS desktop widget. macOS 桌面小组件。
M5 Packaging · 打包	✅ Done 完成	v1.1.0 — DMG + Apple notarization, distributed via GitHub Releases. v1.1.0——DMG + Apple 公证，GitHub Releases 分发。

• macOS 14 or later.

  macOS 14 及以上。

Download the latest release from the button above, or browse every version on GitHub Releases.

从上方按钮下载最新版，或在 GitHub Releases 查看全部版本。

1. The DMG is Apple-notarized (Developer ID signature + Hardened Runtime), so it can be opened directly.

   DMG 已通过 Apple 公证（Developer ID 签名 + Hardened Runtime），下载后可直接打开。

2. Open the DMG and drag PoolProblem.app into Applications.

   打开 DMG，把 PoolProblem.app 拖入 Applications 即可。

Build and run the menu-bar app (Xcode project at PoolProblem/PoolProblem.xcodeproj):

构建并运行菜单栏 App（Xcode 工程在 PoolProblem/PoolProblem.xcodeproj）：

xcodebuild -project PoolProblem/PoolProblem.xcodeproj -scheme PoolProblem -configuration Debug -derivedDataPath .build/xcode-derived build
open .build/xcode-derived/Build/Products/Debug/PoolProblem.app

Build and test the CLI:

构建并测试 CLI：

swift build        # build (first run fetches swift-argument-parser)
swift test         # run all tests

A reservoir water-level icon appears in the menu bar, updating in real time with disk usage:

菜单栏出现蓄水池水位图标（水位随磁盘占用实时变化）：

• Click the panel for available space, target waterline, the explicitly authorized auto-clean ceiling, recovery gap, safety-labelled items, and one-tap manual cleanup (preview first, then confirm).

  点击弹出面板：可用空间、目标水线、明确授权的自动清理上限、恢复缺口、含安全标记的条目，以及先预览再确认的一键手动清理。

• Settings: target waterline (default 30 GB), novice / expert mode, recipe toggles and retention days, whitelist, Full Disk Access status and onboarding, launch at login.

  设置：目标水位（默认 30GB）、傻瓜 / 专家模式、配方开关与保留天数、白名单、完全磁盘访问状态与引导、开机自启。

• Notifications: low space (< 20 GB), abnormal growth, action needed (for example, quit Simulator), cleanup summary.

  通知：空间紧张（<20GB）、异常增长、需要操作（如退出 Simulator）、清理摘要。

• Available capacity is probed every five minutes. Recursive analysis runs only near or below the waterline, or when the user explicitly refreshes. Snapshots are saved to ~/Library/Application Support/PoolProblem or the App Group container.

  每五分钟只探测一次可用容量；仅在接近/低于水线或用户主动刷新时进行递归分析。快照保存在 ~/Library/Application Support/PoolProblem 或 App Group 容器。

On first launch, grant Full Disk Access in System Settings → Privacy & Security so protected directories such as ~/Library/Containers can be scanned.

首次使用请到 系统设置 → 隐私与安全性 → 完全磁盘访问 授权，才能扫描 ~/Library/Containers 等受保护目录。

poolproblem scan               # scan every recipe, report reclaimable space
poolproblem scan --json        # machine-readable JSON
poolproblem suggest            # suggest cleanable items by rule
poolproblem clean --dry-run    # preview what would be cleaned
poolproblem clean              # clean by waterline and rules
poolproblem status             # waterline, fill prediction, recent cleanups
poolproblem mcp                # run as an MCP stdio server for AI agents

Install the CLI into ~/.local/bin:

将 CLI 安装到 ~/.local/bin：

scripts/install-cli.sh

The CLI is also available as an MCP server. Start it with:

CLI 也可以作为 MCP server 供其他 AI Agent 使用：

poolproblem mcp

Exposed MCP tools:

提供的 MCP tools：

• scan
• suggest
• clean
• status

Example MCP client configuration:

MCP 客户端配置示例：

{
  "mcpServers": {
    "poolproblem": {
      "command": "poolproblem",
      "args": ["mcp"]
    }
  }
}

Data directory resolution order: POOLPROBLEM_DATA_DIR → App Group container → ~/Library/Application Support/PoolProblem. Tests point POOLPROBLEM_DATA_DIR at a temporary directory for isolation.

数据目录解析顺序：环境变量 POOLPROBLEM_DATA_DIR → App Group 容器 → ~/Library/Application Support/PoolProblem。测试通过 POOLPROBLEM_DATA_DIR 指向临时目录隔离。

Packages · 包结构

poolproblem/
├── Sources/DiskReservoirCore/   # SwiftPM library, no UI
│   ├── Recipes/                 # recipe definitions and registry
│   ├── Scanner/                 # scanning, APFS clone-aware
│   ├── Snapshot/                # snapshot models and store
│   ├── Flow/                    # flow rates, attribution, rebound, prediction
│   ├── Cleaner/                 # cleaning engine, rule evaluation, ProcessGuard
│   └── Storage/                 # data paths (App Group / Application Support)
├── Sources/poolproblem/         # CLI: scan / suggest / clean / status / mcp
├── PoolProblem/                 # SwiftUI menu-bar app
└── Tests/                       # core and CLI tests

The app, CLI, and a future widget share one core library and one snapshot store; a file lock keeps the app and CLI from writing or cleaning concurrently.

App、CLI 与未来小组件共用同一核心库与快照库；文件锁避免 App 与 CLI 同时写入或清理。

Data flow · 数据流

Launch / login item → load the latest snapshot → cheap capacity probe → healthy: stop; warning: analyze known recipes; critical: analyze, apply safety gates, then clean only explicitly authorized caches → verify actual available space → refresh the menu bar.

启动 / 开机自启 → 载入最近快照 → 低成本容量探测 → 健康：结束；警告：分析已知配方；紧急：分析并通过全部安全门后，仅清理明确授权缓存 → 复测真实可用空间 → 刷新菜单栏。

The app ships without App Sandbox (required for system-level cleanup) and keeps everything local: configuration in UserDefaults, snapshots and logs in ~/Library/Application Support/PoolProblem or the App Group container. Nothing is uploaded; everything stays on your Mac.

App 未启用 App Sandbox（系统级清理所需），数据全部保存在本地：配置在 UserDefaults，快照与日志在 ~/Library/Application Support/PoolProblem 或 App Group 容器中。不会上传任何数据。

APFS clone files (cp -c, Xcode test snapshots) share physical blocks but not inodes, so the real reclaimable space cannot be measured exactly through public APIs before deletion. Therefore:

APFS 克隆文件（cp -c / Xcode 测试快照）的 inode 与资源标识不共享，但物理块共享——删除前无法用公开 API 精确测量真实可释放空间。因此：

• reclaimableBytes deduplicates hard links (same inode), making it an upper bound for clone-heavy directories.

  reclaimableBytes 基于硬链接去重（inode 相同才去重），对克隆密集型目录是上界。

• clean reports both the estimate (freedBytes) and the measured result (actualFreedBytes); trust the measured number.

  clean 输出同时报告估算释放（freedBytes）与量规实测（actualFreedBytes），以实测为准。

• M4: macOS desktop widget (paused).

  M4：macOS 桌面小组件（暂缓）。

• App icon polish.

  应用图标打磨。

• Broader automatic cleanup only after per-recipe safety evidence and recovery testing.

  只有在逐配方安全证据与恢复测试充分后，才扩大自动清理范围。

• Design spec: docs/superpowers/specs/2026-08-09-the-pool-problem-design.md

  设计：docs/superpowers/specs/2026-08-09-the-pool-problem-design.md

• Implementation plan: docs/superpowers/plans/2026-08-09-core-cli.md

  实现计划：docs/superpowers/plans/2026-08-09-core-cli.md

Contributions are welcome! Please read CONTRIBUTING.md and CLA.md first.

欢迎贡献！请先阅读 CONTRIBUTING.md 与 CLA.md。

Before submitting a Pull Request, add your GitHub username to .github/CLA_SIGNERS — this counts as signing the Contributor License Agreement, and CI enforces the CLA status check.

提交 Pull Request 前，请将你的 GitHub 用户名添加到 .github/CLA_SIGNERS，即视为签署贡献者许可协议；CI 的 CLA 状态检查会强制校验。

Released under the Apache License 2.0. Copyright © 2026 xingyu wang.

本项目以 Apache License 2.0 发布。Copyright © 2026 xingyu wang。