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