微信本地附件归档至 ima 和 Obsidian

安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install wechat-archive-to-ima
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 wechat-archive-to-ima。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

此 Openclaw Skills 条目可帮助整理已由 Windows 版微信下载到电脑的附件。它会定位本地数据目录，扫描附件、视频、文件和缓存来源，并将可读取的文档、图片和视频分类到可搜索的归档中。只有在明确请求时，才会解密受支持的微信 4.x .dat 图片缓存。
归档结果可以复制到本地 Obsidian 库，或通过 Tencent ima 的 OpenAPI 上传到知识库。联系人文件夹以哈希值标识，因此用户需要确认对应的联系人名称。此技能仅处理本地文件：不会解密微信数据库、导出聊天文本、取回云端已过期附件，也不会操作手机。

应用场景

将本地下载的微信文档、图片和视频整理到按联系人分类的归档中。
查找散落在微信数据文件夹中的合同、发票、会议文件或其他附件。
用户明确启用该选项时，解密支持的缓存 .dat 图片。
创建包含索引和链接附件的本地 Obsidian 归档。
使用用户提供的 API 凭据，将符合条件的文件批量上传到 ima 知识库。
后续分析归档文档中的合同条款、发票详情、会议行动项或客户洞察。
在决定归档哪些内容前，生成本地微信附件清单。

工作原理

使用 scripts/detect_wechat_paths.py 检测微信安装位置、账户数据根目录和附件来源；不要猜测路径。
确认文件已存在于本地。如果附件尚未下载，用户必须先通过微信下载。
找出相关联系人哈希文件夹。按活跃度或时间范围排列候选项，然后请用户将选定的哈希映射到联系人名称；此技能不会读取加密的联系人数据库。
扫描全部四个相关来源——msg/attach、msg/video、msg/file 和 cache——并整理支持的可读取文件。适当时使用预览/复制模式，因为整理器默认会移动文件。
如有请求，运行 .dat 解密工作流，并将本地密钥结果传递给整理器。解密需主动选择；不加 --decrypt 时，只会列出 .dat 文件，不会解密。
生成分类归档文件夹、索引、README，以及未处理或重复文件报告。
可选择将归档复制到 Obsidian 库，或使用所需 API 信息将文件上传到 ima。
如有请求，分析归档文档。此技能不会导出聊天文本；用户必须为该任务提供单独的导出文件。

配置指南

使用此技能附带的脚本；源资料未指定软件包安装命令。首先检测真实的微信账户路径并检查清单。以下示例假设 Python 可用，并使用必须替换为检测结果的占位路径。
python scripts/detect_wechat_paths.py
python scripts/detect_wechat_paths.py --rank-contacts
整理全部四个来源。--contact 值是写入归档元数据的标签；按联系人分组时，请使用已确认的联系人哈希。由于默认行为会移动文件，进行非破坏性试运行时请添加 --copy。
ACCOUNT="$HOME/xwechat_files/"
OUT=""
for SRC in "msg/attach" "msg/video" "msg/file" "cache"; do
python scripts/organize_attachments.py
--src "$ACCOUNT/$SRC"
--dst "$OUT/$SRC"
--contact "$SRC"
--copy done
要解密受支持的 .dat 图片，请在本地运行解密步骤，并妥善保管生成的密钥文件。然后在整理时启用解密：
python scripts/wechat_dat_decrypt.py
--account "$ACCOUNT"
--out "$OUT/dat-decrypted" python scripts/organize_attachments.py
--src "$ACCOUNT/msg/attach"
--dst "$OUT/msg/attach"
--contact "attach"
--decrypt
--key-file "$OUT/dat-decrypted/secret_hit.json" 对于 Obsidian，请提供库路径；工作流会将归档复制到库中并创建 index.md。对于 ima 上传，请获取 client_id、api_key 和 knowledge_base_id；folder_id 为可选项。ima 凭据具有账户级权限，因此请妥善保管，并在任务完成后轮换 API 密钥。

数据架构

此技能从微信账户数据目录读取本地下载的文件，通常位于 xwechat_files/_/ 下。它会扫描以下四个来源，而不只是依赖 msg/attach：
来源 典型内容
msg/attach/ 联系人/哈希附件文件夹，包含文档和 .dat 图片缓存
msg/video/ 视频相关文件，按日期路径组织
msg/file/ PDF、DOCX、PPTX 和 XLSX 等文档
cache/ 缓存文件和图片
归档输出按文件类型和日期组织。文件按 YYYYMMDD- 模式重命名，并使用 SHA-256 识别重复项。
输出路径 用途 00-index/README.md 归档概览和处理说明 00-index/index.csv 文件清单和索引 00-index/dat_files.csv 未处理或解密失败的 .dat 文件及原因 00-index/secret_hit.json 可在本地重复使用的解密结果；请妥善保管，不要分享 01-documents/ PDF、DOCX、XLSX 和 PPTX 文件 02-images/ JPG 和 PNG 图片 03-videos/ MP4 和 MOV 视频 05-misc/ 其他受支持的输出，包括动态 wxgf 文件 99-duplicates/ 通过 SHA-256 识别的重复文件 对于 Obsidian，工作流会添加一个 index.md，其中的 frontmatter 描述来源、联系人、日期范围、文件数量和标签；附件使用相对 wikilinks 引用。ima 上传使用提供的知识库和可选文件夹标识符，上传失败记录在 upload_failed.csv 中。

