@@ -0,0 +1,574 @@
# 通讯录 (contact) 命令参考
> **CRITICAL — 命令合法性**：
> 不存在 `contact search`、`contact find`、`contact list`、`contact get`、`contact user find/list`。
> 构造命令前必须确认路径在下方「命令总览」中存在；不确定时，**根据意图对照下方「意图判断」选择正确命令**。
>
> **CRITICAL — 创建企业 vs 创建企业账号（必须优先匹配长模式）**：
> - 用户说"创建企业**账号** / 新建企业**账号** / 开通企业**账号** / **专属账号** / **企业登录账号**" → **`account create`**（创建企业专属登录账号）
> - 用户说"创建企业 / 新建企业 / 开通企业 / 初始化企业"（
> - **判断口径**：先检查 query 是否含"账号"关键词；含则必须路由 `account create`，
>
> **CRITICAL — 根部门**：钉钉根部门 `deptId=1`。单部门命令查根部门通常传 `--dept 1`；
## 命令总览
### user (人员查询)
#### 获取当前用户信息
```
Usage:
dws contact user get-self [flags]
Aliases:
get-self, self, me, whoami, current
Example:
dws contact user get-self
dws contact user self # 别名
dws contact user me # 别名
dws contact user whoami # 别名
dws contact user current # 别名
Notes:
- 触发词：我是谁 / 我的信息 / 我的 userId / 当前用户 / 本人 / self / me / whoami
- 顶层亦已挂 `dws contact get-self / user-self / current-user` 提示，误写会引导到正确命令
- **禁止**用 `dws contact user get --ids me/self/current` 代替（会报错）；正确用法是 `get-self` 或其别名
```
#### 按关键词搜索用户
```
Usage:
dws contact user search [flags]
Example:
dws contact user search --query "张三"
Flags:
--query string 搜索关键词 (必填)
Returns: (列表，每项包含以下字段)
name string 成员姓名
nick string 成员昵称
userId string 成员 ID（仅同事关系时返回）
title string 员工职位（仅同事关系时返回）
openDingTalkId string 当前用户视角下的目标用户唯一标识，不可跨用户共享；可用于发消息等好友关系场景的操作
```
> **CAUTION:** 多人同名时禁止默认选第一个 — `user search` 不返回部门信息，须追加 `contact user get --ids userId1,userId2,...` 获取部门/职位后请用户确认。详见 [08-directory.md](08-directory.md)「多命中」。
#### 按手机号搜索用户
```
Usage:
dws contact user search-mobile [flags]
Example:
dws contact user search-mobile --mobile 13800138000
Flags:
--mobile string 手机号 (必填)
```
#### 批量获取用户详情
```
Usage:
dws contact user get [flags]
Example:
dws contact user get --ids userId1,userId2
Flags:
--ids string 用户 ID 列表，逗号分隔 (必填)
Notes:
- **禁止**将 `self/me/current/whoami` 作为 userId 传入；查自己请用 `dws contact user get-self`
```
#### 邀请员工加入企业
```
Usage:
dws contact user invite [flags]
Example:
dws contact user invite --org-user-name "张三" --org-user-mobile "13800138000" --depts '[{"deptId":1}]'
Flags:
--org-user-name string 员工在企业内的名称 (必填)
--org-user-mobile string 员工手机号 (必填)
--depts string 员工所属部门列表 JSON 数组（可选），格式: [{"deptId":1}]
Notes:
- 通过手机号邀请单个员工加入当前企业
- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入
```
#### 修改员工信息
```
Usage:
dws contact user update [flags]
Aliases:
update, modify, edit
Example:
dws contact user update --user-id user001 --org-user-name "张三三"
dws contact user update --user-id user001 --depts '[{"deptId":1}]'
dws contact user update --user-id user001 --master-user-id manager001 --yes
Flags:
--user-id string 要修改的员工 userId (必填)
--org-user-name string 员工在企业内的名称（可选）
--depts string 员工所属部门列表 JSON 数组（可选），格式: [{"deptId":1}]
--master-user-id string 直属主管 userId（可选）
--yes 跳过二次确认（可选）
Notes:
- 至少需要一个修改项（--org-user-name、--depts 或 --master-user-id）
- 未加 --yes 时会交互式提示确认；脚本/自动化场景请显式带上 --yes
- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入
```
#### 更新自己的 profile 信息
```
Usage:
dws contact user update-self [flags]
Aliases:
update-self, update-me, update-self-profile, edit-self, modify-self
Example:
dws contact user update-self --nick "新昵称"
dws contact user update-self --avatar-file-id "xxxxxx" --yes
dws contact user update-self --nick "新昵称" --avatar-file-id "xxxxxx" --yes
Flags:
--nick string 新昵称（可选）
--avatar-file-id string 新头像在钉盘的 fileId（可选）
--yes 跳过二次确认（可选）
Notes:
- 更新当前登录用户自己的个人 profile 信息（昵称 / 头像），不是修改员工组织信息
- 至少需要一个修改项（--nick 或 --avatar-file-id）
- 头像 fileId 需要先上传头像到钉盘获取
- 未加 --yes 时会交互式提示确认；脚本/自动化场景请显式带上 --yes
- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入
```
### profile (用户档案 / 花名册)
#### 查询花名册有权限的字段列表
```
Usage:
dws contact user profile fields
Example:
dws contact user profile fields
Flags:
无
```
查询花名册有权限的字段列表，根据当前用户查询花名册有权限的字段列表。认证信息（corpId、optUserId）由系统自动注入，无需手动传入。
#### 查询员工花名册字段信息（个人档案）
```
Usage:
dws contact user profile get [flags]
Example:
dws contact user profile get --staff-id STAFF_ID
dws contact user profile get --staff-id STAFF_ID --fields fieldCode1,fieldCode2
Flags:
--staff-id string 查询员工 ID（可选）
--fields string 指定字段集合, 逗号分隔, 可通过 profile fields 获取（可选）
```
查询员工花名册字段信息，根据当前用户指定员工和字段列表，查询相应管理范围内员工的字段值信息。
花名册字段包含：试用/转正信息、个人/家庭信息、学历信息、银行卡/合同信息、紧急联系人和其他企业自定义信息。
> **与 `contact user get` 的区别**：
### dismission (离职员工)
#### 分页获取离职员工列表
```
Usage:
dws contact user dismission search [flags]
Example:
dws contact user dismission search
dws contact user dismission search --name "张三"
dws contact user dismission search --start 2026-01-01 --end 2026-03-31
dws contact user dismission search --depts 123456,789012 --page 1 --limit 50
Flags:
--name string 员工姓名，模糊搜索（可选）
--start string 离职日期查询范围开始，格式 YYYY-MM-DD（可选）
--end string 离职日期查询范围结束，格式 YYYY-MM-DD（可选）
--depts string 部门 ID 列表，逗号分隔（可选）
--hide-retirement 是否隐藏退休，默认 true（可选）
--hide-partner 是否隐藏合作伙伴，默认 false（可选）
--page int 页码，从 1 开始（可选，默认 1）
--limit int 页大小，200 以内（可选，默认 20）
```
查询离职员工列表，支持按员工姓名、离职日期范围、部门进行过滤。认证信息（corpId、optUserId）由系统自动注入，无需手动传入。
`--start` 和 `--end` 必须同时设置或同时不设置，不允许只传其中一个。
### dept (部门查询与管理)
#### 搜索部门
```
Usage:
dws contact dept search [flags]
Example:
dws contact dept search --query "技术部"
Flags:
--query string 搜索关键词 (必填)
```
#### 获取部门详情
```
Usage:
dws contact dept get-info [flags]
Example:
dws contact dept get-info --dept 12345
Flags:
--dept string 部门 ID (必填)
Notes:
- **钉钉根部门 `deptId=1`**；查根部门用 `--dept 1`
```
#### 查看子部门
```
Usage:
dws contact dept list-children [flags]
Example:
dws contact dept list-children --dept 1 # 枚举根部门下的一级部门
dws contact dept list-children --dept 12345 # 枚举指定部门的直属子部门
Flags:
--dept string 父部门 ID (必填)
Returns:
success bool 调用是否成功
result list 直属子部门列表，每项包含以下字段：
deptId int 子部门 ID
deptName string 子部门名称
Notes:
- **钉钉根部门 `deptId=1`**；查询一级部门请用 `--dept 1`
- 仅返回**直属**（直接下一级）子部门，不递归；需要逐层下钻请对子 deptId 继续调用本命令
- 受组织架构可见性控制：仅返回调用者**有权限查看**的子部门
- 父部门不可见或无子部门时返回 result=[] 空列表（非错误）
```
#### 查看部门成员
```
Usage:
dws contact dept list-members [flags]
Example:
dws contact dept list-members --ids 12345,67890
dws contact dept list-members --ids 1 # 根部门
Flags:
--ids string 部门 ID 列表，逗号分隔 (必填)
Notes:
- **钉钉根部门 `deptId=1`**；查根部门直属成员用 `--ids 1`
- 仅返回**本部门**直接成员，**不含下级部门**成员；需含下级请先 `dept list-children` 枚举子部门，再对子 deptId 分别/合并调用 `list-members`
- 受组织架构可见性控制；`--ids` 支持逗号分隔批量查询多个部门
- 跨层级成员展开见 [08-directory.md](08-directory.md) 的 `cross-level-dept-members` recipe
```
#### 创建部门
```
Usage:
dws contact dept create [flags]
Example:
dws contact dept create --name "新产品部" --create-dept-group true
dws contact dept create --name "研发一组" --parent 12345 --create-dept-group false --yes
Flags:
--name string 部门名称 (必填)
--parent string 父部门 ID（可选），不传默认根部门
--create-dept-group bool 是否创建部门群（必填）
--yes 跳过二次确认（可选）
Notes:
- 父部门不传时默认钉钉根部门 deptId=1
- --create-dept-group 必须显式指定 true 或 false
- 未加 --yes 时会交互式提示确认；脚本/自动化场景请显式带上 --yes
- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入
```
#### 更新部门
```
Usage:
dws contact dept update [flags]
Example:
dws contact dept update --dept 12345 --name "新部门名"
dws contact dept update --dept 12345 --name "新名称" --parent 67890 --yes
Flags:
--dept string 部门 ID (必填)
--name string 新部门名称（必填）
--parent string 新父部门 ID（可选）
--yes 跳过二次确认（可选）
Notes:
- --dept 为要更新的部门 ID，可通过 dept search 或 dept list-children 获取
- --name 必填；--parent 可选，未指定时只更新部门名称
- 未加 --yes 时会交互式提示确认；脚本/自动化场景请显式带上 --yes
- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入
```
### label (角色查询)
> **角色ID = labelId**：用户提到"角色ID"时，均指通讯录 label 系统中的角色ID，**不是部门ID也不是userId**。查角色成员用 `label list-members --id <角色ID>`，不要传给 `dept get-info` 或 `user get`。
#### 获取企业所有角色列表
```
Usage:
dws contact label list
Example:
dws contact label list
Flags:
无
Notes:
- 无需参数，返回当前企业全部角色列表（labelId、labelName等）
- 用于不知道准确角色名称时先浏览全部角色
- 典型场景：用户说“企业所有主管/查所有管理员/财务人员有哪些”→ 先 label list 浏览全部角色，匹配目标角色后 label list-members 获取成员
```
#### 根据角色名称查询角色
```
Usage:
dws contact label get [flags]
Example:
dws contact label get --names "管理员"
dws contact label get --names "管理员,财务"
Flags:
--names string 角色名称，逗号分隔 (必填)
Notes:
- 精确匹配角色名称，不支持模糊搜索
- 支持同时查询多个角色名称，逗号分隔
- 无需分页
```
#### 查询角色下的成员
```
Usage:
dws contact label list-members [flags]
Example:
dws contact label list-members --id 12345
Flags:
--id string 角色 ID (必填)
Notes:
- 根据角色ID直接查询成员列表；已有角色ID时直接用 `--id <labelId>`
- 不知道角色ID时：先 `dws contact label get --names "角色名"` 或 `dws contact label list` 获取 labelId
```
### org (企业管理)
#### 创建企业
```
Usage:
dws contact org create [flags]
Example:
dws contact org create --org-name "我的企业" --creator-username "张三"
Flags:
--org-name string 企业名称 (必填)
--creator-username string 创建者在企业内的名称，对应 creatorUsername (必填)
Notes:
- 创建一个新的钉钉企业，当前用户将成为该企业的创建者
- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入
```
### account (企业账号管理)
#### 创建企业专属账号
```
Usage:
dws contact account create [flags]
Example:
dws contact account create --org-user-name "张三" --login-id "zhangsan001" --org-user-mobile "13800138000" --email "zhangsan@example.com" --dept-ids "1,2,3" --send-pwd-via-sms
Flags:
--org-user-name string 员工在企业内的名称 (必填)
--login-id string 登录号 (必填)，请勿包含手机号等联系方式
--org-user-mobile string 员工手机号（可选）
--email string 邮箱（可选）
--dept-ids string 要加入的部门 ID 列表，逗号分隔（可选）
--send-pwd-via-sms 是否通过手机短信/邮件发送登录邀请（可选，默认 false）
Notes:
- 为当前企业创建一个专属登录账号
- 登录号请勿包含手机号，否则可能被运营商拦截短信
- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入
```
#### 更新企业账号用户信息
```
Usage:
dws contact account update [flags]
Aliases:
update, modify, edit
Example:
dws contact account update --user-id user001 --org-user-name "张三"
dws contact account update --user-id user001 --depts '[{"deptId":1}]'
dws contact account update --user-id user001 --nick "新昵称" --avatar-file-id "xxxxxx" --yes
Flags:
--user-id string 被修改企业账号的 userId (必填)
--org-user-name string 企业账号在企业内的员工姓名（可选）
--depts string 部门列表 JSON 数组（可选），格式: [{"deptId":1}]
--master-user-id string 直属主管 userId（可选）
--nick string 企业账号自身昵称，用于 profile 展示（可选）
--avatar-file-id string 企业账号头像在钉盘的 fileId（可选）
--yes 跳过二次确认（可选）
Notes:
- 更新指定企业账号用户的信息，不是修改普通员工信息
- 至少需要一个修改项（--org-user-name / --depts / --master-user-id / --nick / --avatar-file-id）
- 头像 fileId 需要先上传头像到钉盘获取
- 未加 --yes 时会交互式提示确认；脚本/自动化场景请显式带上 --yes
- 认证信息（corpId、optUserId）由系统自动注入，无需手动传入
```
## 意图判断
> **按搜索性质分流**：姓名模糊搜索、工号、部门、职责和上下级使用 [aisearch person](../../dingtalk-aisearch/references/aisearch.md)；完整手机号精确反查使用 `user search-mobile`；拿到 userId 后，以下详情、部门和角色场景再用 contact。
用户说"我是谁/我的信息/我的 userId/当前用户/本人/self/me/whoami" → `user get-self` （无需参数；禁止用 `user get --ids me/self` 代替）
用户需要 userId 给其他产品使用（发消息/建待办/约日程）→ `aisearch person` 按对应维度搜索
用户提供完整手机号并要求反查用户 → `user search-mobile --mobile "<完整手机号>"`
用户说"查用户详情/部门/主管/管理员" → `user get` （需 userId，返回组织管理信息）
用户说"修改员工/更新员工/改员工姓名/改员工部门/换部门/改直属主管/换主管/调整员工信息" → `user update` （需 userId；姓名 / 部门 / 主管至少改一项）
用户说"改昵称/改头像/更新我的资料/更新我的profile/更新我的个人信息/修改我的昵称" → `user update-self` （昵称 / 头像至少改一项；头像 fileId 需先上传钉盘）
用户说"邀请员工/添加员工/批量邀请/加人/新员工入职/拉人进企业" → `user invite` （需手机号 + 企业内名称 + 部门）
用户说"花名册字段/有哪些字段/字段列表" → `user profile fields`
用户说"花名册/员工档案/学历/家庭/银行卡/紧急联系人/合同" → `user profile get` （需 staffId，返回个人档案信息）
用户说"离职员工/离职名单/离职人员/已离职" → `user dismission search`
用户说"创建企业账号/新建企业账号/开通企业账号/专属账号/企业登录账号"（含"账号"）→ `account create` （需员工名称 + 登录号；手机号可选）
用户说"更新企业账号/修改企业账号/改企业账号信息/改企业账号姓名/改企业账号部门/改企业账号主管/改企业账号昵称/改企业账号头像"（含"账号"且含"改/更新/修改"）→ `account update` （需 userId；至少改一项）
用户说"创建企业/新建企业/开通企业/初始化企业"（不含"账号"）→ `org create` （需企业名称 + 创建者名称）
用户说"找部门/哪个部门" → `dept search`
用户说"部门详情/部门信息/部门多少人" → `dept get-info` （返回部门ID、部门名称、部门人数；需 deptId，若只有部门名称需先 `dept search` ）
用户说"子部门/下设部门/部门有哪些下级部门/枚举二级部门" → `dept list-children` （需父 deptId；只有部门名先 `dept search` ）
用户说"部门有谁/部门成员/人员名单" → `dept list-members` （需 deptId；**仅本部门不含下级**，含下级先 `dept list-children` 再合并查）
用户说"创建部门/新建部门/添加部门/成立部门/建部门" → `dept create` （需部门名；父部门可选，默认根部门）
用户说"更新部门/修改部门/改部门名/改部门名称/换部门名/改父部门/换上级部门" → `dept update` （需 deptId + name；
用户查询涵盖"角色"（主管/管理员/财务/HR/总经理等任意角色名）→ 统一走 `contact label` 链路，按下方决策树选命令：
- 不知道角色名 / 枚举所有角色 → `label list`
- 已知角色名，查ID或成员 → 先 `label get --names <名>` 拿ID，查成员再调 `label list-members --id <ID>` ； `label list` 模糊匹配**
- 已知角色ID 查成员 → `label list-members --id <ID>`
> [!IMPORTANT]
> **角色查询 3 步决策树**（不依赖字串匹配，按语义判定）：
> 1. 不知道角色名 / 要枚举所有角色（列出企业有哪些角色、每个角色的名称和ID、不确定叫什么角色、负责XX的人有哪些等） → `label list`
> 2. 已知角色名 要查角色ID → `label get --names`
> 3. 已知角色ID 要查成员 → `label list-members --id`
>
> 任何含"角色"一词的查询默认走 `contact label` 链路。**唯一例外**：终点是"某个人是否具备某权限"（如"张三是不是管理员"）→ `user get`。禁止路由到 `user profile fields`（那是花名册字段）、`dept list-members` 筛选、或 OA/chat 模块。
> [!IMPORTANT]
> **角色查人 vs 查某人的角色信息 — 判断口径**：先判断用户的终点是"人"还是"属性"：
> - 终点是**人**（
> - 终点是**属性**（
>
> 反例对照：
> - "管理员角色下都有哪些人" → `label get --names 管理员` → `label list-members`（终点=角色下的**人员列表**）
> - "我想知道管理员这个角色下都有谁" → `label get --names 管理员` → `label list-members`（终点=角色下的**人员列表**）
> - "张三是不是管理员" → `user get --ids <userId>`（终点=某个人的**属性**）
> - "查一下张三的管理员权限" → `user get --ids <userId>`（终点=某个人的**属性**）
> - "角色ID为55808858的角色下有哪些成员" → `label list-members --id 55808858`（已有角色ID直接查成员）
>
> **角色 = 通讯录 label**：用户提到"角色"（角色ID/角色成员/角色名称/企业角色/查角色下的人）时，均指通讯录组织角色，应走 `contact label` 链路。OA 审批只管审批流程（待审批/同意/拒绝），**不支持**查询角色成员；群角色(chat group-role)只管群内身份，不涉及企业组织角色。
用户说"我关注了谁/我的特别关注列表/我的星标联系人/特别关注的人有哪些" → `relation list-my-followings`
> [!IMPORTANT]
> **易混淆硬规则**：
>
> **禁止路由到本命令的场景**（query 中同时包含『关注/特别关注/星标』和以下任一消息域动词/名词时，必须路由到 [`chat message list-focused`](../../dingtalk-chat/references/chat.md)）：
> - 动词类：**发**了什么、**说**了什么/啥、**聊**了什么、**讲**了什么
> - 名词类：**消息**、**聊天**、**动态**、**最新内容**
>
> **判断口径**：先扫描 query 是否含上述动词/名词；含则路由到 `chat message list-focused`，
>
> 反例对照：
> - "我特别关注的人有哪些" → `relation list-my-followings`（终点=人员列表）
> - "我特别关注的人**最近发了什么消息**" → `chat message list-focused`（含"发""消息"）
> - "我关注的人**最近都说了啥**" → `chat message list-focused`（含"说"）
组合场景（多子部门、跨层级成员、强消歧）见 [08-directory.md ](08-directory.md )。
## 核心工作流
``` bash
# 1. 查看自己的信息 — 提取 userId
dws contact user get-self --format json
# 2. 按名字搜索人员 — 统一从 AI 搜问取得 userId/openDingTalkId
dws aisearch person --query "张三" --dimension name --format json
# 3. 查看部门结构 — 提取 deptId
dws contact dept search --query "技术部" --format json
# 4. 查看部门详情（部门ID、名称、人数）
dws contact dept get-info --dept <deptId> --format json
# 5. 查看直属子部门 — 提取子 deptId 列表
dws contact dept list-children --dept <父deptId> --format json
# 6. 查看部门成员
dws contact dept list-members --ids <deptId> --format json
# 7. 获取企业所有角色列表 — 不知道角色名时先浏览
dws contact label list --format json
# 8. 根据角色名称查询角色
dws contact label get --names "管理员" --format json
# 9. 查询角色下的成员
dws contact label list-members --id <labelId> --format json
# 10. 查询花名册有权限的字段列表
dws contact user profile fields --format json
# 11. 根据字段 code 查询指定员工的花名册信息
dws contact user profile get --staff-id <STAFF_ID> --fields fieldCode1,fieldCode2 --format json
# 12. 查询所有可见字段的花名册信息
dws contact user profile get --staff-id <STAFF_ID> --format json
# 13. 查询全部离职员工
dws contact user dismission search --format json
# 14. 按姓名/时间范围/部门筛选离职员工
dws contact user dismission search --name "张三" --format json
dws contact user dismission search --start 2026-01-01 --end 2026-03-31 --format json
dws contact user dismission search --depts 123456,789012 --hide-retirement= false --format json
# 15. 创建企业
dws contact org create --org-name "我的企业" --creator-username "张三" --format json
# 16. 创建企业专属账号
dws contact account create --org-user-name "张三" --login-id "zhangsan001" --org-user-mobile "13800138000" --email "zhangsan@example.com" --dept-ids "1,2,3" --send-pwd-via-sms --format json
# 17. 更新企业账号用户信息
dws contact account update --user-id user001 --org-user-name "张三三" --depts '[{"deptId":1}]' --master-user-id manager001 --nick "新昵称" --avatar-file-id "xxxxxx" --yes --format json
# 18. 邀请员工加入企业
dws contact user invite --org-user-name "张三" --org-user-mobile "13800138000" --depts '[{"deptId":1}]' --format json
# 19. 修改员工信息
dws contact user update --user-id user001 --org-user-name "张三三" --depts '[{"deptId":1}]' --master-user-id manager001 --yes --format json
# 20. 更新自己的 profile 信息
dws contact user update-self --nick "新昵称" --avatar-file-id "xxxxxx" --yes --format json
# 21. 创建部门
dws contact dept create --name "新产品部" --parent 12345 --create-dept-group true --yes --format json
# 22. 更新部门
dws contact dept update --dept 12345 --name "新部门名" --parent 67890 --yes --format json
```
## 上下文传递表
| 操作 | 提取 | 用于 |
|------|------|------|
| `user get-self/search` | `userId` | 其他产品中的 --users/--executor 参数 |
| `user get-self/search` | `orgAuthEmail` | mail message send 的 --to/--cc (跨产品) |
| `user get-self/search` | `userId` | profile get 的 --staff-id |
| `user profile fields` | `fieldCode` | profile get 的 --fields |
| `label list` | `labelId` / `labelName` | `label get --names` 或 `label list-members --id` |
| `label get` | `labelId` | `label list-members` 的 --id |
| `dept search/list-children` | `deptId` | dept get-info/list-children/update 的 --dept；
| `dept search/list-children` | `deptId` | dismission search 的 --depts |
| `dept create` | `deptId` | dept get-info/list-children/update 的 --dept；
## 注意事项
- `user get-self` 是获取 userId 的最快方式，其他产品的 --users/--executor 都需要 userId
- `user get --ids` 和 `dept list-members --ids` 都支持批量查询，逗号分隔
- `user get` 返回组织管理信息（部门、主管、管理员权限），`user profile get` 返回个人档案信息（学历、家庭、银行卡等），注意区分
- `user profile get` 的 `--staff-id` 可通过 `user get-self` 或 `aisearch person` 获取
- `user profile get` 的 `--fields` 可通过 `user profile fields` 获取可用字段 code 列表；不填则查询所有可见字段
- 建议先执行 `user profile fields` 获取可用字段列表，再根据需要的字段 code 执行 `user profile get`
- `user dismission search` 的 `--start` /`--end` 必须同时设置或同时不设置，不允许只传其中一个
- `user dismission search` 默认隐藏退休人员（`--hide-retirement` 默认 true），默认展示合作伙伴（`--hide-partner` 默认 false）
- `label list` 无需参数，适用于不知道准确角色名称的场景；当用户说“查所有主管/主管理员/财务”等角色类型人员时，优先 `label list` 列出企业全部角色，LLM 灵活匹配目标角色后调用 `label list-members`
- 角色类查询（主管、管理员、财务、HR 等任意角色）优先走 label 链路，而非 dept list-members 或 aisearch person；
- `label get` 是精确匹配角色名称，不支持模糊搜索；支持逗号分隔同时查询多个角色名称
- **`label get` 精确匹配无结果时的降级策略**：若 `label get --names "XX"` 返回空结果，必须降级调用 `label list` 获取全部角色列表，从中模糊匹配包含XX关键词的角色（如用户说"管理员"可匹配到"主管理员"和"子管理员"），再对匹配到的角色调用 `label list-members`
- `label list-members` 需要先通过 `label list` 或 `label get` 获取 labelId，再用 --id 查询角色下的成员
- `user update-self` 用于更新当前用户自己的昵称/头像；头像 fileId 需先上传头像到钉盘获取
- `account update` 用于更新企业账号用户信息；`--depts` 为 JSON 数组格式，头像 fileId 需先上传钉盘获取
## 自动化脚本
| 脚本 | 场景 | 用法 |
|------|------|------|
| [contact_dept_members.py ](../scripts/contact_dept_members.py ) | 按部门名称搜索并列出所有成员 | `python contact_dept_members.py --query "技术部"` |
