| name | wecomcli-contact |
| description | 通讯录成员查询技能，获取当前用户可见范围内的通讯录成员，支持按姓名/别名本地筛选匹配。返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员，非全量成员。 |
通讯录成员查询技能
wecom-cli 是企业微信提供的命令行程序，所有操作通过执行 wecom-cli 命令完成。
获取当前用户可见范围内的通讯录成员，并在本地按姓名/别名进行筛选匹配。
Wegent 本地运行
- 当前
SKILL.md 所在目录的 ../.. 是插件根目录。首次调用前，macOS/Linux 运行 sh "<插件根目录>/scripts/ensure-wecom-ready.sh"；Windows 运行 powershell -NoProfile -ExecutionPolicy Bypass -File "<插件根目录>\scripts\ensure-wecom-ready.ps1"。
- 下文的
wecom-cli ... 是逻辑命令。实际执行时，macOS/Linux 使用 sh "<插件根目录>/scripts/run-wecom-cli.sh" ...；Windows 使用 powershell -NoProfile -ExecutionPolicy Bypass -File "<插件根目录>\scripts\run-wecom-cli.ps1" ...。
- 未授权时初始化脚本会打开企业微信官方网页并显示二维码，只在需要用户扫码、企业权限或内网/VPN 时暂停。不要要求用户在对话中粘贴 Bot ID、Secret 或 Access Token，也不要读取、记录或上传
~/.config/wecom 中的本地认证配置。
操作
1. 获取全量通讯录成员
获取当前用户可见范围内的所有企业成员信息：
调用示例：
wecom-cli contact get_userlist '{}'
返回格式：
{
"errcode": 0,
"errmsg": "ok",
"userlist": [
{
"userid": "zhangsan",
"name": "张三",
"alias": "Sam"
},
{
"userid": "lisi",
"name": "李四",
"alias": ""
}
]
}
返回字段说明：
| 字段 | 类型 | 说明 |
|---|
errcode | integer | 返回码，0 表示成功 |
errmsg | string | 错误信息 |
userlist | array | 用户列表 |
userlist[].userid | string | 用户唯一 ID |
userlist[].name | string | 用户姓名 |
userlist[].alias | string | 用户别名，可能为空 |
2. 按姓名/别名搜索人员
get_userlist 返回全量成员后，在本地对结果进行筛选匹配：
- 精确匹配：
name 或 alias 与关键词完全一致，直接使用
- 模糊匹配：
name 或 alias 包含关键词，返回所有匹配结果
- 无结果：告知用户未找到对应人员
搜索示例：
用户问："帮我找一下张三是谁？"
- 调用
get_userlist 获取全量成员
- 在
userlist 中筛选 name 或 alias 包含"张三"的成员
- 返回匹配结果
注意事项
-
get_userlist 返回的是当前用户可见范围内的成员，需经过可见性规则过滤，不一定是全公司所有人员；返回字段仅包含 userid、name（姓名）和 alias（别名）
-
⚠️ 超过 10 人时接口将报错：若 userlist 返回成员数量超过 10 人，视为异常，应立即停止处理并向用户说明：
当前通讯录可见成员数量超过了本技能支持的上限（10 人）。
本技能仅适用于可见范围较小的场景，无法在大范围通讯录中使用。
建议缩小可见范围后重试，或通过其他方式查询目标人员。
-
userid 是用户的唯一标识，在需要传递用户 ID 给其他接口时使用此字段
-
alias 字段可能为空字符串，搜索时需做空值判断
-
若搜索结果有多个同名人员，需将所有候选人展示给用户选择，不得自行决定
-
若 errcode 不为 0，说明接口调用失败，需告知用户错误信息（errmsg）
典型工作流
工作流 1：查询人员信息
用户问："帮我查一下 Sam 是谁？"
wecom-cli contact get_userlist '{}'
获取全量成员列表
- 在结果中筛选
alias 为 Sam 或 name 包含 Sam 的成员
- 若找到唯一匹配，直接展示结果：
📇 找到成员：
- 姓名：张三
- 别名：Sam
- 用户ID：zhangsan
- 若找到多个匹配，展示候选列表请用户确认：
🔍 找到多个匹配成员，请确认您要查询的是哪位：
1. 张三（别名：Sam，ID：zhangsan）
2. 张三丰（别名：Sam2，ID：zhangsan2）
请问您要查询的是哪一位？
工作流 2：为其他功能提供 userid 转换
用户问："帮我发消息给张三"
wecom-cli contact get_userlist '{}'
获取全量成员
- 筛选
name 为"张三"的成员，确认 userid
- 将
userid 传递给消息发送接口
工作流 3：批量查询多个人员
用户问："帮我查一下张三和李四分别是谁？"
wecom-cli contact get_userlist '{}'
获取全量成员列表
- 分别筛选"张三"和"李四"的匹配结果
- 汇总后一并展示
注意：只需调用一次 get_userlist，在本地对结果进行多次筛选，避免重复调用接口。
快速参考
接口说明
| 接口 | 用途 | 输入 | 返回 |
|---|
get_userlist | 获取可见范围内全量通讯录成员 | 无 | 用户列表（userid、name、alias） |
本地筛选策略
| 场景 | 策略 |
|---|
| 精确匹配（name 或 alias 完全一致） | 直接使用，无需用户确认 |
| 模糊匹配（name 或 alias 包含关键词），唯一结果 | 直接使用，向用户展示结果 |
| 模糊匹配，多个结果 | 展示候选列表，请用户选择 |
| 无匹配结果 | 告知用户未找到对应人员 |
