前言¶
在 DSH 里做审计、备份或本地知识整理时，往往需要把 IM 的本地库变成 Agent 可读的结构化数据。常见做法是手工拷贝数据库、自行研究加密格式，或依赖闭源导出工具，边界不清晰且容易误写原库。DeepSeek Harness 的插件机制允许把「识别环境 → 解密 → 解析媒体 → 摘录」收成一组可调工具；下面介绍维护者 jcy0chenyuan0 发布的 dsh-plugin-qqchat（分类 admin-security，v1.0.0），它面向 Windows + QQ NT，在拷贝快照上只读处理本地聊天数据。
这是什么¶
dsh-plugin-qqchat 是挂在 DSH GUI 里使用的 只读 QQ 本地聊天记录获取插件：解密 NT 容器、导出与摘录、会话隔离（部分能力仍在规划中）。仓库：GitHub - jcy0chenyuan0/dsh-plugin-qqchat；目录页：SkillHub 插件页。
插件自述的红线如下，与「能发消息、能 hook QQ」类工具不同：
- 不发消息、不注入 QQ 进程、不 hook、不改 QQ 安装包、不碰网络协议、不调用云端模型。
- 所有读取都在 拷贝出来的快照 上进行，原库零写入。
运行环境以 README 为准：Windows 10/11（x64）、QQ NT 本地库与媒体路径、PowerShell 5.1+ 解密链路；macOS / Linux 未适配。安装 QQ 后仍需手动登录，插件只读已登录账号的本地库。
核心功能与当前进度¶
README 用阶段表说明实现状态；下面只列与使用者相关的已核实能力。
已完成（README 标记 ✅）¶
| 能力 | 说明 |
|---|---|
| 骨架 + 环境体检 | qq_doctor：QQ 版本/进程、账号目录、库形态、容器格式、密钥状态、媒体目录与下一步提示 |
| 容器解密 | 剥 1024 字节头 + 非标准 SQLCipher 解密；qq_decrypt 拷贝 → 剥头 → 解密 → SQLite 头部自校验 → sqlite3 实开验证 |
| 密钥获取 | qq_find_key：缺密钥时才从运行中的 QQ 进程 只读 扫描内存取每库 raw key，按 salt 配对；默认不回显明文 |
| 消息与媒体 | 40800 protobuf 解析；qq_media 定位图片/视频/表情/语音/文件在本机磁盘上的路径 |
真机战绩（README 记载，QQ NT 9.9.35.52892，账号 3960766092）：约 7 秒扫完进程内存，18/18 个非空库密钥配对；nt_msg.db 8290 页约 3 秒解密，33 张表，群消息 33,233 条 + 私聊 165 条；媒体扫描定位 308 个元素到本机文件。
进行中（⏳）¶
- P4：归一化库、会话隔离、增量摘录（
qq_sync/qq_conversations/qq_messages） - P5b：导出 jsonl/csv/md + 脱敏（
qq_export） - P6：mock 后端；P7：打包与端到端验收
技术要点（便于理解工具行为）¶
QQ NT 本地库在文件开头带 1024 字节明文容器头，其后为页大小 4096 的 SQLCipher 加密区。README 说明：本机实测 每库一把 32 字节 raw key，enc_key 直接使用该 key，不走 调研文档里提到的「16 字节 ASCII 口令 + PBKDF2」那条路径。解密器会对每个库用 SQLite 头部自校验探测 crypto reserve（例如多数库 48，个别库 80），校验不过则拒绝采信。
消息体字段与媒体落盘规则（如 Pic\<月>\Ori\<md5>.<ext> 等）在 README 中有表格与路径模板，供 qq_media 按 MD5 索引查找，不套用安卓 Cache 命名。
工具清单¶
在 DSH 中通过插件暴露的 qq_* 工具（JS 桥接 + Python 引擎，stdout 仅输出一个 JSON 对象）：
| 工具 | 作用 |
|---|---|
qq_doctor |
环境体检与下一步指引 |
qq_find_key |
先检查是否已有密钥，缺失时只读内存扫描并配对 |
qq_decrypt |
快照解密并 sqlite3 验证 |
qq_media |
解析消息内媒体并定位本机文件（无文件则如实返回） |
依赖策略：零额外 npm/crypto 库——JS 仅用 Node 内置模块；Python 仅用标准库；对称解密走 PowerShell 5.1 的 .NET（AES 等）。
安装与启用¶
先做仓库侧准备，再在 DSH 里挂载 bundle。安装命令以 README 原文为准，不要 凭插件名拼接 dsh plugin add github:...。
1. 生成 patch 与依赖（首次）¶
在插件目录执行（Windows）：
powershell -ExecutionPolicy Bypass -File .\install.ps1
仅检查环境、不自动安装时：
powershell -ExecutionPolicy Bypass -File .\install.ps1 -CheckOnly
macOS/Linux 上可用 node install.mjs 生成 cordis.patch.yml（但该插件运行仍依赖 Windows QQ 环境）。脚本会按当前目录生成 cordis.patch.yml（已 .gitignore），不写死盘符。
install.ps1 默认静默安装缺失环境（Python 优先 DSH 自带运行时，否则 winget install Python.Python.3.12 --scope user；QQ NT 可用 winget install --id Tencent.QQ.NT -e）。插件加载时还会在后台运行 bootstrap.ps1 -AutoInstall -Quiet（6 小时内不重复）。关闭自动安装：patch 的 config 里设 autoInstall: false，或环境变量 DSH_BOOTSTRAP=0。
2. 安装到 DSH¶
任选其一：
- GUI：「设置 → 插件 → 安装 → 本地路径」填本目录绝对路径（例如
%USERPROFILE%\.dsh\plugins\qqchat）。 - CLI：
plugin_manager install_bundle file:<本目录的绝对路径>
装完后在 GUI「插件」页整体启用/停用。改 JS 代码需 重启 DSH（ESM 按 URL 缓存）；仅改 cordis.patch.yml 时需重新 install_bundle。
换机器时 README 建议：clone 仓库 → 运行 install.ps1 或 install.mjs → install_bundle → 运行 qq_doctor 并按提示配置 config.json（可参考 config.example.json）。产物目录 data/ 与 config.json 不入库。
典型用法¶
经过上面的安装步骤后，建议按 README 顺序自检：
- 在 DSH 中调用
qq_doctor，确认 QQ 进程、账号目录、21 个库形态与密钥状态。 - 若 doctor 提示缺密钥，在 QQ 已登录前提下调用
qq_find_key（只读内存，不注入）。 - 调用
qq_decrypt对快照解密；依赖 SQLite 头自校验，失败则不应继续采信该库。 - 需要媒体路径时调用
qq_media，在已解密消息上解析40800并映射到本机Pic/Video/Ptt等目录。
会话归一化、增量同步与 jsonl/csv/md 导出在路线图中尚未标记完成，使用前以仓库 README「当前进度」表为准。
适用场景与注意¶
适合：在 本机 Windows 上、对已登录 QQ NT 账号做 合规范围内的只读备份/分析；希望把解密与媒体定位封装成 DSH 工具、供 Agent 在明确边界下调用的开发者。
务必注意：
- 插件以 当前 DSH 进程权限 运行；
qq_find_key会读取 QQ 进程内存，属于高敏感操作。安装前应阅读源码与 MIT 许可证，仅在信任维护者与用途的前提下启用。 - 只读指 不改 QQ 原库、不发消息；解密后的快照与
data/摘录仍可能含隐私，导出与脱敏能力（qq_export）尚未完成，需自行管控产物。 - 页面 HMAC 的
mac_key派生 README 标注为未完全弄清；当前以 sqlite3 可读性与头字段一致性作为解密判据。 - SkillHub 等为社区目录，与 DeepSeek / 幻方无官方从属关系；星标与版本以仓库为准（当前 README 为 v1.0.0）。
结尾¶
dsh-plugin-qqchat 把 QQ NT 本地库的容器格式、内存密钥配对、解密校验和媒体路径查找收成 DSH 侧一组只读工具，适合需要在 Harness 里本地化处理聊天数据、又希望边界清晰的场景。完整细节与实测数据见仓库 README。
- 目录页：https://www.skillhub.cn/plugins/jcy0chenyuan0/dsh-plugin-qqchat
- GitHub：https://github.com/jcy0chenyuan0/dsh-plugin-qqchat
