deepclean-mydisk 0.0.0-stage → 0.12.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 huangxiaoliang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# deepclean-mydisk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH 插件：macOS / Windows 原生侧边栏磁盘工具。**扫描只读，清理只移动**——文件先移入废纸篓（macOS）或隔离区（Windows），可撤销；永久删除必须二次确认，且只限本插件移入的批次。提供实时容量、空间可视化、相似照片、跨盘移动、恢复中心，以及只读的 AI 体检解读、条目解释、清理前复核与失败诊断。
+
+DeepClean MyDisk is a DSH plugin for macOS and Windows. It audits disk usage read-only, then moves the files you select to the Trash or a quarantine folder with undo. Cleanup is two-stage: moving files does not free space until you permanently delete a batch after a second confirmation.
+
+- 仓库：[huangxiaoliang/deepclean-mydisk-plugin](https://github.com/huangxiaoliang/deepclean-mydisk-plugin)
+- 安装：`dsh plugin --profile <name> add deepclean-mydisk`（npm）；也可 `add github:huangxiaoliang/deepclean-mydisk-plugin` 或本地 `link:/绝对路径`
+- 反馈：[GitHub Issues](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/issues/new/choose) · 安全问题按 [SECURITY.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/SECURITY.md) 私下发邮件
+- 插件详情：[中文](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/docs/plugin/DETAIL.zh.md) · [English](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/docs/plugin/DETAIL.en.md) · [更新日志](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/CHANGELOG.md)
+
+## 安装
+
+### DSH 安装
+
+```bash
+# 从 npm 安装（推荐；预构建，无构建步骤）
+dsh plugin --profile <name> add deepclean-mydisk
+
+# 或从 GitHub 安装
+dsh plugin --profile <name> add github:huangxiaoliang/deepclean-mydisk-plugin
+
+# 或在本地开发目录安装（改动即时映射）
+dsh plugin --profile <name> add link:/绝对路径/deepclean-mydisk-plugin
+```
+
+安装或修改 host / client 代码后**需要重启 DSH**。
+
+### 平台依赖
+
+- macOS：系统自带 `python3`（扫描器依赖 `du` / `plutil` / `sips`）；
+- Windows：`py -3`（或 `python`），扫描器与照片解码为纯 Python + PowerShell `.NET`，**不需要 Pillow**；
+- 支持 macOS / Windows；Linux 宿主有分支但**未验收**。
+
+### 权限
+
+- macOS 需要「完全磁盘访问」才能读到全部受保护路径；设置页「权限检查」可查看状态，未授权时不会进行任何扫描；
+- Windows 无「完全磁盘访问」概念，只报告当前是管理员还是普通用户；清理部分系统目录需要管理员权限。
+
+## 界面结构
+
+| 入口 | 内容 |
+|---|---|
+| 体检（首页） | 实时容量、开始体检 / 查看清理建议、AI 解读、扫描选项、体检向导、最近一次整理 |
+| 清理 | 垃圾清理（全部项目 + 7 个内容分类，风险分档、搜索排序、逐项「问 AI」与清理前复核）与相似照片 |
+| 空间 | 目录分布（环形图 + 面包屑 + 下钻）与大文件（筛选 + 移动 + 「这是什么」） |
+| 历史 | 趋势与复清、隔离区/废纸篓占用与永久删除、扫描历史、可恢复批次、AI 趋势分析 |
+| 设置 | 安全说明、中英切换、保护名单、权限检查、环境信息 |
+
+## 功能
+
+### 体检
+
+- 打开面板即显示实时容量，**不需要先跑体检**；首次扫描前「建议处理」显示「—」而不是 0。
+- 支持快速扫描与完整扫描；结果分为**推荐清理 / 可选清理 / 需确认 / 受保护**四档。
+- 体检向导：推荐清单 → 二次确认 → 显示已移出 → 撤销 / 清理历史 / 完成。
+- 扫描失败、结果过期、无数据、无推荐项分别提示，不会把空结果当成功。
+
+### 清理
+
+- 7 个内容分类：开发缓存、浏览器缓存、应用缓存、应用残留、聊天软件缓存、其他缓存、系统缓存。
+- 已卸载残留中的可再生缓存子目录会单独拆出为可清理项，其余数据保持「需确认」；聊天/系统/运行中的 App 不拆。
+- 支持名称/路径搜索、按大小或名称排序、风险筛选、跨分类勾选、三态全选与「选择推荐项」。
+- 受保护与只读项不可勾选，也不计入「预计可释放」；「需确认」项不会被自动勾选。
+- 清理必须二次确认；**移入废纸篓/隔离区不会立即释放空间**，永久删除本批次后才真正释放。
+- 单次超过 200 项时服务端自动分片，每片独立批次、统一撤销；结果超过 10 分钟会过期并禁用清理。
+
+### 空间
+
+- 目录分布以家目录为范围（含隐藏项），环形图与明细表共用分母，长尾归入「其他」；支持下钻、面包屑、显示更多与重新统计。
+- 大文件视图支持全局（完整扫描）与目录联动，可按名称/路径搜索，按大小或未修改天数排序，按修改时间/类型/大小筛选。
+- 明细行可跳到清理页查看该路径的可清理项；移动完成后自动重新统计当前目录。
+
+### 相似照片
+
+- 基于 dHash 指纹分组，扫描 Pictures / Downloads / Desktop / Documents，最多 600 张、最小 200 KB；云盘目录与照片图库会被跳过。
+- 保留策略：最大 / 最新 / 路径最浅；支持文件夹筛选、分组缩略图与并排对比。
+- 批量移入废纸篓，可在历史中撤销。
+
+### 跨盘移动
+
+- 大文件可移动到其他磁盘；目标盘显示可用空间并做容量预检，浏览目标目录只读、**不创建目录**。
+- **云盘文件与 App 数据目录不允许移动**（照片图库、Mail、Messages、应用容器、商店应用数据）。
+- 同盘直接改名；跨盘复制后做 **SHA-256 + 大小**双向校验，失败删除临时文件并保留原文件。
+- 后台任务、逐文件进度与取消；**移动不可撤销，原位置不再保留文件**。
+
+### 历史与恢复
+
+- 扫描历史：时间、可用空间、可回收、耗时。
+- 清理批次：时间、项数、可恢复项数；「恢复此批次」从审计日志把文件移回原位置（跨重启可用）。
+- 永久删除本批次或全部批次需二次确认，只允许本插件移入的条目，拒绝符号链接与隔离区外路径。
+- 审计日志在 `$DSH_HOME/deepclean-audit.log`，历史在 `$DSH_HOME/deepclean-history.json`。
+
+### AI 辅助（只读解释）
+
+- 入口：体检解读、逐项「问 AI / 解释这一项」、清理前「复核这 n 项」、大文件「这是什么」、失败/降级诊断、历史趋势分析。
+- 只把面板已经算好的脱敏数据拼成提示词注入当前 DSH 会话；AI 不参与扫描、分档、允许集合或任何写操作。
+- 插件读不到模型回复，不会根据回答自动勾选或执行；没有可用会话时降级为复制提示词。
+- 提示词与工具输出默认不含完整绝对路径；清理判断仍以面板分档与二次确认为准。
+
+### 保护名单与双语
+
+- 设置页可添加/移除绝对路径；保护名单路径永远不进清理允许集合，子目录同样受保护，宿主会二次校验。
+- 中英双语（中文为源语言）、跟随系统暗色主题、窄窗口适配；无运行时 CDN、无外部字体。
+
+## 安全边界
+
+- 扫描与查询接口只读；清理与移动默认只**移动**，不自动永久删除；永久删除仅限本插件移入的批次，且需二次确认。
+- 只接受最近 **10 分钟**的结果；「需确认」项、运行中的缓存与系统项永不进入清理允许集合。
+- 保护名单、符号链接、云盘文件与 App 数据目录在宿主二次校验，无法通过 UI 绕过。
+- 单批最多 200 项；超过由服务端分片，每片独立批次。
+- 清理、移动、恢复、永久删除都会写入审计日志；重名自动加序号，不覆盖。
+
+## 已知限制
+
+- 云盘保护基于路径与 Windows 云占位属性识别（iCloud Drive / OneDrive / Dropbox / Google Drive）；企业自建网盘或自定义同步目录需通过 `DEEPCLEAN_CLOUD_ROOTS` 补充。
+- Windows 暂未提供 VSS / 回收站占用提示：永久删除后可用空间可能因卷影副本短暂滞后。
+- **Windows 的聊天软件专项分类仅 macOS 提供**；Windows 的应用缓存扫描也尚未实现（报告字段已预留）。
+- Windows 需要管理员权限的目录（如 `C:\Windows\Temp`），非管理员执行时清理会失败。
+- 真实释放估算有 8 秒预算：超大目录可能被截断，最终以清理前后可用空间差为准。
+- Linux 未验收；英文模式下少量扫描器生成的文本仍是中文。
+- 撤销只针对本会话内存中的批次；跨重启恢复请用历史页的「恢复此批次」。
+- 相似照片范围固定为四个目录、最多 600 张、最小 200 KB；HEIC/WebP 等格式受系统解码能力限制，云盘目录与照片图库会被跳过。
+- 残留细粒度拆分只认目录名像缓存的子目录（Caches/tmp/Code Cache/GPUCache/CacheStorage 等）；缓存目录用了别的名字或 App 仍在运行时，整组仍留在「需确认」。
+- AI 入口依赖当前 DSH 会话与模型；没有打开的会话时只能复制提示词，提示词带的是报告摘要而不是完整报告，模型也可能答错。
+- 依赖本机 Python 3（Windows `py -3`）；缺失时扫描与权限检查不可用。
+
+## 反馈与支持
+
+- **Bug / 使用问题 / 功能建议**：请开 [GitHub Issue](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/issues/new/choose)（推荐用问题模板）。
+- **安全问题**（越权删除、路径逃逸、恢复失败、隐私泄露等）：不要公开提 Issue，请发邮件到 **coolway.me@gmail.com**，详见 [SECURITY.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/SECURITY.md)。
+- **提交前**：升级或改过插件后先重启 DSH；权限检查未授权时先授权再重试。
+- **请附上**：插件版本、DSH 版本、系统版本、出问题的功能、错误码/失败阶段、复现步骤、已脱敏的日志或截图。
+- **不要贴**：完整磁盘路径、用户名、文件名、聊天记录或未脱敏的审计日志原文；用 `~/…`、`%LOCALAPPDATA%\…` 代替。
+- 详细支持说明见 [SUPPORT.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/SUPPORT.md)。
+
+## 开发与测试
+
+开发环境、目录结构、常用命令、测试与 CI、HTTP API、隔离预览与扫描器同步见 [CONTRIBUTING.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/CONTRIBUTING.md)；Windows 验收见 [docs/windows-ci.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/docs/windows-ci.md) 与 [docs/windows-acceptance.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/docs/windows-acceptance.md)。
+
+## 许可证
+
+MIT

package/SECURITY.md

@@ -0,0 +1,40 @@
+# Security Policy（安全策略）
+
+## 支持版本
+
+安全修复只针对**最新发布版本**（[Releases](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/releases)）。旧版本如果问题仍然存在，请先升级并确认是否复现。
+
+## 报告安全问题（请勿公开）
+
+**不要**在公开的 GitHub Issue 中披露安全问题。请发邮件到：
+
+**coolway.me@gmail.com**
+
+邮件主题建议：`[deepclean-mydisk security] <一句话摘要>`
+
+请尽量包含：
+
+- 插件版本、DSH 版本、操作系统与架构；
+- 问题类型（越权删除、路径逃逸、恢复失败、允许集合绕过、隐私泄露等）；
+- 影响范围与触发条件；
+- 可复现的最小步骤（路径请用 `~/…` / `%LOCALAPPDATA%\…` 脱敏）；
+- 是否已经公开、是否在真实用户目录上验证过。
+
+通常会在 **3 个工作日内**回复（尽力而为，不是商业 SLA）。确认问题后会尽快发布修复，并在
+Release Notes 中致谢（如需匿名请注明）。请在没有修复前避免公开细节。
+
+## 范围
+
+属于安全问题的例子：
+
+- 清理 / 恢复 / 永久删除超出允许集合，覆盖或丢失用户文件；
+- 符号链接、junction、`..`、大小写或路径归一化绕过 `isProtected` / 允许集合；
+- 恢复或永久删除越出本插件批次目录；
+- 审计日志、报告、AI 提示词或工具输出泄露完整路径、用户名、文件名等隐私信息；
+- 云盘 / App 数据目录保护被绕过，导致同步删除或应用数据损坏；
+- 依赖、构建链或发布产物被篡改。
+
+## 不属于安全问题
+
+扫描误报、UI 文案、性能、兼容性、功能建议等，请走
+[GitHub Issues](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/issues/new/choose)。

package/SUPPORT.md

@@ -0,0 +1,44 @@
+# 支持与反馈
+
+DSH 市场的插件详情页没有内置的反馈按钮；详情页的「主页」和「源代码」都指向本仓库，因此
+**GitHub Issues 是公开的反馈入口**。
+
+## 渠道
+
+| 用途 | 入口 |
+|---|---|
+| Bug、使用问题、功能建议 | [GitHub Issues](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/issues/new/choose)（推荐用问题模板） |
+| 安全 / 敏感数据（越权删除、路径逃逸、隐私泄露） | 邮件 **coolway.me@gmail.com**，不要公开提 Issue，详见 [SECURITY.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/SECURITY.md) |
+| 安装、权限、平台限制 | [README](https://github.com/huangxiaoliang/deepclean-mydisk-plugin#readme) · [插件详情](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/docs/plugin/DETAIL.zh.md) · [Windows 验收](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/docs/windows-acceptance.md) |
+
+中文或 English 都可以；收到后会尽力尽快回复，但这是个人维护的项目，没有商业 SLA。
+
+## 提交前请先自查
+
+以下命令需要在**插件源码目录**运行（npm / DSH 安装版没有 `resources/` 路径，改用面板「设置 → 权限检查」）：
+
+```bash
+python3 resources/scripts/deepclean.py --self-test
+python3 resources/scripts/deepclean.py --check-permissions
+```
+
+- 升级或修改过插件后，**重启 DSH** 再试；
+- 权限检查显示未授权「完全磁盘访问」时，扫描结果会明显偏少，先按面板提示授权；
+- Windows 的已知限制（`appCaches` 未实现、聊天软件专项仅 macOS、部分系统目录需要管理员）见
+  [README 已知限制](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/README.md#已知限制)。
+
+## 提交 Issue 时请附上
+
+- 插件版本（设置页或 `dsh plugin list`）、DSH 版本、操作系统版本；
+- 出问题的功能（体检 / 清理 / 恢复 / 永久删除 / 照片 / 空间 / 搬家 / AI）；
+- 复现步骤、期望结果、实际结果；
+- UI 显示的错误码或失败阶段（如 `eacces`、`exdev`、`notfound`、`symlink`）；
+- 已脱敏的日志片段或截图。
+
+## 日志、报告与隐私
+
+- 审计日志：`$DSH_HOME/deepclean-audit.log`；历史：`$DSH_HOME/deepclean-history.json`；
+- 在源码目录重新生成脱敏报告：`deepclean.py --quick --redact --md report.md --json report.json`；
+- **不要**贴完整磁盘路径、用户名、文件名、聊天记录或未脱敏的审计日志原文；用 `~/…`、
+  `%LOCALAPPDATA%\…` 或只保留错误码 / 大小 / 分类来复现问题；
+- 插件不会自动上传任何扫描结果、日志或文件列表。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-plugin-deepclean —— DSH bundle patch
+# 安装：dsh plugin --profile desktop add link:<本目录绝对路径>
+- insert:
+    - id: deepclean-mydisk
+      name: deepclean-mydisk

package/docs/plugin/DETAIL.en.md

@@ -0,0 +1,65 @@
+# DeepClean MyDisk
+
+DeepClean MyDisk is a DSH plugin for macOS and Windows that audits disk usage without changing anything, then moves the files you select to the Trash or a quarantine folder with undo. It adds a native sidebar panel with five sections: Checkup, Cleanup, Space, History, and Settings.
+
+![Checkup home screen](shot-home.jpg)
+
+## What it does
+
+**Checkup.** The home screen shows live capacity before the first scan. Quick and full scans report recommended, optional, needs-review, and protected tiers with an estimated reclaimable total and a per-item explanation.
+
+**Cleanup.** Seven content categories cover developer, browser, app, chat, system, and other caches, plus uninstalled-app leftovers. Regenerable caches inside uninstalled apps are split out; the rest stays in needs review. Search, sorting, and risk filters are available; chat-app classification is macOS-only.
+
+![Cleanup screen](shot-clean.jpg)
+
+**Space.** A directory breakdown with a ring chart, breadcrumbs, and drill-down covers the home directory, and a large-file view supports size and age filters.
+
+**Similar photos.** dHash fingerprinting groups similar photos across Pictures, Downloads, Desktop, and Documents, up to 600 photos of at least 200 KB. Keep-largest, keep-newest, and keep-shallowest strategies are available.
+
+**Cross-disk moves.** Large files can be copied to another volume and verified with SHA-256 and size before the source is removed. Space is pre-checked and progress can be cancelled.
+
+![Move screen](shot-move.jpg)
+
+**History and restore.** Scan history, cleanup batches, a free-space trend, and quarantine occupancy live in one place. Batches can be restored across restarts while the audit log has them.
+
+**Read-only model tools.** Five tools are exposed: `disk_check_permissions`, `disk_audit`, `disk_report`, `disk_inspect`, and `disk_self_test`. `disk_audit` starts a scan; `disk_report` reads the latest panel report without scanning; `disk_inspect` checks one item by `itemId` or a covered path. None can clean, move, or delete.
+
+**Read-only AI assistance.** You can ask AI to explain a checkup, explain one cleanup item, review a selection before cleanup, identify a large file, diagnose a failure, or analyze history trends. The AI explains only; it cannot select, clean, move, or delete anything. Prompts contain only redacted data the panel already computed, and model output cannot change risk tiers or the allow-set.
+
+## Safety model
+
+Scans are read-only. Cleanup only moves files: on macOS to `~/.Trash`, on Windows to a quarantine folder under `%LOCALAPPDATA%`. A moved batch can be undone from the panel or History. Permanent deletion happens only in the panel, after a second confirmation, and only for batches this plugin moved; it cannot delete arbitrary paths and cannot be undone.
+
+The allow-set is re-checked in the host. Protected paths always win, symbolic links are rejected for cleanup items, move sources, move destinations, and directory browsing, and only results from the last 10 minutes are accepted. Needs-review items, running caches, and system items never enter the allow-set. Cloud-backed files and app data directories are excluded from moves. Batches are capped at 200 items and split by the server.
+
+## Requirements
+
+- macOS: Full Disk Access plus `python3`; the scanner uses built-in tools such as `du`, `plutil`, and `sips`.
+- Windows: `py -3` or `python`, with PowerShell for photo decoding; some system directories need administrator rights.
+- DSH 0.2.x (>=0.2.1-rc.5, <0.3.0). Linux is unverified.
+
+## Install
+
+Install from the DSH plugins page (Discover), or run:
+
+```bash
+dsh plugin add deepclean-mydisk
+```
+
+Add `--profile <name>` for a named profile. This installs the published npm package (prebuilt, no build step); to install from the source repository instead, use `dsh plugin add github:huangxiaoliang/deepclean-mydisk-plugin`. Restart DSH after installing or updating.
+
+## Feedback and support
+
+- Bugs and usage questions: open a [GitHub issue](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/issues/new/choose).
+- Security issues (deleting outside the allow-set, path escapes, failed restores, privacy leaks): do not open a public issue; email **coolway.me@gmail.com** with the version, reproduction and impact.
+- Before filing, restart DSH and include the plugin version, DSH version, OS, error code or failing stage, and redacted logs or screenshots. The audit log lives at `$DSH_HOME/deepclean-audit.log`.
+- Never paste full disk paths, user names, file names or chat content; see [SUPPORT.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/SUPPORT.md) and [SECURITY.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/SECURITY.md).
+
+## Limits
+
+- Windows `appCaches` scanning is not implemented, and chat-app cache classification is macOS-only.
+- Windows is covered by CI acceptance on Windows Server 2022, Server 2025 and Windows 11 Arm64; the manual real-device checklist is in [docs/windows-acceptance.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/docs/windows-acceptance.md).
+- Cross-disk moves are not undoable, and the original location is not kept.
+- Similar-photo scanning is limited to four folders, 600 photos, and a 200 KB minimum; cloud folders and photo libraries are skipped.
+- Permanent deletion is irreversible. Undo applies to moved batches only.
+- Linux is unverified. In English mode, some scanner-generated text is still Chinese.

package/docs/plugin/DETAIL.zh.md

@@ -0,0 +1,65 @@
+# DeepClean MyDisk
+
+DeepClean MyDisk 是 macOS / Windows 上的 DSH 磁盘插件：先做**只读**磁盘体检，再由你选择要清理的文件，把它们移入废纸篓或隔离区，并可撤销。它在 DSH 侧边栏提供五个入口：体检、清理、空间、历史、设置。
+
+![体检首页](shot-home.jpg)
+
+## 功能
+
+**体检。** 首页在第一次扫描前就显示实时容量。快速/完整扫描按「推荐清理 / 可选清理 / 需确认 / 受保护」分档，给出预计可释放合计与逐项说明。
+
+**清理。** 七个内容分类覆盖开发缓存、浏览器缓存、应用缓存、应用残留、聊天软件缓存、系统缓存与其他缓存。已卸载 App 容器里的可再生缓存会单独拆出；其余仍留在「需确认」。支持搜索、排序与风险筛选；聊天软件分类仅 macOS 提供。
+
+![清理页](shot-clean.jpg)
+
+**空间。** 家目录环形图 + 面包屑 + 下钻，另有按大小/修改时间筛选的大文件视图。
+
+**相似照片。** 用 dHash 指纹在图片、下载、桌面、文稿四个目录中分组相似照片（最多 600 张、最小 200 KB），支持保留最大/最新/路径最浅。
+
+**跨盘移动。** 大文件可复制到其他磁盘，复制完成后做 SHA-256 + 大小校验，通过后才移除原文件；写入前检查目标容量，过程可取消。
+
+![移动页](shot-move.jpg)
+
+**历史与恢复。** 扫描历史、清理批次、可用空间趋势、隔离区占用集中在一页。只要审计日志里还有记录，批次可跨重启恢复。
+
+**只读模型工具。** 共 5 个：`disk_check_permissions`、`disk_audit`、`disk_report`、`disk_inspect`、`disk_self_test`。`disk_audit` 会启动一次扫描；`disk_report` 只读面板最近报告、不触发扫描；`disk_inspect` 按 `itemId` 或报告覆盖的路径检查单个条目。它们都不能清理、移动或删除文件。
+
+**AI 辅助（只读）。** 你可以让 AI 解读体检结果、逐项解释清理条目、在清理前复核已勾选集合、判断大文件是什么、诊断失败原因，或分析历史空间趋势。AI 只负责解释，不能勾选、清理、移动或删除；提示词只带面板已经算好的脱敏数据，模型输出也不会改变分档或允许集合。
+
+## 安全模型
+
+扫描只读。清理只移动文件：macOS 移入 `~/.Trash`，Windows 移入 `%LOCALAPPDATA%` 下的隔离区。移入的批次可在面板或历史里撤销。永久删除只在面板中、经过二次确认后发生，且只针对本插件移入的批次；不能删除任意路径，也不能撤销。
+
+允许集合由宿主再次校验：保护名单永远优先；清理项、移动源、移动目标与目录浏览都拒绝符号链接；只接受最近 10 分钟的扫描结果。「需确认」项、运行中的缓存与系统项永不进入允许集合。云盘文件与 App 数据目录不参与移动。单批最多 200 项，超过由服务端分片。
+
+## 环境要求
+
+- macOS：需要「完全磁盘访问」与 `python3`；扫描器使用系统自带的 `du`、`plutil`、`sips` 等工具。
+- Windows：需要 `py -3` 或 `python`；照片解码使用 PowerShell；部分系统目录需要管理员权限。
+- DSH 0.2.x（≥0.2.1-rc.5，<0.3.0）。Linux 未验收。
+
+## 安装
+
+在 DSH 的「插件 → 发现」里安装，或运行：
+
+```bash
+dsh plugin add deepclean-mydisk
+```
+
+命名 profile 用 `--profile <name>`。这里装的是已发布的 npm 包（预构建，无构建步骤）；想从源码仓库安装可用 `dsh plugin add github:huangxiaoliang/deepclean-mydisk-plugin`。安装或更新后需要重启 DSH。
+
+## 反馈与支持
+
+- 遇到 Bug 或有使用问题，请开 [GitHub Issue](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/issues/new/choose)。
+- 安全问题（越权删除、路径逃逸、恢复失败、隐私泄露等）请勿公开，发邮件到 **coolway.me@gmail.com**，说明版本、复现与影响。
+- 提交前请先重启 DSH，并附上插件版本、DSH 版本、系统版本、错误码/失败阶段与已脱敏的日志或截图；审计日志在 `$DSH_HOME/deepclean-audit.log`。
+- 不要贴完整磁盘路径、用户名、文件名或聊天记录；详见仓库的 [SUPPORT.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/SUPPORT.md) 与 [SECURITY.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/SECURITY.md)。
+
+## 已知限制
+
+- Windows 的 `appCaches` 扫描尚未实现；聊天软件专项分类仅 macOS 提供。
+- Windows 已由 CI 在 Windows Server 2022 / Server 2025 / Windows 11 Arm64 三个镜像上自动验收；手动真机清单见 [docs/windows-acceptance.md](https://github.com/huangxiaoliang/deepclean-mydisk-plugin/blob/main/docs/windows-acceptance.md)。
+- 跨盘移动不可撤销，原位置不再保留文件。
+- 相似照片只扫描四个目录、最多 600 张、最小 200 KB；云盘目录与照片图库会被跳过。
+- 永久删除不可撤销；撤销只适用于移入废纸篓/隔离区的批次。
+- Linux 未验收；英文模式下少量扫描器生成的文本仍是中文。