跳转到主要内容

juhecli-wx-contact 个微联系人

SKILL: juhecli-wx-contact — 管理微信个微联系人,包括同步、搜索、添加好友、验证、备注、置顶和删除等操作

使用案例

搜索微信好友张三给李四设置备注添加王五为好友

搜索手机号

>搜索手机号13800138000
// Agent 调用 wx contact search 按手机号搜索
$juhe-cli wx contact search --username 13800138000 --search_scene 1
{ "username": "wxid_xiaoming2024", "nickname": "小明", "avatar": "https://wx.qlogo.cn/xxx", "sex": 1, "signature": "" }

修改联系人备注

>修改张三备注为客户
// Agent 先通过 db contact search 查找张三的 username
$juhe-cli db contact search --keyword 张三
{ "username": "wxid_zhangsan", "nickname": "张三", "remark": "" }
// Agent 调用 wx contact remark 修改备注
$juhe-cli wx contact remark --username wxid_zhangsan --remark 客户
{ "success": true }

概述

个微联系人 SKILL 由 juhecli-wx-contact 提供,支持完整的微信联系人生命周期管理。 包括全量/增量同步、搜索联系人、添加/验证好友、修改备注、置顶和删除等 9 个命令。

大部分联系人操作需要先获取 username。推荐通过 db contact search 按姓名查询获得, 而非直接使用 wx contact search。当用户提到联系人姓名时,Agent 应先查后操作。

触发方式

当用户说出以下内容时,Agent 应触发此 SKILL:

  • "同步联系人"
  • "搜索微信号"
  • "加张三为好友"
  • "修改备注"
  • "删除好友"
  • "查看联系人详情"
  • "置顶聊天"
  • "通过好友验证"

SKILL 包

SKILL 名称说明
juhecli-wx-contact个微联系人管理 - 同步/置顶/详情/搜索/加好友/验证/备注/删除

命令详细说明与 Agent 交互示例

wx contact init — 同步联系人

同步微信联系人列表到本地数据库。首次使用传 0 为全量同步,后续使用上次返回的 seq 值做增量同步。

参数类型说明来源
contact_seqint联系人序列号,0 = 全量同步[来自上次同步返回值]
room_seqint群序列号,0 = 全量同步[来自上次同步返回值]
text
用户:帮我同步一下联系人
Agent:好的,正在全量同步联系人列表。
→ 调用 wx contact init,contact_seq=0, room_seq=0
Agent:联系人同步完成,共同步 356 个联系人,42 个群组。

wx contact top — 置顶聊天

置顶或取消置顶某个联系人的聊天。Agent 需先通过 db contact search 查询 username。

参数类型说明来源
usernamestring联系人 username[需查询]
statusint0=取消置顶, 1=置顶固定值
text
用户:置顶张三的聊天
Agent:好的,我先查找张三。
→ 调用 db contact search {"keyword":"张三"}
→ 获取 username="wxid_zhangsan"
→ 调用 wx contact top {"username":"wxid_zhangsan","status":1}
Agent:已置顶张三的聊天。

wx contact get — 获取联系人详情

获取一个或多个联系人的详细信息。

参数类型说明来源
username_listarrayusername 列表[需查询]
room_usernamestring群 username,仅查询群成员详情时使用可选
text
用户:查看李四的详细信息
Agent:好的,我来查找李四的详细信息。
→ 调用 db contact search {"keyword":"李四"}
→ 获取 username="wxid_lisi"
→ 调用 wx contact get {"username_list":["wxid_lisi"]}
Agent:李四的详细信息:
- 昵称:李四
- 微信号:lisi_wx
- 头像:[头像URL]

wx contact brief — 批量获取简要信息

批量获取多个联系人的简要信息,适用于需要一次性查询多个联系人的场景。

参数类型说明来源
username_listarrayusername 列表[需查询]
text
用户:查一下张三、李四和王五的信息
Agent:好的,我来批量查询。
→ 调用 db contact search 查询三人 username
→ 调用 wx contact brief {"username_list":["wxid_zhangsan","wxid_lisi","wxid_wangwu"]}
Agent:查询结果:
- 张三:在线
- 李四:在线
- 王五:离线

