C盘清理

概述

Windows C 盘清理技能。扫描、分析、清理均在本地执行，不读取或上传用户文件；授权走在线验证。核心产出是一份分级报告 + 一个本地交互清理服务。

何时使用

• 用户说「扫描电脑」即自动启动；想清理 C 盘 / 释放系统盘空间
• 用户问「哪些文件可以删」「缓存/垃圾在哪」「微信/QQ/浏览器占用太大」
• 用户要「一键清理」「安全删除缓存」「把大目录迁移到 D 盘」
• 注意：红区（已装应用本体、系统核心）不进报告、不在可清理范围，也不为了「覆盖率」去展示或清理红区。

前置条件

• Python 3.10+（python 或 python3 可用）
• Windows 10/11（绿区纯缓存永久删除·自动重建）
• 管理员权限（可选但强烈建议）：部分系统缓存非管理员读不到。无管理员也能跑，只是系统缓存部分会被标 denied，不影响其余功能。
• 交互清理需要授权码（见下方「许可与等级」）。

目录结构（技能内）

ai-pc-butler/
├── SKILL.md
├── scripts/
│   ├── run.py          # 一键流水线：scan -> analyze -> report
│   ├── scan.py         # 只读扫描 C 盘，JSON 打到 stdout
│   ├── analyze.py      # 分级聚合：绿区 / 迁移
│   ├── migrate.py      # 迁移执行（建立目录联接，Pro）
│   ├── path_rules.py   # 路径分类规则（安全缓存段 / 保留段）
│   ├── build_report.py # analysis.json -> 单文件 HTML 报告
│   ├── server.py       # 本地交互服务：渲染报告 + 一键清理 API
│   ├── license.py      # 授权验签（在线验证）
│   ├── open_report.py  # 取回报告页地址 / 打开报告（第 1 步第 ② 条命令）
│   └── config.json     # 应用名 / 指纹 / 版本 / 渠道
└── assets/
    └── report_template.html  # 报告模板（server 与 build_report 共用）

server.py / build_report.py 通过 脚本目录/../assets/ 解析模板，config.json 从脚本目录读取，并 import 同目录 license / migrate。保持 scripts/ 与 assets/ 的相对位置，不要拆散。

工作流（报告页在 WB 侧边栏 = 操作台，AI 只做引导）

自动触发：用户无论以何种方式调用本技能——在对话框输入「扫描电脑 / 清理C盘 / 释放空间 / 迁移大目录到D盘」，还是点击聊天框左下角「+」按钮选择本技能——都不需要再输入任何触发词。技能被调用后即进入第 1 步扫描流程（扫描为只读操作），用户不必再重复输入触发词。按下面第 1 步的两条命令执行（① 后台 run.py + ② 前台取址）：扫描 / 分析 / 生成报告各环节实时打印进度提示，完成后启动本地交互服务，报告页通过 present 展示在 WB 侧边栏（=操作台，按钮/进度/付款码全在报告页，不弹系统浏览器）。

第 1 步（自动执行）：扫描 → 报告页（操作台）展示在侧边栏

分两条命令，缺一不可：第 ① 条后台跑流水线，第 ② 条前台取回报告页地址。

① 后台启动流水线（必须 run_in_background=true）—— 它要一直挂着保活本地报告服务，几十分钟都不会结束：

cd <skill>/scripts
python run.py        # ← 用 run_in_background 启动
# 或自定义输出目录： python run.py --out /path/to/out

② 前台取回报告页地址（必须前台执行、等它返回）：

cd <skill>/scripts
python open_report.py --print --wait 100

按 ② 的输出分支处理（报告页能不能跳出来，全看这一步）：

铁律·兜底报告不许冒充本次结果（AIPC-RESCUE-HONEST-FIX）：若 ② 的输出里同时出现 RESCUE_SOURCE=<文件> | 数据时间=<时间>，说明这次扫描/分析没跑完，报告用的是更早一次扫描的数据。必须如实告诉用户：「这次扫描没跑完，报告用的是 <数据时间> 那一次的数据，我重新扫一遍给你」，绝不能把它说成"本次扫描结果"。

