Skip to content

sukichen1101-eng/cold-project-archiver

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

3 Commits
.github
.github
 
 
scripts
scripts
 
 
.gitignore
.gitignore
 
 
CONTRIBUTING.md
CONTRIBUTING.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
SKILL.md
SKILL.md
 
 

Repository files navigation

Cold Project Archiver / 冷项目归档器

English · 中文

A Claude Skill (and standalone CLI) that finds long-untouched projects, backs them up to a Chinese cloud drive, verifies the upload file-by-file, and only then helps you delete the local copies to reclaim disk space.

一个 Claude 技能 （同时也是独立 CLI 工具）：按修改日期找出长期没碰的「冷项目」，备份到百度网盘 / 阿里云盘， 逐文件校验上传完整性，确认无误后才协助删除本地副本、腾出磁盘空间。

English

Why

Dragging folders into the Baidu/Aliyun desktop client looks like it works, but it silently skips files, chokes on emoji filenames, and never tells you what was missed. This tool uses the community CLI tools with an rsync-style skip-existing policy so uploads are resumable and verifiable — you get a clean "every file is present remotely" signal before anything local is deleted.

Demo

$ python scripts/scan_cold.py ~/Desktop --days 90 --json ~/backup_manifests/cold.json
Scanning: /Users/you/Desktop
Cold threshold: >= 90 days since last file change

NAME                                    NEWEST  AGE(d)     SIZE  FILES  FLAG
------------------------------------------------------------------------------------
OldRobotArm                         2025-08-12     200    1.2G    482  COLD
EMG-dataset                         2025-09-01     180    7.0G   9439  COLD
current-webapp                      2026-05-30       1   120M    315  active
------------------------------------------------------------------------------------
Cold candidates: 2 folders, 8.2G total
Cold-candidate list written to: /Users/you/backup_manifests/cold.json

$ python scripts/preflight.py ~/Desktop --dry-run
[DRY-RUN] preflight on /Users/you/Desktop
== Baidu temp files: 3 ==
  del EMG-dataset/.foo.baiduyun.uploading.cfg
== Illegal/emoji renames: 2 ==
  🚀 启动说明.md  ->  启动说明.md
  report:v1.md   ->  reportv1.md
(DRY-RUN) Re-run with --apply to perform the changes above.

$ python scripts/upload.py --backend baidu --remote /Backup --base ~/Desktop \
    --names OldRobotArm EMG-dataset --low-mem
>>> uploading: OldRobotArm
<<< done: OldRobotArm (reported failures: 0)
>>> uploading: EMG-dataset
<<< done: EMG-dataset (reported failures: 2)
  ! retrying 2 files... resolved.

=== SUMMARY ===
All folders uploaded and verified. 0 unresolved failures.

$ python scripts/verify.py --backend baidu --remote /Backup --base ~/Desktop \
    --names OldRobotArm EMG-dataset
>>> verifying: OldRobotArm
    filled-in: 0, reported failures: 0
>>> verifying: EMG-dataset
    filled-in: 0, reported failures: 0
=== VERIFY SUMMARY ===
VERIFIED COMPLETE. Every file present on remote.
It is now safe to delete these folders locally.

Want real screenshots? Run the steps and drop the images into a docs/ folder, then reference them here. PRs with screenshots welcome.

Supported backends

Backend CLI tool Login Notes
Baidu Netdisk (百度网盘) BaiduPCS-Go BDUSS + STOKEN cookies non-VIP upload is rate-limited
Aliyun Drive (阿里云盘) aliyunpan QR / refresh token generally faster uploads

Install

brew install baidupcs-go   # or: brew install aliyunpan

If brew install fails to compile (it builds from Go source; go.dev downloads can be flaky), grab the prebuilt binary from the tool's GitHub Releases, then:

chmod +x ./BaiduPCS-Go
xattr -d com.apple.quarantine ./BaiduPCS-Go   # macOS Gatekeeper

Requires Python 3.8+ (standard library only — no pip dependencies). The scripts find the CLI binary via PATH, or you can point to it with the BAIDUPCS_GO_BIN / ALIYUNPAN_BIN environment variables.

Use as a Claude Skill

Place this folder where your Claude client discovers skills, then just ask:

"Find projects on my Desktop I haven't touched in 3 months and back them up to Baidu Netdisk, then free up the space."

