hdmx — yardım masası CLI'si

hdmx, yardım masası için tek dosyalık bir komut satırı istemcisidir. Herkese açık GraphQL API'yi kaynak-ve-eylem biçimindeki kullanışlı komutların arkasına sarar; böylece hem yapay zekâ aracıları hem de insanlar yardım masasını tarayıcı yerine bir terminalden veya betikten yönetebilir.

Tasarımı önce aracılar, sonra insanlar ilkesine dayanır: her komut etkileşimsiz çalışır, veri döndüren her komut yapılandırılmış bir --json zarfı üretebilir, hatalar bekledikleri geçerli değerleri sıralar ve makine tarafından okunabilir bir komut şeması sayesinde bir aracı tüm yüzeyi tek bir çağrıda öğrenip birçok görevde yeniden kullanabilir.

Ayrı depo

CLI kendi deposundan, github.com/mirasvit/hdmx üzerinden dağıtılır — yardım masası kod tabanının parçası değildir. Yardım masası tarafı yalnızca hdmx'in kimlik doğrulaması için kullandığı herkese açık API ve kişisel erişim jetonlarını sağlar. Güncel komut listesi için canlı doğruluk kaynağı o deponun README dosyasıdır; bu sayfa genel yönlendirmeyi ve dayanılan sözleşmeyi anlatır.

Kurulum

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

Her sürümle birlikte hazır ikili dosyalar (Linux, macOS, Windows), bir Homebrew tap'i ve bir konteyner imajı yayımlanır. hdmx version komutu sürümü, derleme tarihini ve ikili dosyanın hangi API şema sürümüne göre derlendiğini yazdırır.

Kimlik doğrulama

hdmx, bir kişisel erişim jetonuyla kimlik doğrular — bkz. Herkese açık API → Kimlik doğrulama. Jetonu temsilci uygulamasında Settings → API tokens altında kendiniz oluşturun; jeton kapsamlar, zorunlu bir IP izin listesi ve bir son kullanma tarihi taşır.

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

Jeton, işletim sisteminin anahtar zincirinde saklanır. CI ve konteynerler için üç ortam değişkeni, hiçbir etkileşimli soru sormadan kayıtlı profilin yerine geçer: HDMX_HOST, HDMX_SUBDOMAIN, HDMX_TOKEN.

Birden çok kiracı profillerle yönetilir — bir profil; bir sunucuyu, bir alt alan adını, bir jetonu ve bir dizi varsayılanı bir arada tutar:

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

Neler yapabilir

Komut yüzeyi, yardım masasının kaynak ailelerine karşılık gelir. Öne çıkan alanlar:

Alan	Yapabilecekleriniz
Talepler	listeleme, arama, önceliklendirme, görüntüleme, güncelleme, atama, durum / öncelik / etiket ayarlama, birleştirme, silme
Mesajlar	bir talebin mesajlarını okuma, herkese açık yanıt veya dahili not gönderme
Sohbet	görüşmeleri listeleme ve görüntüleme, gönderme, kapatma, yeniden açma, katılma, ayrılma, okundu işaretleme
Müşteriler	listeleme, arama, görüntüleme, oluşturma, güncelleme, birleştirme
Referans verileri	departmanlar, durumlar, öncelikler, posta kutuları, etiketler, kullanıcılar
Raporlar	genel bakış, hacim, yanıt süreleri, temsilci bazında, biriken iş, kırılımlar
Hesap	geçerli hesap, üst veriler, geçerli kullanıcı

Özellikle belirtmeye değer iki kolaylık var:

• Kimlikler yerine adlar. Bayraklar hem okunabilir bir adı hem de bir kimliği kabul eder — --status open, --assignee [email protected] ya da ham tanımlayıcı, hepsi çözümlenir. Bu eşleme her hesap için yerel olarak önbelleğe alınır.
• Adlandırılmış iş akışları. hdmx tickets triage, standart önceliklendirme görünümünü çalıştırır (açık, kapatılmamış, özellik isteği olmayan, önceliğe göre sıralı); çağıran tarafın filtreyi her seferinde yeniden kurmasına gerek kalmaz.

Çıktı ve güvenlik

• Makineler için varsayılan olarak yapılandırılmış. Boruya aktarılan çıktı bir JSON zarfıdır (ok, data, summary, warnings, error, meta); bir TTY ise okunabilir Markdown alır. --jq JSON'u anında süzer. Veriler stdout'a, tanılama bilgileri stderr'e gider.
• Öğreten hatalar. Bir değer reddedildiğinde hata, geçerli değerleri ve somut bir sonraki komutu belirtir — örneğin hatalı bir durum girildiğinde gerçek durumların listesi ve bir çağrı örneği döner.
• Sınırlı yanıtlar. Listeleme komutlarının varsayılan bir sayfa boyutu ve kesin bir üst sınırı vardır; çıktı kırpıldığında yanıt bunu bildirir ve nasıl daraltacağınızı söyler. Böylece yanıtlar bir aracının jeton bütçesi içinde kalır.
• Deneme çalıştırması ve onay kapıları. Her mutasyon --dry-run bayrağını kabul eder (işlemi ve öngörülen etkisini göndermeden gösterir). Yıkıcı işlemler --force gerektirir; müşteriye görünen mesajların veya dahili notların gönderilmesi ise --approve gerektirir.

Yüzeyi öğrenme

Yardım üç katmanlıdır ve üç ayrı kitleye yöneliktir:

• hdmx <command> --help — serbest metinle kullanım ve örnekler (insanlar için).
• hdmx agent-context — her komutun, bayrağın, enum'ın, hata kodunun, varsayılanın ve adlandırılmış iş akışının sürümlenmiş, makine tarafından okunabilir şeması (kararlı bir yüzeye bağlanan aracılar için).
• hdmx skills — birkaç komutu adlandırılmış bir uygulama kılavuzunda birleştiren bileşim tarifleri (örneğin önceliklendir-ve-yanıtla akışı).

Herkese açık API ile ilişkisi

hdmx, yardım masasının herkese açık API'sinin tarayıcı dışındaki ilk tüketicisidir. Yaptığı her şey, aynı PAT ile kimliği doğrulanan GraphQL uç noktasından, aynı kapsamlar ve istek limitleri altında geçer — ayrıcalıklı bir arka kapı yoktur. Sözleşme API şemasıdır; hdmx sabitlenmiş bir API sürümüne göre derlenir ve API'nin kullanımdan kaldırma politikasını izler, böylece bir CLI sürümü uyumlu (uyumluluğu bozmayan) her sunucu şemasıyla çalışmaya devam eder.