juhecli-contact 企微联系人
juhecli-contact — 企微联系人管理：搜索、增量同步、批量查询、更新备注、好友管理
使用案例
搜索联系人张三同步我的联系人同意李四的好友申请给张三加备注技术总监把李四拉黑
搜索联系人张三
按关键词搜索联系人
>搜索联系人张三
$juhe-cli contact search --keyword 张三
{
"data": {
"list": [
{
"user_id": "xxxx-xxxx-xxxx",
"nickname": "张三",
"department": "技术部",
"position": "技术总监"
},
{
"user_id": "yyyy-yyyy-yyyy",
"nickname": "张三丰",
"department": "市场部",
"position": "市场经理"
}
]
}
}
同步联系人
增量同步联系人列表
>同步我的联系人
// 首次同步无需传入 seq，后续使用上次返回的 seq
$juhe-cli contact sync
{
"data": {
"seq": "1234567890",
"continue": true,
"list": [
{
"user_id": "xxxx-xxxx-xxxx",
"nickname": "张三",
"remark": "技术总监"
},
{
"user_id": "yyyy-yyyy-yyyy",
"nickname": "李四",
"remark": "产品经理"
}
]
}
}
// Agent 保存 seq 用于下次增量同步
概述
企微联系人 SKILL 提供全面的企业微信联系人管理功能。支持搜索联系人、增量同步、批量查询详细信息、 更新备注信息、同意好友申请、删除联系人和黑名单管理等操作。 是 AI Agent 管理企业通讯录的核心工具。
SKILL 定位
联系人搜索的返回值（user_id）是消息 SKILL 构建 conversation_id 的来源。 AI Agent 在发送消息前，通常需要先通过此 SKILL 查找联系人。
触发方式
用户可能会这样自然地表达需求：
- "搜索联系人张三"
- "同步联系人"
- "同意好友申请"
- "修改备注"
- "拉黑xxx"
- "删除联系人李四"
- "查看好友申请"
命令列表
| SKILL 名称 | 说明 |
|---|---|
juhecli-contact | 企微联系人管理 - 增量同步、批量查询、搜索、更新、删除、黑名单、同意申请 |
详细命令说明
搜索联系人 (contact search)
按关键词搜索联系人，返回匹配的用户列表。这是查找特定联系人的首选方式。用户只需提供搜索关键词。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
keyword | string | 是 | [用户提供] | 用户提供的搜索关键词（姓名、手机号等） |
type | number | 否 | [用户提供] | 用户可指定搜索类型：1-联系人，2-企业，默认 1 |
返回值
- 匹配的联系人列表（user_id、姓名、部门等）
user_id可用于构建消息的 conversation_id（格式：S:user_id）
增量同步联系人 (contact sync)
增量获取联系人变更数据。首次同步不需要提供 seq，后续同步 Agent 会自动使用上次返回的 seq 值。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
limit | number | 否 | [用户提供] | 用户可指定每次获取数量，默认 10 |
seq | string | 否 | [来自上次同步返回值] | 同步位置标识，首次无需提供 |
返回值
- 增量联系人列表
- 新的
seq值（Agent 保存用于下次同步） - 是否还有更多数据
增量同步
seq 参数来自上次同步的返回值。AI Agent 应自动保存此值，下次同步时传入。 用户无需关心此参数，Agent 会自动处理。批量获取联系人信息 (contact batch_get_info)
一次性获取多个联系人的详细信息。用户提供用户 ID 列表。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
user_list | array | 是 | [用户提供] | 用户提供的用户 ID 列表 |
批量获取企业联系人 (contact batch_get_corp)
批量获取企业联系人的信息。用户提供企业 ID 列表。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
corp_list | array | 是 | [用户提供] | 用户提供的企业 ID 列表 |
同意添加好友 (contact agree)
同意来自其他用户的好友申请。Agent 通常会先通过 contact sync_apply 获取待处理申请，再调用此命令。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
corp_id | string | 是 | [需查询] | 申请者企业 ID（来自好友申请列表） |
user_id | string | 是 | [需查询] | 申请者用户 ID（来自好友申请列表） |
同步好友申请 (contact sync_apply)
获取待处理的好友申请列表。用户说"查看好友申请"时 Agent 调用此命令。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
guid | string | 是 | [需查询] | 来自设备管理 SKILL |
更新联系人信息 (contact update)
更新联系人的备注、描述、标签等信息。用户只需告诉 Agent 要修改什么内容。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
user_id | string | 是 | [需查询] | Agent 通过搜索联系人获取 |
remark | string | 否 | [用户提供] | 用户提供的备注名称 |
company_remark | string | 否 | [用户提供] | 用户提供的公司备注 |
desc | string | 否 | [用户提供] | 用户提供的描述信息 |
label_info_list | array | 否 | [用户提供] | 用户提供的标签列表 |
phone_list | array | 否 | [用户提供] | 用户提供的电话列表 |
remark_url | string | 否 | [用户提供] | 用户提供的备注图片 URL |
删除联系人 (contact delete)
删除指定的联系人。此操作不可逆，Agent 应在执行前向用户确认。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
corp_id | string | 是 | [需查询] | Agent 通过搜索联系人获取 |
user_id | string | 是 | [需查询] | Agent 通过搜索联系人获取 |
删除不可逆
删除联系人后无法恢复，AI Agent 应在执行前向用户确认。
操作黑名单 (contact op_black_list)
添加或移除黑名单成员。用户只需说明要拉黑还是解除拉黑，以及目标联系人。
参数
| 参数 | 类型 | 必填 | 来源 | 说明 |
|---|---|---|---|---|
op_type | number | 是 | [用户提供] | 用户意图决定：1-添加黑名单，2-移除黑名单 |
username | string | 是 | [需查询] | Agent 通过搜索联系人获取 |
参数来源说明
| 参数 | 来源标记 | 获取方式 |
|---|---|---|
guid | [需查询] | Agent 通过 device list 获取 |
keyword | [用户提供] | 用户直接提供搜索关键词 |
seq | [来自上次同步返回值] | Agent 自动保存和传入，首次无需提供 |
user_list | [用户提供] | 用户直接提供 ID 列表 |
corp_list | [用户提供] | 用户直接提供企业 ID 列表 |
user_id | [需查询] | Agent 通过 contact search 或 contact sync 获取 |
corp_id | [需查询] | Agent 通过 contact search 或好友申请列表获取 |
username | [需查询] | Agent 通过 contact search 获取 |
op_type | [用户提供] | 根据用户意图判断（拉黑=1，解除=2） |
remark / desc / phone_list 等 | [用户提供] | 用户直接提供更新内容 |
Agent 交互示例
搜索联系人
text
用户: "搜索联系人张三"
AI: 好的，正在搜索...
[Agent 调用 contact search，keyword: "张三"]
找到以下匹配的联系人：
1. 张三 (技术部) — user_id: zhangsan
2. 张三丰 (市场部) — user_id: zhangsanfeng
请问您要找的是哪位？同步联系人
text
用户: "同步联系人"
AI: 好的，开始同步您的联系人列表...
[Agent 调用 contact sync，seq: ""（首次同步）]
已同步 50 个联系人。继续同步中...
[Agent 自动调用 contact sync，使用返回的 seq]
又同步了 30 个联系人。
同步完成，共同步 80 个联系人。同意好友申请
text
用户: "同意好友申请"
AI: 正在查看待处理的好友申请...
[Agent 调用 contact sync_apply]
您有 1 条待处理的好友申请：
- 李四（来自：A公司）
是否同意？
用户: "同意"
AI: [Agent 调用 contact agree]
已成功添加李四为好友。修改备注
text
用户: "把张三的备注改成'技术总监'"
AI: 好的，先搜索张三的联系人信息...
[Agent 调用 contact search，keyword: "张三"]
找到张三 (user_id: zhangsan)
[Agent 调用 contact update，user_id: "zhangsan", remark: "技术总监"]
备注已更新成功！张三的备注已改为"技术总监"。拉黑联系人
text
用户: "把李四拉黑"
AI: 好的，先搜索李四的信息...
[Agent 调用 contact search，keyword: "李四"]
找到李四 (username: lisi)
[Agent 调用 contact op_black_list，op_type: 1, username: "lisi"]
已将李四加入黑名单。典型工作流
搜索联系人后发送消息
- 用户说"给张三发消息"
- Agent 调用
contact search查找张三的 user_id - Agent 构建 conversation_id（
S:user_id） - Agent 调用
msg send_text发送消息
text
用户: "给张三发消息：你好"
AI: [Agent 调用 contact search，keyword: "张三"]
找到张三 (user_id: zhangsan)
[Agent 调用 msg send_text，conversation_id: "S:zhangsan", content: "你好"]
消息已发送给张三！管理好友申请
- Agent 定期调用
contact sync_apply检查新申请 - 向用户展示待处理申请列表
- 用户确认后，Agent 调用
contact agree同意申请
错误处理
| 错误 | 原因 | 处理方式 |
|---|---|---|
| 联系人不存在 | keyword 未匹配到结果 | 提示用户检查关键词或换词搜索 |
| user_id 无效 | ID 错误或联系人已删除 | 重新搜索获取正确的 user_id |
| 权限不足 | 无权操作该联系人 | 告知用户权限限制 |
| 同步失败 | seq 过期或网络问题 | 重新从空 seq 开始全量同步 |
性能建议
大量联系人建议使用增量同步 + 分批查询（每次 50-100 条），避免一次性加载过多数据。 搜索比全量同步更高效，优先使用 search 定位联系人。