wx contact search — 搜索联系人

按手机号、微信号或 QQ 号搜索用户。注意:此命令用于搜索非好友用户,查找已有联系人建议用 db contact search

参数类型说明来源
usernamestring搜索内容[用户提供]
from_sceneint来源场景,默认 0可选
search_sceneint1=手机号, 2=微信号, 3=QQ号[用户提供]
text
用户:搜索手机号 13800138000
Agent:好的,我来搜索这个手机号。
→ 调用 wx contact search {"username":"13800138000","search_scene":1}
Agent:搜索到用户:小明(wxid_xiaoming),是否添加为好友?

wx contact add_friend — 添加好友

向目标用户发送好友申请。Agent 需先通过搜索获取目标 username。

参数类型说明来源
usernamestring目标 username[需查询]
verify_contentstring验证消息[用户提供] 可选
sceneint添加来源场景,默认 3可选
ticketstring验证票据可选
text
用户:用手机号 13800138000 搜索添加好友
Agent:好的,我先搜索这个手机号。
→ 调用 wx contact search {"username":"13800138000","search_scene":1}
→ 获取 username
→ 调用 wx contact add_friend {"username":"wxid_xxx","verify_content":"你好"}
Agent:好友申请已发送,请等待对方确认。

wx contact verify — 好友状态验证

检查好友状态、发送好友申请或通过好友请求。通过 opcode 区分不同操作。

参数类型说明来源
usernamestring目标 username[需查询]
opcodeint1=检查好友状态, 2=发送好友申请, 3=通过好友请求固定值
ticketstring操作票据可选
sceneint场景值可选
text
用户:通过张三的好友验证
Agent:好的,正在通过张三的好友请求。
→ 调用 db contact search {"keyword":"张三"}
→ 获取 username="wxid_zhangsan"
→ 调用 wx contact verify {"username":"wxid_zhangsan","opcode":3}
Agent:已通过张三的好友请求,你们现在是好友了。

wx contact remark — 修改好友备注

修改联系人的备注名。Agent 需先查询 username。

参数类型说明来源
usernamestring联系人 username[需查询]
remarkstring新备注名[用户提供]
text
用户:把李四的备注改成"客户-李四"
Agent:好的,我先查找李四。
→ 调用 db contact search {"keyword":"李四"}
→ 获取 username="wxid_lisi"
→ 调用 wx contact remark {"username":"wxid_lisi","remark":"客户-李四"}
Agent:已成功将李四的备注修改为"客户-李四"。

wx contact del — 删除好友

从联系人列表中删除好友。Agent 应在执行前向用户确认此操作。

参数类型说明来源
usernamestring联系人 username[需查询]
text
用户:删除好友王五
Agent:确认删除好友王五吗?此操作不可撤销。
用户:确认
Agent:正在删除...
→ 调用 db contact search {"keyword":"王五"}
→ 获取 username="wxid_wangwu"
→ 调用 wx contact del {"username":"wxid_wangwu"}
Agent:已成功删除好友王五。

参数来源说明

参数来源标记获取方式
username[需查询]db contact search 按姓名查询
remark[用户提供]用户直接提供备注内容
search_scene[用户提供]用户说明搜索方式(手机号=1 / 微信号=2 / QQ=3)
contact_seq / room_seq[来自上次同步返回值]上次 init 同步返回的 seq 值

典型工作流

按姓名查 ID 后操作

  1. Agent 调用 db contact search 按姓名查询,获取 username
  2. 根据用户意图调用 wx contact get / wx contact remark / wx contact del

通过手机号加好友

  1. Agent 调用 wx contact search 搜索手机号
  2. Agent 调用 wx contact add_friend 发送好友申请

通过好友验证

  1. Agent 调用 wx contact verify,opcode=3 通过好友请求

错误处理

  • username 不存在:Agent 应提示用户该联系人不存在
  • 已是好友:添加好友时 Agent 应提示用户双方已是好友
  • 好友申请已发送:Agent 应告知避免重复发送申请