hdmx — 服務台命令列工具
hdmx 是服務台的單一執行檔命令列用戶端。它把公開 GraphQL API 包裝成「資源加動作」式的好用命令，讓 AI 代理程式與人都能從終端機或指令碼操作服務台，而不必開啟瀏覽器。
它的設計是代理程式優先、人其次：每個命令都以非互動方式執行，每個回傳資料的命令都能輸出結構化的 --json 信封，錯誤會列舉它所預期的有效值，而機器可讀的命令 schema 讓代理程式一次呼叫就能學會整套介面，並在許多工作中重複使用。
這個命令列工具由自己的儲存庫 github.com/mirasvit/hdmx 發行，並不屬於服務台的程式碼庫。服務台這一側只提供 hdmx 用來驗證的公開 API 與個人存取權杖。該儲存庫的 README 才是目前命令清單的即時權威來源；本頁提供整體導覽，以及它所依據的契約。
安裝
go install github.com/mirasvit/hdmx/cmd/hdmx@latest
每次發行都會提供預先建置的執行檔（Linux、macOS、Windows）、Homebrew tap 與容器映像檔。hdmx version 會印出版本、建置日期，以及該執行檔所依據的 API schema 版本。
驗證
hdmx 使用個人存取權杖進行驗證——參見公開 API → 驗證。請在客服端應用程式的 Settings → API tokens 中自行建立權杖；它帶有權限範圍、必填的 IP 允許清單與到期時間。
hdmx auth login --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx auth status
hdmx auth logout
權杖會存放在作業系統的金鑰圈中。在 CI 與容器環境下，三個環境變數可在不出現任何互動提示的情況下覆寫已儲存的設定檔：HDMX_HOST、HDMX_SUBDOMAIN、HDMX_TOKEN。
多租戶透過設定檔處理——一個設定檔會打包主機、子網域、權杖與一組預設值：
hdmx profile save acme --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx profile use acme
hdmx --profile other tickets list
它能做什麼
命令體系對應服務台的資源族。主要領域包括：
| 領域 | 可以做什麼 |
|---|---|
| 工單 | 列出、搜尋、分流、檢視、更新、指派、設定狀態 / 優先順序 / 標籤、合併、刪除 |
| 訊息 | 閱讀某張工單的訊息，張貼公開回覆或內部備註 |
| 聊天 | 列出並檢視對話，傳送、結束、重新開啟、加入、離開、標示為已讀 |
| 客戶 | 列出、搜尋、檢視、建立、更新、合併 |
| 基礎資料 | 部門、狀態、優先順序、信箱、標籤、使用者 |
| 報表 | 總覽、工單量、回應時間、依客服統計、待處理積壓、細項分析 |
| 帳戶 | 目前帳戶、中繼資料、目前使用者 |
有兩項便利之處值得特別一提：
- 用名稱取代 ID。 旗標同時接受可讀名稱與 ID——
--status open、--assignee [email protected]或原始識別碼都能被解析。這份對應會依帳戶在本機快取。 - 具名工作流程。
hdmx tickets triage會直接執行標準分流檢視（開啟中、未結束、排除功能需求、依優先順序排序），呼叫端不必每次重新組出篩選條件。
輸出與安全
- 預設為機器導向的結構化輸出。 透過管線傳出的輸出是一個 JSON 信封（
ok、data、summary、warnings、error、meta）；在 TTY 下則輸出易讀的 Markdown。--jq可就地篩選 JSON。資料寫入 stdout，診斷資訊寫入 stderr。 - 會教人的錯誤。 當某個值遭到拒絕時，錯誤會列出有效的值以及一條具體的後續命令——例如狀態填錯時，會回傳實際存在的狀態清單與一個呼叫範例。
- 有上限的回應。 列表類命令有預設頁面大小與硬性上限；輸出遭到截斷時，回應會明確說明，並告訴你如何縮小範圍。這能讓回應維持在代理程式的 token 預算之內。
- 試跑與核准關卡。 每個變更操作都接受
--dry-run（只呈現該操作及其預期效果，不實際送出）。破壞性操作需要--force；張貼客戶看得到的訊息或內部備註則需要--approve。
認識整套介面
說明分為三層，面向三種對象：
hdmx <command> --help—— 自由文字的用法說明與範例（給人看）。hdmx agent-context—— 一份帶版本的機器可讀 schema，涵蓋每個命令、旗標、列舉、錯誤碼、預設值與具名工作流程（給需要繫結穩定介面的代理程式）。hdmx skills—— 把多個命令串成具名操作手冊的組合配方（例如分流後回覆的流程）。
與公開 API 的關係
hdmx 是服務台公開 API 的第一個非瀏覽器使用者。它所做的一切都走同一個以 PAT 驗證的 GraphQL 端點，遵循相同的權限範圍與速率限制——沒有任何特權後門。API schema 就是契約；hdmx 依據釘選的 API 版本建置，並遵循該 API 的淘汰政策，因此某個 CLI 版本能繼續與任何相容（不含破壞性變更）的伺服器 schema 一同運作。