为什么必须有第 ② 条：run.py 必须后台跑（它不结束），而后台任务的输出在它结束前拿不到 —— 只跑 run.py 等它打印 REPORT_URL，等的是一个几十分钟都不结束的任务，报告页就永远不 present，用户在这一步流失。第 ② 条是秒级返回的前台命令，它从磁盘把地址取回来，前台命令的返回必然被看到，这条链就不会再断。单次 --wait 不超过 110 秒（超过工具的前台等待上限，命令会被转成后台任务，输出又拿不到了）。

扫描期间说明：扫描为只读操作——只读取文件的名称、大小、时间等信息用于统计，不修改、不删除任何文件。文件数量多时首次扫描需要几分钟。

铁律·不许让用户"假等"（AIPC-NO-FAKE-WAIT-FIX）：禁止对用户说「正在后台跑 / 预估需要几分钟 / 跑完报告页会自动打开 / 稍等一下」这一类话——后台任务的输出在它结束前拿不到，没有人去 present，报告页就永远不会出现，用户就是被扔在原地干等。这是本技能最容易犯、也最致命的一步。

正确做法：在同一轮对话里把第 ② 条命令一轮一轮执行下去——拿到 REPORT_PENDING 就再执行一次，直到真的拿到 REPORT_URL 并用 present_files 展示出来为止；拿到 REPORT_URL 之前不允许结束本轮。

需要向用户交代进展时，如实说明当前进行到哪一步（正在扫描 / 正在生成报告 / 报告页还没就绪），并说明你会一直等到报告页打开；不得让用户产生「等一会儿会自动打开」的预期。

run.py 自动完成：完整扫描（一次到位，含绿区 + 全部迁移候选）-> 分级 -> 生成报告 -> 启动本地交互服务。

铁律：REPORT_URL 是唯一权威呈现，禁止在 Agent 沙箱内自验 localhost：第 ② 条命令只要拿到了 REPORT_URL=...，就无条件、立即用 present_files 把它展示到 WB 侧边栏。严禁在 Agent 自己的执行沙箱里用 curl / urllib / 浏览器去"验证"这个 localhost 地址是否可达。用户侧边栏 = 用户本机浏览器，能正常打开该 URL，按钮就能用。只有当第 ② 条命令确实没拿到 REPORT_URL（拿到的是 REPORT_FILE=）→ 才用静态兜底。

执行顺序：

1. 首选 REPORT_URL（唯一正解）：只要第 ② 条命令拿到了 REPORT_URL，立即用 present_files 把它展示到 WB 侧边栏——这就是操作台：完整报告、明细展开、一键清/迁移/解锁按钮、进度条、付款码全在报告页内。报告页已完整呈现，不需要重启服务即可操作。
2. 对话框用一句大白话告诉用户「报告已在右侧打开，可以直接操作」，把用户引导到报告页完成操作
3. 仅当第 ② 条命令拿到的是 REPORT_FILE=（没有 REPORT_URL） → 用 REPORT_FILE 静态展示 + 对话框引导操作（兜底，绝不主动选择这条）
4. 报告打不开时的浏览器兜底（v1.7.65 新增，务必执行）：若侧边栏没能打开报告

（用户说"没反应/打不开/白屏"，或 present 失败），立刻执行兜底命令，用系统浏览器打开：

   python scripts/open_report.py

它会自动读取上次报告地址并调起系统默认浏览器；成功后把地址一并告诉用户。

run.py 内部还有最后一道自动保险：报告页就绪后 90 秒仍无人加载（=侧边栏没打开）会自动用

系统浏览器弹出，用户无需开口。它只是保险，不能替代第 1 步的第 ② 条命令。

第 2 步：报告页即操作台（用户点点点，AI 仅兜底引导）

报告页在侧边栏打开后，用户直接在报告页操作（无需 AI 介入）：

• 解锁/付款：报告页「解锁」按钮 → 弹付款码 → 扫码付 → 自动解锁
• 一键清：报告页「一键清」按钮 → 确认 → 进度条 → 完成提示
• 迁移：报告页「迁移」按钮 → 勾选项 → 确认 → 进度 → 迁移记录
• 激活码：报告页授权弹窗输入，或对话框粘贴 WX-XXXX-XXXX（detect_activation_code 识别）

