Servosity/zammad

Zammad - Claude Code 技能

先決條件：安裝 CLI

此技能驅動 zammad-cli 二進位檔。在呼叫此技能的任何命令之前，您必須先確認 CLI 已安裝。 如果尚未安裝，請先執行安裝：

1. macOS / Linux：

   bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/zammad/install.sh)
   

2. Windows (PowerShell)：

   iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/zammad/install.ps1 | iex
   

3. 驗證：zammad-cli --version
4. 確保 ~/.local/bin (macOS / Linux) 或 %LOCALAPPDATA%\Programs\msp-skills (Windows) 已在 $PATH 環境變數中。

安裝程式會將 zammad-cli 和 zammad-mcp 二進位檔下載到 ~/.local/bin (macOS / Linux) 或 %LOCALAPPDATA%\Programs\msp-skills (Windows)。它不會 向您的代理註冊此技能，也不會寫入任何 MCP 用戶端設定 - 請參閱 mcp-install.md 進行該整合設定。

如果安裝後 --version 顯示「command not found」，表示執行環境無法在 $PATH 中找到該二進位檔目錄。在驗證成功之前，請勿繼續執行技能命令。

一個覆蓋整個 Zammad REST + 知識庫表面區域的 Go 單一二進位檔，具備離線 SQLite 儲存、結構化的 --json/--select 輸出，以及每個寫入操作的 --dry-run 模式。在其基本功能之上，它還根據同步的工單計算出一個團隊管理層：agent-load 和 agent-trend 用於計算工作量，customer-health 和 churn-risk 用於評估帳戶風險，overdue 用於處理逾期累積，escalate 用於情緒分類，以及 feedback 用於挖掘客戶的需求。可適用於任何 Zammad 實例 - 設定您的實例網址和 Token。

何時使用此 CLI

當代理需要讀取、搜尋或分類 Zammad 工單和知識庫內容，或回答團隊管理問題時，請使用此 CLI - 例如誰工作量超載、哪些客戶有風險、哪些工單擱置過久、哪些客戶可能流失、以及哪些意見回饋主題反覆出現。它非常適合用於支援營運自動化、每日站立會議和帳戶健康審查，因為這些問題的答案需要彙總大量工單的資訊。

反觸發條件

請勿將此 CLI 用於：

• 請勿使用此 CLI 發送客戶導向的行銷郵件 - 它管理的是工單文章，而非行銷活動。
• 請勿使用它來設定 Zammad 的觸發器、自動化規則、SLA 或頻道 - 這些是管理控制台功能，此處未公開。
• 請勿將 escalate/churn/feedback 視為權威性的情感分析結果 - 它們是啟發式的關鍵字分類，用於為人類或代理提供判斷的訊號。

獨特功能

團隊管理

• agent-load - 查看每位客服當前的工單負載（按狀態分組：開啟/待處理/積壓），以便在問題堆積前平衡工作。

  當被問到誰工作量超載或目前支援團隊的工作如何分配時，可以使用此功能。

  zammad-cli agent-load --json
  

• agent-trend - 顯示過去 N 週內每位客服的佇列是成長還是縮減，並附上開單 vs 關單的差異。

  當被問到團隊是否能跟上進度或隨著時間推移是否落後時，可以使用此功能。

  zammad-cli agent-trend --weeks 2 --json
  

• customer-health - 根據由開啟工單數量、最舊工單年齡、重新開啟率、處理速度及最後活動時間構建的健康訊號，對組織進行排名。

  使用此功能可在客戶抱怨前，找出哪些客戶正面臨困難。

  zammad-cli customer-health --at-risk --json
  

• overdue - 找出超過閾值仍處於新建/開啟/待處理狀態的逾期工單，並按優先順序加權，使最嚴重的工單排在最前面。

  使用此功能可捕捉即將違反 SLA 或變成僵屍工單的工單。

  zammad-cli overdue --days 3 --json
  

• escalate - 找出活躍工單中，近期客戶訊息帶有不滿情緒的（啟發式負面訊號掃描），按命中次數、工單年齡和優先順序排名 - 並顯示匹配的片段。

  使用此功能可找出聽起來很生氣的客戶並應升級處理；這是帶有片段的關鍵字分類，最終判斷仍由您做出。

  zammad-cli escalate --json
  

• churn-risk - 根據開啟的積壓工單、逾期工單、未回覆的待處理工單以及帶有負面情緒的客戶訊息，為每個組織評分流失風險，並列出促成因素。

  使用此功能可提前預防流失；它會顯示各個因素，供您判斷與採取行動。

  zammad-cli churn-risk --json
  

• feedback-scan - 將工單和文章文字分桶到功能請求、定價、合規和錯誤主題，並附上來源工單參考和片段。

  使用此功能可挖掘客戶在功能、定價和合規方面持續要求的項目。

  zammad-cli feedback-scan --bucket pricing --json
  

