---
id: daily-wecomcli-contact
name: "wecomcli-contact"
url: https://skills.yangsir.net/skill/daily-wecomcli-contact
author: wecomteam
domain: ai-data-management-analysis
tags: ["enterprise", "contact-management", "automation", "hr", "productivity-tools"]
install_count: 8100
rating: 4.50 (20 reviews)
github: https://github.com/wecomteam/wecom-cli
---

# wecomcli-contact

> 获取企业通讯录成员信息并本地筛选，支持姓名/别名匹配，自动处理同名候选

**Stats**: 8,100 installs · 4.5/5 (20 reviews)

## Before / After 对比

### 通讯录查询速度

**Before**:

在企业管理后台或手机应用中查找成员信息，需要手动搜索、记住userid，同名时难以区分，重复查询效率低

**After**:

一次性获取全量通讯录并本地缓存，支持姓名/别名快速匹配，同名时自动展示候选列表供选择

| Metric | Before | After | Change |
|---|---|---|---|
| 查询时间 | 15秒/次 | 2秒/次 | -87% |

## Readme

# wecomcli-contact

# 通讯录成员查询技能

`wecom-cli` 是企业微信提供的命令行程序，所有操作通过执行 `wecom-cli` 命令完成。

获取当前用户可见范围内的通讯录成员，并在本地按姓名/别名进行筛选匹配。

## 操作

### 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 包含关键词），唯一结果
直接使用，向用户展示结果

模糊匹配，多个结果
展示候选列表，请用户选择

无匹配结果
告知用户未找到对应人员

Weekly Installs1.0KRepository[wecomteam/wecom-cli](https://github.com/wecomteam/wecom-cli)GitHub Stars1.6KFirst Seen6 days agoSecurity Audits[Gen Agent Trust HubPass](/wecomteam/wecom-cli/wecomcli-contact/security/agent-trust-hub)[SocketPass](/wecomteam/wecom-cli/wecomcli-contact/security/socket)[SnykPass](/wecomteam/wecom-cli/wecomcli-contact/security/snyk)Installed ongithub-copilot1.0Kgemini-cli1.0Kcodex1.0Kkimi-cli1.0Kantigravity1.0Kcursor1.0K

---
*Source: https://skills.yangsir.net/skill/daily-wecomcli-contact*
*Markdown mirror: https://skills.yangsir.net/api/skill/daily-wecomcli-contact/markdown*