磁盘资料归类

概述

把「下载文件夹是坨浆糊」变成「每个文件都有明确归属」。

核心不是分类得多漂亮，而是三件事：看得清（占用与重复一目了然）、改不错（先方案后动手）、能反悔（一键回滚）。文件在你自己的机器上，脚本只做确定性的搬运；「按什么维度归档、这个文件是合同还是发票」这类判断由服务端的体系模板给出 —— 模板不在本包内，脱离服务端拿不到同一套标准。

30 秒速览

平台支持

Windows 三点注意

1. 环境自检需要 bash：scripts/healthcheck.sh 是 shell 脚本。Git Bash / WSL 下直接跑；

纯 PowerShell / cmd 没有 bash 时跳过自检即可——直接用 Python 脚本，python scripts/disk_tidy.py scan --help 能打出帮助就说明环境可用。

1. 云盘占位文件会被自动跳过：OneDrive 等云盘的「仅在线」文件一旦被读取就会触发下载。

扫描时这类文件被跳过并在报告里注明数量，避免白烧流量与磁盘。想连它们一起整理，先在资源管理器里把它们「始终保留在此设备上」再扫描。

1. 路径长度上限 260 字符：Windows 的 MAX_PATH 限制。归档目录层级深 + 文件名长时可能搬移失败

（失败会记进清单，不会中断整批）。把目标根目录放在浅一点的位置即可。

清单与方案里的相对路径统一用 /（与平台无关），脚本内部按当前平台换算成 。

服务端返回什么

使用工作流

Step 1（免费）：环境自检与本地盘点

bash <SKILL_DIR>/scripts/healthcheck.sh          # Windows 无 bash 时可跳过
python3 <SKILL_DIR>/scripts/disk_tidy.py scan --root "<用户要整理的目录>" --out "<工作目录>"

产出两份文件：

• inventory.json —— 机器可读的清单（文件名 / 扩展名 / 体积 / 修改日期 / 来源目录名）
• report.md —— 体检报告：目录占用排行、大文件 Top、可再生目录（node_modules、.venv、__pycache__…）、垃圾文件、安装包

这一步不触碰计费：只读扫描，任何文件都不会被改动。

盘点结果要向用户复述三件事：扫了多少文件、总共多大、能安全回收多少。

选体系：按 [references/taxonomy.md](references/taxonomy.md) 选 profile（general / freelancer / smallbiz / creator / ai-project），拿不准就用 general。

上传什么、要传多少，先说清楚（隐私知情同意）：只有文件名、扩展名、体积、修改日期会发给服务端；文件内容与绝对路径永不上传；来源目录名默认会带上（更准），用户介意时改用 --no-dir-hint。

Step 2（付费门控，必经）：请求归类方案并完成支付

前置检查：当前智能体是否支持微信 AI 支付

发起下单前，先检查你的可用工具列表中是否存在名称包含 weixinpay_ 的工具（工具名带前缀也算，如 mcp__weixinpay__weixinpay_register；存在任意一个即视为支持）。

只以你的工具列表为证据，本文档中提到的工具名不算；无法确认时按「不支持」处理。

• 支持：静默继续本 Skill 的后续流程，不向用户提及本检查。
• 不支持：终止流程且不要发起下单。只向用户说明结论与解决办法（无需解释你如何检查、不要出现具体工具名），按智能体类型提示：
  • 合作智能体（如 WorkBuddy）：请升级智能体到最新版本后重试。
  • 开放智能体（如 OpenClaw / DeepSeek Harness）：请根据 <https://skillhub.cn/install/skillhub.md>，安装 @tencent-adm/weixinpay-installer。
  • 无法判断类型：请升级智能体或安装微信支付 AI 支付插件后重试。

第一步：请求资源（首次不要携带 X-Out-Trade-No）

python3 <SKILL_DIR>/scripts/x402_request.py 
  --inventory "<工作目录>/inventory.json" 
  --profile <profile> 
  --base "<目标根目录名>"

