Lark Contact

lark-contact

选哪个命令

user 身份和 bot 身份是两条完全独立的路径。先确定当前身份,再按下表选命令:

已知 open_id 只是想发消息 / 排日程,不必经过 contact —— 直接 `lark-im` / `lark-calendar`。

典型场景

# 找张三给他发消息:先搜,确认 open_id,再发
lark-cli contact +search-user --query "张三" --has-chatted --as user
lark-cli im +messages-send --user-id ou_xxx --text "Hi!"

搜索命中多条且后续操作有副作用(发消息、邀请会议等),把候选列给用户挑;不要擅自选第一条。

注意事项

• 41050 / Permission denied 受当前身份的可见范围限制(两条命令都可能遇到)。换 bot 身份或让管理员调整可见范围,细节见 `lark-shared`。
• 跨租户用户(is_cross_tenant=true)多数业务字段为空字符串,这是飞书可见性规则,下游做空值兜底。
• ID 类型:默认 open_id。+get-user 可改 --user-id-type union_id|user_id;+search-user 只接受 open_id。

不在本 skill 范围

• 发消息 / 查聊天记录 → `lark-im`
• 排日程 / 邀请会议 → `lark-calendar`
• 部门树 / 按部门列员工 / 组织架构 ,通过 `lark-openapi-explorer` 查找原生接口

+get-user

按 ID 取用户基本信息(姓名等)。

# 取自己
lark-cli contact +get-user --as user

# bot 按 ID 取他人
lark-cli contact +get-user --user-id ou_xxx --as bot

# 按 union_id / user_id 取(默认 open_id)
lark-cli contact +get-user --user-id <id> --user-id-type union_id --as bot

注意事项

• user 身份按 ID 取他人请用 `+search-user --user-ids <id>`,字段比本命令多(部门 / 邮箱 / 是否激活等)。本命令的 user 模式只回很少字段。
• `--as bot` 必须传 `--user-id`:不传会直接报错(只有 user 身份能省略 --user-id 取自己)。

+search-user

仅 user 身份。需要 scope contact:user:search。

适用范围

• ✅ 已知姓名 / 邮箱 / 「聊过的人」想找出 open_id
• ✅ 已知一组 open_id 想批量校验或回填字段(--user-ids,最多 100,支持 me)
• ✅ 按聊天关系 / 在职状态 / 租户边界 / 企业邮箱等维度筛选员工
• ❌ 已知 open_id 想拿完整 profile → 用 +get-user --as bot
• ❌ 已知 open_id 想发消息 → 直接走 lark-im,不经过本命令

关键 flag

--query / --queries / --user-ids / bool filter 至少传一个。bool filter 显式传 =false 会报错——不传等于不过滤。

常用例子

# 按姓名搜,看候选确认是哪个张三
lark-cli contact +search-user --query "张三" --has-chatted

# 按完整邮箱搜(命中通常唯一,适合作后续命令的输入)
lark-cli contact +search-user --query "alice@example.com"

# 查看自己
lark-cli contact +search-user --user-ids me

# 批量回填:已知一组 open_id,取姓名 / 邮箱 / 部门
lark-cli contact +search-user --user-ids "ou_a,ou_b,ou_c" --format json

# 多 filter 组合:同租户的、有企业邮箱的「王」姓员工
lark-cli contact +search-user --query "王" --exclude-external-users --has-enterprise-email

# filter-only 枚举:列出所有"聊过天的离职同事"(无关键词)
lark-cli contact +search-user --has-chatted --left-organization

批量并行查询 (fanout)

一次查多个名字:

lark-cli contact +search-user --queries "Alice,Bob,张三"

• 每行 user 带 matched_query,标识来自哪个 query
• queries[] 每个输入一条 {query, error?, has_more},失败的有 error
• 部分失败不影响其它 query;全部失败才 exit 非 0

# bool filter 对每个 query 都生效
lark-cli contact +search-user --queries "Alice,Bob" --has-chatted

# 与 --query / --user-ids 互斥
lark-cli contact +search-user --queries "a" --query "b"