🛡️ SpaceSentinel

智能释放空间，守护每一寸磁盘 | Smart disk cleanup for every device

🌐 在线体验 / Live Demo: https://spacesentinel.vercel.app

中文 | English

中文

🚀 30 秒上手（Windows 清理）

1. 下载 CleanMyPC.zip 并解压
2. 双击 run.bat —— 自动扫描并清理 13 类系统垃圾（右键"以管理员身份运行"解锁全部项）
3. 查看"本次共释放"报告，按回车退出。完成！

只想看看能清多少？命令行运行 run.bat -ScanOnly，只统计不删除。

SpaceSentinel 包含两个互补的交付物：

1. 多语言清理向导网站（纯静态，零后端）—— 引导 Windows / Mac / iOS / Android 用户安全释放磁盘空间，并提供浏览器本地图片压缩。
2. CleanMyPC 一键清理工具（Windows）—— 双击即自动扫描并清理白名单垃圾，真正释放磁盘空间。

✨ 网站功能

• 🌍 7 语种自由切换：中文 / English / Français / Deutsch / Español / 日本語 / 한국어（自动检测浏览器语言，localStorage 记忆选择）
• 📱 全设备适配：桌面 / 手机 / 平板响应式布局
• 🧭 分设备清理指引：Windows、Mac、iOS、Android 各 4 步安全清理步骤
• 🖼️ 图片在线瘦身：Canvas 本地压缩，质量可调，文件不离开设备、不上传任何服务器
• ⬇️ Windows 一键工具下载：选择 Windows 后可直接下载 CleanMyPC
• 💎 玻璃拟态 UI + 雷达扫描动效

诚实原则：扫描动画明确标注为引导演示——网页无法访问访问者的文件，真实清理由本地开源工具或用户按指引亲手完成。绝不显示虚构的"已释放 XX GB"。

🧹 CleanMyPC 一键清理工具

使用：下载 CleanMyPC.zip（或直接用仓库 tools/ 目录），解压后双击 run.bat 即自动完成扫描 → 清理 → 释放量报告。右键"以管理员身份运行"可解锁全部 13 项。

run.bat            # 双击：自动全量清理
run.bat -ScanOnly  # 只扫描统计，不删除任何文件
run.bat -Deep      # 清理后额外运行 DISM 压缩 WinSxS 组件存储（需管理员，约 10-20 分钟）

安全白名单（仅清理以下 13 类，绝不触碰文档/桌面/下载/相册）：

安全设计：

• 仅操作白名单路径（TEMP / Windows / LocalAppData 根之下），路径合法性双重防御（拒绝空路径与盘根相对路径）
• junction / 符号链接只删链接本身，绝不递归进目标目录
• 被占用文件自动跳过，不报错不中断
• Pester 单元测试覆盖（含白名单安全测试、删除逃逸防御测试）

🤖 AI 集成（面向 Agent 与开发者）

• 内容 API：/api/guides.json —— 7 语种 × 4 设备的清理步骤，机器可读，AI Agent 可直接引用（由 tools/build-api.js 从语言包生成）
• llms.txt：/llms.txt —— 面向 AI 爬虫与助手的站点导引和事实清单
• MCP Server：spacesentinel-mcp（npm v0.1.4，已收录 MCP 官方注册表：io.github.SheldonZhuang/spacesentinel-mcp）—— 让 Claude Desktop 等 Agent 对话式扫描/清理本机，新增 analyze_disk 磁盘归属分析（只读证据采集，AI 推理，用户决策）。配置："command": "npx", "args": ["-y", "spacesentinel-mcp"]，详见 mcp/README.md
• Claude Skill：skills/disk-cleanup —— 拷贝到 ~/.claude/skills/ 即可让 Claude Code 掌握清理决策流
• GPTs Action：api/openapi.json + 配置指南 —— 5 分钟接入 ChatGPT
• SEO 指引页：/guides —— 4 设备 × 7 语种共 28 个静态页（hreflang + HowTo 结构化数据）
• 长尾问答页：/qa —— 6 个高频磁盘问题 × 中英双语共 12 页（FAQ 结构化数据，内容源 tools/qa-content.js，全部来自真实案例、零恐吓话术）
• 路线图：Claude Skill、SEO 内容页等，详见 docs/ai-roadmap.md

❤️ 支持项目 / Support

如果这个项目帮你释放了磁盘空间，欢迎请作者喝杯咖啡：GitHub Sponsors · Buy Me a Coffee。开源免费，永不捆绑。

If SpaceSentinel freed up your disk, consider buying the author a coffee — free & open source forever, no bundleware.

⚙️ 自动部署

push 到 main 分支即自动生产部署（Vercel Git 集成，仓库单分支工作流）。

🗂️ 项目结构