脚本会打印两行关键值：

WeixinPay-Required (payment_code) = <payment_code>
X-Out-Trade-No (out_trade_no)      = <out_trade_no>

第二步：处理 402 支付响应

HTTP/1.1 402 Payment Required
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>

必须同时记下两个值：WeixinPay-Required 作为 paymentCode 交给 weixinpay_pay；X-Out-Trade-No 作为支付成功后的重试凭证。

第三步：发起微信支付授权

调用 weixinpay_pay(paymentCode=<WeixinPay-Required>)，由用户在微信支付 AI 专属卡确认支付。支付未完成、取消或失败时停止交付，只返回可读的失败说明，不得进入第四步。

付费门控：未拿到服务端 200 响应前，Agent 不得自行拼装一份近似方案交付给用户。

Step 3（付费后必须执行）：取回归类方案

支付成功后，用完全相同的请求体重试，并携带订单号（订单号与 payment_code 只走环境变量，不进命令行）：

DISK_TIDY_ORDER_NO=<out_trade_no> DISK_TIDY_PAYMENT_CODE=<payment_code> 
python3 <SKILL_DIR>/scripts/x402_request.py 
  --inventory "<工作目录>/inventory.json" 
  --profile <profile> 
  --base "<目标根目录名>" 
  --out "<工作目录>/plan.json"

服务端向微信查单，确认 trade_state=SUCCESS 后才返回方案。未确认支付时返回 PAYMENT_NOT_CONFIRMED，此时保留订单号重试原请求，不得重新下单。

Step 4：本地执行（确认后再动手）

# ① 方案转可执行清单（校验越界、覆盖、缺文件）
python3 <SKILL_DIR>/scripts/disk_tidy.py manifest 
  --plan "<工作目录>/plan.json" 
  --inventory "<工作目录>/inventory.json"

# ② 先看计划（dry-run，不动文件）
python3 <SKILL_DIR>/scripts/disk_tidy.py apply --manifest "<工作目录>/manifest.json"

# ③ 用户确认后再执行
python3 <SKILL_DIR>/scripts/disk_tidy.py apply --manifest "<工作目录>/manifest.json" --apply

给用户看的东西（执行前必须复述）：用了哪套体系、归成几类、搬多少个文件、涉及多大体积、哪些文件进了待确认区。不回滚就别说做完 —— 执行完一定要把回滚命令给出来。

Step 5：报告与回滚

python3 <SKILL_DIR>/scripts/disk_tidy.py report --session "<工作目录>/session-*.json" --out "<工作目录>/report-applied.md"
python3 <SKILL_DIR>/scripts/disk_tidy.py undo --session "<工作目录>/session-*.json"

Pay Skill 服务接口

微信支付 API 证书、SkillHub 开发者私钥、体系模板与商户配置只保存在服务端，不进入 Skill ZIP、前端、日志或对话。

排障速查

安全红线

完整清单见 [references/safety.md](references/safety.md)。最要紧的几条：

1. 永不删除文件，只搬移；目标同名自动加序号，不覆盖。
2. 默认 dry-run，--apply 才落盘；不越界（目标必须在扫描根目录内）。
3. 低置信不硬塞：置信度低于 0.7 的文件留在待确认区，由人工判断。
4. 不上传文件内容，绝对路径不出本机；来源目录名可关闭。
5. 全程可回滚，每次执行都有会话日志与一键 undo。

边界与限制

• 本技能不替用户判断文件的重要性，「这份要不要留」永远由用户决定。
• 不做云同步、不做备份托管、不做文件加密、不做常驻定时任务。
• 分类依据只有文件名、扩展名、体积、修改日期与来源目录名 —— 读不懂文件内容（内容不会上传）。
• 一次调用对应一份清单与一套体系；要整理多个目录请分别调用（分别计费）。
• 体检与执行在本地完成，不消耗调用次数；只有生成归类方案计费。