lark-contact

用途

lark-contact 是飞书（Lark）开放平台的通讯录查询技能，供 AI 智能体在 lark-cli 工具环境中检索飞书通讯录信息，例如查找员工、获取用户资料、搜索可见的机器人与智能体。它本身不负责发消息或安排日程，只解决「找到人 / 拿到 ID」这一步。

主要能力

该技能区分 user 身份与 bot 身份两条完全独立的使用路径，需先确定当前身份，再选择命令。

user 身份下支持：

按姓名或邮箱搜索员工并获取 open_id（+search-user）。
按关键词搜索当前用户可见的机器人 / 智能体（+search-bot）。
已知 open_id 时查询他人资料（+search-user --user-ids <id>）。
查看自己（+get-user，或 +search-user --user-ids me）。
查询同事的个人状态 / 个性签名（user_profiles batch_query）。

bot 身份下仅支持：

已知 open_id 时获取用户资料（+get-user --user-id <id>）。

按姓名 / 邮箱搜员工、搜索机器人 / 智能体、查看自己、查询同事个人状态等操作在 bot 身份下不支持。

+search-bot 使用 user 身份按关键词搜索当前用户可见的机器人，返回 ou_ 开头的机器人 open_id，支持单关键词或逗号分隔的多关键词查询。它不支持按 ID 查询。

使用方式

文档给出的典型命令示例包括：

找张三并发送消息时，先搜索确认 open_id，再进行后续操作：

lark-cli contact +search-user --query "张三" --has-chatted --as user
lark-cli im +messages-send --user-id ou_xxx --text "Hi!"

批量查询同事个人状态 / 个性签名（先用 schema 查看参数）：

lark-cli schema contact.user_profiles.batch_query
lark-cli contact user_profiles batch_query \
  --params '{"user_id_type":"open_id"}' \
  --data '{"user_ids":["ou_xxx","ou_yyy"],"query_option":{"include_personal_status":true,"include_description":true}}' \
  --as user

搜索机器人 / 智能体：

lark-cli contact +search-bot --query '会议助手' --as user
lark-cli contact +search-bot --queries '会议助手,日报助手,审批助手' --as user

ID 类型方面：+get-user 可通过 --user-id-type 使用 open_id、union_id 或 user_id；+search-user 使用用户 open_id；+search-bot 按关键词搜索并返回机器人 open_id。

适用场景

已知姓名但需要拿到 open_id 后再发消息或安排日程。
名字无法判断是人还是机器人 / 智能体时（例如名字含 bot / agent / AI / 助手 / 机器人 / 智能体 / assistant 等特征，或用户表述如「和 reviewDuck 约个会」），可两边都搜索确认。
需要批量查看同事的个人状态与个性签名。
需要搜索当前用户可见的机器人与智能体。

限制与注意事项

身份分离：user 与 bot 是两条独立路径，部分命令仅 user 身份可用。
41050 / Permission denied 错误受当前身份的可见范围限制，三条命令都可能遇到。
跨租户用户（is_cross_tenant=true）多数业务字段为空字符串，这是飞书可见性规则，下游需做空值兜底。
搜索命中多条且后续操作有副作用（如发消息、邀请会议等）时，应把候选列给用户挑选，不要擅自选第一条。
已知 open_id 只是想发消息或排日程，不必经过 contact，直接使用 lark-im / lark-calendar。
发消息 / 查聊天记录属于 lark-im 范围；排日程 / 邀请会议属于 lark-calendar 范围；部门树、按部门列员工、组织架构需通过 lark-openapi-explorer 查找原生接口。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项