高级特性

自动发现微信安装路径和账户路径、文件数量、大小及附件的月度分布。
根据文件数量和最近活动对联系人哈希排序，帮助用户识别文件夹，而无需访问加密的联系人数据。
递归扫描四个本地数据来源，找到的文件可能远多于仅扫描
attach
的方式。
可选择解密微信 4.x
.dat
V2 图片，自动推断代码并验证图片；技能文档报告的测试结果为 3,898 个文件中成功解密 3,898 个。
提供已知代码、wxid 候选值、密钥文件和可配置超时的解密控制；解密期间源目录为只读。
使用 SHA-256 检测重复项，并生成按日期/类型分类的文件夹及 CSV/Markdown 清单。
可选集成 Obsidian 库并通过 ima OpenAPI 批量上传。ima 上传遵守每秒一个请求的限制，最多重试失败请求三次，并在 CSV 中报告失败情况。
明确的隐私和能力边界：不解密 SQLCipher 数据库、不提取内存密钥、不控制手机、不导出聊天文本，也不恢复已过期的云端附件。

name: wechat-archive-to-ima slug: wechat-archive-to-ima displayName: 微信聊天记录图片文件归档到ima知识库 summary: 把微信PC端已落地的聊天附件按联系人归类、批量上传ima知识库或Obsidian；.dat加密图片一键解密，实测3898/3898成功。 description: >- 把用户微信 PC 端已经落地到本地的聊天附件（图片、视频、文档）做系统化归档， 按联系人归类，并同步上传到腾讯 ima 知识库（OpenAPI）或本地 Obsidian 库。 适用场景：(1) 用户说"帮我整理微信里跟某人的所有资料/文件/图片"； (2) 用户说"把微信聊天里的合同、发票、会议纪要归档到知识库"； (3) 用户说"微信收到的文件太多找不到，帮我分类"； (4) 用户给了 ima 的 ClientID / APIKey，要求把本地资料批量入库； (5) 用户要对已归档的微信资料做摘要、合同条款提取、待办清单、客户画像分析； (6) 用户说"帮我把微信里所有人的附件都整理到电脑"； (7) 用户说"微信存下来的图片是 .dat 打不开，帮我解出来"（已支持：自动推导 code 并解密）。 不适用：解密微信加密数据库（message_.db / contact.db）、读取用户未在 PC 端打开过的消息、 远程操作手机微信、抓内存密钥、导出聊天正文 —— 这些一律不做， 遇到这类要求直接说明边界并给替代方案。 version: 1.0.0 author: 初五Agent tags: [微信, ima, 附件归档, 图片解密, 知识库, wechat, ima-knowledge-base] license: MIT 微信本地附件归档到 ima / Obsidian
核心原则（必须先读）
只整理已经落地到本地磁盘的附件文件。微信 PC 端把图片/文件下载到本地后是明文文件， 可以直接读、复制、改名、分类。没有下载到本地的附件，本 skill 不做。
不碰加密数据库。db_storage\message_.db、contact.db 是 SQLCipher 4 加密的， 不破解、不 dump 内存密钥、不调用第三方解密工具。
.dat 图片缓存已支持解密。微信 4.x 把图片存成 V2 头的 .dat（单账号常见 3800+ 个）， scripts/wechat_dat_decrypt.py 自动探测 .dat → 尾字节反推 xor → 枚举 wxid 候选 → 推导 code（下界 0）→ 批量解密 → PIL 校验，实测 3898/3898 成功、0 失败， PIL 3104/3104 全部可打开（jpg 2689 / wxgf 794 / png 415）。 organize_attachments.py 默认仍只列清单，加 --decrypt 才解密归档。
手机端备份必须用户本人操作。智能体碰不到用户手机。
wxid/hash → 备注名映射需要用户配合一次。本地按 hash 分目录，但映射在加密的 contact.db 里。
ima API Key 等同账号权限。任务结束提醒用户轮换 Key。
实测过的真实目录结构（微信 4.1.x Windows）

数据根目录（注意：不在 Documents 下）：

\xwechat_files_\

账号下一级目录：

