前言¶
在 DeepSeek Harness（DSH）裏跑智能體或本地工具鏈時，聊天、通知和文件往往分散在手機和電腦之間。若要在同一套 Harness 界面裏對照個人 WhatsApp 收發短信、同步會話並傳文件，通常只能再開瀏覽器標籤或獨立桌面客戶端，與側欄裏的其他能力割裂。
dsh-whatsapp 是 AJN-Tech 維護的 DSH 客戶端類插件：在 DSH 左側欄提供接近 WhatsApp Web 的「已關聯設備」體驗，通過掃碼關聯手機號，在電腦側實時同步消息並支持媒體與文件，會話狀態本地加密保存。下文按定位、能力、安裝與首次關聯、安全與限制說明可覈對的事實與步驟。
這是什麼¶
- 名稱：dsh-whatsapp（倉庫 AJN-Tech/dsh-whatsapp）
- 維護者：AJN-Tech
- 分類：客戶端（社區目錄：SkillHub 插件頁）
- 當前資料版本：
0.1.2（見package.json） - 定位：非官方的 WhatsApp Web 風格關聯設備插件；基於開源 Baileys 走 WhatsApp Web 多設備協議，不屬於 WhatsApp / Meta 官方產品。
README 明確提示：個人賬號沒有公開 API，非官方客戶端可能違反 WhatsApp 服務條款，關聯號碼存在被封禁（含永久封禁）風險；勿用無法承受損失的賬號，勿用於批量或自動化羣發。
環境與依賴¶
安裝前需滿足 README 所列條件：
| 項 | 要求 |
|---|---|
| DSH | 0.2.0 及以上（engines.dsh: ">=0.2.0"；README 註明曾在 0.2.2-rc.1 上測試） |
| Node.js | 22.5+（與 DSH 0.2.2 運行時要求一致） |
| 手機 | 已安裝 WhatsApp，電腦需能聯網；首次關聯需手機掃碼一次 |
核心功能（以 README 功能表爲準）¶
下面僅列出資料中標註爲已實現或明確說明的行爲。
關聯與在線
- 手機 WhatsApp → 關聯設備 掃 QR 碼完成一次關聯。
- 作爲獨立關聯設備，擁有各自的端到端加密連接。
- 在 WhatsApp 多設備規則下，主手機關機或離線時仍可收發（關聯設備約 14 天未使用會被 WhatsApp 解除關聯，插件會提示重新掃碼）。
消息與會話
- 文本、回覆、表情、@ 提及；聊天列表、搜索、未讀數、歷史同步、已讀回執、輸入狀態與在線狀態。
- 羣組：收發、參與者名稱、羣元數據。
媒體與文件
- 收發照片、視頻、音頻、文檔；支持下載媒體（媒體按需拉取，僅緩存在內存，不落盤明文）。
會話持久化
- 啓動之間安全保存關聯會話：AES-256-GCM 靜態加密。
明確未實現或僅佔位
- 語音 / 視頻通話：未實現（可顯示來電並 Reject；無法傳輸音視頻；頂欄通話按鈕禁用並附說明）。
- 狀態 / 動態、頻道 / 簡報、閱後即焚管理、支付等：未實現。
安裝與啓用¶
官方 README 提供三種路徑；不要憑倉庫名自行拼接 dsh plugin add github:owner/repo 作爲唯一安裝方式。
從本地打包的 tarball（推薦）¶
在已獲取源碼的目錄中執行：
cd dsh-whatsapp
npm install
npm pack # 產生 dsh-whatsapp-0.1.2.tgz
dsh plugin add "$PWD/dsh-whatsapp-0.1.2.tgz"
若插件管理器提示需要重啓，請重啓 DSH。成功後左側欄出現 WhatsApp 入口；若安裝時 DSH 已在運行且未出現入口，重啓一次進程（README 說明運行中主機可能緩存失敗的模塊導入）。
從 GitHub Release¶
從 latest release 下載 dsh-whatsapp-0.1.2.tgz，然後：
dsh plugin add /path/to/dsh-whatsapp-0.1.2.tgz
源碼目錄（開發）¶
git clone https://github.com/AJN-Tech/dsh-whatsapp.git
cd dsh-whatsapp
npm install
dsh plugin add "$PWD"
dsh plugin dev "$PWD" --host http://127.0.0.1:46739 # 推送 client.js，無需重啓
pnpm 與依賴構建腳本¶
@whiskeysockets/baileys 與 protobufjs 帶有 install 腳本；新版 pnpm 可能攔截，可在 DSH 插件管理 Web UI 中批准並重試，或使用 approved-builds 選項。手動 npm install 時，README 稱對這兩個包使用 npm install --ignore-scripts 即可。
安裝完成後重啓 DSH（按提示），打開側欄 WhatsApp 即可進入關聯流程。
首次關聯（典型用法）¶
- 在 DSH 左側欄打開 WhatsApp。
- 手機上：WhatsApp → 設置 → 關聯設備 → 關聯設備。
- 掃描 DSH 中顯示的 QR 碼，在手機上確認新設備。
- 界面切換到聊天列表並開始同步歷史。
該設備會出現在手機的關聯設備列表中，形態類似瀏覽器 / 桌面客戶端；同一賬號最多可關聯 四臺設備，本插件佔其一。
日常使用即在 DSH 全頁客戶端中收發消息、回覆、傳文件，與手機端保持實時同步；需要解除關聯時可在插件 Settings → Log out（或 Re-link）。
本地數據、加密與卸載¶
狀態目錄默認爲 ${DSH_HOME:-~/.dsh}/whatsapp/：
creds.enc 封存的設備憑證
keys.enc 封存的 Signal 會話 / 預密鑰等狀態
store.enc 封存的本地聊天與消息緩存
device.json 關聯元數據（重連非必需）
key.bin 主密鑰（口令模式下不存在）
salt.bin scrypt 鹽（僅口令模式）
- 默認用
key.bin（目錄0700、文件0600）保護上述封存文件。 - 啓動 DSH 前設置環境變量
DSH_WHATSAPP_PASSPHRASE時，用 scrypt 從口令派生密鑰，不寫入key.bin；更改或丟失口令需重新關聯。 - 插件不記錄消息正文、憑證、密鑰、QR、Cookie 或媒體字節；除 WhatsApp 服務器外無遙測外連。本地 API 掛在 DSH 已認證的 Web 服務下，路由與 DSH 一方路由同樣的連接 / 屬主校驗。
卸載插件不會自動刪除數據目錄：
dsh plugin remove dsh-whatsapp
rm -rf "${DSH_HOME:-$HOME/.dsh}/whatsapp"
更完整威脅模型見倉庫 docs/SECURITY.md。
適用場景與注意事項¶
較適合
- 已在用 DSH 0.2.0+，希望把個人 WhatsApp 收進 Harness 側欄，減少在瀏覽器 / 獨立客戶端間切換。
- 接受「關聯設備」能力邊界：要強依賴語音視頻通話、動態、頻道等，仍需使用手機或官方 WhatsApp Web / Desktop。
務必注意
- 非官方客戶端：自行承擔封號與服務條款風險；README 建議閱讀 docs/FEASIBILITY.md。
- 插件以當前 DSH 進程權限運行：安裝前應閱讀源碼與 MIT 許可證（
package.json），確認依賴與行爲可接受。 - 通話：來電可拒絕，不能在本插件內接通音視頻。
- 長期不用：約 14 天未使用關聯設備會被 WhatsApp .unlink，需重新掃碼。
DSH 生態強調「一切皆插件」；SkillHub 等爲社區目錄站點，與 DeepSeek / 幻方無官方從屬關係，本文所述安裝與能力均以倉庫 README 與 package.json 爲準。
結尾¶
dsh-whatsapp 把 WhatsApp 多設備關聯設備嵌進 DSH 左側欄：掃碼一次、實時同步、文件與媒體、本地 AES-256-GCM 會話封存，並如實標明通話與部分 WhatsApp 功能未實現。若你正在搭建 Harness 工作區並需要把常用 IM 收攏進同一界面，可按上文 tarball 或 Release 路徑安裝，並在接受非官方風險的前提下完成首次 QR 關聯。
