hdmx — CLI helpdesku

hdmx je jednosouborový klient příkazové řádky pro helpdesk. Obaluje veřejné GraphQL API do pohodlných příkazů ve tvaru „zdroj a sloveso", takže helpdesk mohou z terminálu nebo ze skriptu ovládat jak AI agenti, tak lidé — místo prohlížeče.

Je navržený nejprve pro agenty, teprve potom pro lidi: každý příkaz běží neinteraktivně, každý datový příkaz umí vypsat strukturovanou obálku --json, chyby vyjmenují platné hodnoty, které očekávaly, a strojově čitelné schéma příkazů umožní agentovi naučit se celé rozhraní jediným voláním a znovu je použít v mnoha úlohách.

Samostatný repozitář

CLI se dodává z vlastního repozitáře github.com/mirasvit/hdmx — není součástí kódu helpdesku. Strana helpdesku poskytuje pouze veřejné API a osobní přístupové tokeny, vůči nimž se hdmx ověřuje. Aktuálním zdrojem pravdy o seznamu příkazů je soubor README v onom repozitáři; tato stránka poskytuje orientaci a popisuje smlouvu, o kterou se CLI opírá.

Instalace

go install github.com/mirasvit/hdmx/cmd/hdmx@latest

S každým vydáním se publikují předpřipravené binárky (Linux, macOS, Windows), tap pro Homebrew a kontejnerový obraz. hdmx version vypíše verzi, datum sestavení a verzi schématu API, vůči které byla binárka sestavena.

Ověřování

hdmx se ověřuje osobním přístupovým tokenem — viz Veřejné API → Ověřování. Token si vytvořte sami v aplikaci pro agenty v sekci Settings → API tokens; nese oprávnění, povinný seznam povolených IP a platnost.

hdmx auth login --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx auth status
hdmx auth logout

Token se ukládá do klíčenky operačního systému. Pro CI a kontejnery přepíšou uložený profil tři proměnné prostředí, a to bez jakéhokoli interaktivního dotazu: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Více nájemců se řeší profily — jeden profil sdružuje hostitele, subdoménu, token a sadu výchozích hodnot:

hdmx profile save acme --host helpdesk.example.com --subdomain acme --token hdmx_…
hdmx profile use acme
hdmx --profile other tickets list

Co umí

Sada příkazů odpovídá rodinám zdrojů helpdesku. Hlavní oblasti:

Oblast	Co můžete dělat
Tikety	vypsat, hledat, třídit, zobrazit, upravit, přiřadit, nastavit stav / prioritu / štítky, sloučit, smazat
Zprávy	číst zprávy tiketu, publikovat veřejnou odpověď nebo interní poznámku
Chat	vypsat a zobrazit konverzace, odeslat, uzavřít, znovu otevřít, připojit se, odejít, označit jako přečtené
Zákazníci	vypsat, hledat, zobrazit, vytvořit, upravit, sloučit
Číselníky	oddělení, stavy, priority, schránky, štítky, uživatelé
Reporty	přehled, objem, doby odezvy, podle agenta, nevyřízené položky, členění
Účet	aktuální účet, metadata, aktuální uživatel

Dvě vymoženosti stojí za zmínku:

• Jména místo ID. Přepínače přijímají jak čitelné jméno, tak ID — --status open, --assignee [email protected] i holý identifikátor se stejně vyhodnotí. Mapování se ukládá do místní keše pro každý účet zvlášť.
• Pojmenované postupy. hdmx tickets triage spustí standardní pohled pro třídění (otevřené, neuzavřené, bez požadavků na novou funkci, seřazené podle priority), aniž by volající musel filtr pokaždé skládat znovu.

Výstup a bezpečnost

• Ve výchozím stavu strukturovaný pro stroje. Výstup přesměrovaný do roury je obálka JSON (ok, data, summary, warnings, error, meta); v terminálu (TTY) dostanete čitelný Markdown. --jq filtruje JSON přímo na místě. Data jdou na stdout, diagnostika na stderr.
• Chyby, které učí. Když je hodnota odmítnuta, chyba pojmenuje platné hodnoty i konkrétní další příkaz — například chybný stav vrátí seznam skutečných stavů a ukázku volání.
• Omezené odpovědi. Výpisové příkazy mají výchozí velikost stránky a pevný strop; když je výstup oříznut, odpověď to uvede a poradí, jak dotaz zúžit. Odpovědi tak zůstávají v tokenovém rozpočtu agenta.
• Zkušební běh a schvalovací brány. Každá mutace přijímá --dry-run (vykreslí operaci a její předpokládaný účinek, aniž by ji odeslala). Destruktivní akce vyžadují --force; publikování zpráv viditelných pro zákazníka nebo interních poznámek vyžaduje --approve.

Jak poznat celé rozhraní

Nápověda má tři vrstvy určené třem skupinám:

• hdmx <command> --help — volný text s použitím a příklady (pro lidi).
• hdmx agent-context — verzované, strojově čitelné schéma každého příkazu, přepínače, výčtu, chybového kódu, výchozí hodnoty a pojmenovaného postupu (pro agenty, kteří se váží na stabilní rozhraní).
• hdmx skills — kompoziční recepty, které spojují několik příkazů do pojmenovaného postupu (například třídění a odpověď).

Vztah k veřejnému API

hdmx je prvním neprohlížečovým konzumentem veřejného API helpdesku. Vše, co dělá, jde přes tentýž koncový bod GraphQL ověřený tokenem PAT, pod stejnými oprávněními a limity požadavků — žádná privilegovaná zadní vrátka neexistují. Schéma API je smlouva; hdmx se sestavuje proti zafixované verzi API a řídí se jejími zásadami ukončování podpory, takže vydání CLI dál funguje s jakýmkoli kompatibilním (nerozbíjejícím) schématem serveru.