磁盘资料归类
把「下载文件夹是坨浆糊」变成「每个文件都有明确归属」。
核心不是分类得多漂亮，而是三件事：看得清（占用与重复一目了然）、改不错（先方案后动手）、能反悔（一键回滚）。
文件在你自己的机器上，脚本只做确定性的搬运；「按什么维度归档、这个文件是合同还是发票」这类判断由服务端的体系模板给出 —— 模板不在本包内，脱离服务端拿不到同一套标准。
30 秒速览
| 项 | 内容 |
|---|---|
| 能力 | 磁盘体检 → 归类方案 → 确认后归档 → 一键回滚 |
| 一次调用产出 | 体系模板（分类维度 + 判定规则）、逐文件归类方案、疑似重复清单、待确认清单、人工复核清单 |
| 单价 | ¥18.8 / 次（1880 分），一次收取，套内盘点与执行不计费 |
| 支付协议 | 微信 Agent Pay X402（WeixinPay-Required / X-Out-Trade-No） |
| 能否离线使用 | 部分可以：本地体检、归类执行、回滚都能离线；生成归类方案必须联网调用付费接口 |
| 本地动作 | 体检与执行默认只读/dry-run，加 --apply 才真正搬运，永不删除 |
平台支持
| 平台 | 状态 | 说明 |
|---|---|---|
| macOS | ✅ | 全功能。只需 Python 3.8+ 标准库，无第三方依赖 |
| Linux | ✅ | 同上 |
| Windows | ✅ | 全功能，三点注意见下 |
Windows 三点注意
- 环境自检需要 bash：
scripts/healthcheck.sh是 shell 脚本。Git Bash / WSL 下直接跑；
纯 PowerShell / cmd 没有 bash 时跳过自检即可——直接用 Python 脚本，
python scripts/disk_tidy.py scan --help能打出帮助就说明环境可用。 - 云盘占位文件会被自动跳过：OneDrive 等云盘的「仅在线」文件一旦被读取就会触发下载。
扫描时这类文件被跳过并在报告里注明数量，避免白烧流量与磁盘。
想连它们一起整理，先在资源管理器里把它们「始终保留在此设备上」再扫描。 - 路径长度上限 260 字符：Windows 的 MAX_PATH 限制。归档目录层级深 + 文件名长时可能搬移失败
（失败会记进清单，不会中断整批）。把目标根目录放在浅一点的位置即可。
清单与方案里的相对路径统一用 /（与平台无关），脚本内部按当前平台换算成 \。
服务端返回什么
| 字段 | 含义 |
|---|---|
taxonomy |
本次使用的体系分类维度：目录名、说明、命中的文件数 |
plan |
逐文件归类方案：目标目录、分类、置信度、一句话理由 |
needs_review |
判不准的文件：置信度不足、扩展名歧义（如 PDF 可能是合同也可能是发票），附候选分类供人工选择 |
duplicates |
疑似重复组（同名同体积），给出去重建议 |
rules |
这套体系的整理规则（如「发票按月归档」） |
checklist |
人工复核清单 |
stats |
总数、已归类数、待确认数、重复组数、预计可回收体积 |
使用工作流
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 选 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 服务接口
| 项 | 值 |
|---|---|
| 服务入口 | https://pay.zcmfopc.com/wxpay/api/skillhub/pay/disk-tidy |
| 健康检查 | GET https://pay.zcmfopc.com/wxpay/api/skillhub/pay/health → status=ok |
| Skill ID | disk-tidy |
| Skill Version | 1.1.0 |
| 计费模式 | 按次调用，¥18.8 / 次（1880 分） |
| 支付协议 | 微信 Agent Pay X402 |
| 支付触发 Header | WeixinPay-Required |
| 订单重试 Header | X-Out-Trade-No |
| Platform Product ID | 见 frontmatter pricing.product_id |
| 请求体 | {"profile": "...", "base": "...", "inventory": [{"name","ext","size","mtime","dir"}]} |
微信支付 API 证书、SkillHub 开发者私钥、体系模板与商户配置只保存在服务端，不进入 Skill ZIP、前端、日志或对话。
排障速查
| 现象 | 含义 | 处置 |
|---|---|---|
402 + WeixinPay-Required |
尚未支付 | 走第三步 weixinpay_pay，不要重复下单 |
402 + PAYMENT_NOT_CONFIRMED |
微信侧未确认收款 | 稍后携同一 X-Out-Trade-No 重试原请求 |
409 + ORDER_REQUEST_MISMATCH |
重试请求体与首次不一致 | 用完全相同的请求体重试（同一份 inventory、同一组参数），不要改任何字段 |
404 + ORDER_NOT_FOUND |
订单不存在或已过期（15 分钟） | 重新走第一步创建订单 |
200 + REFUNDED |
履约不可恢复失败，已自动全额退款 | 说明已退款，修正入参后可重新调用 |
200 + UNKNOWN_SKILL |
服务端没有这个 Skill | 检查 service_url 路径 |
needs_review 很长 |
体系不合适或文件命名不规范 | 换一套 profile 重判（新一轮按次计费），或先人工改名 |
安全红线
完整清单见 references/safety.md。最要紧的几条：
- 永不删除文件，只搬移；目标同名自动加序号，不覆盖。
- 默认 dry-run，
--apply才落盘；不越界（目标必须在扫描根目录内）。 - 低置信不硬塞：置信度低于 0.7 的文件留在待确认区，由人工判断。
- 不上传文件内容，绝对路径不出本机；来源目录名可关闭。
- 全程可回滚，每次执行都有会话日志与一键 undo。
边界与限制
- 本技能不替用户判断文件的重要性，「这份要不要留」永远由用户决定。
- 不做云同步、不做备份托管、不做文件加密、不做常驻定时任务。
- 分类依据只有文件名、扩展名、体积、修改日期与来源目录名 —— 读不懂文件内容（内容不会上传）。
- 一次调用对应一份清单与一套体系；要整理多个目录请分别调用（分别计费）。
- 体检与执行在本地完成，不消耗调用次数；只有生成归类方案计费。
