WhatsApp 助手 songjongdevsecops/wa-agent

wa-agent

为 DeepSeek Harness 智能体提供 WhatsApp 控制能力。

wa-agent 新增一组 46 个 wa_ 工具，让智能体可以操作 WhatsApp 账号：连接与配对、聊天与消息历史、文本、媒体、位置、联系人与投票、表情回应、编辑、删除、群组、通讯录、资料与隐私、在线状态，以及事件流。

这些工具与一个长期运行的 wa-agent bridge 通信，bridge 随本包一起发布。bridge（bridge/bridge.mjs，基于 Baileys 构建）持有 WhatsApp socket、认证状态和消息存储；它还暴露一个回环 HTTP 端点，供人查看二维码。插件通过 stdio 上的 JSON-lines RPC 与它通信；当由服务管理 bridge 时，则通过回环 HTTP 通信。

安装

一条命令即可安装插件、bridge 以及 bridge 的 npm 依赖：

npx @deepseek-ai/dsh plugin --profile web add github:songjongdevsecops/wa-agent

在 pnpm 11 及更新版本上，这条命令可能中途停下一次，因为 pnpm 默认阻止依赖的构建脚本（ERR_PNPM_IGNORED_BUILDS）。它会列出相关包名。在配置档的 pnpm-workspace.yaml 中批准这些包，然后重新执行同一条命令：

allowBuilds:
baileys: true # preinstall only checks the Node.js version
protobufjs: false # postinstall belongs to the protobufjs CLI, not the runtime

重启 harness 以加载 bundle（bundle 层在启动时读取，而不是在安装时）：

npx @deepseek-ai/dsh web

本包声明了 dsh.bundle.patch，因此 add 命令会把 wa-agent 追加到配置档清单的 dsh.profile.bundles 中。这一行就是唯一的启用方式。

检查已加载的行：

npx @deepseek-ai/dsh --profile web --dump-config | grep -A3 wa-agent

预期结构：

- id: wa-agent
name: wa-agent
config: {}

运行 bridge 无需额外步骤：插件在第一次调用工具时启动它（autoStart，默认 true），并在崩溃后重启它。接下来要做的第一件事是配对 WhatsApp 账号（见下一节）。

更新与卸载

update: re-run the add command, then restart the harness
npx @deepseek-ai/dsh plugin --profile web remove wa-agent # uninstall, then restart

环境要求

- Node.js ^22.19.0 || >=24.0.0。
- pnpm 在 PATH 中（npm install -g pnpm）；harness 用它管理配置档插件。
- DeepSeek Harness 本身，例如 npx @deepseek-ai/dsh web。
- 一个你能控制的 WhatsApp 账号，由你完成配对（见下文）。

配对

首次运行时 bridge 没有会话，会显示二维码。使用默认的 httpPort: 29141：

1. 打开 <http://127.0.0.1:29141/qr.png>。
2. 在手机上打开 WhatsApp > Linked devices > Link a device，扫描二维码。
3. 调用 wa_status（或让智能体调用）确认阶段和已配对的账号。

另一种方式：让智能体调用 wa_pair_sms_code，并传入完整的国际手机号。手机会收到 6 位验证码，在 WhatsApp > Linked devices > Link with phone number 中输入。

会话由 bridge 保存，本包从不保存。每次重连都会复用该会话，直到调用 wa_logout。配对按账号进行；你配对的是自己的账号。

用法

用自然语言向智能体提问：

- 「WhatsApp 状态如何？」
- 「显示这个聊天最近 20 条消息。」
- 「把这张图片发给 <recipient>，配文 。」
- 「创建名为 <name> 的群组，并加入 <participants>。」
- 「把这个聊天标记为已读。」

工具分组：

| 分组 | 工具 |
| 连接 | wa_status、wa_pair、wa_pair_sms_code、wa_restart、wa_logout |
| 聊天与消息 | wa_chats、wa_chat_messages、wa_send_text、wa_edit_message、wa_send_media、wa_send_location、wa_send_contact、wa_send_poll、wa_send_reaction、wa_pin_message、wa_delete_message、wa_forward_message、wa_download_media、wa_mark_read、wa_chat_modify |
| 群组 | wa_groups、wa_group_info、wa_group_create、wa_group_join、wa_group_update、wa_group_participants、wa_group_settings、wa_group_invite、wa_group_approvals、wa_group_leave |
| 联系人 | wa_contacts、wa_contacts_allow、wa_contacts_clear、wa_phone_check、wa_peer_info、wa_block_user、wa_blocklist、wa_save_contact |
| 账号 | wa_profile、wa_profile_update、wa_profile_picture、wa_privacy_get、wa_privacy_set、wa_status_post |
| 事件 | wa_events |

