wecomcli-contact

通訊錄成員查詢技能

wecom-cli 是企業微信提供的命令列程式，所有操作透過執行 wecom-cli 命令完成。

取得目前使用者可見範圍內的通訊錄成員，並在本地依姓名/別名進行篩選比對。

操作

1. 取得全部通訊錄成員

取得目前使用者可見範圍內的所有企業成員資訊：

呼叫範例：

wecom-cli 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	使用者別名，可能為空

---

2. 依姓名/別名搜尋人員

get_userlist 回傳全部成員後，在本地對結果進行篩選比對：

• 精確比對：name 或 alias 與關鍵詞完全一致，直接使用
• 模糊比對：name 或 alias 包含關鍵詞，回傳所有比對結果
• 無結果：告知使用者未找到對應人員

搜尋範例：

使用者問："幫我找一下張三是誰？"

1. 呼叫 get_userlist 取得全部成員
2. 在 userlist 中篩選 name 或 alias 包含"張三"的成員
3. 回傳比對結果

---

注意事項

• get_userlist 回傳的是目前使用者可見範圍內的成員，需經過可見性規則過濾，不一定是全公司所有人員；回傳欄位僅包含 userid、name（姓名）和 alias（別名）

• ⚠️ 超過 10 人時介面將報錯：若 userlist 回傳成員數量超過 10 人，視為異常，應立即停止處理並向使用者說明：

  目前通訊錄可見成員數量超過了本技能支援的上限（10 人）。
  本技能僅適用於可見範圍較小的場景，無法在大範圍通訊錄中使用。
  建議縮小可見範圍後重試，或透過其他方式查詢目標人員。

• userid 是使用者的唯一識別，在需要傳遞使用者 ID 給其他介面時使用此欄位

• alias 欄位可能為空字串，搜尋時需做空值判斷

• 若搜尋結果有多個同名人員，需將所有候選人展示給使用者選擇，不得自行決定

• 若 errcode 不為 0，表示介面呼叫失敗，需告知使用者錯誤訊息（errmsg）

---

典型工作流程

工作流程 1：查詢人員資訊

使用者問："幫我查一下 Sam 是誰？"

wecom-cli contact get_userlist '{}'

取得全部成員列表

2. 在結果中篩選 alias 為 Sam 或 name 包含 Sam 的成員
3. 若找到唯一比對，直接展示結果：

📇 找到成員：
- 姓名：張三
- 別名：Sam
- 使用者ID：zhangsan

4. 若找到多個比對，展示候選列表請使用者確認：

🔍 找到多個比對成員，請確認您要查詢的是哪位：

1. 張三（別名：Sam，ID：zhangsan）
2. 張三丰（別名：Sam2，ID：zhangsan2）

請問您要查詢的是哪一位？

---

工作流程 2：為其他功能提供 userid 轉換

使用者問："幫我發訊息給張三"

wecom-cli contact get_userlist '{}'

取得全部成員

2. 篩選 name 為"張三"的成員，確認 userid
3. 將 userid 傳遞給訊息發送介面

---

工作流程 3：批次查詢多個人員

使用者問："幫我查一下張三和李四分別是誰？"

wecom-cli contact get_userlist '{}'

取得全部成員列表

2. 分別篩選"張三"和"李四"的比對結果
3. 彙總後一併展示

注意：只需呼叫一次 get_userlist，在本地對結果進行多次篩選，避免重複呼叫介面。

---

快速參考

介面說明

介面	用途	輸入	回傳
get_userlist	取得可見範圍內全部通訊錄成員	無	使用者列表（userid、name、alias）

本地篩選策略

場景	策略
精確比對（name 或 alias 完全一致）	直接使用，無需使用者確認
模糊比對（name 或 alias 包含關鍵詞），唯一結果	直接使用，向使用者展示結果
模糊比對，多個結果	展示候選列表，請使用者選擇
無比對結果	告知使用者未找到對應人員