wecomcli-contact · diff
git:20260818.7ceff2c to git:20260819.88dccb9
34 added, 104 removed. Audit A to A.
---
name: wecomcli-contact
- description: 何时用:仅当用户明确指向企业微信(查企微通讯录、给企微同事发消息前找人)时使用;泛指找人默认走本地联系人,不要误用。获取当前用户可见范围内的企微通讯录成员,支持按姓名/别名本地筛选匹配,返回 userid、姓名和别名。⚠️ 仅返回当前用户有权限查看的成员,非全量成员。
+ description: 何时用:仅当用户明确指向企业微信(查企微通讯录、给企微同事发消息前找人)时使用;泛指找人默认走本地联系人,不要误用。按姓名、拼音、英文名或别名搜索企微通讯录人员,返回 userid、部门和职务;适用于区分同名人员、获取 userid、列出全部同名人员。
metadata:
requires:
bins: ["wecom-cli"]
- cliHelp: "wecom-cli contact --help"
---
- # 通讯录成员查询技能
+ # 企业微信联系人搜索
- 获取当前用户可见范围内的通讯录成员，并在本地按姓名/别名进行筛选匹配。
+ > 执行任何 `wecom-cli` 命令前，必须先读取并完成 `wecomcli-shared` 技能的公共前置检查。
- ## 操作
+ 使用 `wecom-cli` 按关键词搜索企业微信通讯录中的人员。
- ### 1. 获取全量通讯录成员
+ ## 接口
- 获取当前用户可见范围内的所有企业成员信息：
+ 按关键词批量模糊搜索人员，一次最多 10 个关键词，返回命中 `users` 数组（姓名 / 英文名 / 职务 / 部门）。关键词可匹配的字段包括：姓名（用户名）、姓名拼音、英文名、别名，而不仅限于中文名和别名。
- **调用示例：**
+ ### 命令
```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
+ wecom-cli contact users search --json '<JSON 参数>'
```
- 4. 若找到多个匹配，展示候选列表请用户确认：
-
- ```
- 🔍 找到多个匹配成员，请确认您要查询的是哪位：
+ ### 参数
- 1. 张三（别名：Sam，ID：zhangsan）
- 2. 张三丰（别名：Sam2，ID：zhangsan2）
+ | 字段 | 类型 | 必填 | 默认值 | 语义 |
+ |---|---|---|---|---|
+ | `keywords` | string[] | 是 | — | 搜索关键词列表，可按姓名（用户名）/ 拼音 / 英文名 / 别名匹配，最多 10 个；多个关键词之间是 OR 关系 |
+ | `search_mode` | string | 否 | — | 搜索模式，默认不传该参数；仅当需要拿到完整人员名单时，才显式传 `"list"` |
- 请问您要查询的是哪一位？
- ```
+ - 默认（不传 `search_mode`）：返回最相关的候选结果，用于常规按名 / 拼音等查单个人的场景，绝大多数场景走此分支。
+ - 传 `search_mode = "list"`：返回全量命中列表。仅当用户明确要"完整名单"时才传，典型话术如"一共有几个张三 / 所有叫李四的人 / 列出全部同名 / 全部同名人员"等清点、穷举意图；此时不受"前 5 位"展示上限约束。
- > 注意：批量查询多个人员时只需调用一次 `get_userlist`，在本地对结果进行多次筛选，避免重复调用接口。
+ ### 返回
- ---
+ | 字段 | 类型 | 说明 |
+ |---|---|--|
+ | `users` | array | 命中的用户列表 |
+ | `users[].userid` | string | 用户唯一标识 |
+ | `users[].name` | string | 中文姓名 |
+ | `users[].alias` | string | 英文名 / 别名（可能为空） |
+ | `users[].email` | string | 邮箱（可能为空） |
+ | `users[].position` | string | 管理职务（如"负责人"），**不是**"职位"（可能为空） |
+ | `users[].matched_keywords` | string[] | 本条 user 命中的请求关键词|
+ | `users[].departments` | string[] | 所在部门路径列表（从大到小），主部门靠前 |
+ | `hint` | string | 结果限制提示（可能为空）：当某个关键词的命中结果因限制未完整返回时，接口会在此字段给出说明 |
+ | `users_count` | integer | `users` 数组元素数量 |
- ### 工作流 2：为其他功能提供 userid 转换
+ ### 使用规则
- 用户问："帮我发消息给张三"
+ - 歧义展示上限：同一关键词下候选超过 5 位时，只展示前 5 位（附姓名 / 英文名 / 职务等区分信息），告知用户"若目标不在其中可要求『查看更多』"，仅在用户明确要求时再展开下一批；
+ - 展示顺序：必须严格按照接口返回 `users` 数组的原始顺序展示，不得自行随机排序、重排或打乱次序。
+ - 结果限制提示：当返回中 hint 字段非空时，必须在回复中告知用户"当前返回内容有限，仅返回了部分结果"，并可结合 hint 内容说明受限原因。
- 1.
- ```bash
- wecom-cli contact get_userlist '{}'
- ```
- 获取全量成员
+ ## 缺少参数
- 2. 筛选 `name` 为"张三"的成员，确认 `userid`
- 3. 将 `userid` 传递给消息发送接口
+ > 必填参数缺失（未提供搜索关键词）且上下文无法推断时，用简洁自然语言向用户追问缺失信息，不得猜测默认值。