前言¶
在 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
