| name | wechat-file-organizer |
| description | 整理 Windows 微信聊天文件存储目录的技能。当用户说"整理微信文件"、"清理微信缓存"、"整理微信图片/视频/文档"、"微信文件去重"、"清理微信存储"、"删除微信重复文件"、"整理最近N个月的微信文件"时，必须使用本技能。自动检测微信文件目录（含电脑管家迁移路径），识别微信 (1)(2)(3) 括号命名重复文件，支持移到回收站、按月份+类型分类整理、按时间范围过滤，所有操作前必须 dry-run 预览并等待用户二次确认。 |
微信文件整理技能
功能概述
-
自动检测微信文件存储路径（含非默认迁移路径）
-
识别微信重复文件：普通重复 + 括号序号命名（文件(1).pdf、文件(2).pdf）
-
重复文件移入回收站（非永久删除，可恢复）
-
按月份+类型分类，复制到用户指定目录
-
支持 --since 时间范围过滤（如只整理最近3个月）
-
两阶段确认：dry-run 预览 → 用户确认 → 执行
执行流程
第一步：检测 / 读取配置
python scripts/detect_wechat_dir.py
脚本会输出当前状态，Agent 根据结果执行不同的后续操作：
情况 A：已有配置文件（status = found_config）
脚本展示已保存的源目录、目标目录、上次整理时间。
情况 B：首次运行 / 检测到候选路径（status = found_single / found_multiple）
情况 C：未检测到任何路径（status = not_found）
-
请用户手动输入源目录路径
-
确认路径存在后 → 进入第二步
配置文件位置：skill 根目录下的 config.json
（与 SKILL.md 同级，即 .agents/skills/wechat-file-organizer/config.json）
操作日志同样保存在 skill 根目录：organizer_log.txt
第二步：询问并保存配置
仅在以下情况执行本步骤：首次运行、reset、或配置文件中缺少某项字段。
需要收集并确认的字段：
-
source_dir（微信源目录）
-
来自第一步检测结果或用户手动输入
-
必须确认路径实际存在
-
dest_dir（目标保存目录）
-
mode（分类方式，默认 month_type）
收集完成后，用以下格式写入配置文件：
import json
from pathlib import Path
config = {
"source_dir": "<用户确认的源目录>",
"dest_dir": "<用户确认的目标目录>",
"mode": "month_type",
"last_run": None
}
config_path = Path(__file__).parent.parent / "config.json"
with open(config_path, "w", encoding="utf-8") as f:
json.dump(config, f, ensure_ascii=False, indent=2)
print(f"✅ 配置已保存到：{config_path}")
保存后告知用户配置文件的完整路径。
每次整理前：确认目标目录
无论是否已有配置，每次执行整理操作前，都必须向用户展示目标目录并明确确认：
「将整理到：%USERPROFILE%\Documents\微信整理，确认吗？（或输入新路径）」
第三步：统一 Dry-run 预览（必须执行，不可跳过）
用一个命令同时展示「重复文件分析」+「整理后目录结构」：
python scripts/preview.py \
--source "<源目录>" --dest "<目标目录>" \
[--mode month_type] [--since YYYY-MM]
预览报告包含两部分：
📋 微信文件整理完整预览
══════════════════════════════════════════════════════════
源目录：D:\xxx\xwechat_files\wxid_xxx\msg\file
目标目录：D:\Documents\微信整理
分类模式：month_type 时间范围：2026-01 至今
─────────────────────────────────────────────────────────
🗑 Part 1 · 重复文件（将移入回收站）
─────────────────────────────────────────────────────────
发现重复组：32 组 → 将移入回收站：74 个文件（节省 197 MB）
括号序号重复：28 组（如 文件(2).pdf）
完全相同重复：4 组
月份 重复文件数 节省空间
------------ ---------- ------------
2026-01 12 个 45.3 MB
2026-02 35 个 98.1 MB
2026-03 27 个 53.6 MB
示例（前15组）：
保留 移除（→回收站）
文件.pdf ❌ 文件(2).pdf (9.8 MB)
report.html ❌ report(2).html (60 KB)
...
─────────────────────────────────────────────────────────
📂 Part 2 · 整理后目录结构（将复制到目标目录）
─────────────────────────────────────────────────────────
待整理文件：109 个（共 293 MB）
文件类型分布：
文档 64 个 ████████████████
其他 35 个 ████████
压缩包 9 个 ██
音频 1 个
目标目录结构：
D:\Documents\微信整理\2026-01\文档\ → 15 个文件 · 120 MB
D:\Documents\微信整理\2026-02\文档\ → 28 个文件 · 89 MB
...
══════════════════════════════════════════════════════════
📌 操作建议
══════════════════════════════════════════════════════════
步骤 A · 清理重复文件 → 将 74 个文件移入回收站（释放 197 MB）
步骤 B · 整理文件到目标目录 → 复制 109 个文件
⚠️ 以上为完整预览，确认后请告知执行哪些步骤。
若用户只想做去重或只想整理，可以只执行步骤 A 或步骤 B。
第四步：等待用户明确确认
展示 dry-run 报告后，必须明确询问用户是否执行，不得自动继续。
示例确认语：「以上是预览结果，确认执行吗？」
第五步：执行
用户确认后，分步执行（可选择只做其中一步）：
python scripts/dedup_recycle.py --source "<源目录>"
python scripts/scan_and_organize.py \
--source "<源目录>" --dest "<目标目录>" \
--mode <模式> [--since YYYY-MM]
执行日志追加写入 ~/.wechat_organizer_log.txt。
去重规则（重要）
两类重复的识别方式
A. 括号序号重复（微信自动命名）：
-
识别 文件名 (N).ext 格式（N 为数字）
-
提取基础名：文件名.ext
-
将相同基础名、相同大小的归为一组
-
⚠️ 大小不同则不视为重复（可能是真的不同版本）
B. 完全相同重复：
保留策略
不同名、不同大小 = 不是重复
report.html 和 report_v2.html 不会被误判为重复，即使基础名相似。
文件类型分类规则
类型 | 扩展名 |
|---|
图片 | jpg, jpeg, png, gif, webp, bmp, heic, tiff, svg |
视频 | mp4, avi, mov, mkv, wmv, flv, m4v, 3gp, rmvb |
音频 | mp3, wav, aac, m4a, ogg, opus, amr, flac, wma |
文档 | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, md, rtf |
压缩包 | zip, rar, 7z, tar, gz, bz2, xz |
其他 | 以上未覆盖的文件（html, json, py, sql 等） |
--since 时间范围参数
--since YYYY-MM 表示只处理该月份及之后的文件（按文件修改时间）。
示例：
python scripts/scan_and_organize.py --source ... --dest ... --since 2026-01
python scripts/scan_and_organize.py --source ... --dest ...
Agent 收到"最近N个月"的指令时，自动计算起始月份并传入 --since。
配置文件
保存在 ~/.wechat_organizer_config.json：
{
"source_dir": "D:\\电脑管家迁移文件\\xwechat_files\\wxid_xxx\\msg\\file",
"dest_dir": "D:\\Documents\\微信整理",
"mode": "month_type",
"last_run": "2026-03-29 14:00:00"
}
脚本说明
脚本 | 用途 |
|---|
scripts/detect_wechat_dir.py
| 检测微信文件目录（含电脑管家迁移路径） |
scripts/preview.py
| 统一预览：同时展示去重分析 + 整理结构，不执行任何操作 |
scripts/dedup_recycle.py
| 去重并将重复文件移入回收站（支持 --dry-run） |
scripts/scan_and_organize.py
| 扫描、分类、复制到目标目录（支持 --dry-run、--since） |
标准使用顺序：
-
detect_wechat_dir.py → 确认路径
-
preview.py → 查看完整预览
-
用户确认后 → dedup_recycle.py（可选）+ scan_and_organize.py
