# 通讯录与找人

## 能做什么

| 场景 | 说明 |
| --- | --- |
| 查自己 | 姓名、userId、部门、组织、角色、手机号 |
| 按姓名找人 | 语义搜索，支持模糊；多候选会列出让你选 |
| 按手机号反查 | 完整手机号 → 用户 |
| 按部门列成员 | 本部门 / 含下级 |
| 角色与标签 | 企业角色列表、角色下成员 |
| 花名册档案 | 学历、家庭、银行卡、合同等（需 HR 权限） |
| 离职员工 | 离职记录查询 |

## 两个产品域的分界（最容易搞错的地方）

钉钉把「找人」拆成了两个产品，助手会按下面的判据自动分流：

| 你的输入 | 走哪个 | 为什么 |
| --- | --- | --- |
| 完整手机号 | `contact` 精确查询 | 手机号是唯一键，直接反查 |
| 已经有 userId | `contact` 补详情 | 有主键就不需要搜索 |
| 姓名、工号、职责、上下级关系 | `aisearch` 语义搜索 | 模糊匹配，可能多候选 |

**语义搜索拿到 userId 后会回到 `contact` 补详情**——这是官方推荐的链路，助手不会用搜索结果里的残缺字段直接作答。

## 实际用法

### 查自己

```
我在钉钉里是谁？
```

真机实测助手执行了两条命令：

```bash
dws schema --cli-path "contact +me" --compact --format json   # 先确认参数
dws contact +me --format json                                  # 再执行
```

返回姓名、userId、部门、组织、角色、手机号、企业邮箱。

> **注意这个模式**：助手先查 schema 确认参数再执行，而不是凭记忆拼命令。官方 CLI 会随版本变化，这一步能避免用过时的参数。

### 按姓名找人

```
帮我找一下姓王的同事，列出来。
```

走 `aisearch +search-person --query <关键词>`。

⚠️ **flag 是 `--query` 不是 `--name`**——`--name` 被显式屏蔽了自动归一化，写错会报 `blocked_flag`。助手会先查 schema 所以不会踩，但你手工调用时要注意。

**多候选时助手会列出让你选，不会默认取第一个。** 这是硬规则：搞错人的代价（发错消息、约错会）远大于多问一句。

### 按手机号反查

```
查一下手机号 138xxxxxxxx 是谁
```

走 `contact` 而不是 `aisearch`——完整手机号是精确查询。

## 边界

- 语义搜索的维度限于 `all` / `name` / `department` / `position` / `duty` / `supervisor` / `subordinate` / `phone` / `jobNumber`，`all` 不能与其他维度并用
- 花名册档案需要 HR 相关权限，无权限时助手会说明缺哪个权限点，不会换个命令硬试
- 返回结果只包含**你有权限查看的**成员，不是全量通讯录