AI 的角色 = 兜底引导，不重复操作：

• 只在用户主动说「帮我清理/迁移/解锁」时，用 skill_tools 函数代为执行（作为报告页操作的补充）
• 用户粘贴激活码 → 识别 → activate_code → 提示结果
• 不做报告页已经能做的事（避免双通道冲突）

设计原则：

• 报告页 = 唯一的操作台：所有点点点操作都在侧边栏报告页完成，不割裂、不重复
• AI 只做引导和兜底：对话框不承担主要操作
• 不弹系统浏览器：报告页始终在 WB 侧边栏
• 付款秒级：点解锁即出码，付完自动解锁

第 3 步：AI 兜底执行（仅当用户主动要求对话框代为操作）

报告页已能完成全部操作。以下为用户主动说「帮我清理/迁移/解锁」时的兜底路径，用 skill_tools 函数执行，避免与报告页双通道冲突。

解锁（对话框通道）：报告页连接正常时，付款在报告页内完成即可。当报告页提示「连接断了」、或用户点解锁后弹出「复制这句话到对话框」的引导框时，付款必须改在对话框完成 —— 用户会说「帮我解锁基础版 / 帮我解锁高级版 / 帮我补差价升级到高级版」：

1. 先救单，再下单（AIPC-PAY-RECOVER-FIX，这一步务必先做）：调 skill_tools.rescue_orders()。

它会扫描本机全部订单，把「已经付过钱但没解锁」的（含页面报「确认失败」的）当场捞回来。

• 返回 rescued 非空 → 直接告诉用户已解锁，不要再下单、不要再让用户付任何钱
• 返回为空 → 再走下面 1~6 步下单

这一步同时是防重复付款的闸门：用户在报告页可能已经付款成功、只是没解锁，不先查就下单会让他付第二遍。

1. 产品键不要写死（三壳前缀不同）：从 scripts/config.json 的 plans 里取 —— tier=1 的键 = 基础版；tier=2 且名字不含「升级」的键 = 高级版；名字含「升级」的键 = 补差价升级
2. skill_tools.get_pay_qr(该键) 取付款码
3. 把返回的 payment_code 交给 weixinpay 插件拉起支付（code_url 作扫码兜底）
4. skill_tools.poll_paid(order_id) 轮询；钱到位后自动写入本机授权，不要让用户再输入任何码
5. 回复用户「已解锁，回报告页就能用了」

激活码直达：用户粘贴激活码或说「激活这个码」→ detect_activation_code(text) → activate_code → 提示结果

这条通道完全不经过本地报告服务（skill_tools 是进程内 Python 函数，不起 HTTP 服务），所以报告服务退出与否都不影响收款。<!– AIPC-PAY-VIA-CHAT-FIX –>

用户说「我付了钱但没解锁 / 没收到码 / 页面说确认失败」（AIPC-PAY-RECOVER-FIX）：

1. skill_tools.rescue_orders() —— 把本机所有「未解锁」订单逐一拿去服务端确认，查到已付当场激活
2. 返回 rescued 非空 → 回用户「已帮你确认到付款并解锁了，回报告页就能用」
3. 返回为空、still_pending 有值 → 服务端还没看到这笔钱，请用户核对微信账单是否真的付款成功
4. 用户能提供激活码 → detect_activation_code → activate_code 直接激活
5. 绝不让用户「再付一次」 —— 重复付款是事故。先把已有的钱查清楚，再谈要不要付

服务端履约是幂等的（同一单号重复查不会重复扣费、不会重复发码），所以「多查几次」永远安全。<!– AIPC-PAY-RECOVER-FIX –>

一键清理（兜底）：用户说「一键清理」→ 列项确认 → clean_green(green_trash_paths) → 汇报（已释放 X GB / 重启后释放 Y GB / 前后对比）

迁移（兜底）：用户说「迁移」→ get_migration_options 列候选（含容量标记）→ 用户选序号 → plan_selected_migration → 确认 → migrate_items → 汇报（含迁移记录）

基础版权限 = 一键清；高级版权限 = 一键清 + 迁移（tier_capabilities 判断）

