hdmx — helpdeskin komentorivityökalu

hdmx on yhden binäärin komentoriviasiakas helpdeskiin. Se kääräisee julkisen GraphQL-rajapinnan sujuviksi resurssi-ja-verbi-muotoisiksi komennoiksi, jotta sekä tekoälyagentit että ihmiset voivat ohjata helpdeskiä päätteestä tai skriptistä selaimen sijaan.

Se on suunniteltu ensin agenteille, sitten ihmisille: jokainen komento toimii vuorovaikutuksetta, jokainen dataa palauttava komento osaa tuottaa jäsennellyn --json-kuoren, virheet luettelevat odottamansa kelvolliset arvot, ja koneluettava komentoskeema antaa agentin oppia koko pinnan yhdellä kutsulla ja käyttää sitä uudelleen monissa tehtävissä.

Erillinen repositorio

Komentorivityökalu julkaistaan omasta repositoriostaan, github.com/mirasvit/hdmx — se ei ole osa helpdeskin koodipohjaa. Helpdeskin puolelta tarjotaan vain julkinen rajapinta ja henkilökohtaiset käyttöoikeustunnisteet, joita vasten hdmx tunnistautuu. Kyseisen repositorion README on ajantasainen totuuden lähde nykyisestä komentolistasta; tämä sivu antaa yleiskuvan ja kuvaa sopimuksen, johon työkalu nojaa.

Asennus

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

Jokaisen julkaisun yhteydessä tarjotaan valmiit binäärit (Linux, macOS, Windows), Homebrew-tap ja konttikuva. hdmx version tulostaa version, käännöspäivän ja sen rajapintaskeeman version, jota vasten binääri on käännetty.

Tunnistautuminen

hdmx tunnistautuu henkilökohtaisella käyttöoikeustunnisteella — katso Julkinen rajapinta → Tunnistautuminen. Luo tunniste itse agenttisovelluksessa kohdassa Settings → API tokens; siinä on käyttöoikeusalueet, pakollinen sallittujen IP-osoitteiden lista ja voimassaoloaika.

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

Tunniste tallennetaan käyttöjärjestelmän avainnippuun. CI-ympäristöissä ja konteissa kolme ympäristömuuttujaa ohittaa tallennetun profiilin ilman vuorovaikutteista kyselyä: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Useita vuokralaisia hallitaan profiileilla — yksi profiili niputtaa palvelimen, aliverkkotunnuksen, tunnisteen ja joukon oletusarvoja:

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

Mitä sillä voi tehdä

Komentojen kokonaisuus vastaa helpdeskin resurssiperheitä. Tärkeimmät alueet:

Alue	Mitä voit tehdä
Tiketit	listata, hakea, triagoida, näyttää, päivittää, määrittää käsittelijän, asettaa tilan / prioriteetin / tunnisteet, yhdistää, poistaa
Viestit	lukea tiketin viestejä, julkaista julkisen vastauksen tai sisäisen muistiinpanon
Chat	listata ja näyttää keskusteluja, lähettää, sulkea, avata uudelleen, liittyä, poistua, merkitä luetuksi
Asiakkaat	listata, hakea, näyttää, luoda, päivittää, yhdistää
Perustiedot	osastot, tilat, prioriteetit, postilaatikot, tunnisteet, käyttäjät
Raportit	yleiskuva, määrät, vasteajat, agenttikohtaisesti, ruuhka, erittelyt
Tili	nykyinen tili, metatiedot, nykyinen käyttäjä

Kaksi mukavuutta ansaitsee erillisen maininnan:

• Nimet tunnisteiden sijaan. Valitsimet hyväksyvät sekä ihmisluettavan nimen että tunnisteen — --status open, --assignee [email protected] tai raaka tunniste tunnistetaan kaikki. Vastaavuudet tallennetaan paikalliseen välimuistiin tilikohtaisesti.
• Nimetyt työnkulut. hdmx tickets triage ajaa vakiomuotoisen triage-näkymän (avoimet, ei suljetut, ei ominaisuuspyyntöjä, prioriteetin mukaan järjestettynä) ilman että kutsujan tarvitsee koota suodatinta joka kerta uudelleen.

Tuloste ja turvallisuus

• Oletuksena koneille jäsennelty. Putkeen ohjattu tuloste on JSON-kuori (ok, data, summary, warnings, error, meta); päätteessä (TTY) saat luettavaa Markdownia. --jq suodattaa JSONia lennossa. Data menee vakiotulosteeseen, diagnostiikka virhevirtaan.
• Opettavat virheet. Kun arvo hylätään, virhe nimeää kelvolliset arvot ja konkreettisen seuraavan komennon — esimerkiksi virheellinen tila palauttaa luettelon todellisista tiloista ja esimerkin kutsusta.
• Rajatut vastaukset. Listauskomennoilla on oletussivukoko ja kova yläraja; kun tuloste katkaistaan, vastaus kertoo siitä ja neuvoo, miten rajata hakua. Näin vastaukset pysyvät agentin token-budjetin sisällä.
• Koeajo ja hyväksyntäportit. Jokainen mutaatio hyväksyy --dry-run-valitsimen (näyttää operaation ja sen arvioidun vaikutuksen lähettämättä sitä). Tuhoavat toimet vaativat --force; asiakkaalle näkyvien viestien tai sisäisten muistiinpanojen julkaisu vaatii --approve.

Pinnan opetteleminen

Ohjeita on kolmessa kerroksessa, kolmelle yleisölle:

• hdmx <command> --help — vapaamuotoinen käyttöohje ja esimerkit (ihmisille).
• hdmx agent-context — versioitu, koneluettava skeema jokaisesta komennosta, valitsimesta, enum-arvosta, virhekoodista, oletusarvosta ja nimetystä työnkulusta (agenteille, jotka sitoutuvat vakaaseen pintaan).
• hdmx skills — koosteohjeita, jotka sitovat useita komentoja nimetyksi toimintaohjeeksi (esimerkiksi triagoi-ja-vastaa-kulku).

Suhde julkiseen rajapintaan

hdmx on helpdeskin julkisen rajapinnan ensimmäinen selaimen ulkopuolinen käyttäjä. Kaikki mitä se tekee kulkee saman PAT-tunnistautuvan GraphQL-päätepisteen kautta, samoilla käyttöoikeusalueilla ja pyyntörajoilla — erillistä etuoikeutettua takaovea ei ole. Rajapinnan skeema on sopimus; hdmx käännetään kiinnitettyä rajapinnan versiota vasten ja noudattaa rajapinnan käytäntöä poistuvista osista, joten komentorivityökalun julkaisu toimii edelleen minkä tahansa yhteensopivan (rikkomattoman) palvelinskeeman kanssa.