├── apm_record\ （APM 监控，忽略）
├── business\ （业务数据）
├── cache\ （缓存）
├── config\ （配置）
├── db_storage\ （加密数据库 ★ 不碰）
├── msg\ （★ 附件都在这）
│ ├── attach\ ← 230 个联系人/群，每个目录是一个人的图片和文件
│ ├── file\YYYY-MM\ ← 文档按月分（通常为空，文档实际在 attach 下）
│ ├── video\YYYY-MM\ ← 视频按月分（同上）
│ └── migrate\ ← 3.x 迁移过来的孤儿文件
├── resource\
└── temp\

实测样例（2026-10-06 在本机跑出来的）：

账号目录 ：账号总 2.1 GB，msg\attach\ 3909 个文件
attach\ 下有 230 个 hash 子目录（即 230 个联系人/群）
明文文件散在 4 个源，不止 attach（关键，别只跑 attach）：
源目录 文件数 主要内容
msg\attach\ 3909 .dat 3848（图片缓存，可用 --decrypt 解出）、pdf 14、pptx 7
msg\video\ 299 jpg 208、mp4 91
msg\file\ 72 pdf 35、docx 13、pptx 11、xlsx 6
cache\ 193 jpg 33、.dat 50

实跑归档结果：只跑 attach\ 得到 61 个明文；跑全 4 源得到 509 个（attach 61 + video 261 + file 49 + cache 138），8.3 倍。另有 66 个重复文件进 99-duplicates/。

时间分布：主要集中在 2026-04 ~ 2026-09
完整工作链路
阶段 0：环境探测（智能体做，5 分钟）
↓
阶段 1：用户手动把附件下载到本地（用户做，可能几小时）
↓
阶段 2：列联系人 hash 清单，用户指认备注名（智能体+用户，10 分钟）
↓
阶段 3：本地整理（智能体做，10~60 分钟）
↓
阶段 4：双轨入库（智能体做）
├─ 4A：Obsidian 本地库
└─ 4B：ima 知识库（OpenAPI）
↓
阶段 5：分析与总结（按需）

阶段 0：环境探测

执行 scripts/detect_wechat_paths.py，会自动找出：

微信安装路径（注册表）
数据根目录（候选：~/xwechat_files/、~/Documents/xwechat_files/、~/Documents/WeChat Files/）
当前活跃账号（按最近修改时间排序）
msg 下的联系人 hash 目录数、文件总数、总大小
按月份的附件分布

不要凭猜写路径。每个用户电脑路径不同，必须先跑脚本拿真值。

阶段 1：让附件真正落地到本地

问题：很多用户的 msg\attach\ 下文件不多，是因为微信默认只在用户点开图片/文件时才下载。

两条路（选一条）：

路径 A：开"自动下载"设置 + GUI 批量滚动
让用户在电脑微信 → 设置 → 文件管理 → 打开自动下载（图片/视频/文件全开）
智能体用桌面自动化（computer_use）逐个打开聊天窗口，滚动到顶/到底
后台等几分钟，让附件下载完

适合：全量整理所有人的附件。但 230 个联系人逐个滚动要几小时。

路径 B：手机备份 + PC 端窗口触发
用户在手机发起"备份到电脑"
备份完后，电脑微信打开几个重要联系人窗口滚一遍
附件落地后开始整理

适合：先挑几个重要联系人试水。

注意：用户如果想全量整理，推荐路径 A，但要做好"几小时跑批"的心理准备。

阶段 2：hash → 备注名映射（关键步骤）

attach\ 下每个 hash 目录就是一个联系人/群，但 hash 没有备注名。

三种解决方案：

活跃度排行法（推荐）：跑 scripts/detect_wechat_paths.py --rank-contacts， 列出所有 hash 目录按文件数、最近修改时间排序，用户从 TOP 20/50 里指认常用的人。
时间特征法：用户说"我上周跟张三聊了很多"，脚本找最近一周有大量文件的 hash 目录， 让用户确认。
最笨但最稳：用户列出想整理的几个联系人备注名，脚本把候选 hash 列出来， 用户逐个指认。

绝对不要尝试读 contact.db 去解密。

阶段 3：本地整理

必须扫全账号 4 个源（只跑 attach\ 会漏掉 8.3 倍明文文件）：

ACCOUNT="$HOME/xwechat_files/"
for SRC in "msg/attach" "msg/video" "msg/file" "cache"; do

python scripts/organize_attachments.py \

--src "$ACCOUNT/$SRC"
--dst "/$SRC"
--contact "$SRC"

done

参数说明（注意：参数名是 --contact，不是 --contact-hash）：

--src 传的是该源目录，脚本会用 rglob 递归遍历其下所有层级（含 attach\2026-09\Img\） --contact 只写进日志/README，传源目录名即可；按联系人分组时传该 hash 默认移动文件，预览/试跑请加 --copy
要把 .dat 也解出来，追加 --decrypt（见下面"解密 .dat"）
解密 .dat（--decrypt 开关）