知識庫

• kb browse - 將知識庫以從初始化套件解析出的類別/答案樹狀結構列印出來。

  在閱讀或搜尋答案前，使用此功能查看知識庫的結構。

  zammad-cli kb browse
  

• kb search - 在即時知識庫初始化套件中，對 KB 答案標題和內容進行文字搜尋。

  使用此功能可依關鍵字找到正確的 KB 答案。

  zammad-cli kb search "restore" --json
  

• kb get - 從初始化套件中解析 KB 答案 ID，取得其完整翻譯後的內容。

  使用此功能可閱讀 KB 答案的完整內容。

  zammad-cli kb get 42
  

工單人因工程

• ticket note - 在一行指令內為工單新增內部或合作方可見的備註，並使用正確的內容類型預設值。

  使用此功能可記錄工單工作，而無需手動建構文章內容。

  zammad-cli ticket note 12345 --body "Investigated, awaiting logs" --internal --dry-run
  

Webhook（無需輪詢）

Zammad 可以在建立或更新工單、或新增文章時通知此機器，因此無需進行輪詢。

# 一次性設定，需使用具備 admin.webhook 和 admin.trigger 權限的 Token
zammad-cli webhooks register --endpoint http://127.0.0.1:8789/zammad --yes
# 持續在 Zammad 發送通知的機器上執行
zammad-cli webhooks listen
# 讀取已接收的事件；將回傳的游標作為 --since 傳入下一次執行
zammad-cli events list --since 0 --json

• register 會為每個事件（zammad.ticket.created、zammad.ticket.updated、zammad.article.created）建立一個 Zammad Webhook 和一個觸發器。它會產生簽章密鑰並儲存在您的 API Token 旁，僅您本人可讀取；ZAMMAD_WEBHOOK_SECRET 環境變數可覆蓋該密鑰。密鑰永遠不會被印出：webhooks status 僅顯示其來源。
• listen 預設僅綁定到本機（127.0.0.1，連接埠 8789），且若缺少密鑰則拒絕啟動。每個請求都必須攜帶 Zammad 的 X-Hub-Signature，在讀取請求正文前進行驗證；已處理過的傳遞會被丟棄，大於 1 MiB 的請求正文也會被拒絕。
• Webhook 僅傳遞 ID。監聽器會透過 API 擷取工單並記錄事件，因此客戶文字永遠不會經由 Webhook 傳輸。
• Zammad 在約兩分鐘內若無法成功傳遞五次，便會放棄。每次 listen 啟動時，會先記錄其在離線期間發生的變更。當 listen 執行中但因網路中斷而無法到達時，Zammad 放棄的傳遞不會被記錄。
• Zammad 必須能夠連接到監聽器。在同一台伺服器上自託管的 Zammad 可使用預設設定。位於您區域網路中另一台機器上的 Zammad，則需要 listen --addr <lan-ip>:8789 --tls-cert <file> --tls-key <file> 和一個 https:// 端點。Zammad Cloud 實例無法連接到您區域網路內的機器。
• 當使用者想要對新工單或已變更的工單做出反應時，請使用此功能。使用 events list --since <cursor> 讀取事件，並保留回傳的游標；執行 tickets get <id> 以取得工單文字。
• 在 MCP 中，events_list 用於讀取已記錄的事件（唯讀，不呼叫 Zammad）。webhooks_register 和 webhooks_unregister 僅在 confirm: true 時才會更改 Zammad。listen 僅限 CLI 使用。

命令參考

articles - 讀取和新增工單文章（備註和電子郵件）

• zammad-cli articles by-ticket - 列出某張工單的所有文章
• zammad-cli articles create - 為工單新增一篇文章（備註或電子郵件）
• zammad-cli articles get - 依 ID 取得單一文章

groups - 工單分組

• zammad-cli groups get - 依 ID 取得群組
• zammad-cli groups list - 列出所有群組

kb - 知識庫類別和答案

• zammad-cli kb answer-create - 建立 KB 答案。以 JSON 格式傳入 translations_attributes，然後發佈或標記為內部。
• zammad-cli kb answer-delete - 刪除 KB 答案（需要 KB 編輯者權限）
• zammad-cli kb answer-internal - 將 KB 答案標記為內部（僅限客服）
• zammad-cli kb answer-publish - 發佈 KB 答案（設為公開）
• zammad-cli kb category-create - 建立 KB 類別。以 JSON 格式傳入 translations_attributes。
• zammad-cli kb init - 擷取完整的知識庫套件（類別、答案、翻譯）。由 'kb browse/search/get' 內部使用。

organizations - 讀取和管理組織（客戶 / 合作夥伴）