发送按收件人进行。插件不提供群发、抓取或涨粉相关的功能。

bridge 解析

插件按以下顺序查找 bridge：

1. 显式部署：插件配置中的 bridgeDir，或环境变量 WA_WORKSPACE。该目录可以直接放 bridge.mjs，也可以是包含 wa-agent/bridge.mjs 的工作区。
2. 本包内置的 bridge：bridge/bridge.mjs。
3. ~/wa-agent 下的历史独立部署（bridge.mjs 或 wa-agent/bridge.mjs）。

设置 bridgeDir（或 WA_WORKSPACE），继续使用你已经在跑的 bridge。一旦设置，它即为准：文件缺失会报 WA_BRIDGE_MISSING，而不是悄悄用内置 bridge 去连另一个状态目录。未设置时使用内置 bridge，运行时根目录在你的主目录，状态存放在 ~/wa-agent/。

配置

所有路径都可配置；默认值由你的主目录推导。补丁会替换该行的整份配置，所以要保留的键必须全部重写。

| 键 | 环境变量 | 默认值 | 含义 |
| bridgeDir | WA_WORKSPACE | 内置 bridge | bridge 部署目录；同时是状态的运行时根目录 |
| dataDir | | <root>/wa-agent/data | WhatsApp 认证状态目录覆盖 |
| mediaDir | | <root>/wa-agent/media | 下载媒体目录覆盖 |
| httpPort | | 29141 | 供二维码、健康检查和 RPC 使用的回环端口；设为 0 关闭 HTTP |
| autoStart | | true | 按需启动 bridge，崩溃后自动重启 |
| rpcTimeoutMs | | 120000 | 单次 RPC 超时 |

配置档补丁示例（~/.dsh/profiles/web/cordis.patch.yml）：

- id: wa-agent
config:
bridgeDir: '/absolute/path/to/wa-agent'
httpPort: 29141

配置里请用绝对路径；harness 不会展开 ~。不填 bridgeDir 就用内置 bridge。

如果已有 bridge 在监听 httpPort（比如由某个服务托管），插件会直接接管它，不再重复启动。设了 autoStart: false，调用工具前你得自己先启动 bridge：

WA_WORKSPACE="$HOME" WA_HTTP_PORT=29141 \
node "$HOME/.dsh/profiles/web/node_modules/wa-agent/bridge/bridge.mjs"

故障排查

- pnpm not found on PATH —— 执行 npm install -g pnpm，再重跑 add 命令。
- ERR_PNPM_IGNORED_BUILDS —— pnpm ≥ 11 拦截了 baileys 的 preinstall 和 protobufjs 的 postinstall。把 Install* 一节里的 allowBuilds 块加到配置档的 pnpm-workspace.yaml，再重跑 add 命令。
- WA_BRIDGE_MISSING —— 显式指定的 bridgeDir/WA_WORKSPACE 里没有 bridge.mjs 或 wa-agent/bridge.mjs。报错会列出它试过的路径。取消该设置即可改用内置 bridge。
- 没有二维码 —— 调用 wa_status。bridge 可能还在连接，或者 httpPort 是 0（HTTP 已关闭）。
- 手机上配对被拒 —— 上报的 WhatsApp Web 版本可能过旧。bridge 每次启动都会向 Baileys 要当前版本；如果仍然连不上，更新包和 Baileys。
- 插件装了但工具不出现 —— 重启 harness；bundle 层只在启动时读取。

安全与限制

- WhatsApp 会话就是一把私钥。 bridge 把它存在自己的数据目录（<root>/wa-agent/data，用内置 bridge 时是 ~/wa-agent/data）。绝不要提交它、粘贴进提示词，或复制进仓库。本包只附带 bridge 代码：不含会话、不含消息存储、不含二维码缓存，也不含媒体。
- HTTP 端点只走回环。 不要把 httpPort 暴露到网络：谁能连上它，谁就能操控这个账号。
- Baileys 是非官方的 WhatsApp Web 客户端。 自动化可能违反 WhatsApp 的服务条款，并让账号面临风险。请在自己的账号上、自行判断后使用。
- bridge 与 harness 同生共死。 它是插件的子进程，不是服务：harness 停了它就停，崩溃后插件会重启它。bridge 缺失会明确报错（WA_BRIDGE_MISSING 或 WA_BRIDGE_DOWN），绝不会假装成功。
- 手机离线。 已知会话的收发在手机离线时照常工作。首次联系人和群组可能需要手机在线来分发密钥；长时间离线可能导致设备解绑。
- Windows。 插件和桥接层都是纯 Node.js，只要 Node 能连上 WhatsApp，它们就能原生运行。路径和子进程都使用 Node 的跨平台 API。

许可证

MIT