hdmx — CLI ของเฮลป์เดสก์
hdmx คือไคลเอนต์บรรทัดคำสั่งไฟล์เดียวสำหรับเฮลป์เดสก์ มันห่อหุ้มGraphQL API สาธารณะ ไว้เบื้องหลังคำสั่งรูปแบบ "ทรัพยากร + การกระทำ" ที่ใช้งานง่าย เพื่อให้ทั้งเอเจนต์ AI และคนสั่งงานเฮลป์เดสก์จากเทอร์มินัลหรือสคริปต์ได้ แทนที่จะต้องใช้เบราว์เซอร์
ออกแบบโดยยึด เอเจนต์เป็นหลัก คนเป็นรอง ทุกคำสั่งทำงานแบบไม่โต้ตอบ ทุกคำสั่งที่คืนข้อมูลสามารถส่งออกซองข้อมูล --json แบบมีโครงสร้าง ข้อผิดพลาดจะระบุค่าที่ถูกต้องซึ่งระบบคาดหวัง และสคีมาคำสั่งที่เครื่องอ่านได้ช่วยให้เอเจนต์เรียนรู้ส่วนต่อประสานทั้งหมดได้ในการเรียกครั้งเดียว แล้วนำไปใช้ซ้ำได้ในงานอีกมากมาย
CLI นี้เผยแพร่จากคลังโค้ดของตัวเอง github.com/mirasvit/hdmx ไม่ได้เป็นส่วนหนึ่งของโค้ดเฮลป์เดสก์ ฝั่งเฮลป์เดสก์จัดเตรียมเพียงAPI สาธารณะและโทเค็นการเข้าถึงส่วนบุคคล ที่ hdmx ใช้ยืนยันตัวตนเท่านั้น ไฟล์ README ของคลังโค้ดนั้นคือแหล่งข้อมูลที่เป็นปัจจุบันสำหรับรายการคำสั่ง ส่วนหน้านี้ให้ภาพรวมและอธิบายข้อตกลงที่ CLI อาศัยอยู่
การติดตั้ง
go install github.com/mirasvit/hdmx/cmd/hdmx@latest
ทุกครั้งที่ออกเวอร์ชันใหม่จะมีไฟล์ไบนารีสำเร็จรูป (Linux, macOS, Windows) แท็ป Homebrew และอิมเมจคอนเทนเนอร์เผยแพร่ด้วย คำสั่ง hdmx version จะแสดงเวอร์ชัน วันที่บิลด์ และเวอร์ชันสคีมาของ API ที่ไบนารีนี้ถูกบิลด์ขึ้นมา
การยืนยันตัวตน
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
ทำอะไรได้บ้าง
ชุดคำสั่งสอดคล้องกับกลุ่มทรัพยากรของเฮลป์เดสก์ พื้นที่หลัก ๆ ได้แก่:
| พื้นที่ | สิ่งที่ทำได้ |
|---|---|
| ทิกเก็ต | แสดงรายการ ค้นหา คัดแยก ดูรายละเอียด แก้ไข มอบหมาย ตั้งสถานะ / ระดับความสำคัญ / แท็ก รวม ลบ |
| ข้อความ | อ่านข้อความในทิกเก็ต ส่งคำตอบแบบสาธารณะหรือบันทึกภายใน |
| แชท | แสดงรายการและดูบทสนทนา ส่ง ปิด เปิดใหม่ เข้าร่วม ออก ทำเครื่องหมายว่าอ่านแล้ว |
| ลูกค้า | แสดงรายการ ค้นหา ดูรายละเอียด สร้าง แก้ไข รวม |
| ข้อมูลอ้างอิง | แผนก สถานะ ระดับความสำคัญ กล่องจดหมาย แท็ก ผู้ใช้ |
| รายงาน | ภาพรวม ปริมาณงาน เวลาตอบกลับ แยกตามเจ้าหน้าที่ งานค้าง และการแจกแจงต่าง ๆ |
| บัญชี | บัญชีปัจจุบัน ข้อมูลเมตา ผู้ใช้ปัจจุบัน |
มีสองความสะดวกที่ควรกล่าวถึงเป็นพิเศษ:
- ใช้ชื่อแทนรหัส ตัวเลือกคำสั่งรับได้ทั้งชื่อที่คนอ่านเข้าใจและรหัส —
--status open,--assignee [email protected]หรือรหัสดิบ ล้วนถูกแปลงให้ถูกต้อง การจับคู่นี้ถูกแคชไว้ในเครื่องแยกตามบัญชี - เวิร์กโฟลว์ที่มีชื่อเรียก คำสั่ง
hdmx tickets triageเรียกมุมมองคัดแยกมาตรฐาน (เปิดอยู่ ยังไม่ปิด ไม่ใช่คำขอฟีเจอร์ เรียงตามระดับความสำคัญ) โดยผู้เรียกไม่ต้องประกอบเงื่อนไขกรองขึ้นใหม่ทุกครั้ง
ผลลัพธ์และความปลอดภัย
- มีโครงสร้างสำหรับเครื่องเป็นค่าเริ่มต้น ผลลัพธ์ที่ส่งผ่านไปป์จะเป็นซองข้อมูล JSON (
ok,data,summary,warnings,error,meta) ส่วนบนเทอร์มินัล (TTY) จะได้ Markdown ที่อ่านง่าย ตัวเลือก--jqใช้กรอง JSON ได้ทันที ข้อมูลออกทาง stdout ส่วนข้อมูลวินิจฉัยออกทาง stderr - ข้อผิดพลาดที่สอนวิธีใช้ เมื่อค่าที่ป้อนถูกปฏิเสธ ข้อผิดพลาดจะระบุค่าที่ถูกต้องพร้อมคำสั่งถัดไปที่เป็นรูปธรรม เช่น หากระบุสถานะผิด ระบบจะคืนรายการสถานะที่มีอยู่จริงและตัวอย่างการเรียกใช้
- ผลลัพธ์มีขอบเขตจำกัด คำสั่งแสดงรายการมีขนาดหน้าเริ่มต้นและเพดานสูงสุดที่ตายตัว เมื่อผลลัพธ์ถูกตัด การตอบกลับจะแจ้งให้ทราบและบอกวิธีจำกัดขอบเขตให้แคบลง ทำให้ผลลัพธ์อยู่ในงบโทเค็นของเอเจนต์
- โหมดทดลองและด่านอนุมัติ ทุกมิวเทชันรับตัวเลือก
--dry-run(แสดงการดำเนินการและผลที่คาดว่าจะเกิดขึ้นโดยไม่ส่งจริง) การกระทำที่ทำลายข้อมูลต้องใช้--forceส่วนการส่งข้อความที่ลูกค้ามองเห็นหรือบันทึกภายในต้องใช้--approve
การเรียนรู้ชุดคำสั่ง
คำแนะนำมีสามระดับ สำหรับผู้ใช้สามกลุ่ม:
hdmx <command> --help— คำอธิบายการใช้งานและตัวอย่างในรูปข้อความอิสระ (สำหรับคน)hdmx agent-context— สคีมาที่เครื่องอ่านได้และมีการกำหนดเวอร์ชัน ครอบคลุมทุกคำสั่ง ตัวเลือก ค่า enum รหัสข้อผิดพลาด ค่าเริ่มต้น และเวิร์กโฟลว์ที่มีชื่อเรียก (สำหรับเอเจนต์ที่ต้องยึดกับส่วนต่อประสานที่เสถียร)hdmx skills— สูตรการประกอบคำสั่งหลายคำสั่งเข้าเป็นคู่มือปฏิบัติที่มีชื่อเรียก (เช่น ขั้นตอนคัดแยกแล้วตอบกลับ)
ความสัมพันธ์กับ API สาธารณะ
hdmx เป็นผู้ใช้API สาธารณะ ของเฮลป์เดสก์รายแรกที่ไม่ใช่เบราว์เซอร์ ทุกอย่างที่มันทำล้วนผ่านเอนด์พอยต์ GraphQL เดียวกันที่ยืนยันตัวตนด้วย PAT ภายใต้ขอบเขตสิทธิ์และขีดจำกัดอัตราการเรียกชุดเดียวกัน ไม่มีทางลัดพิเศษใด ๆ สคีมาของ API คือข้อตกลง hdmx ถูกบิลด์กับเวอร์ชัน API ที่ตรึงไว้ และปฏิบัติตามนโยบายการเลิกใช้งานของ API ดังนั้น CLI เวอร์ชันหนึ่งจะยังทำงานได้กับสคีมาฝั่งเซิร์ฟเวอร์ใดก็ตามที่เข้ากันได้ (ไม่มีการเปลี่ยนแปลงที่ทำให้ใช้งานเดิมไม่ได้)