hamster-archiver

<div align="center"> <img src="README.assets/iconC_cropped_1022x1022.png" alt="仓鼠症大结局图标" width="96"> # 仓鼠症大结局 Hamster Archiver ### 收藏的时候很快乐，整理的时候也应该是。 Windows 本地文件整理、媒体建库与可校验批量归档工具。支持可选的本机 CLI / MCP 接入，可由具备本机操作能力的 AI / Agent 调用（实验功能）。    **[下载 Windows 版](https://github.com/CarlosZ16420/hamster-archiver/releases/latest)** · [English](README.en.md) · [反馈问题](https://github.com/CarlosZ16420/hamster-archiver/issues) </div> [快速开始](#快速开始) · [功能介绍](#把整理做顺手也把细节做好) · [实验性 AI 接入](#实验功能) · [常见问题](#常见问题) · [文档与贡献](#文档与贡献) 下载/备份的资源越积越多，硬盘快满了，却一直没整理好？ - 文件夹散落各处，不知道怎么分类，也舍不得随便删。 - 想备份到网盘，又不愿让隐私图片、视频被审核和处理。 - 准备先压缩再上传，却又担心以后只剩一堆看不出内容的压缩包。 **从添加一个资源文件夹开始。** Hamster Archiver 为文件夹和视频建立带封面、预览与目录清单的本地仓库，让你用标签、星级和备注整理收藏；需要备份时，再批量生成压缩包，按需设置密码和分卷，方便自行上传到网盘或保存到其他硬盘。 **资源可以备份到别处，里面有什么、备份放在哪里，仍在本地留下清楚的记录。** [](README.assets/仓库-主目录.png) [](README.assets/大缩略图模式.png) ## 一座资源仓库，两种整理方式 | 这次想做什么 | 你会得到什么 | | --- | --- | | **本地整理：先把电脑里的收藏管起来** | 原文件保持原位，为资源生成预览和清单，在仓库里分类、打标签、写备注。以后需要备份，还能把这些项目继续送去压缩。 | | **打包备份：把资源存储到网盘或其他硬盘** | 批量压缩、完整性验证、登记仓库、记录备份位置；本地仍能看封面、视频抽帧和目录，知道每个压缩包装了什么。 | 打包和仓库登记由应用完成，网盘上传由你或同步工具完成；本地分类通过仓库标签进行管理，不会自动重排磁盘上的文件夹。 已经不压缩入库的目录可以在仓库详情中直接“校对更新”，也可以批量检查。应用在任务真正执行时只扫描一次：仅新增文件会自动合并；修改、删除或旧清单不完整时会先展示逐项变化，让你选择覆盖原项目、新建独立项目或跳过。未变化文件复用已有 MD5 和预览，不重复抽帧；整个过程不会修改、移动或删除原文件。再次拖入同一路径时，也会先引导到校对更新或压缩，而不是静默创建重复项目。 入库自动查重，在提供相似度报告的同时，可以自动跳过已存在内容；大目录也能流畅浏览，并可快速检索整个仓库。 ## 快速开始 适用于 **Windows x64**，提供中英文界面。直接使用请选择 [Releases 发行包](https://github.com/CarlosZ16420/hamster-archiver/releases/latest)；GitHub 的 Source code 和克隆仓库用于源码开发。 1. 下载 **Setup EXE 安装版**，或完整解压 **ZIP 便携版**后运行 `HamsterArchiver.exe`。 2. 在“归档工作台”扫描目录，或拖入文件夹、视频，查看待处理内容。第一次可以先添加一个小文件夹。 3. 想先做**本地整理**，点击“不压缩直接入库”；准备**打包备份**，在“收纳设置”中填写“压缩包保存在”，点击“开始压缩入库”。完成后到“仓库”浏览和整理。 压缩和视频预览所需工具已随发行包提供，无需另装 Node.js。 便携版完整目录为 `HamsterArchiver-v4.6.18-win-x64/`，请保留随附文件。 [](README.assets/归档工作台-主目录.png) ### 面向现代本机工作流 除桌面界面外，Hamster Archiver 还提供可选的 CLI / MCP 自动化入口，便于脚本和具备本机工具能力的 AI / Agent 调用。该能力目前作为实验功能提供，不影响默认的本地桌面使用。 ## 备份到别处，内容仍然看得见 每个项目都保留图片缩略图、视频抽帧和完整目录结构。你可以为它选封面、记下解压密码和备份位置；即使暂时不打开压缩包，也能浏览归档的内容。 [](README.assets/项目详情.png) ## 把整理做顺手，也把细节做好 ### 文件安全：先核验，再处理原文件 压缩入库按 **生成清单 → 压缩 → 完整性验证 → 登记仓库 → 按设置处理原文件** 的顺序执行。磁盘不足、异常体积等情况会停止或要求确认，验证与登记成功后才执行原文件后处理。 <details> <summary>展开：为文件保全和异常恢复做了哪些工作？</summary> - 压缩前生成清单并复核源文件；跨盘移动先复制、核验，再处理源位置。 - 归档成品在移动与清理前复核文件身份，避免误处理被同名替换的文件；分卷成品按整组处理。 - 仓库写入失败时保留已生成成品供恢复；缩略图阶段取消任务时保留源文件，并清理未提交生成物。 - 区分“源文件操作失败”和“操作已完成但状态保存失败”，把恢复线索写入诊断信息。 - 追踪原文件位置与处理状态；符合条件时，可将已移动或已回收的原文件复原。 - 数据位置失效时明确提示；安全切换数据位置时保留原目录，避免无声打开空仓库。 </details> ### 便于整理：看预览，分好类，记清楚 用封面浏览收藏，用标签、星级和备注建立自己的分类习惯。标题、标签、备注、路径和文件名都能搜索，备份位置也可以批量记录。 <details> <summary>展开：整理工具与轻快浏览的细节</summary> - 大缩略图与文本列表满足不同浏览习惯；支持键盘翻页、批量追加标签、修改备份位置，以及支持操作的撤回；本次运行中误删的仓库条目及其 Windows 回收站文件也可直接撤回，相似关系会一并恢复。 - 标签自动补全复用已有分类，可用 Tab 接受建议；选中项目时原位更新状态，减少闪烁和页面跳动。 - 同一视频的多帧预览成组展示，竖屏画面完整保留；封面可更换，也可手动添加或粘贴补充图片。 - 大项目详情按需读取，媒体靠近可见区域才加载，同时限制图片读取数量；目录使用虚拟列表，减少无效渲染。 - 列表与缩略图均支持框选、Ctrl 反选及 Shift 范围选择，可直接清空跨页选择。“仓库工具”可按偏好隐藏“未压缩”标签；向下浏览后可一键返回搜索与批量操作栏。 - 仓库保存缩略图而非再复制一整套原始媒体，预览数量可调。 - 提供五套主题与中英文界面，持续完善深色菜单、文字对比度和动态提示。 </details> ### 相似资源：给出依据，让你决定 **名称相似、文件内容一致、整个项目重复，分开显示。** 符合完整重复规则时可按设置自动跳过；只是相似的资源保留确认机会，避免因为一个公共词就替你作决定。 <details> <summary>展开：怎样减少误报，又控制检查成本？</summary> - 名称相似只标出实际匹配片段；点击红色词语，可确认加入排除词表，减少这类词造成的干扰。内容一致证据用金色区别显示。 - 相似判断降低短标题、数字编号和公共词的干扰；支持调整强度，手动解除的关系在后续重算时仍保持排除。 - 先用索引缩小候选，再按需核验内容；候选排除后停止多余读取，报告复用已有证据，避免逐文件遍历整个仓库。 - 同一原始位置且完整目录、文件路径、数量和大小快照都一致时，可走快捷重复判断；不满足条件时继续内容核验，不能只靠同名或同大小自动跳过。 - 大文件夹“卡顿规避”限制普通相似分析的代表文件数量，并可跳过极小文件的普通 MD5 记录；完整目录清单和归档内容仍覆盖全部文件。 - 调整相似强度不会擅自启动全库重算；单项或全库重算由你选择。 </details> ### 打包方式：按你的备份习惯来 支持 7z/ZIP、密码和自定义分卷；资源多时可以批量排队、暂停或定时运行。压缩、视频抽帧和缩略图数量都可调整。 <details> <summary>展开：压缩、密码记录与批量任务</summary> - 压缩等级 0—9，主动分卷大小可设为 64 MiB—10 GiB；工具随发行包提供。 - 可设置压缩密码，并按项目记录解压密码；记录默认遮盖，主动显示后可查看或复制。密码记录随本地用户数据保存，应一并妥善保管。 - 队列支持暂停、完成当前项后暂停、定时运行和剩余时间估算；桌面运行期间还能继续添加下一轮资源。 - 视频抽帧数与单项目缩略图上限可自定义，设置随任务保存。 - 密码保护不等于网盘保管承诺；软件不保证第三方平台永不审核或删除文件。 </details> ## 实验功能 ### AI / Agent 接入（CLI · MCP · 自动发现预览） Hamster Archiver 持续跟进本机 AI / Agent 工作流，并提供实验性的本地接入能力。启用后，支持本机命令或 MCP 的 AI 助手可以查询仓库、添加标签，以及提交不压缩入库或压缩归档任务。 AI 接入默认关闭，不影响普通桌面使用。推荐使用 Setup EXE 安装版，因为它提供稳定的程序位置、升级和卸载生命周期；ZIP 便携版仍可手动使用 CLI / MCP。 在 **更多设置 → 实验功能 → AI 助手接入** 中，可以按需启用 Codex / ChatGPT Desktop、Codex MCP、WorkBuddy、通用 MCP，以及受支持 Windows 上的 ODR 自动发现预览。每种接入都可以单独关闭。 日常使用只需要直接说目标，例如：“请用 Hamster Archiver 把 `D:\Downloads\示例目录` 不压缩入库并保留原文件。”应用负责输入校验、排队、归档验证和结果保存；只有真实缺少输入、需要确认或发生错误时，AI 才需要进一步处理。 > 这是实验功能。AI 客户端会看到工具返回的路径、标题、标签、备注等元数据；Hamster Archiver 本身不会把媒体文件上传到在线模型。具体可用性取决于所使用的 AI 客户端、操作系统和权限设置。 [AI 快速上手](docs/AI-QUICKSTART.md) · [CLI 参考](docs/CLI.md) · [MCP 参考](docs/MCP.md) · [排错](docs/AI-TROUBLESHOOTING.md) ## 常见问题 <details> <summary>硬盘快满了，打包后就能腾出空间吗？</summary> 打包用于组织和备份资源，不代表视频、图片一定能大幅缩小。生成成品还需要可用磁盘空间，请选择空间充足的其他硬盘作为输出位置。 需要先确认成品已在目标位置妥善保存，再决定如何处理本地文件；仍在本机保留成品或回收站文件会继续占用空间。应用的归档后处理发生在本地核验与登记完成之后，**不会等待或核实网盘上传**。计划上传后再清理的资源，请先保留原文件，自行确认备份结果。 </details> <details> <summary>资源和仓库数据保存在哪里？</summary> 本地整理时原文件保持原位，仓库保存索引和缩略图；打包备份的成品放在你指定的位置。便携版默认使用程序旁的 `userdata`，安装版使用 Windows 用户数据目录。“更多设置”提供安全切换入口。 应用自身不上传资源，网盘上传由你或同步工具完成；检查和下载更新会访问 GitHub。接入 AI 时，返回的元数据会进入所选客户端的上下文。 </details> <details> <summary>关闭应用后还能查看运行日志吗？</summary> 可以。运行日志保存在当前用户数据区的 `logs/app.log`，关闭应用不会清空；下次启动会在界面中恢复最近 300 条有效记录。日志包含任务处理、设置字段变化、用户数据区切换、更新操作和关键错误，但不记录密码内容，也不记录普通搜索、浏览或复制动作。 </details> <details> <summary>老用户如何更新？仓库导出是否包含原文件？</summary> 在“检查更新”中查看新版说明并更新。网络不便时，先下载新版发行文件，再选择“手动更新”：便携版选择 ZIP，安装版选择 Setup EXE。 旧版本没有可用更新入口时，可先导出仓库，再在新程序中“并入外部仓库”；核对记录和缩略图后再处理旧目录。**仓库导出保存索引和缩略图，不等于备份原文件或归档成品**，它们仍需单独保管。 </details> ## 文档与贡献 | 你需要什么 | 入口 | | --- | --- | | 下载安装、查看已发布版本 | [Releases](https://github.com/CarlosZ16420/hamster-archiver/releases) | | 实验性 AI / CLI / MCP 接入 | [AI 快速上手](docs/AI-QUICKSTART.md) · [CLI 参考](docs/CLI.md) · [MCP 参考](docs/MCP.md) · [排错](docs/AI-TROUBLESHOOTING.md) | | 了解功能变化 | [更新日志](CHANGELOG.md)（`Unreleased` 为待发布改动） | | 报告 Bug 或建议功能 | [Issues](https://github.com/CarlosZ16420/hamster-archiver/issues)，请附版本号、操作步骤和错误信息，隐去私人路径及密码 | | 修改源码或参与文档 | [贡献指南](CONTRIBUTING.md) · [开发指南](docs/DEVELOPMENT.md) | | 报告安全问题、了解许可 | [安全反馈](SECURITY.md) · [MIT License](LICENSE) | 源码开发使用 Windows、Node.js 22.12+（22.x）或 24.x、npm 10.x/11.x。依赖、Electron 运行时与内置工具的准备方式见开发指南。 Hamster Archiver 原本是我为自己整理收藏写的小工具，也希望它能帮你找回整理的乐趣。感谢 7-Zip、FFmpeg、LinuxDo 社区，以及每一位试用和反馈的朋友。如果它对你有帮助，欢迎点个 Star，或分享你的使用建议。