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_seq | int | 联系人序列号,0 = 全量同步 | [来自上次同步返回值] |
room_seq | int | 群序列号,0 = 全量同步 | [来自上次同步返回值] |
text
用户:帮我同步一下联系人
Agent:好的,正在全量同步联系人列表。
→ 调用 wx contact init,contact_seq=0, room_seq=0
Agent:联系人同步完成,共同步 356 个联系人,42 个群组。wx contact top — 置顶聊天
置顶或取消置顶某个联系人的聊天。Agent 需先通过 db contact search 查询 username。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
username | string | 联系人 username | [需查询] |
status | int | 0=取消置顶, 1=置顶 | 固定值 |
text
用户:置顶张三的聊天
Agent:好的,我先查找张三。
→ 调用 db contact search {"keyword":"张三"}
→ 获取 username="wxid_zhangsan"
→ 调用 wx contact top {"username":"wxid_zhangsan","status":1}
Agent:已置顶张三的聊天。wx contact get — 获取联系人详情
获取一个或多个联系人的详细信息。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
username_list | array | username 列表 | [需查询] |
room_username | string | 群 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_list | array | username 列表 | [需查询] |
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。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
username | string | 搜索内容 | [用户提供] |
from_scene | int | 来源场景,默认 0 | 可选 |
search_scene | int | 1=手机号, 2=微信号, 3=QQ号 | [用户提供] |
text
用户:搜索手机号 13800138000
Agent:好的,我来搜索这个手机号。
→ 调用 wx contact search {"username":"13800138000","search_scene":1}
Agent:搜索到用户:小明(wxid_xiaoming),是否添加为好友?wx contact add_friend — 添加好友
向目标用户发送好友申请。Agent 需先通过搜索获取目标 username。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
username | string | 目标 username | [需查询] |
verify_content | string | 验证消息 | [用户提供] 可选 |
scene | int | 添加来源场景,默认 3 | 可选 |
ticket | string | 验证票据 | 可选 |
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 区分不同操作。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
username | string | 目标 username | [需查询] |
opcode | int | 1=检查好友状态, 2=发送好友申请, 3=通过好友请求 | 固定值 |
ticket | string | 操作票据 | 可选 |
scene | int | 场景值 | 可选 |
text
用户:通过张三的好友验证
Agent:好的,正在通过张三的好友请求。
→ 调用 db contact search {"keyword":"张三"}
→ 获取 username="wxid_zhangsan"
→ 调用 wx contact verify {"username":"wxid_zhangsan","opcode":3}
Agent:已通过张三的好友请求,你们现在是好友了。wx contact remark — 修改好友备注
修改联系人的备注名。Agent 需先查询 username。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
username | string | 联系人 username | [需查询] |
remark | string | 新备注名 | [用户提供] |
text
用户:把李四的备注改成"客户-李四"
Agent:好的,我先查找李四。
→ 调用 db contact search {"keyword":"李四"}
→ 获取 username="wxid_lisi"
→ 调用 wx contact remark {"username":"wxid_lisi","remark":"客户-李四"}
Agent:已成功将李四的备注修改为"客户-李四"。wx contact del — 删除好友
从联系人列表中删除好友。Agent 应在执行前向用户确认此操作。
| 参数 | 类型 | 说明 | 来源 |
|---|---|---|---|
username | string | 联系人 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 后操作
- Agent 调用
db contact search按姓名查询,获取 username - 根据用户意图调用
wx contact get/wx contact remark/wx contact del等
通过手机号加好友
- Agent 调用
wx contact search搜索手机号 - Agent 调用
wx contact add_friend发送好友申请
通过好友验证
- Agent 调用
wx contact verify,opcode=3 通过好友请求
错误处理
- username 不存在:Agent 应提示用户该联系人不存在
- 已是好友:添加好友时 Agent 应提示用户双方已是好友
- 好友申请已发送:Agent 应告知避免重复发送申请