` | 否 | — | 当用户名搜索结果过多时，用于过滤的职位名称，与username一起收敛搜索结果 | | `--department-name <dept>` | 否 | — | 当用户名搜索结果过多时，用于过滤的部门名称，与username一起收敛搜索结果 | ### 使用准则 - **调用前先过门禁**：先完成本文顶部「调用前置门禁」的两问自检；若用户诉求只是"查询某人姓名/部门/职位/联系方式/是否存在"而无下游会议动作，**禁止**调用 `search`，按门禁话术回复用户。 - **`--username` 为必填**：缺失时命令会报错，必须先与用户确认要查找的用户名后再执行。 - **无结果时禁止臆测原因**：返回空统一按「未找到」处理，**不得推测人员状态**（如「可能已离职/未激活账号」）。标准话术：「在企业通讯录中未找到「<关键词>」。是否换一个关键词（全名/别名/英文名）再试？」 - **结果较多时建议追加过滤**：当仅按用户名查询返回的成员较多（如同名情况）时，建议结合 `--job-title` 或 `--department-name` 进一步过滤，提升匹配精准度。 - **唯一命中时仅返回 `open_id`**：当搜索结果**只有一条**时，命令仅返回该成员的 `open_id` 字段，**不会返回部门、职位等其他成员信息**；模型可直接将该 `open_id` 用于后续命令（如会议邀请、呼叫入会），无需也无法基于该响应向用户展示部门/职位等字段。 - **多结果必须由用户确认，禁止自行猜测**：当搜索返回 **多个匹配成员** 时（例如同名、同部门多人等），**严禁**模型基于职位、部门、入职时间等任何信息自行选择某一条结果继续后续操作。必须将候选成员的关键信息以清晰列表形式展示给用户，并明确询问"请确认要选择哪一位"，待用户明确指定后再继续执行后续命令（如发起会议邀请、呼叫、踢人等）。即便其中某条结果看起来"明显更匹配"，也必须等待用户确认，不得跳过该步骤。 - **隐私提示**：返回的数据可能包含工号、手机号、邮箱等敏感字段，输出给用户时仅展示与问题直接相关的关键信息（如姓名、部门、职位），不得擅自展示其他敏感字段。 --- ## lookup-by-phone — 按手机号查找用户 ```bash # 按单个手机号查找 tmeet contact lookup-by-phone --phones "13800138000" # 按多个手机号批量查找（逗号分隔，最多50个） tmeet contact lookup-by-phone --phones "13800138000,13900139000,13700137000" # 启用精简输出模式 tmeet contact lookup-by-phone --phones "13800138000" --compact # 美化格式输出 tmeet contact lookup-by-phone --phones "13800138000" --format json-pretty ``` ### 参数 | 参数 | 必填 | 默认值 | 说明 | |------|------|--------|------------------------------| | `--phones <numbers>` | ✅ | — | 要查找的手机号列表，用英文逗号分隔，最多支持50个号码，仅支持中国大陆手机号（11 位数字，首位 1，第 2 位 3-9） | ### 使用准则 - **调用前先过门禁**：先完成本文顶部「调用前置门禁」的两问自检；若用户诉求只是"通过手机号反查某人是谁 / 是否存在"而无下游会议动作（邀请入会 / 呼叫入会），**禁止**调用本命令，按门禁话术回复用户。 - **手机号格式校验**：系统会自动校验手机号格式，格式不正确时会报错。 - **批量查询上限**：单次最多 50 个手机号，仅用于批量解析 `open_id`。 - **返回内容**：仅取用 `open_id` 用于后续邀请/呼叫；**不得向用户展示手机号、邮箱、工号、部门、职位等任何其他字段**。 --- ## lookup-by-email — 按邮箱查找用户 ```bash # 按单个邮箱查找 tmeet contact lookup-by-email --emails "zhangsan@example.com" # 按多个邮箱批量查找（逗号分隔，最多50个） tmeet contact lookup-by-email --emails "zhangsan@example.com,lisi@example.com,wangwu@example.com" # 启用精简输出模式 tmeet contact lookup-by-email --emails "zhangsan@example.com" --compact # 美化格式输出 tmeet contact lookup-by-email --emails "zhangsan@example.com" --format json-pretty ``` ### 参数 | 参数 | 必填 | 默认值 | 说明 | |------|------|--------|------| | `--emails <addresses>` | ✅ | — | 要查找的邮箱地址列表，用英文逗号分隔，最多支持50个邮箱 | ### 使用准则 - **调用前先过门禁**：先完成本文顶部「调用前置门禁」的两问自检；若用户诉求只是"通过邮箱反查某人是谁 / 是否存在"而无下游会议动作（邀请入会 / 呼叫入会），**禁止**调用本命令，按门禁话术回复用户。 - **邮箱格式校验**：系统会自动校验邮箱格式，格式不正确时会报错。 - **批量查询上限**：单次最多 50 个邮箱，仅用于批量解析 `open_id`。 - **返回内容**：仅取用 `open_id` 用于后续邀请/呼叫；**不得向用户展示手机号、邮箱、工号、部门、职位等任何其他字段**。 --- ## 常见错误 | 错误现象 | 原因 | 解决方案 | |---------|------|---------| | `--username is required` | 缺少必填参数 | 补充 `--username` | | `--phones is required` | 缺少必填参数 | 补充 `--phones` | | `--emails is required` | 缺少必填参数 | 补充 `--emails` | | `invalid phone format` | 手机号格式不正确 | 检查手机号格式 | | `invalid email format` | 邮箱格式不正确 | 检查邮箱格式 | | `500263`（请输入更精确的关键词） | 关键词过宽 | **禁止原样重试**。①有职位/部门则追加 --job-title/--department-name；②否则向用户索取更完整信息；③能提供手机号/邮箱时改用 lookup-by-phone/lookup-by-email 精确反查 | | `500264`（username 关键词中文字符x<2 or x>8 ；英文/拼音 y<3 or >31） | username入参非法 | 中文 2 ≤ x ≤ 8 字、英文/拼音 3 ≤ x < 32 字符，单次仅 1 个关键词 | | `500265`（手机号参数非法） | phone入参非法 | 仅支持中国大陆手机号（11 位数字，首位 1，第 2 位 3-9） | | `500267`（手机号单次批量查询用户超过50个） | 批量查询时，单次最多查询50个 | 按单次50个进行分批查询 | | `500271`（email单次批量查询用户超过50个） | 批量查询时，单次最多查询50个 | 按单次50个进行分批查询 | | `500272`（email参数非法） | emails入参非法 | 使用合法的email | | `HTTP状态码 429` | 当前 CLI 使用过于频繁，请稍后再试 | 请稍后再试 | | `HTTP状态码 403` | 当前账号近期存在不符合使用规范的访问行为，已临时关闭访问权限，请联系管理员处理 | 请联系管理员处理 | | 返回结果中不包含查不到的用户信息 | 搜索结果为空（包含不在通讯录可见可搜范围、关键词未命中、未激活、已离职） | 未找到相关用户，请先在app/客户端-通讯录中添加该用户 | ## 参考 - [tmeet](../SKILL.md) — 命令总览与详情索引（各细节文档入口统一从此处进入） - [tmeet-meeting](tmeet-meeting.md) — 会议管理，可使用本文档返回的 `open_id` 邀请成员 - [tmeet-report](tmeet-report.md) — 会议报告，**`control kick` 的成员必须从 `report participants` 获取，而非本文档** - [tmeet-control](tmeet-control.md)

