使用 wacli 技能为 OpenAgent 打通 WhatsApp 消息发送与历史检索

原创2026-10-11 22:24:471,361 阅读
文章标签:人工智能大模型AI AgentRAG本地部署交互助手知识库工具调用后端前端语音

使用 wacli 技能为 OpenAgent 打通 WhatsApp 消息发送与历史检索

本篇文章以开源仓库 openagent 中 skills/wacli/SKILL.md 技能文档为核心,系统讲解如何借助 wacli CLI 让 OpenAgent 智能体在对话中直接发送 WhatsApp 文本/群组/文件消息、检索聊天记录并同步历史。读完本文,你将掌握 wacli 技能的全部命令用法、JID 与存储目录等关键参数,以及 OpenAgent 中技能从 skills/ 目录加载到注入系统提示词(load_skill)的完整实现链路。

技能定位:Agent 与 WhatsApp 之间的桥

skills/wacli/SKILL.md 是一个典型的 OpenAgent 技能(Skill)文件,其 front matter 中声明:

---
name: wacli
description: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI.
homepage: https://wacli.sh
metadata:
  {
    "emoji": "📱",
    "requires": { "bins": ["wacli"] }
  }
---

它解决的核心问题是:当用户在对话中提出"给某人发 WhatsApp 消息"、"同步我的 WhatsApp 历史"、"在聊天记录里检索某条信息"等诉求时,Agent 应优先调用本技能所描述的 wacli CLI 命令来完成操作,而不是凭模型记忆猜测。技能正文开篇即给出明确的触发约定:

Use wacli when the user asks you to message someone on WhatsApp or to sync/search WhatsApp history.

从元数据看,requires.bins 声明了运行本技能的前提——系统必须存在 wacli 可执行文件。这意味着在使用该技能前,需要先安装 wacli 并保证其在 PATH 中(仓库内不包含 wacli 二进制,技能只负责告诉 Agent 如何使用它)。仓库解析器 skillmd/skillmd.go 会把整段 metadata 作为原始文本存入 Skill.Metadata 字段,并显式提取其中的 emoji(📱);requires.bins 这类声明式依赖标注可供上层在触发技能时核对运行环境。

技能文件的加载原理:SKILL.md 如何进入 Agent 上下文

在深入命令细节之前,先理解这条技能在 OpenAgent 中的"生命周期",有助于你理解技能正文为何如此精炼:

  1. 目录扫描加载:服务启动时,object/init.go 的 initSkillsFromFolder() 会在可执行文件旁或当前工作目录下查找 skills/ 目录,对每个子目录调用 LoadSkill(dir);若磁盘上没有 skills/ 目录,则回退到嵌入的 skills 文件系统。

  2. 解析与入库:object/skill.go 的 LoadSkill 基于 skillmd.LoadFolder 读取 {dir}/SKILL.md 与可选的 references/ 目录,生成 Skill 对象(Owner 默认 admin,State 为 Active)并入库;技能名称缺失时会回退为目录名。解析细节(front matter 支持单引号/双引号/裸值、未闭合 front matter 的处理、references 目录只读取文件不读子目录等)都有对应测试用例验证,见 skillmd/skillmd_test.go。

  3. 注入系统提示词:当某个 Store 配置了 Skills 列表时,controllers/message_answer.go 会调用 object.GetSkillsCatalog(),把"技能使用规则 + 技能目录"追加进 store.Prompt。object/skill.go 生成的目录形如:

    ## Skills Usage Rules
    - If the user explicitly mentions a skill by name, you MUST call load_skill for that skill before answering.
    - If the user's request is clearly about a listed skill's domain, you MUST load that skill before giving procedural, policy, workflow, or step-by-step guidance.
    - Do not answer from general memory when a relevant listed skill exists but has not been loaded.
    - If the user asks what skills are available, answer from the catalog below instead of giving a generic summary of your broad abilities.
    
    ## Skills Catalog
    You have access to the following skills. Do not assume all details are already loaded. If a skill looks relevant, call the load_skill tool to load its full instructions before relying on it.
    
    - wacli description: Send WhatsApp messages to other people or search/sync WhatsApp history via the wacli CLI. | type: built-in
    
  4. 按需加载正文:Agent 判定 wacli 相关时,调用内置 load_skill 工具(tool/skill.go)加载完整正文。该工具由 object/merge_agent_tools.go 通过 NewLoadSkillBuiltin 注册,受 allowedSkillNames(即 Store 的 Skills 列表)约束,未启用会返回 skill is not enabled for this store;加载内容由 LoadSkillPromptContent 生成——正文 + 可选的 ## Available References 列表或指定 reference 全文。

