通过 QR 配对将 WhatsApp 连接到 xiantong，支持 self-chat 与附件
通过 QR 配对将 WhatsApp 连接到 xiantong，支持 self-chat 模式、Baileys worker 架构与附件。
非官方集成。 WhatsApp 适配器使用 Baileys，它是社区维护的 WhatsApp Web 客户端实现，并非官方 WhatsApp Business API。请主要用于个人自动化，并自行评估平台限流或会话失效风险。
WhatsApp 集成使用与 WhatsApp Web 相同的 QR 码配对流程，并在 子进程 worker 中运行，以隔离 Baileys 的全局状态。
配对账号#
- 打开 设置 → 消息，点击 WhatsApp 卡片上的 连接。
- 在弹窗中扫描 QR 码：手机打开 WhatsApp → 设置 → 已关联设备 → 关联设备。
- 等待连接。对话框会显示
Connected as <your-name>。Baileys 会话保存在：
~/.xiantong/workspaces/{workspaceId}/messaging/whatsapp-session/
请保留此目录；删除它会强制重新配对。
无需第二部手机。 默认启用 self-chat 模式，您可以给自己的 WhatsApp 账号发消息来驱动 xiantong。
第一次对话#
Self-chat（推荐）#
- 在 WhatsApp 中打开与自己的聊天。
- 发送
/new。 - worker 会识别来自自己的消息，创建会话并绑定聊天。Agent 回复会带有 🤖 前缀，方便与您自己的消息区分。
- 正常聊天即可。请不要移除回复中的 🤖 前缀，因为它也用于避免 worker 把自己的回复再次当作输入。
第二部手机或联系人#
- 让联系人向配对的号码发送
/new。 - worker 创建并绑定新会话。
- 后续该联系人的消息会驱动绑定会话，直到发送
/unbind。
Self-chat 模式#
启用后（默认），您从同一 WhatsApp 账号的其他设备给自己的 JID发送的消息，会被视为入站消息并路由到绑定会话。
| 行为 | 作用 |
|---|---|
| 回复前缀 | worker 发给自己的所有出站消息会带 🤖 前缀，用于过滤自身回声，避免无限循环 |
| 已发送 ID 跟踪 | worker 会跟踪自己发送的消息 ID，把相关回复作为上下文处理 |
| LID 支持 | WhatsApp 新的 long-ID 联系人格式会在映射到当前账号时识别为“自己” |
如只想由单独联系人驱动会话，可在 设置 → 消息 → WhatsApp 中关闭 self-chat。
附件#
支持照片、文档、语音、视频和音频。单个附件上限为 20 MB。文件会作为带原始 MIME 类型的 FileAttachment 进入会话。
审批通道#
WhatsApp 绑定的 approvalChannel 始终为 app。当会话处于 请求编辑 模式且 Agent 请求执行敏感命令时，审批提示只会显示在桌面应用中，而不会在 WhatsApp 中以内联方式完成。
计划提交#
当 Agent 在 探索模式 下通过 SubmitPlan 提交计划时，WhatsApp 用户会收到文本提示：
📝 A plan is ready for review. Open the desktop app to inspect and approve it.
目前不能从 WhatsApp 直接接受或拒绝计划；审批需要在桌面应用中完成。
架构概览#
WhatsApp 适配器较特殊，因为 Baileys 持有大量全局状态，并预期自己是进程中的唯一实例。为避免影响主进程，xiantong 在独立 worker 中运行它：
Electron 主进程 <── NDJSON over stdio ──> messaging-whatsapp-worker
messaging-gateway Baileys 事件循环
- worker 以 Electron 内置 Node 运行。
- 通信使用 newline-delimited JSON over stdio。
- worker 退出时，主进程会在超时时间内尽量清空待发送队列。
故障排除#
QR 码显示但一直无法连接#
确认手机在线、WhatsApp 已更新。必要时从菜单中断开连接并重新配对。
“Disconnect” 与 “Forget Device”#
当前菜单文案为 Disconnect。它会清除本地 Baileys 会话，下次连接时需要重新配对。
手机能看到 Agent 回复，但桌面 WhatsApp 看不到#
WhatsApp 多设备同步可能有延迟。打开手机 WhatsApp 等待 10–15 秒，或从手机发送一条消息触发同步。
退出应用时丢失待发送消息#
worker 退出时会尝试清空待发送队列。强制结束应用可能丢失正在发送中的 Agent 回复，但 WhatsApp 侧已持久化的入站消息不会丢失。
Self-chat 未识别#
确认 self-chat 已启用。如账号刚迁移到 LID，旧绑定可能仍引用旧 JID，请解绑后重新绑定。
无法从 WhatsApp 接受计划#
这是当前设计限制。请在桌面应用中打开并批准计划。