Storage Agent

安全、可解释、可撤销的 Agentic 存储管理 TUI。

Storage Agent 是一个独立的 Textual 终端产品，用本地扫描器生成可信存储事实，用 DeepSeek API 做只读归因和建议，并用强制安全规则控制所有优化操作。

产品能力

核心优化流程

产品启动后默认进入第 1 步，并在顶部始终显示：

① AI 解释并排序 → ② 分级选择清理项 → ③ 确认风险 / 管理员验证后移入废纸篓

1. 点击 生成 AI 优化建议，理解空间占用和优先级。
2. 点击 → ② 选择清理项，进入候选审核。
3. 按风险分级选择并加入“清理清单”：
   • safe：普通确认即可。
   • review：会显示强化确认，要求你理解内容可能不是纯缓存。
   • protected（如 Documents/Desktop 中的项目）：执行前会弹出 macOS 原生管理员身份验证。
4. 点击 清理已选项（移入废纸篓，可恢复），输入确认文字后执行。
5. 如需撤销，在 History & Undo 中恢复。

管理员密码由 macOS 系统对话框负责，应用不会读取或保存密码。以下路径即使通过管理员验证也绝对禁止：.git、.ssh、.gnupg、钥匙串、邮件、消息、照片库、扫描根目录和符号链接。

Dashboard

• 磁盘总量、已用比例、可用空间
• 规则确认的安全可回收空间
• 一级目录占用排行、分类、风险和文件年龄
• 扫描耗时与告警

Explorer

• 在配置根目录内逐层钻取
• 查看目录大小、类别、风险、修改年龄
• 严格禁止越出扫描根目录

Optimize

• 自动发现缓存、旧日志、安装包、构建产物与备份候选
• safe / review / protected 三档风险
• safe 普通确认；review 强化确认；protected 需 macOS 管理员身份验证
• 显示已选项目数量、预计清理空间和风险分布
• 输入完整确认词后才执行
• 清理已选项表示移动到 macOS 废纸篓，不是永久删除
• 只有清空废纸篓后空间才真正释放

History & Undo

• SQLite 持久化扫描历史
• 完整操作审计：源路径、废纸篓路径、大小、类型和时间
• 支持从废纸篓恢复
• 恢复时拒绝覆盖现有文件

Agent

• 使用 my-provider/deepseek-v4-flash
• 一键生成整体归因与优化优先级
• 支持针对当前快照继续提问
• AI 只接收结构化摘要
• 通过 --no-tools --no-session --no-context-files 运行
• AI 无法读取任意文件、执行 shell 或触发删除

Settings & Health

• TUI 内配置扫描根目录、深度、候选阈值、DeepSeek API Key / 模型
• 配置持久化
• 内置 Doctor：系统、根目录、DeepSeek API Key、数据目录和废纸篓诊断
• 配置文件中 API Key 以 chmod 600 保存，config 命令输出时脱敏为 ***

CLI 与报告

storage-agent                 # 启动 TUI
storage-agent tui             # 启动 TUI
storage-agent scan            # 只读扫描摘要
storage-agent scan --json     # 结构化输出
storage-agent scan --analyze  # 加入 AI 分析（需配置 DeepSeek API Key）
storage-agent report          # 导出 Markdown
storage-agent report --format json
storage-agent doctor          # 产品诊断
storage-agent config          # 显示非敏感有效配置

安全保证

1. 本地扫描与 AI 分离：事实由 Python 扫描器生成，AI 不直接访问磁盘。
2. 默认保护用户数据：Documents、Desktop、Git、SSH、邮件、消息、照片库、钥匙串及应用主数据禁止直接优化。
3. 构建产物仍需审核：node_modules、.venv、target 等可重建内容是 review，不会自动进入计划。
4. 可逆操作：优化只移动到当前用户废纸篓。
5. 强确认：批量计划必须输入 TRASH N ITEMS。
6. 操作审计：每次移动都写入本地 SQLite。
7. 撤销不覆盖：目标已存在时拒绝恢复。
8. 范围约束：候选和目录浏览只能位于配置根目录与用户 Home 内。

AI 模型配置

应用直接调用 DeepSeek 的 OpenAI 兼容接口（https://api.deepseek.com），不依赖任何外部 Agent 运行时。

配置 API Key 的方式（按优先级）：

1. 环境变量（推荐，不落盘）：export DEEPSEEK_API_KEY=sk-...
2. TUI Settings 页：填写 DeepSeek API Key 并保存（配置文件权限 chmod 600）

默认模型为 deepseek-v4-flash，可在 Settings 页修改；自定义 API 地址用 STORAGE_AGENT_DEEPSEEK_BASE_URL。

验证：

storage-agent doctor     # 检查 API Key 是否已配置
storage-agent config     # 查看有效配置（API Key 脱敏显示）

应用发起一次无状态 chat completion：

POST https://api.deepseek.com/chat/completions
Authorization: Bearer <API Key>
model: deepseek-v4-flash
messages: [system 只读分析指令, user 结构化快照]

自动更新

• TUI：Settings & Health 页 →「检查更新」/「立即升级」；启动时后台静默检查。
• CLI：storage-agent update 检查，storage-agent update --yes 检查并升级。
• 升级按安装方式自适应（Homebrew / uv tool / pipx / 源码），不触碰用户配置与审计数据。

安装

一键安装到 ~/.local

chmod +x scripts/install.sh scripts/uninstall.sh
./scripts/install.sh
storage-agent doctor
storage-agent

确保 ~/.local/bin 在 PATH 中。

卸载程序：

./scripts/uninstall.sh

卸载默认保留设置、扫描历史和操作审计。

开发模式

uv sync --extra dev
uv run storage-agent doctor
uv run storage-agent

快捷键

配置与数据位置

macOS：

~/Library/Application Support/Storage Agent/config.json
~/Library/Application Support/Storage Agent/storage-agent.sqlite3
~/Library/Application Support/Storage Agent/reports/

环境变量优先于配置文件：

测试

uv run pytest -q
uv run python -m compileall -q src tests

测试覆盖：

• 风险规则和受保护路径
• 扫描器候选发现
• 废纸篓移动和恢复
• 配置持久化与边界钳制
• SQLite 扫描历史、操作审计、分析缓存
• Markdown/JSON 报告
• CLI 输出
• Textual headless pilot 启动

项目结构

src/storage_agent/
├── app.py          # Textual 产品界面
├── cli.py          # 独立 CLI
├── scanner.py      # 本地扫描器
├── rules.py        # 风险策略
├── optimizer.py    # 废纸篓事务与撤销
├── repository.py   # SQLite 历史与审计
├── agent.py        # DeepSeek 只读分析
├── reporting.py    # Markdown / JSON 报告
├── diagnostics.py  # Doctor
├── config.py       # 持久化设置
└── app.tcss        # 产品主题