这种"先目录、后正文、按需加载"的渐进式披露设计,正是技能正文可以短小精悍、聚焦于命令速查的原因所在。

安全约束:发送前的"确认"护栏

技能正文对发送类操作给出了三条硬性安全规则:

  • 必须获得明确的收件人 + 消息文本(Require explicit recipient + message text);
  • 发送前确认收件人与消息内容(Confirm recipient + message before sending);
  • 任何信息有歧义时,先提问澄清,不要擅自猜测后发送(If anything is ambiguous, ask a clarifying question)。

这三点对应到 Agent 的实操行为是:当用户说"帮我给小王发个消息"但未提供完整号码、或消息内容不明确时,Agent 应当先列出待确认信息向用户求证,而非直接执行 wacli send。这是技能文档中少有的"约束型"条款,也是 WhatsApp 这类强身份绑定 IM 渠道的合规底线。

认证与历史同步:三个命令搭建数据通道

wacli 的接入从认证开始,技能正文给出的命令组合是:

命令 作用
wacli auth QR 登录 + 首次同步(QR login + initial sync)
wacli sync --follow 持续同步模式(continuous sync),跟随新消息
wacli doctor 环境/连接诊断,排查登录与同步问题

建议的实际落地顺序为:

  1. 先执行 wacli doctor 检查 CLI 与运行环境是否就绪;
  2. 执行 wacli auth 完成二维码扫码登录,这一步同时触发首次全量同步,把历史聊天数据落到本地;
  3. 后续如需保持数据新鲜,启动 wacli sync --follow 做持续增量同步。

技能的 Notes 一节特别提醒:历史回填(backfill)要求手机保持在线,且结果是 best-effort(尽力而为)的——这源于 WhatsApp 个人账号的端到端机制,Agent 在执行回填后若发现部分消息缺失,属于预期内的行为,应向用户如实说明。

查找会话与消息:用查询缩小检索范围

同步完成后,Agent 需要先"找到目标会话",再"定位具体消息",技能正文给出了两级检索命令:

# 列出会话,按名称或号码过滤,最多返回 20 条
wacli chats list --limit 20 --query "name or number"

# 在指定会话(--chat <jid>)中搜索消息
wacli messages search "query" --limit 20 --chat <jid>

# 按时间窗口搜索,例如查找 2025 年内的 "invoice" 相关消息
wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31

参数语义拆解:

  • --limit:限制返回条数,防止检索结果淹没上下文窗口;
  • --query:会话过滤条件,可填联系人姓名或号码片段;
  • --chat <jid>:把搜索范围限定到某个具体会话(JID 格式见下文);
  • --after / --before:时间窗口过滤,配合日期格式 YYYY-MM-DD,适合"查某段时间内关于某事的聊天"这类典型场景。

历史回填:补齐不完整的历史

当本地历史存在缺口(例如仅部分同步、或需要更早的数据)时,使用回填命令:

wacli history backfill --chat <jid> --requests 2 --count 50

参数含义:

  • --chat <jid>:指定要回填的会话;
  • --requests 2:发起 2 次回填请求;
  • --count 50:每次请求拉取 50 条消息。

如 Notes 所述,回填需要手机在线,且"best-effort"意味着不保证每次请求都能取满 --count 条数。在 OpenAgent 场景中,Agent 应在执行前先通过 wacli chats list 确认 JID 存在,再回填,并在结果不足以回答问题时如实告知用户。

发送消息:文本、群组与文件

技能正文覆盖了三种发送形态,对应三类高频需求:

# 文本消息(个人号码,E.164 格式)
wacli send text --to "+14155551212" --message "Hello! Are you free at 3pm?"

# 群组消息(JID 形如 <id>@g.us)
wacli send text --to "1234567890-123456789@g.us" --message "Running 5 min late."

# 文件消息(附带 caption 说明文字)
wacli send file --to "+14155551212" --file /path/agenda.pdf --caption "Agenda"

要点:

  • --to 支持两类收件人:个人号码(带国家码的 E.164 格式,如 +14155551212)与群组 JID(如 1234567890-123456789@g.us);
  • --message 为文本内容,可直接使用自然语言,Agent 会原样传递;
  • --file 为待发送文件的路径,--caption 为文件配文,适合发送 PDF、图片等附件(例如把生成的 agenda.pdf 直接发给客户)。

