wecomcli-contact · diff
git:20260728.ff7bff1 to git:20260818.7ceff2c
1 added, 1 removed. Audit A to A.
---
name: wecomcli-contact
- description: 通讯录成员查询技能，获取当前用户可见范围内的通讯录成员，支持按姓名/别名本地筛选匹配。返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员，非全量成员。
+ description: 何时用:仅当用户明确指向企业微信(查企微通讯录、给企微同事发消息前找人)时使用;泛指找人默认走本地联系人,不要误用。获取当前用户可见范围内的企微通讯录成员,支持按姓名/别名本地筛选匹配,返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员,非全量成员。
metadata:
requires:
bins: ["wecom-cli"]
cliHelp: "wecom-cli contact --help"
---
# 通讯录成员查询技能
获取当前用户可见范围内的通讯录成员，并在本地按姓名/别名进行筛选匹配。
## 操作
### 1. 获取全量通讯录成员
获取当前用户可见范围内的所有企业成员信息：
**调用示例：**
```bash
wecom-cli contact get_userlist '{}'
```
**返回格式：**
```json
{
"errcode": 0,
"errmsg": "ok",
"userlist": [
{
"userid": "zhangsan",
"name": "张三",
"alias": "Sam"
},
{
"userid": "lisi",
"name": "李四",
"alias": ""
}
]
}
```
**返回字段**：`errcode`（0=成功）、`errmsg`、`userlist[]`（每项含 `userid`/`name`/`alias`，alias 可能为空）。
---
### 2. 按姓名/别名搜索人员
`get_userlist` 返回全量成员后，在本地对结果进行筛选匹配：
- **精确匹配**：`name` 或 `alias` 与关键词完全一致，直接使用
- **模糊匹配**：`name` 或 `alias` 包含关键词，返回所有匹配结果
- **无结果**：告知用户未找到对应人员
**搜索示例：**
用户问："帮我找一下张三是谁？"
1. 调用 `get_userlist` 获取全量成员
2. 在 `userlist` 中筛选 `name` 或 `alias` 包含"张三"的成员
3. 返回匹配结果
---
## 注意事项
- `get_userlist` 返回的是当前用户**可见范围内**的成员，需经过可见性规则过滤，不一定是全公司所有人员；返回字段仅包含 `userid`、`name`（姓名）和 `alias`（别名）
- ⚠️ **超过 10 人时接口将报错**：若 `userlist` 返回成员数量超过 10 人，视为异常，应立即停止处理并向用户说明：
> 当前通讯录可见成员数量超过了本技能支持的上限（10 人）。
> 本技能仅适用于可见范围较小的场景，无法在大范围通讯录中使用。
> 建议缩小可见范围后重试，或通过其他方式查询目标人员。
- `userid` 是用户的唯一标识，在需要传递用户 ID 给其他接口时使用此字段
- `alias` 字段可能为空字符串，搜索时需做空值判断
- 若搜索结果有多个同名人员，需将所有候选人展示给用户选择，不得自行决定
---
## 典型工作流
### 工作流 1：查询人员信息
用户问："帮我查一下 Sam 是谁？"
1. 调用 get_userlist 获取全量成员（示例见上）
2. 在结果中筛选 `alias` 为 `Sam` 或 `name` 包含 `Sam` 的成员
3. 若找到唯一匹配，直接展示结果：
```
📇 找到成员：
- 姓名：张三
- 别名：Sam
- 用户ID：zhangsan
```
4. 若找到多个匹配，展示候选列表请用户确认：
```
🔍 找到多个匹配成员，请确认您要查询的是哪位：
1. 张三（别名：Sam，ID：zhangsan）
2. 张三丰（别名：Sam2，ID：zhangsan2）
请问您要查询的是哪一位？
```
> 注意：批量查询多个人员时只需调用一次 `get_userlist`，在本地对结果进行多次筛选，避免重复调用接口。
---
### 工作流 2：为其他功能提供 userid 转换
用户问："帮我发消息给张三"
1.
```bash
wecom-cli contact get_userlist '{}'
```
获取全量成员
2. 筛选 `name` 为"张三"的成员，确认 `userid`
3. 将 `userid` 传递给消息发送接口