第 4 步：结果与报告联动

• 清理/迁移完成后，报告页自动刷新（server 实时按 junction/磁盘状态过滤，释放量/迁移记录更新）
• AI 兜底执行时：对话框汇报结果（释放了多少/还剩多少），明细与展开都在报告页
• 清理/迁移完成后，重新生成报告并按第 1 步第 ② 条取回地址、重新 present 侧边栏（释放量/迁移记录更新）
• 对话框汇报结果（释放了多少/还剩多少/还能做什么），明细与展开都在报告页

安全前提：清理/迁移一律走「先列项 → 用户明确确认 → 再执行」的流程，不做自动执行；对话框给出用户能看懂的结果（释放了多少 / 还能做什么）。

等价手动三步（当 run.py 不适用时）：

python scan.py > scan.json
python analyze.py scan.json analysis.json
python build_report.py analysis.json report.html config.json

安全护栏（所有操作通用）

清理/迁移/付款的安全护栏（报告页操作与 AI 兜底执行都适用）：

• 仅限清单内路径：清理/迁移只接受报告 analysis.json 里列出的绿区/迁移路径
• 越界检查：删除仅限用户目录内系统缓存；个人文件（文档/桌面/图片/视频/音乐）不自动删
• 强确认：破坏性操作必须先列项 + 用户明确确认
• 界面克制：对话只做引导，明细与路径信息统一由报告页呈现

许可与等级

清理功能受本地许可门控：

模拟「一键清理」前必须先授权基础版：用签名工具签一个 tier≥1 的测试码，在 WB 对话框让用户输入（调 skill_tools.activate_code），或直接付款解锁。未授权时调用清理/迁移返回 {locked:true}，属正常权限门控，不是 bug。

安全模型（向用户说明的要点）

• 绿区 = 100% 安全：仅含纯缓存（浏览器/微信/软件缓存），删除后自动重建，无任何用户数据损失。
• 红区不进报告、不在处理范围：系统核心与应用本体不出现在报告，也不在可清理清单内。
• 迁移 = 只搬不删：大目录（微信/QQ/游戏等）搬到其它盘并建目录联接，软件照常用、以后新文件也落其它盘；绿区永久删除但仅含纯缓存、删了自动重建。
• 本地优先：扫描与清理全在本地，无文件外传。

常见问题

• 报告打不开/乱码：确认用 present_files 展示的 HTML 路径正确；报告是 UTF-8，含中文。
• 绿区偏小：多半是非管理员运行，系统缓存被 denied。用管理员身份重跑 run.py。
• 点清理提示未授权：未授权基础版，先在对话框付款或输入激活码（见许可）。
• 迁移失败提示权限不足：迁移需管理员权限建立目录联接；退出后用「右键 → 以管理员身份运行」重开再迁移（运行中进程无法一键自我提权）。
• 报告页按钮点不动、或页面提示「连接断了」：本地报告服务已退出（它随 run.py 后台任务一起被回收）。按第 1 步重跑一遍（① 后台 run.py + ② 前台 open_report.py --print --wait 100）：扫描结果会被复用、无需重新扫描，拿到新的 REPORT_URL 后重新 present_files，然后请用户重新点一次原来的按钮即可。但付款是个例外：付款不需要重启 —— 让用户把报告页引导框里那句话复制到对话框发给你，你按上面「第 3 步 → 解锁（对话框通道）」直接下单即可。<!– AIPC-PAY-VIA-CHAT-FIX –>
• 走了静态兜底（REPORT_FILE）时：该报告是只读展示，页面上的付款/清理按钮点不了。必须主动告诉用户「报告是只读的，付款和清理请在对话框里让我代做」，不要等用户点了报错才发现。<!– AIPC-SKILLFILE-RECOVER-FIX –>

输出交付

• 报告 HTML 是展示交付物：present_files 侧边栏展示（完整、可展开明细）。
• 模拟真实用户场景时，建议顺序：① run.py 出报告 → ② present 侧边栏看报告（验证分区与文案）→ ③ server.py + 授权 → 点绿区「一键清理」→ ④（Pro）迁移区。