# 通讯录

按姓名、拼音、英文名或别名在企业微信通讯录里找人，拿到姓名、职务、部门和邮箱。
它同时是**几乎所有「约人 / 发给某人 / 分派给某人」的前置**——助手得先在通讯录里找到这个人，才能把事情落到他头上。
它只查人，不遍历部门树、不列组织架构、不导出花名册。

## 你可以怎么说

> 「张三是谁？」
> 「帮我找一下李四」
> 「王五在哪个部门？」
> 「公司有几个叫张伟的？」
> 「张三的邮箱是多少？」
> 「Tony 是谁」（英文名、拼音、别名都能搜）

## 📋 验证状态

| 项 | 状态 |
|---|---|
| 按姓名搜索成员 | ✅ **已实测**（真实企业微信账号，命令层） |
| 同名消歧、多候选选择 | ⚠️ 未实测（实测账号里没有同名样本） |
| 「你说一句话 → 助手自动查完再往下做」的完整链路 | ⚠️ 未实测 |

**实测记录**（命令层，人工在真实账号上执行）：

```bash
wecom-cli contact users search --keywords '王轶'
```

返回解析出了真人「王轶」，带回了成员标识（内部使用）、所属部门（日冕科技）以及命中的关键词。
这一条同时印证了另一件事：**没有关键词就一定失败**——工具的帮助文本没有把关键词标成必填，
但实际不传就会被拒。助手知道这个坑，不会拿空请求去试。

## 能力清单

| 能做什么 | 命令 | 风险 |
|---|---|---|
| 按关键词搜索通讯录成员 | `wecom-cli contact users search` | 读取（隐私敏感：会返回邮箱、部门、职务） |

只有一个方法，但它是整套能力的枢纽。下面这些操作都要先经过它：

| 你想做的事 | 为什么要先查通讯录 |
|---|---|
| 约日程 / 开会时拉上某人 | 企业微信认的是成员标识，不认名字 |
| 把待办分派给某人 | 同上 |
| 把文档权限开给某人 | 同上 |
| 按「谁上传的」筛微盘文件 | 同上 |
| 按人（而不是邮箱地址）发邮件 | 同上 |

一次最多给 10 个关键词，彼此是「或」的关系（找三个人可以一次问完）。

## 注意事项

**只返回你有权限看到的人。** 助手是以你的身份工作的，搜到的是**你在通讯录里能看到的范围**，
不是企业全体成员。所以——

- **搜不到 ≠ 这个人不存在。** 助手的说法会是「在你的通讯录可见范围内没有找到」，而不是「公司里没这个人」。
  这两句话意思完全不同，别当成同一句。
- **数量不能当结论。** 就算搜到 3 个「张伟」，也不代表公司里只有 3 个张伟——**两种搜索模式都会截断结果**。
  返回里带「结果受限」提示时，助手会明确告诉你「这不是全部」。

**同名时它会让你选，不会替你猜。** 找到多个同名的人，助手会按接口返回的原始顺序，
用「序号 + 姓名 + 英文名 + 职务 + 部门」列出来让你挑（超过 5 位先给前 5 位）。
它不会用内部编号让你辨认，也不会自作主张挑一个"最像的"就往下发消息。

**「职务」不是「职位」。** 返回里的那个字段表达的是「负责人」这类管理身份，不是 job title。
助手不会说「张三的职位是负责人」。

**要完整名单要说清楚。** 说「找一下张三」走的是默认模式（按热度截断，返回最相关的几个）；
说「一共有几个张三」「列出所有叫李四的」这类**清点、穷举**意图，助手才会切到全量列表模式。

**这几件事它做不到**（会直接告诉你不支持，不会用多次搜索去拼凑）：

- 遍历部门树、按部门列出全部员工
- 拉组织架构图
- 导出全量花名册

**成员标识不会给你看。** 这个能力唯一的产出物就是内部成员标识，也正因如此最容易漏。
你问「他的 ID 是多少」，助手会说明这属于内部字段，然后换个方式帮你把事办成。

**不会拿旧结果凑合。** 人可能离职、改名、换部门，所以每次需要指定人的操作，助手都会当场重新解析一遍，
不复用上一轮记住的结果。

### 三条通用边界在本域怎么体现

1. **只能改它自己建的东西**——通讯录这一域是**纯读取**，不存在写入，所以这条不影响你查人。
   但它影响下游：查到人之后要把待办分派给他、或改他的文档权限时，边界就开始生效了。
2. **能力按品类逐项开通**——通讯录是独立的一个品类。未开通时第一次调用就会被拒，
   助手会把企业微信官方的开通指引原样转给你（含链接，一字不改），**然后停下，不重试**。
   实测账号是在 2026-09-03 单独补开了通讯录品类之后才搜通的。
3. **危险动作先问你**——查人本身不危险，助手直接查。但**批量搜集人员信息**（邮箱、部门、职务）时，
   它会先说明要查什么再执行。另外，身份证号、家庭住址、健康状况这类隐私字段，
   无论你怎么要求它都不会导出。

## 相关

- [03 消息与会话](03-消息与会话.md)——查到人之后给他发消息。注意：**发消息的目标不是从通讯录取的**，
  有额外一层限制，见那篇
- [05 日程](05-日程.md) / [06 会议](06-会议.md)——拉人进日程、会议前先查通讯录
- [07 待办](07-待办.md)——把待办分派给别人前先查通讯录
- [08 邮件](08-邮件.md)——按人名发邮件时先查邮箱
- [13 文档管理](13-文档管理.md)——给某人开文档权限前先查通讯录
- [99 风险与确认](99-风险与确认.md)——隐私敏感读取的处理规则