# Storage Steward · 存储管家

A macOS storage organizer with a local dashboard and a Codex MCP plugin. Review file names and destinations, copy with content verification, and explicitly confirm before removing local originals.

在同一个面板中管理本地目录、外接硬盘和已授权的云盘。你可以手动安排文件去处，也可以让 Codex 读取有限内容，生成命名、分类和存放计划。

**状态：早期版本，面向 macOS。** 本地普通文件流程有自动测试；真实云盘和外接设备需在自己的环境中验证。首次请使用可恢复的测试文件。

## 能做什么

- 只读元数据索引、搜索、文件详情与按需文本／文字型 PDF 内容提取。
- 手动指定目标、文件名与目录；Codex 可以通过 9 个 MCP 工具生成和执行已授权计划。
- 来源目录和分类规则，以及禁止上云、保留本地、禁止改名、禁止删除等文件保护。
- 本地原子改名、复制、云盘上传和取回、暂停／取消、完整 SHA-256 读回校验、恢复计划。
- 复制完成后保留原件。移除本地原件必须另外确认，随后重新检查源内容、目标内容和 Mac 属性。
- 通过 rclone 接入 Google Drive、OneDrive、WebDAV 等后端。容量来自实际连接；没有预置任何个人账号或套餐额度。
- 外接设备身份绑定；离线设备无法作为有效目标。本版不操作 iCloud，不格式化磁盘。

## 快速开始

需要 macOS、Python 3.12+；云端功能另需 [rclone](https://rclone.org/install/)。没有捆绑云盘账号，也不需要额外的模型 API 密钥来运行本地面板。

```sh
git clone https://github.com/yusongcao2004/storage-steward.git
cd storage-steward
python3.12 scripts/bootstrap.py
./打开存储管家.command
```

`bootstrap.py` 在当前用户的 `~/Documents/Codex/StorageStewardRuntime/venv` 创建独立环境并安装声明的 Python 依赖。已存在的环境不会默认覆盖；升级需明确传入 `--update`。脚本不会自动安装 rclone、启动登录项、扫描正文或迁移文件。

启动脚本需要从终端运行，或在 Finder 中双击；网页／聊天里的文件链接不等于运行脚本。也可以创建 Finder 应用入口：

```sh
python3.12 scripts/build_macos_app.py
open "build/Storage Steward.app"
```

将生成的应用保留在仓库的 `build/` 中。启动器会打开默认浏览器，并在需要时启动只监听 `127.0.0.1` 的本机服务。关闭网页不停止已开始的传输。

首次登记常见本地目录；点击“更新索引”后才扫描。添加云盘并完成授权后，再读取账号容量和文件列表。具体操作见 [使用说明](使用说明.md)。

## Codex 插件与独立 MCP

仓库包含标准 `.codex-plugin/plugin.json`、`.mcp.json` 和 `skills/`。若你的 Codex 提供 `plugin-creator` 本机脚手架，完成运行环境安装后可以执行：

```sh
python3.12 scripts/install_personal.py
```

它会检查前置条件、保留已有市场配置备份，然后通过官方脚手架添加个人插件。已有同名安装会停止，避免覆盖。安装后新开 Codex 任务以加载工具。此脚本依赖本机脚手架，未提供该脚手架的版本可直接使用面板，或将仓库内 `scripts/mcp-server` 的绝对路径配置为 stdio MCP 服务。

工具：`storage_overview`、`storage_files`、`storage_scan`、`storage_inspect`、`storage_plan`、`storage_execute`、`storage_control`、`storage_restore`、`storage_panel`。自动执行仅限用户明确开启的规则；MCP 不暴露删除原件或自行批准的工具。

## 隐私和数据范围

源码不包含文件清单、聊天记录、运行数据库、截图、账号配置、访问令牌或编译后的应用。运行数据保存在当前用户的私有数据目录，不能随 issue、截图或发布包上传。

本机服务不提供公开托管或遥测功能。配置云盘时会连接相应服务；Codex 内容分析会将你授权读取的摘录交给所使用的 Codex 服务，不能将“本地面板”理解为模型分析全程离线。

目录、索引、任务记录和文件名本身可能敏感；云端元数据 sidecar 包括恢复所需的原相对路径、ACL 和扩展属性，它与文件内容一样需要合适的云端权限。此项目没有加密保险箱或独立版本备份。详见 [SECURITY.md](SECURITY.md)。

## 测试与开发

```sh
python3.12 scripts/bootstrap.py --update --dev
"$HOME/Documents/Codex/StorageStewardRuntime/venv/bin/python" -m pytest -q
node --check web/app.js
```

测试使用临时目录与人工生成的文件，不需要个人云账号。rclone 测试使用其真实本地后端，以及不打开浏览器的 OAuth 状态检查；缺少 rclone 时相关项会跳过。它们不证明某个真实云账号或设备的往返测试已通过。

可配置 `STORAGE_STEWARD_HOME`（私有状态目录）、`STORAGE_STEWARD_PYTHON`（启动器使用的 Python）、`STORAGE_STEWARD_RCLONE`（rclone 可执行文件）。开发时使用单独的状态目录，避免接触日常目录的索引与计划。

本版内容提取不含 OCR 和完整 Office／照片理解；最后打开时间可能未知。项目、运行环境、应用包、符号链接与云占位文件受保护。大文件传输需要临时本地空间；恢复依赖保存的归档副本及记录。源码审查和自动测试不构成对所有文件系统与网盘的无损保证。

## 复用与许可

复用 [rclone](https://github.com/rclone/rclone) 处理云协议，[官方 MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 处理 MCP，[Codex 插件结构](https://developers.openai.com/plugins/build/plugins) 提供入口，FastAPI／SQLite 提供本机服务和索引。没有集成 restic 或 Czkawka，不将本项目作为完整备份工具。依赖列表见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。

项目代码采用 [MIT License](LICENSE)。欢迎提交只包含合成测试资料的 issue 和 pull request。