Claude reads SKILL.md and drives the workflow, pausing for your confirmation at the human-in-the-loop gates (which folders to archive; final go-ahead to delete).

Use as a standalone CLI

# 1. Scan for cold projects
python scripts/scan_cold.py ~/Desktop --days 90 --json ~/backup_manifests/cold.json
# 2. Review the table, decide what to archive
# 3. Preflight cleanup — DRY RUN first, then apply
python scripts/preflight.py ~/Desktop --dry-run
python scripts/preflight.py ~/Desktop --apply
# 4. Record local manifests (survive deletion as proof-of-completeness)
python scripts/manifest.py ~/Desktop --out ~/backup_manifests --names ProjA ProjB
# 5. Login (Baidu needs BOTH cookies)
BaiduPCS-Go login -bduss=<BDUSS> -stoken=<STOKEN>
# 6. Upload + auto-retry (low-mem recommended for big folders / <8GB RAM)
python scripts/upload.py --backend baidu --remote /Backup --base ~/Desktop \
  --names ProjA ProjB --low-mem
# 7. Independent verify pass — must be clean before deleting
python scripts/verify.py --backend baidu --remote /Backup --base ~/Desktop \
  --names ProjA ProjB
# 8. Only after verify is clean and you've eyeballed the remote listing,
#    delete local copies (prefer Trash).

Safety model

  • No deletion until verified. verify.py re-runs a skip-existing pass; only a clean result unlocks deletion.
  • Manifests kept outside the archived folders so they survive deletion.
  • Resumable. A killed upload is harmless — re-run and it fills only the gaps.
  • Credentials stay local. Login cookies live in the CLI tool's own config; the scripts never transmit or print them.

Gotchas this tool handles for you

  • Emoji / \ / : * ? " < > | in filenames (Baidu rejects them) → preflight.py renames
  • Baidu STOKEN required for uploading new files → login guidance in SKILL.md
  • Big folders OOM-killed at default concurrency → --low-mem per-folder uploads
  • File-count mismatches from empty dirs / .DS_Store / pagination → trust the rsync verify, not counts
  • Leftover .baiduyun.uploading.cfg turds → cleaned by preflight.py

Scripts

Script Role
scan_cold.py Detect cold folders by newest inner-file mtime
preflight.py Fix illegal filenames; optionally strip caches/dup archives
manifest.py Write per-folder file lists (proof of completeness)
upload.py Upload + per-file retry, resumable
verify.py Independent skip-existing pass; gates deletion
backend.py Thin wrapper over BaiduPCS-Go / aliyunpan

Disclaimer

Uses third-party, community-maintained CLI tools. You are responsible for your own account credentials and data. Always verify before deleting. Netdisk deletions go to the provider's recycle bin (recoverable for a limited time).

License

MIT — see LICENSE.

中文

为什么做这个

直接把文件夹拖进百度 / 阿里云盘的桌面客户端，看起来传完了，其实会悄悄漏传文件、 遇到 emoji 文件名就卡住，而且从不告诉你漏了哪些。本工具改用社区命令行工具，配合 rsync 式「跳过已存在」策略，让上传可断点续传、可校验——在删除任何本地文件之前， 你会得到一个明确的「每个文件都已在网盘」的信号。

演示

$ python scripts/scan_cold.py ~/Desktop --days 90 --json ~/backup_manifests/cold.json
Scanning: /Users/you/Desktop
Cold threshold: >= 90 days since last file change

NAME                                    NEWEST  AGE(d)     SIZE  FILES  FLAG
------------------------------------------------------------------------------------
OldRobotArm                         2025-08-12     200    1.2G    482  COLD
EMG-dataset                         2025-09-01     180    7.0G   9439  COLD
current-webapp                      2026-05-30       1   120M    315  active
------------------------------------------------------------------------------------
Cold candidates: 2 folders, 8.2G total

# 预处理（先 dry-run 预览，再 --apply）→ 上传 → 校验 → 确认后才删本地
$ python scripts/verify.py --backend baidu --remote /Backup --base ~/Desktop \
    --names OldRobotArm EMG-dataset
=== VERIFY SUMMARY ===
VERIFIED COMPLETE. Every file present on remote.
现在可以安全删除这些文件夹的本地副本了。

想要真实截图？跑一遍上面的步骤，把图片放进 docs/ 目录再引用进来。 欢迎提交带截图的 PR。

支持的网盘