• zammad-cli organizations create - 建立組織
• zammad-cli organizations get - 依 ID 取得組織
• zammad-cli organizations list - 列出組織（分頁）
• zammad-cli organizations search - 依名稱或自訂欄位搜尋組織
• zammad-cli organizations update - 更新組織

overviews - 客服工單總覽（已儲存的檢視）

• zammad-cli overviews get - 依 ID 取得總覽（及其工單）
• zammad-cli overviews list - 列出所有總覽

priorities - 工單優先順序參考（ID 對名稱的對映）

• zammad-cli priorities - 列出工單優先順序

states - 工單狀態參考（ID 對名稱的對映）

• zammad-cli states - 列出工單狀態

tags - 工單標籤

• zammad-cli tags add - 為物件新增標籤
• zammad-cli tags all - 列出實例中定義的所有標籤（詞彙表）
• zammad-cli tags list - 列出物件上的標籤（預設為工單）
• zammad-cli tags remove - 移除物件上的標籤

tickets - 讀取、搜尋、建立和變更 Zammad 工單

• zammad-cli tickets create - 建立工單。需提供標題、群組、客戶和一則初始文章。
• zammad-cli tickets delete - 永久刪除工單（需要管理員 / 刪除權限）
• zammad-cli tickets get - 依 ID 取得工單
• zammad-cli tickets list - 列出工單（分頁）
• zammad-cli tickets search - 使用 Zammad 查詢語法搜尋工單（例如 'state:open owner_id:3'）
• zammad-cli tickets update - 更新工單（狀態、優先順序、擁有者、標題、組織）

users - 讀取和管理使用者（客服和客戶）

• zammad-cli users create - 建立使用者
• zammad-cli users get - 依 ID 取得使用者
• zammad-cli users list - 列出使用者（分頁）
• zammad-cli users me - 取得已驗證的使用者（身份驗證自我檢查）
• zammad-cli users search - 依電子郵件、名稱或查詢詞搜尋使用者（例如 organization_id:5）
• zammad-cli users update - 更新使用者

agent-load

• zammad-cli agent-load - 查看每位客服當前的工單負載（按狀態分組：開啟/待處理/積壓），以便在問題堆積前平衡工作。

agent-trend

• zammad-cli agent-trend - 顯示過去 N 週內每位客服的佇列是成長還是縮減，並附上開單 vs 關單的差異。

churn-risk

• zammad-cli churn-risk - 根據開啟的積壓工單、逾期工單、未回覆的待處理工單以及帶有負面情緒的客戶訊息，為每個組織評分流失風險，並列出促成因素。

customer-health

• zammad-cli customer-health - 根據由開啟工單數量、最舊工單年齡、重新開啟率、處理速度及最後活動時間構建的健康訊號，對組織進行排名。

escalate

• zammad-cli escalate - 找出活躍工單中，近期客戶訊息帶有不滿情緒的（啟發式負面訊號掃描），按命中次數、工單年齡和優先順序排名 - 並顯示匹配的片段。

feedback-scan

• zammad-cli feedback-scan - 將工單和文章文字分桶到功能請求、定價、合規和錯誤主題，並附上來源工單參考和片段。

kb

• zammad-cli kb browse - 將知識庫以從初始化套件解析出的類別/答案樹狀結構列印出來。

• zammad-cli kb search - 在即時知識庫初始化套件中，對 KB 答案標題和內容進行文字搜尋。

• zammad-cli kb get - 從初始化套件中解析 KB 答案 ID，取得其完整翻譯後的內容。

events

• zammad-cli events list - 列出 webhooks listen 在游標之後記錄的 Zammad 事件，最先列出最舊的事件（本機操作，不呼叫 Zammad）。

webhooks

• zammad-cli webhooks register - 建立會呼叫 webhooks listen 的 Zammad Webhook 和觸發器（僅在加上 --yes 時才寫入）。
• zammad-cli webhooks listen - 接收、驗證並記錄 Zammad Webhook，直到被停止（僅限 CLI）。
• zammad-cli webhooks status - 顯示已註冊的 Webhook 和觸發器，以及密鑰的來源（永遠不會顯示密鑰本身）。
• zammad-cli webhooks unregister - 移除 webhooks register 建立的內容（僅在加上 --yes 時才寫入）。

overdue

• zammad-cli overdue - 找出超過閾值仍處於新建/開啟/待處理狀態的逾期工單，並按優先順序加權，使最嚴重的工單排在最前面。

ticket

• zammad-cli ticket note - 在一行指令內為工單新增內部或合作方可見的備註，並使用正確的內容類型預設值。

尋找正確的命令

當您知道想做什麼，但不確定哪個命令可以達成時，可以直接詢問 CLI：

zammad-cli which "<以您自己的話描述能力>"

which 會將自然語言的能力查詢解析為此 CLI 精選功能索引中最匹配的命令。退出碼 0 表示至少有一個匹配；退出碼 2 表示沒有置信的匹配。