hdmx — CLI helpdesku

hdmx to jednoplikowy klient wiersza poleceń dla helpdesku. Opakowuje publiczne API GraphQL w wygodne polecenia typu zasób-i-czasownik, dzięki czemu zarówno agenci AI, jak i ludzie mogą obsługiwać helpdesk z terminala lub skryptu zamiast z przeglądarki.

Został zaprojektowany najpierw dla agentów, a dopiero potem dla ludzi: każde polecenie działa nieinteraktywnie, każde polecenie zwracające dane może wypisać ustrukturyzowaną kopertę --json, błędy wyliczają oczekiwane poprawne wartości, a maszynowo czytelny schemat poleceń pozwala agentowi poznać całą powierzchnię w jednym wywołaniu i wykorzystywać ją wielokrotnie.

Osobne repozytorium

CLI jest dostarczane z własnego repozytorium, github.com/mirasvit/hdmx — nie jest częścią kodu helpdesku. Strona helpdesku dostarcza jedynie publiczne API i osobiste tokeny dostępu, wobec których hdmx się uwierzytelnia. Plik README tamtego repozytorium jest aktualnym źródłem prawdy o bieżącej liście poleceń; ta strona daje ogólną orientację i opisuje kontrakt, na którym CLI się opiera.

Instalacja

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

Z każdym wydaniem publikowane są gotowe pliki binarne (Linux, macOS, Windows), tap Homebrew oraz obraz kontenera. hdmx version wypisuje wersję, datę kompilacji i wersję schematu API, wobec której zbudowano plik binarny.

Uwierzytelnianie

hdmx uwierzytelnia się osobistym tokenem dostępu — zobacz Publiczne API → Uwierzytelnianie. Utwórz token samodzielnie w aplikacji agenta, w sekcji Settings → API tokens; niesie on zakresy uprawnień, obowiązkową listę dozwolonych adresów IP i termin ważności.

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

Token jest przechowywany w pęku kluczy systemu operacyjnego. Dla CI i kontenerów trzy zmienne środowiskowe zastępują zapisany profil bez żadnego interaktywnego pytania: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Obsługę wielu najemców zapewniają profile — jeden profil łączy host, subdomenę, token i zestaw wartości domyślnych:

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

Co potrafi

Powierzchnia poleceń odwzorowuje rodziny zasobów helpdesku. Najważniejsze obszary:

Obszar	Co możesz zrobić
Zgłoszenia	wylistować, wyszukać, posegregować, wyświetlić, zaktualizować, przypisać, ustawić status / priorytet / tagi, scalić, usunąć
Wiadomości	odczytać wiadomości zgłoszenia, opublikować publiczną odpowiedź lub notatkę wewnętrzną
Czat	wylistować i wyświetlić rozmowy, wysłać, zamknąć, otworzyć ponownie, dołączyć, opuścić, oznaczyć jako przeczytane
Klienci	wylistować, wyszukać, wyświetlić, utworzyć, zaktualizować, scalić
Dane słownikowe	działy, statusy, priorytety, skrzynki pocztowe, tagi, użytkownicy
Raporty	przegląd, wolumen, czasy odpowiedzi, według agenta, zaległości, podziały
Konto	bieżące konto, metadane, bieżący użytkownik

Dwa udogodnienia warte wyróżnienia:

• Nazwy zamiast identyfikatorów. Flagi przyjmują zarówno czytelną nazwę, jak i identyfikator — --status open, --assignee [email protected] czy surowy identyfikator zostaną rozpoznane tak samo. Odwzorowanie jest buforowane lokalnie dla każdego konta.
• Nazwane przepływy pracy. hdmx tickets triage uruchamia standardowy widok segregacji (otwarte, niezamknięte, bez próśb o nowe funkcje, uporządkowane według priorytetu), bez konieczności każdorazowego odtwarzania filtra przez wywołującego.

Wyjście i bezpieczeństwo

• Domyślnie ustrukturyzowane dla maszyn. Przekierowane wyjście to koperta JSON (ok, data, summary, warnings, error, meta); w terminalu (TTY) otrzymujesz czytelny Markdown. --jq filtruje JSON w locie. Dane trafiają na stdout, diagnostyka na stderr.
• Błędy, które uczą. Gdy wartość zostaje odrzucona, błąd wymienia poprawne wartości i konkretne następne polecenie — na przykład błędny status zwraca listę rzeczywistych statusów i przykład wywołania.
• Ograniczone odpowiedzi. Polecenia listujące mają domyślny rozmiar strony i twardy limit; gdy wyjście zostaje przycięte, odpowiedź mówi o tym i podpowiada, jak zawęzić zapytanie. Dzięki temu odpowiedzi mieszczą się w budżecie tokenów agenta.
• Próbne uruchomienie i bramki zatwierdzania. Każda mutacja przyjmuje --dry-run (pokazuje operację i jej przewidywany skutek bez wysyłania). Działania destrukcyjne wymagają --force; publikowanie wiadomości widocznych dla klienta lub notatek wewnętrznych wymaga --approve.

Poznawanie powierzchni

Pomoc ma trzy warstwy, skierowane do trzech odbiorców:

• hdmx <command> --help — opis użycia i przykłady w zwykłym tekście (dla ludzi).
• hdmx agent-context — wersjonowany, maszynowo czytelny schemat każdego polecenia, flagi, wyliczenia, kodu błędu, wartości domyślnej i nazwanego przepływu pracy (dla agentów wiążących się ze stabilną powierzchnią).
• hdmx skills — przepisy kompozycji łączące kilka poleceń w nazwany scenariusz (na przykład przepływ segregacji i odpowiedzi).

Relacja z publicznym API

hdmx jest pierwszym konsumentem publicznego API helpdesku spoza przeglądarki. Wszystko, co robi, przechodzi przez ten sam punkt końcowy GraphQL uwierzytelniany tokenem PAT, w ramach tych samych zakresów uprawnień i limitów zapytań — nie ma żadnego uprzywilejowanego tylnego wejścia. Schemat API jest kontraktem; hdmx jest budowany pod przypiętą wersję API i stosuje politykę wycofań tego API, więc wydanie CLI działa dalej z każdym zgodnym (niełamiącym) schematem serwera.