用途
wecom-contact-lookup 是一个通讯录成员查询技能，通过 MCP tool 协议封装的 get_userlist 接口，获取当前用户可见范围内的通讯录成员，并在本地按姓名或别名进行筛选匹配。返回 userid、姓名和别名。
该技能仅返回当前用户有权限查看的成员，非全量成员。
主要能力
- 获取当前用户可见范围内的所有企业成员信息。
- 在本地对返回结果按姓名（name）或别名（alias）进行精确匹配或模糊匹配。
- 为其他功能提供 userid 转换，例如将姓名转换为 userid 后传递给消息发送接口。
- 支持批量查询多个人员，只需调用一次 get_userlist，在本地对结果进行多次筛选。
使用方式
所有操作通过调用 wecom_mcp tool 完成。
前置条件：首次调用 wecom_mcp 前，必须按 wecom-preflight 技能执行前置条件检查，确保工具已加入白名单。
获取全量通讯录成员
调用示例：
使用 wecom_mcp tool 调用 wecom_mcp call contact get_userlist '{}'
返回格式：
{ "errcode": 0, "errmsg": "ok", "userlist": [ { "userid": "zhangsan", "name": "张三", "alias": "Sam" }, { "userid": "lisi", "name": "李四", "alias": "" } ] }
返回字段说明：
- errcode：integer，返回码，0 表示成功。
- errmsg：string，错误信息。
- userlist：array，用户列表。
- userlist[].userid：string，用户唯一 ID。
- userlist[].name：string，用户姓名。
- userlist[].alias：string，用户别名，可能为空。
按姓名/别名搜索人员
get_userlist 返回全量成员后，在本地对结果进行筛选匹配：
- 精确匹配：name 或 alias 与关键词完全一致，直接使用。
- 模糊匹配：name 或 alias 包含关键词，返回所有匹配结果。
- 无结果：告知用户未找到对应人员。
搜索示例：
用户问："帮我找一下张三是谁？"
- 调用 get_userlist 获取全量成员。
- 在 userlist 中筛选 name 或 alias 包含"张三"的成员。
- 返回匹配结果。
典型工作流
工作流 1：查询人员信息
用户问："帮我查一下 Sam 是谁？"
- 使用 wecom_mcp tool 调用 wecom_mcp call contact get_userlist '{}' 获取全量成员列表。
- 在结果中筛选 alias 为 Sam 或 name 包含 Sam 的成员。
- 若找到唯一匹配，直接展示结果：
📇 找到成员：
- 姓名：张三
- 别名：Sam
- 用户ID：zhangsan
若找到多个匹配，展示候选列表请用户确认：
🔍 找到多个匹配成员，请确认您要查询的是哪位：
- 张三（别名：Sam，ID：zhangsan）
- 张三丰（别名：Sam2，ID：zhangsan2）
请问您要查询的是哪一位？
工作流 2：为其他功能提供 userid 转换
用户问："帮我发消息给张三"
- 使用 wecom_mcp tool 调用 wecom_mcp call contact get_userlist '{}' 获取全量成员。
- 筛选 name 为"张三"的成员，确认 userid。
- 将 userid 传递给消息发送接口。
工作流 3：批量查询多个人员
用户问："帮我查一下张三和李四分别是谁？"
- 使用 wecom_mcp tool 调用 wecom_mcp call contact get_userlist '{}' 获取全量成员列表。
- 分别筛选"张三"和"李四"的匹配结果。
- 汇总后一并展示。
注意：只需调用一次 get_userlist，在本地对结果进行多次筛选，避免重复调用接口。
快速参考
接口说明：
- get_userlist：获取可见范围内全量通讯录成员；输入无；返回用户列表（userid、name、alias）。
本地筛选策略：
- 精确匹配（name 或 alias 完全一致）：直接使用，无需用户确认。
- 模糊匹配（name 或 alias 包含关键词），唯一结果：直接使用，向用户展示结果。
- 模糊匹配，多个结果：展示候选列表，请用户选择。
- 无匹配结果：告知用户未找到对应人员。
适用场景
- 查询当前用户可见范围内某位成员的信息（姓名、别名、userid）。
- 将姓名或别名转换为 userid，供其他接口使用。
- 批量查询多个可见范围内的人员。
限制与注意事项
- get_userlist 返回的是当前用户可见范围内的成员，需经过可见性规则过滤，不一定是全公司所有人员；返回字段仅包含 userid、name（姓名）和 alias（别名）。
- 超过 10 人时接口将报错：若 userlist 返回成员数量超过 10 人，视为异常，应立即停止处理并向用户说明：
- 当前通讯录可见成员数量超过了本技能支持的上限（10 人）。
- 本技能仅适用于可见范围较小的场景，无法在大范围通讯录中使用。
- 建议缩小可见范围后重试，或通过其他方式查询目标人员。
- userid 是用户的唯一标识，在需要传递用户 ID 给其他接口时使用此字段。
- alias 字段可能为空字符串，搜索时需做空值判断。
- 若搜索结果有多个同名人员，需将所有候选人展示给用户选择，不得自行决定。
- 若 errcode 不为 0，说明接口调用失败，需告知用户错误信息（errmsg）。