网盘 命令行工具 登录方式 说明
百度网盘 BaiduPCS-Go BDUSS + STOKEN cookie 非会员上传限速
阿里云盘 aliyunpan 扫码 / refresh token 上传通常更快

安装

brew install baidupcs-go   # 或：brew install aliyunpan

如果 brew install 编译失败（它从 Go 源码编译，go.dev 下载有时不稳），改从对应工具的 GitHub Releases 下载预编译二进制，然后：

chmod +x ./BaiduPCS-Go
xattr -d com.apple.quarantine ./BaiduPCS-Go   # macOS 去除隔离属性

需要 Python 3.8+（纯标准库，无需 pip 安装依赖）。脚本会通过 PATH 自动找到命令行工具， 也可以用环境变量 BAIDUPCS_GO_BIN / ALIYUNPAN_BIN 指定路径。

作为 Claude 技能使用

把本文件夹放到 Claude 客户端能识别技能的位置，然后直接说：

「找出我桌面上三个月没碰过的项目，备份到百度网盘，然后腾出空间。」

Claude 会读取 SKILL.md 自动驱动整个流程，并在关键节点（选哪些文件夹归档、最终是否删除） 停下来等你确认。

作为独立 CLI 使用

# 1. 扫描冷项目（按文件夹内最新文件的修改时间）
python scripts/scan_cold.py ~/Desktop --days 90 --json ~/backup_manifests/cold.json
# 2. 看表格，决定要归档哪些
# 3. 预处理清理——务必先 dry-run，再 apply
python scripts/preflight.py ~/Desktop --dry-run
python scripts/preflight.py ~/Desktop --apply
# 4. 生成本地清单（删除后仍可作为完整性凭证）
python scripts/manifest.py ~/Desktop --out ~/backup_manifests --names 项目A 项目B
# 5. 登录（百度需要 BDUSS 和 STOKEN 两个 cookie）
BaiduPCS-Go login -bduss=<BDUSS> -stoken=<STOKEN>
# 6. 上传 + 自动重试（大文件夹 / 内存<8GB 建议加 --low-mem）
python scripts/upload.py --backend baidu --remote /Backup --base ~/Desktop \
  --names 项目A 项目B --low-mem
# 7. 独立校验——必须干净才能删
python scripts/verify.py --backend baidu --remote /Backup --base ~/Desktop \
  --names 项目A 项目B
# 8. 只有校验通过、并亲眼核对网盘列表后，才删除本地副本（建议先进废纸篓）

安全设计

  • 没校验完绝不删。 verify.py 重跑一遍「跳过已存在」校验，只有结果干净才解锁删除。
  • 清单存在归档文件夹之外，删除后依然保留，可作为完整性凭证。
  • 可断点续传。 上传中途被杀也没关系——重跑只补缺的部分。
  • 凭证只留本地。 登录 cookie 存在命令行工具自己的配置里，脚本从不传输或打印它们。

这个工具帮你避开的坑

  • 文件名含 emoji / \ / : * ? " < > |（百度会拒绝）→ preflight.py 自动改名
  • 百度上传新文件必需 STOKEN → SKILL.md 里有取凭证的指引
  • 大文件夹默认并发会被系统因内存杀掉 → --low-mem 逐文件夹上传
  • 空目录 / .DS_Store / 分页导致文件数对不上 → 信 rsync 校验，别数文件数
  • 残留的 .baiduyun.uploading.cfg 垃圾文件 → preflight.py 清理

脚本一览

脚本 作用
scan_cold.py 按文件夹内最新文件修改时间检测冷项目
preflight.py 修复非法文件名；可选清理缓存 / 重复压缩包
manifest.py 生成每个文件夹的文件清单（完整性凭证）
upload.py 上传 + 逐文件重试，可续传
verify.py 独立的跳过已存在校验；作为删除前置闸门
backend.py BaiduPCS-Go / aliyunpan 的薄封装

免责声明

本工具依赖第三方社区维护的命令行工具。你需对自己的账号凭证和数据负责。删除前务必先校验。 网盘删除会进入对应平台的回收站（一段时间内可找回）。

许可证

MIT —— 见 LICENSE。

About

Claude Skill + CLI: find long-untouched projects, back them up to Baidu/Aliyun netdisk with file-by-file verification, then reclaim local disk space.

Topics

python cli backup archiver disk-cleanup baidupcs-go baidu-netdisk aliyunpan aliyun-drive claude-skill

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages