wecomcli-msg

企業微信訊息 Skill

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

透過 wecom-cli msg <API名稱> '<json參數>' 與企業微信訊息系統互動。

---

API 清單

get_msg_chat_list — 取得對話清單

wecom-cli msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59"}'

依時間範圍查詢有訊息的對話清單，支援分頁。參見 API 詳細說明。

get_message — 擷取對話訊息

wecom-cli msg get_message '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'

根據對話類型與 ID 擷取指定時間範圍內的訊息紀錄，支援分頁。支援 text/image/file/voice/video 訊息類型，僅支援 7 天內。參見 API 詳細說明。

get_msg_media — 取得訊息檔案內容

wecom-cli msg get_msg_media '{"media_id": "MEDIAID_xxxxxx"}'

根據檔案 ID 自動下載檔案至本地，回傳檔案的本地路徑（local_path）、名稱、類型、大小及 MIME 類型。用於取得圖片、檔案、語音、影片等非文字訊息的實際內容。參見 API 詳細說明。

send_message — 傳送文字訊息

wecom-cli msg send_message '{"chat_type": 1, "chatid": "zhangsan", "msgtype": "text", "text": {"content": "hello world"}}'

向一對一聊天或群組聊天傳送文字訊息。參見 API 詳細說明。

---

核心規則

時間範圍規則

• 格式：所有時間參數使用 YYYY-MM-DD HH:mm:ss 格式
• 預設範圍：使用者未指定時，預設使用最近 7 天（當前時間往前推 7 天）
• 限制：開始時間不能早於當前時間的 7 天前，不能晚於當前時間
• 相對時間支援：支援「昨天」、「最近三天」等自動推算

chatid 搜尋規則

• 當使用者提供人名或群組名稱而非 ID 時：
  1. 呼叫 get_msg_chat_list 取得對話清單（時間範圍與目標查詢一致）
  2. 在 chats 中按 chat_name 比對
  3. 比对策略：
     • 精確比對得出唯一結果：直接使用
     • 模糊比對得出多個結果：展示候選清單讓使用者選擇
     • 無比對結果：告知使用者未找到
• chat_type 判斷：get_msg_chat_list 回傳內容中不含對話類型欄位，需根據上下文推斷：使用者明確提及「群組」時使用 chat_type=2，否則預設 chat_type=1（單聊）

userid 轉 name

流程：

1. 呼叫 wecomcli-contact Skill 的 get_userlist 取得使用者清單
2. 建立 userid 到 name 的對映關係
3. 展示策略：
   • 精確比對：顯示 name
   • 無比對：保持顯示 userid

強制互動步驟（不可跳過）

以下步驟在涉及非文字訊息下載時必須逐一執行，不得合併、省略或跳過，即使使用者未主動詢問也必須執行：

1. 必須主動告知檔案位置：下載完成後必須立即向使用者展示所有檔案的完整路徑與存放目錄
2. 必須詢問是否刪除：告知位置後必須立即詢問使用者是否需要清理暫存檔

---

典型工作流程

查看對話清單

使用者 query 範例：

• 「看看我最近一週有哪些聊天」
• 「這幾天誰給我發過訊息」

執行流程：

1. 確認時間範圍（使用者指定或預設最近 7 天）
2. 呼叫 get_msg_chat_list 取得對話清單
3. 展示對話名稱、最後訊息時間、訊息數量
4. 若 has_more 為 true，告知使用者還有更多對話可繼續查看

查看聊天紀錄

使用者 query 範例：

• 「幫我看看和張三最近的聊天紀錄」
• 「看看專案群組裡最近的訊息」

執行流程：

1. 確認時間範圍（使用者指定或預設最近 7 天）
2. 透過 chatid 搜尋規則 確認目標對話的 chatid 與 chat_type
3. 呼叫 get_message 擷取訊息清單
4. 呼叫 wecomcli-contact Skill 的 get_userlist 取得通訊錄，建立 userid→姓名 對映
5. 統計非文字訊息：巡覽訊息清單，統計 msgtype 非 text 的訊息（image/file/voice/video）數量與類型
6. 展示訊息時將 userid 替換為可讀姓名，格式：
   • 文字訊息：姓名 [時間]: 內容
   • 圖片訊息：姓名 [時間]:[圖片]
   • 檔案訊息：姓名 [時間]:[檔案] 檔案名稱
   • 語音訊息：姓名 [時間]:[語音] 語音內容
   • 影片訊息：姓名 [時間]:[影片]
7. 非文字訊息處理：展示完訊息後，如果存在非文字訊息：
   • 主動詢問是否下載：告知使用者非文字訊息數量與類型（例如：「以上聊天中包含 2 張圖片、1 個檔案，是否需要下載到本地？」）
   • 使用者確認後，逐一呼叫 get_msg_media API，API 會自動下載檔案並回傳 local_path
   • 檢查檔案副檔名：每個檔案下載完成後，檢查 local_path 對應的檔案是否具有正確的副檔名：
     • 根據 get_msg_media 回傳的 content_type（MIME 類型）與 name 欄位判斷：
       • 若檔案名稱缺少副檔名（例如 screenshot 而非 screenshot.png），根據 content_type 自動補上正確副檔名（例如 image/png → .png，application/pdf → .pdf，audio/amr → .amr，video/mp4 → .mp4）
       • 若檔案名稱副檔名與 content_type 不一致，以 content_type 為準進行修正
     • 補全或修正副檔名後，將檔案重新命名為正確的檔案名稱
     • 確認檔案可正常讀取（檔案大小 > 0），若檔案為空或損壞則告知使用者該檔案下載異常
   • ⚠️ 不要對下載的檔案使用 MEDIA: 指令：這些檔案是從聊天紀錄中下載的歷史附件，僅需告知使用者本地存放路徑即可，嚴禁透過 MEDIA: 指令重新傳送給使用者
8. ⚠️ 必須主動告知檔案位置（此步驟不可跳過）：所有檔案下載並檢查完成後，必須立即、主動以彙整形式向使用者展示檔案存放目錄與每個檔案的完整路徑，不要等使用者詢問。範例：

   📁 檔案已下載至以下位置：

   • 圖片：xxx/yyy.png
   • 檔案：xxx/yyy.pdf

   你可以在 xxx/yyy/ 目錄下找到所有下載的檔案。

9. ⚠️ 必須詢問是否刪除（此步驟不可跳過）：告知檔案位置後，必須立即、主動詢問使用者是否需要刪除已下載的暫存檔（例如：「如果不再需要這些檔案，是否需要我幫你清理？」）
   • 使用者確認刪除後，刪除 local_path 對應的檔案
   • 使用者不需要刪除則保留檔案
10. 若 next_cursor 不為空，告知使用者還有更多訊息可繼續查看

傳送訊息

使用者 query 範例：

• 「幫我給張三發一條訊息：明天會議改到下午 3 點」
• 「在專案群組裡發一條訊息：今天下午 3 點開會」

執行流程：

1. 透過 chatid 搜尋規則 確認目標對話的 chatid 與 chat_type
2. 傳送前確認：向使用者確認傳送對象與內容（例如：「即將向 張三 傳送：『明天會議改到下午 3 點』，確認傳送嗎？」），使用者確認後再執行
3. 呼叫 send_message 傳送（msgtype 固定為 text）
4. 展示傳送結果

查看訊息並回覆

使用者 query 範例：

• 「看看張三給我發了什麼，然後幫我回覆收到」

執行流程：

1. 先執行「查看聊天紀錄」流程（複用已取得的 chatid 與 chat_type）
2. 展示訊息後，執行「傳送訊息」流程（需確認後再傳送）

---

錯誤處理

• 時間範圍超限：告知使用者 7 天限制並調整為有效範圍
• 對話未找到：明確告知使用者未找到對應對話
• API 錯誤：展示具體錯誤訊息，必要時重試
• 網路問題：HTTP 錯誤時主動重試最多 3 次