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，不格式化磁盘。

Related MCP server: File Manager MCP

快速开始

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

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 应用入口：

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

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

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

Codex 插件与独立 MCP

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

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。

测试与开发

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 处理云协议，官方 MCP Python SDK 处理 MCP，Codex 插件结构 提供入口，FastAPI／SQLite 提供本机服务和索引。没有集成 restic 或 Czkawka，不将本项目作为完整备份工具。依赖列表见 THIRD_PARTY_NOTICES.md。

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