Files

T

2026-09-02 11:44:52 +08:00

29 KiB

Raw Permalink Blame History

通讯录 (contact) 命令参考

CRITICAL — 命令合法性：contact 二级子命令包括 user / dept / label / relation / org / account。不存在 contact search、contact find、contact list、contact get、contact user find/list。构造命令前必须确认路径在下方「命令总览」中存在；不确定时，根据意图对照下方「意图判断」选择正确命令。

CRITICAL — 创建企业 vs 创建企业账号（必须优先匹配长模式）：

用户说"创建企业账号 / 新建企业账号 / 开通企业账号 / 专属账号 / 企业登录账号" → account create（创建企业专属登录账号）

用户说"创建企业 / 新建企业 / 开通企业 / 初始化企业"（不含"账号"二字）→ org create（创建企业组织本身）

判断口径：先检查 query 是否含"账号"关键词；含则必须路由 account create，禁止路由 org create。

CRITICAL — 根部门：钉钉根部门 deptId=1。单部门命令查根部门通常传 --dept 1；dept list-members 传 --ids 1。dept search 精确命中企业根部门时可能返回 deptId=-1 哨兵，后续部门命令必须规范化为 1。不要传 self / me / root / 0。

命令总览

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「多命中」。

按手机号搜索用户

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 的区别：user get 返回组织管理信息（部门、主管、管理员权限），user profile 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；完整手机号精确反查使用 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；parent 可选）用户查询涵盖"角色"（主管/管理员/财务/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 步决策树（不依赖字串匹配，按语义判定）：

不知道角色名 / 要枚举所有角色（列出企业有哪些角色、每个角色的名称和ID、不确定叫什么角色、负责XX的人有哪些等） → label list

已知角色名要查角色ID → label get --names

已知角色ID 要查成员 → label list-members --id

任何含"角色"一词的查询默认走 contact label 链路。唯一例外：终点是"某个人是否具备某权限"（如"张三是不是管理员"）→ user get。禁止路由到 user profile fields（那是花名册字段）、dept list-members 筛选、或 OA/chat 模块。

Important

角色查人 vs 查某人的角色信息 — 判断口径：先判断用户的终点是"人"还是"属性"：

终点是人（"管理员角色有哪些人""管理员下都有谁""查XX角色的成员"）→ 角色维度查人，必须走 contact label 链路（label get/label list → label list-members），禁止通过 dept list-members 筛选 isAdmin 等字段替代

终点是属性（"张三是不是管理员""查某人的主管/管理员权限"）→ 已知 userId 查个人详情，走 user get（返回 isAdmin/leader 等字段）

反例对照：

"管理员角色下都有哪些人" → 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

易混淆硬规则：relation list-my-followings 只返回"我特别关注的人员列表"（一组 openDingTalkId），不返回任何消息内容。

禁止路由到本命令的场景（query 中同时包含『关注/特别关注/星标』和以下任一消息域动词/名词时，必须路由到 chat message list-focused）：

动词类：发了什么、说了什么/啥、聊了什么、讲了什么

名词类：消息、聊天、动态、最新内容

判断口径：先扫描 query 是否含上述动词/名词；含则路由到 chat message list-focused，不论 query 主语是否为"我特别关注的人"。

反例对照：

"我特别关注的人有哪些" → relation list-my-followings（终点=人员列表）

"我特别关注的人最近发了什么消息" → chat message list-focused（含"发""消息"）

"我关注的人最近都说了啥" → chat message list-focused（含"说"）

组合场景（多子部门、跨层级成员、强消歧）见 08-directory.md。

核心工作流

# 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 list-members 的 --ids
`dept search/list-children`	`deptId`	dismission search 的 --depts
`dept create`	`deptId`	dept get-info/list-children/update 的 --dept；dept list-members 的 --ids

注意事项

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 精确命中角色维度，返回完整名单
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	按部门名称搜索并列出所有成员	`python contact_dept_members.py --query "技术部"`

29 KiB Raw Permalink Blame History Unescape Escape