Metadata-Version: 2.5
Name: storage-agent-tui
Version: 0.4.6
Summary: Agentic, safety-first storage analysis and optimization TUI built with Textual and Pi
Author: Storage Agent Contributors
License: MIT License
        
        Copyright (c) 2026 Storage Agent Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agentic,macos,pi,storage,textual,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: textual<9,>=8.2
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Storage Agent

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

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

## 产品能力

### 核心优化流程

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

```text
① 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 与报告

```bash
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`。

验证：

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

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

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

## 安装

### 一键安装到 `~/.local`

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

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

卸载程序：

```bash
./scripts/uninstall.sh
```

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

### 开发模式

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

## 快捷键

| 键 | 功能 |
|---|---|
| `R` | 重新扫描 |
| `A` | AI 整体分析 |
| `Space` | 加入/移出优化计划 |
| `E` | 执行计划 |
| `U` | 恢复选中的操作 |
| `X` | 导出报告 |
| `?` | 快捷键提示 |
| `Q` | 退出 |

## 配置与数据位置

macOS：

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

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

| 环境变量 | 默认值 |
|---|---|
| `STORAGE_AGENT_ROOT` | `$HOME` |
| `STORAGE_AGENT_DEPTH` | `3` |
| `STORAGE_AGENT_TOP` | `100` |
| `STORAGE_AGENT_MIN_CANDIDATE_BYTES` | `10485760` |
| `DEEPSEEK_API_KEY` / `STORAGE_AGENT_DEEPSEEK_API_KEY` | （必填）DeepSeek API Key |
| `STORAGE_AGENT_DEEPSEEK_BASE_URL` | `https://api.deepseek.com` |
| `STORAGE_AGENT_DEEPSEEK_MODEL` | `deepseek-v4-flash` |
| `STORAGE_AGENT_AI_TIMEOUT` | `180` |
| `STORAGE_AGENT_DATA_DIR` | 平台应用数据目录 |
| `STORAGE_AGENT_CONFIG` | 平台配置路径 |

## 测试

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

测试覆盖：

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

## 项目结构

```text
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        # 产品主题
```
