用途：把 WhatsApp 账号当作已链接的伴随设备（类似 WhatsApp Web）来驱动，基于异步 Python 库 pywhats（pre-alpha，仅支持文本与图片）。这是非官方多设备客户端，不是官方 WhatsApp Business / Cloud API。
主要能力：一次性扫码配对；发送 1:1 文本与图片（jpg/png/webp，≤16MB，可带说明文字）；获取群信息、向群发文本；标记已读（蓝勾）；设置全局在线状态与输入状态；通过 listen 以 JSON 行输出事件流接收消息与回执。
使用方式：CLI 入口为 scripts/wa.py，首次运行会自动引导创建受管 venv。配对：scripts/wa.py pair 显示 ASCII 二维码，在 WhatsApp → 已链接设备中扫描；凭据持久化到 $PYWHATS_HOME/<session>.session（及 .signal.db），后续命令静默复用会话，无需再次扫码。常用命令：scripts/wa.py send-text 15550001234 "hello"、scripts/wa.py send-image 15550001234 photo.jpg --caption hi、scripts/wa.py group-info 120363000000000000@g.us、scripts/wa.py group-send 120363000000000000@g.us "hi all"、scripts/wa.py mark-read 15550001234 MSGID [--sender JID]、scripts/wa.py presence available、scripts/wa.py typing 15550001234 composing [--media audio]、scripts/wa.py listen --read --events message,receipt。全局参数 --session NAME 需放在子命令之前，例如 scripts/wa.py --session work send-text 15550001234 "hi"。JID 寻址：裸手机号 15550001234 对应 15550001234@s.whatsapp.net，群组为 ...@g.us。
限制与注意：事件处理器在接收循环内联执行，切勿在处理器中直接 await send_*、mark_read、get_group_info、download_media 等调用，否则会死锁连接，应使用 asyncio.create_task(...)；listen 子命令已为 --read 处理该问题。若配对后立即提示设备被登出，属于 WhatsApp 设备回收机制而非技能失败，死会话会自动删除，按其提示恢复（移除已链接设备、等待 15–20 分钟、重新配对一次）。多账号通过 --session 与 PYWHATS_HOME 隔离。完整参考见 references/api.md（含全部 Client 方法、事件负载、JID 构造与 download_media 说明）。