# tmeet contact — 通讯录 > **前置条件：** 先执行 `tmeet auth login` 完成登录授权。 > 🚫 **定位与适用场景硬约束**：本文档下的命令**不是人员信息查询接口**。`search` / `lookup-by-phone` / `lookup-by-email` 的唯一用途是"将用户名/手机号/邮箱解析为后续会议动作所需的 `open_id`"。返回的 `open_id` **仅可用于「会议邀请」（`meeting invitees-add` / `meeting invitees-replace` 等邀请命令）和「呼叫会外成员入会」（`control call`）**两类场景；**严禁作为 `control kick`（会中踢人）的成员来源**——`kick` 的成员必须从 `tmeet report participants` 命令的返回结果中获取（详见 [SKILL.md](../SKILL.md) 「安全规则」章节中「会中踢人（`control kick`）的成员来源硬约束」条目）。原因：本文档返回的是组织成员名录，并不代表这些成员已加入当前会议；且踢人需要区分普通成员 / Sip / Pstn 三类身份，只有 `report participants` 能准确提供。 > 🚦 **调用前置门禁**：在调用 `search` / `lookup-by-phone` / `lookup-by-email` 中的任一命令前，Agent **必须**先完成如下自检——① 本轮存在明确的下游会议动作（邀请入会 / 呼叫入会）？② 用户名/手机号/邮箱只是达成该动作的**手段**，而非"了解某人是谁"的**目的**？两问缺一即视为不满足使用前提。**若用户诉求止步于"查询某人姓名/部门/职位/联系方式/是否存在"**，严禁调用本文档任一命令，并使用以下话术回复：**"通讯录查询仅用于会议邀请或呼叫入会场景，无法单独用于查询某人的姓名、部门、职位或联系方式。如果您需要将该成员加入会议或呼叫其入会，我可以帮您操作。"** ## 目录 - [search — 搜索企业通讯录成员](#search--搜索企业通讯录成员) - [lookup-by-phone — 按手机号查找用户](#lookup-by-phone--按手机号查找用户) - [lookup-by-email — 按邮箱查找用户](#lookup-by-email--按邮箱查找用户) - [常见错误](#常见错误) - [参考](#参考) --- ## search — 搜索企业通讯录成员 > ⚠️ **`search` 返回的 `open_id` 是组织成员名录中的 ID，并不代表该成员已在某场会议中。请勿将本命令的输出作为 `control kick` 的成员来源；踢人场景请使用 `tmeet report participants` 拉取会中成员（详见 [SKILL.md](../SKILL.md) 「安全规则」章节中「会中踢人（`control kick`）的成员来源硬约束」条目）。** ```bash # 按用户名搜索 tmeet contact search --username "张三" # 用户名 + 职位过滤（用于命中结果较多时进一步缩小范围） tmeet contact search \ --username "张三" \ --job-title "工程师" # 用户名 + 部门过滤 tmeet contact search \ --username "张三" \ --department-name "研发部" # 同时使用职位 + 部门过滤 tmeet contact search \ --username "张三" \ --job-title "工程师" \ --department-name "研发部" ``` ### 参数 | 参数 | 必填 | 默认值 | 说明 | |------|------|--------|-------------------------------------------------------| | `--username ` | ✅ | — | 要搜索的用户名，中文 2 ≤ x ≤ 8 字、英文/拼音 3 ≤ x < 32 字符，单次仅 1 个关键词 | | `--job-title ` | 否 | — | 当用户名搜索结果过多时，用于过滤的职位名称，与username一起收敛搜索结果 | | `--department-name <dept>` | 否 | — | 当用户名搜索结果过多时，用于过滤的部门名称，与username一起收敛搜索结果 | ### 使用准则 - **调用前先过门禁**：先完成本文顶部「调用前置门禁」的两问自检；若用户诉求只是"查询某人姓名/部门/职位/联系方式/是否存在"而无下游会议动作，**禁止**调用 `search`，按门禁话术回复用户。 - **`--username` 为必填**：缺失时命令会报错，必须先与用户确认要查找的用户名后再执行。 - **无结果时禁止臆测原因**：返回空统一按「未找到」处理，**不得推测人员状态**（如「可能已离职/未激活账号」）。标准话术：「在企业通讯录中未找到「<关键词>」。是否换一个关键词（全名/别名/英文名）再试？」 - **结果较多时建议追加过滤**：当仅按用户名查询返回的成员较多（如同名情况）时，建议结合 `--job-title` 或 `--department-name` 进一步过滤，提升匹配精准度。 - **唯一命中时仅返回 `open_id`**：当搜索结果**只有一条**时，命令仅返回该成员的 `open_id` 字段，**不会返回部门、职位等其他成员信息**；模型可直接将该 `open_id` 用于后续命令（如会议邀请、呼叫入会），无需也无法基于该响应向用户展示部门/职位等字段。 - **多结果必须由用户确认，禁止自行猜测**：当搜索返回 **多个匹配成员** 时（例如同名、同部门多人等），**严禁**模型基于职位、部门、入职时间等任何信息自行选择某一条结果继续后续操作。必须将候选成员的关键信息以清晰列表形式展示给用户，并明确询问"请确认要选择哪一位"，待用户明确指定后再继续执行后续命令（如发起会议邀请、呼叫、踢人等）。即便其中某条结果看起来"明显更匹配"，也必须等待用户确认，不得跳过该步骤。 - **隐私提示**：返回的数据可能包含工号、手机号、邮箱等敏感字段，输出给用户时仅展示与问题直接相关的关键信息（如姓名、部门、职位），不得擅自展示其他敏感字段。 --- ## lookup-by-phone — 按手机号查找用户 ```bash # 按单个手机号查找 tmeet contact lookup-by-phone --phones "13800138000" # 按多个手机号批量查找（逗号分隔，最多50个） tmeet contact lookup-by-phone --phones "13800138000,13900139000,13700137000" # 启用精简输出模式 tmeet contact lookup-by-phone --phones "13800138000" --compact # 美化格式输出 tmeet contact lookup-by-phone --phones "13800138000" --format json-pretty ``` ### 参数 | 参数 | 必填 | 默认值 | 说明 | |------|------|--------|------------------------------| | `--phones <numbers>` | ✅ | — | 要查找的手机号列表，用英文逗号分隔，最多支持50个号码，仅支持中国大陆手机号（11 位数字，首位 1，第 2 位 3-9） | ### 使用准则 - **调用前先过门禁**：先完成本文顶部「调用前置门禁」的两问自检；若用户诉求只是"通过手机号反查某人是谁 / 是否存在"而无下游会议动作（邀请入会 / 呼叫入会），**禁止**调用本命令，按门禁话术回复用户。 - **手机号格式校验**：系统会自动校验手机号格式，格式不正确时会报错。 - **批量查询上限**：单次最多 50 个手机号，仅用于批量解析 `open_id`。 - **返回内容**：仅取用 `open_id` 用于后续邀请/呼叫；**不得向用户展示手机号、邮箱、工号、部门、职位等任何其他字段**。 --- ## lookup-by-email — 按邮箱查找用户 ```bash # 按单个邮箱查找 tmeet contact lookup-by-email --emails "zhangsan@example.com" # 按多个邮箱批量查找（逗号分隔，最多50个） tmeet contact lookup-by-email --emails "zhangsan@example.com,lisi@example.com,wangwu@example.com" # 启用精简输出模式 tmeet contact lookup-by-email --emails "zhangsan@example.com" --compact # 美化格式输出 tmeet contact lookup-by-email --emails "zhangsan@example.com" --format json-pretty ``` ### 参数 | 参数 | 必填 | 默认值 | 说明 | |------|------|--------|------| | `--emails <addresses>` | ✅ | — | 要查找的邮箱地址列表，用英文逗号分隔，最多支持50个邮箱 | ### 使用准则 - **调用前先过门禁**：先完成本文顶部「调用前置门禁」的两问自检；若用户诉求只是"通过邮箱反查某人是谁 / 是否存在"而无下游会议动作（邀请入会 / 呼叫入会），**禁止**调用本命令，按门禁话术回复用户。 - **邮箱格式校验**：系统会自动校验邮箱格式，格式不正确时会报错。 - **批量查询上限**：单次最多 50 个邮箱，仅用于批量解析 `open_id`。 - **返回内容**：仅取用 `open_id` 用于后续邀请/呼叫；**不得向用户展示手机号、邮箱、工号、部门、职位等任何其他字段**。 --- ## 常见错误 | 错误现象 | 原因 | 解决方案 | |---------|------|---------| | `--username is required` | 缺少必填参数 | 补充 `--username` | | `--phones is required` | 缺少必填参数 | 补充 `--phones` | | `--emails is required` | 缺少必填参数 | 补充 `--emails` | | `invalid phone format` | 手机号格式不正确 | 检查手机号格式 | | `invalid email format` | 邮箱格式不正确 | 检查邮箱格式 | | `500263`（请输入更精确的关键词） | 关键词过宽 | **禁止原样重试**。①有职位/部门则追加 --job-title/--department-name；②否则向用户索取更完整信息；③能提供手机号/邮箱时改用 lookup-by-phone/lookup-by-email 精确反查 | | `500264`（username 关键词中文字符x<2 or x>8 ；英文/拼音 y<3 or >31） | username入参非法 | 中文 2 ≤ x ≤ 8 字、英文/拼音 3 ≤ x < 32 字符，单次仅 1 个关键词 | | `500265`（手机号参数非法） | phone入参非法 | 仅支持中国大陆手机号（11 位数字，首位 1，第 2 位 3-9） | | `500267`（手机号单次批量查询用户超过50个） | 批量查询时，单次最多查询50个 | 按单次50个进行分批查询 | | `500271`（email单次批量查询用户超过50个） | 批量查询时，单次最多查询50个 | 按单次50个进行分批查询 | | `500272`（email参数非法） | emails入参非法 | 使用合法的email | | `HTTP状态码 429` | 当前 CLI 使用过于频繁，请稍后再试 | 请稍后再试 | | `HTTP状态码 403` | 当前账号近期存在不符合使用规范的访问行为，已临时关闭访问权限，请联系管理员处理 | 请联系管理员处理 | | 返回结果中不包含查不到的用户信息 | 搜索结果为空（包含不在通讯录可见可搜范围、关键词未命中、未激活、已离职） | 未找到相关用户，请先在app/客户端-通讯录中添加该用户 | ## 参考 - [tmeet](../SKILL.md) — 命令总览与详情索引（各细节文档入口统一从此处进入） - [tmeet-meeting](tmeet-meeting.md) — 会议管理，可使用本文档返回的 `open_id` 邀请成员 - [tmeet-report](tmeet-report.md) — 会议报告，**`control kick` 的成员必须从 `report participants` 获取，而非本文档** - [tmeet-control](tmeet-control.md) — 会中控制，`call` 可用本文档 `open_id`；`kick` 不可