所有发送操作都必须先满足上文"安全约束":确认收件人号码/群组无误、消息内容正确后,方可执行。

关键概念:JID、存储目录与结构化输出

技能正文的 Notes 一节集中解释了三个容易被忽略的核心概念:

1. JID(Jabber/WhatsApp ID)

WhatsApp 的会话标识符(JID)有两种形态,直接聊天与群组形态不同:

  • 直接聊天:<number>@s.whatsapp.net,如 +14155551212@s.whatsapp.net;
  • 群组:<id>@g.us,如 1234567890-123456789@g.us。

技能明确建议:不确定 JID 时用 wacli chats list 查询,而不是凭记忆拼写——这是避免"找不到会话/发错群"的最可靠手段。

2. 存储目录

本地数据默认存放在 ~/.wacli,可用 --store 参数覆盖路径。这意味着:

  • 认证凭证、同步索引与消息数据库都在该目录下;
  • 多环境/多账号场景可通过 --store 隔离数据;
  • Agent 排查问题时,可结合 wacli doctor 检查该目录的完整性与可读性。

3. --json 结构化输出

技能建议在程序解析场景下使用 --json 标志获取机器可读输出:

wacli chats list --limit 20 --json
wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31 --json

对于 OpenAgent 这类由 LLM 驱动的 Agent,结构化 JSON 比人类友好的文本输出更利于:

  • 可靠地提取 JID、消息时间戳、发件人等字段;
  • 降低解析歧义,避免模型"看走眼";
  • 支持后续的会话级二次检索(拿返回的 JID 再执行 messages search --chat <jid>)。

wacli 技能与项目内其他 WhatsApp 通道的关系

需要厘清的是:wacli 是个人账号级的本地 CLI 方案(扫码登录个人 WhatsApp 账号,读写个人历史);而仓库中 pipe/whatsapp.go 实现的是 WhatsApp Business API(Cloud API) 通道,基于 https://graph.facebook.com/v19.0,需要 accessToken / phoneNumberId / verifyToken,面向企业号的 webhook 收发。二者定位互补:

  • 面向个人日常消息的收发与历史检索 → 使用 wacli 技能;
  • 面向企业客服/自动化消息管道 → 使用 pipe 层的 WhatsAppPipe。

作为对比,web 前端 provider-setting.ts 中也登记了 WhatsApp Business 的连接配置(EAAxxx... 格式的 Access Token)。理解这条边界,能帮助你在对话中准确判断该让 Agent 走 wacli 命令,还是走企业 API 通道。

实战速查表

将技能正文的完整命令汇总如下,便于直接复制使用:

场景 命令
首次登录 + 同步 wacli auth
持续同步 wacli sync --follow
环境诊断 wacli doctor
列出会话 wacli chats list --limit 20 --query "name or number"
会话内搜索 wacli messages search "query" --limit 20 --chat <jid>
时间窗搜索 wacli messages search "invoice" --after 2025-01-01 --before 2025-12-31
历史回填 wacli history backfill --chat <jid> --requests 2 --count 50
发送文本 wacli send text --to "+14155551212" --message "Hello! Are you free at 3pm?"
发送群组消息 wacli send text --to "1234567890-123456789@g.us" --message "Running 5 min late."
发送文件 wacli send file --to "+14155551212" --file /path/agenda.pdf --caption "Agenda"

配套约束(贯穿所有命令):

  • 发送前必须确认收件人 + 内容,有歧义先提问;
  • 检索/解析场景优先加 --json;
  • 默认数据目录 ~/.wacli,可用 --store 覆盖;
  • 回填依赖手机在线,结果为 best-effort;
  • JID 拿不准时用 wacli chats list 确认。

小结

skills/wacli/SKILL.md 是一份"命令即文档"的高密度技能:以 auth/sync 建立数据通道,以 chats/messages 检索历史,以 history backfill 补齐缺口,以 send 完成文本、群组、文件的对外发送,再用安全约束与 JID/--json 等细节把误操作风险降到最低。配合 OpenAgent 从 object/init.go 目录扫描、object/skill.go 提示词注入到 tool/skill.go load_skill 按需加载的完整链路,它可以让 Agent 在"给客户发文件、查某段时间的聊天记录、群内报备迟到"等真实场景中直接完成任务,无需任何人工复制粘贴。

登录后查看全文
openagent