# 第一步：单独跑解密，拿到 code（写到 /secret_hit.json，只留在本机）
python scripts/wechat_dat_decrypt.py \

--account "$ACCOUNT"
--out "/dat-decrypted"

# 第二步：归档时直接复用，二次使用秒出
python scripts/organize_attachments.py \

--src "$ACCOUNT/msg/attach"
--dst "/msg/attach"
--contact "attach" --decrypt
--key-file "/dat-decrypted/secret_hit.json"

wechat_dat_decrypt.py 参数：--account 、--out 、 [--wxid 候选]、[--code 已知code]、[--timeout 秒]；已知 code 时跳过暴力推导
organize_attachments.py --decrypt 可用 --code / --key-file / --wxid 直接给密钥， 一个都不给就自动推导（默认超时 300s，--decrypt-timeout 可调）
源目录只读，解密产物只写 --out / --dst

它会：

不加 --decrypt（原行为）：跳过 .dat，记录到 00-index/dat_files.csv 加 --decrypt：解出 .dat 后按 YYYY-MM/类型/ 正常归档（jpg/png 进 02-images/， wxgf 动图进 05-misc/），解密失败的才留在 dat_files.csv 并标注原因 把明文文件（pdf/docx/xlsx/pptx/jpg/mp4）按 YYYY-MM/类型/ 分子目录
重命名为 YYYYMMDD-
SHA256 去重，重复文件移入 99-duplicates/
生成 index.csv 和 README.md

输出目录结构：

/
├── 00-index/
│ ├── README.md
│ ├── index.csv
│ ├── dat_files.csv ← 未解密/解密失败的 .dat 清单（加 --decrypt 后通常为空）
│ └── secret_hit.json ← --decrypt 命中的 code（本机复用，不要外发）
├── 01-documents/ (.docx .pdf .xlsx .pptx)
├── 02-images/ (.jpg .png)
├── 03-videos/ (.mp4 .mov)
├── 05-misc/
└── 99-duplicates/

阶段 4A：入 Obsidian（可选）

如果用户指定了 Obsidian 库路径：

把输出目录整个复制到 /豆包工作成果/03-知识沉淀/微信归档//
生成 index.md，frontmatter 写好来源、联系人、时间范围、文件数、标签
附件用相对路径 ![[文件名]] 引用
阶段 4B：入腾讯 ima 知识库

用户必须提供 4 个参数（缺一不可）：

client_id：从 https://ima.qq.com/agent-interface 生成
api_key：同上
knowledge_base_id：ima 网页进入目标库，URL 中复制
folder_id：目标文件夹 ID（可选）

跑 scripts/ima_upload.py：

单文件 ≤ 50 MB
PDF ≤ 1000 页
QPS 限流：每秒 1 个，失败重试 3 次
失败清单写入 upload_failed.csv

详细 API 参数见 references/ima_api.md。

阶段 5：分析与总结（按需）
分析类型 输入 输出
合同关键条款提取 01-documents/*.docx/pdf 甲乙方、金额、期限、违约条款表
发票/收据清单 01-documents 里的发票类 开票方、金额、日期、税额表
会议纪要要点 文档 决议、待办、责任人
客户画像 整个归档目录 职业、关注点
往来款流水 发票 + 转账截图 按时间排的流水表

注意：聊天文字本 skill 不导出。要文字记录，用户自己用 WeChatMsg 跑一遍（开源免费）， 导出 HTML/Word 后给智能体整理。

边界与免责（第一次回复用户时必须说清楚）
事项 可行度 说明
自动定位本地附件目录 100% 脚本直接遍历
整理明文附件（pdf/docx/jpg/mp4） 100% 明文文件
入 Obsidian 100% 本地写文件
入 ima 90% 需 API Key
hash → 备注名映射 60% 通常要用户指认一次
解密 .dat 图片 100% 已支持：自动推导 code 并解密，实测 3898/3898、PIL 100%
提取聊天文字 30% 依赖用户手动导出或 WeChatMsg
读加密 message.db 0% 做不到，不承诺：聊天正文当前解不开
远程操作手机 0% 做不到
找回云端过期附件 0% 救不回
参考文件索引
路径对照、版本差异、实测结构：references/wechat_paths.md
ima OpenAPI 完整参数、错误码、调用示例：references/ima_api.md
可行性反推论证全过程：references/feasibility.md
.dat V2 格式、code 推导原理、两个关键坑与真实边界：references/dat_decryption.md

只有需要时才读对应 reference，不要一次全加载到上下文。

PulseNetwork Robinhood Chain 兑换路线

Awam To-Do