├── index.html          # 单页四区块：Hero → 设备选择 → 扫描动效 → 指引+压缩
├── css/                # tailwind.css（构建期静态生成）+ style.css（玻璃拟态/雷达动效）
├── js/
│   ├── i18n.js         # i18n 引擎（自动检测 / localStorage 记忆 / 失败兜底）
│   ├── app.js          # 区块状态机 / 扫描动效 / 指引渲染
│   └── compressor.js   # Canvas 本地图片压缩
├── locales/*.json      # 7 语种语言包（43 keys 逐一对齐）
├── api/guides.json     # 机器可读清理指引 API（AI Agent 友好）
├── qa/                 # 长尾问答页（6 题 × 中英，FAQ JSON-LD）
├── llms.txt            # AI 爬虫/助手导引（GEO）
├── downloads/          # CleanMyPC.zip（含使用说明.txt）
├── tools/
│   ├── CleanMyPC.ps1   # 清理脚本（PowerShell 5.1，函数化 + dot-source 守卫）
│   ├── AnalyzeDisk.ps1 # 磁盘归属分析（只读证据采集，MCP analyze_disk 后端）
│   ├── run.bat         # 双击入口（绕过执行策略，透传参数）
│   ├── pack.ps1        # 打包脚本：重新生成 downloads/CleanMyPC.zip
│   ├── build-api.js    # 从语言包生成 api/guides.json
│   ├── build-guides-pages.js # 生成 guides/qa 静态页 + sitemap
│   ├── qa-content.js   # 问答页内容源（中英双语）
│   └── gen-og.ps1      # 生成 og.png / apple-touch-icon.png
├── docs/ai-roadmap.md  # AI 时代战略规划与路线图
├── .github/workflows/  # push main 自动部署 Vercel
└── tests/              # Pester 单元测试

🛠️ 开发

# 本地预览（语言包 fetch 需要 HTTP 服务，file:// 不可用）
npx -y serve -l 3999

# 运行测试（Windows 自带 Pester）
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-Pester -Path tests/CleanMyPC.Tests.ps1"

# 修改 CleanMyPC.ps1 后：重新打包下载分发的 zip
powershell -NoProfile -ExecutionPolicy Bypass -File tools/pack.ps1

# 部署（Vercel）
vercel deploy --prod

English

🚀 30-Second Quick Start (Windows)

1. Download CleanMyPC.zip and unzip
2. Double-click run.bat — automatic scan & cleanup of 13 whitelisted junk categories (right-click "Run as administrator" to unlock all)
3. Check the freed-space report, press Enter. Done!

Scan without deleting: run.bat -ScanOnly

For AI agents & developers: machine-readable cleanup guides at /api/guides.json, site guide for AI assistants at /llms.txt. MCP server & Claude Skill on the roadmap — see docs/ai-roadmap.md.

SpaceSentinel ships two complementary deliverables:

1. A multilingual cleanup guide website (pure static, zero backend) — walks Windows / Mac / iOS / Android users through safely freeing up disk space, plus an in-browser image compressor.
2. CleanMyPC one-click cleanup tool (Windows) — double-click to automatically scan and clean whitelisted junk, actually reclaiming disk space.

✨ Website Features

• 🌍 7 languages: 中文 / English / Français / Deutsch / Español / 日本語 / 한국어 (auto-detected, remembered via localStorage)
• 📱 Responsive across desktop / phone / tablet
• 🧭 Per-device cleanup guides: 4 safe steps each for Windows, Mac, iOS, Android
• 🖼️ Image slimming: Canvas-based local compression with adjustable quality — files never leave your device
• ⬇️ One-click tool download for Windows users
• 💎 Glassmorphism UI + radar scan animation

Honesty principle: the scan animation is clearly labeled as a guided demo — web pages cannot access visitors' files. Real cleanup is done by the local open-source tool or by the user following the guide. No fake "XX GB freed" numbers, ever.

🧹 CleanMyPC

Usage: download CleanMyPC.zip (or use tools/ in this repo), unzip, double-click run.bat — it scans, cleans, and reports freed space automatically. Run as Administrator to unlock all 13 targets.

run.bat            # double-click: automatic full cleanup
run.bat -ScanOnly  # scan & report only, deletes nothing
run.bat -Deep      # additionally compress the WinSxS component store via DISM (admin, ~10-20 min)

Safety whitelist — only these 13 categories are ever touched (never Documents / Desktop / Downloads / Photos): user temp, system temp (admin), Recycle Bin (all drives), Windows Update cache (admin), thumbnail cache, Chrome / Edge caches, npm / pip caches, legacy Roaming npm cache, installer cache (SquirrelTemp), app crash dumps, system crash dumps (admin).

Safety design: whitelist-rooted paths with input hardening (rejects empty and drive-root-relative paths), reparse points (junctions/symlinks) deleted link-only without recursing into targets, in-use files skipped silently, covered by Pester unit tests including deletion-escape defenses.

🛠️ Development

npx -y serve -l 3999          # local preview (locales fetch requires HTTP)
powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-Pester -Path tests/CleanMyPC.Tests.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File tools/pack.ps1   # repack zip after editing CleanMyPC.ps1
vercel deploy --prod          # deploy

Tech Stack: HTML5 · Tailwind CSS (CDN) · Vanilla JS (ES6+) · PowerShell 5.1 · Pester · Vercel