hdmx — 帮助台命令行工具
hdmx 是帮助台的单二进制命令行客户端。它把公共 GraphQL API 封装成“资源 + 动作”式的好用命令，让 AI 智能体和人都能从终端或脚本操作帮助台，而不必打开浏览器。
它的设计是智能体优先、人其次：每条命令都以非交互方式运行，每条返回数据的命令都可以输出结构化的 --json 信封，错误会列举它所期望的有效取值，而机器可读的命令 schema 让智能体一次调用即可学会整套接口，并在众多任务中反复使用。
该命令行工具从自己的仓库 github.com/mirasvit/hdmx 发布，并不属于帮助台代码库。帮助台一侧只提供 hdmx 用于认证的公共 API 和个人访问令牌。该仓库的 README 才是当前命令清单的实时权威来源；本页提供整体导览，以及它所依赖的契约。
安装
go install github.com/mirasvit/hdmx/cmd/hdmx@latest
每次发布都会提供预编译二进制文件（Linux、macOS、Windows）、Homebrew tap 和容器镜像。hdmx version 会打印版本号、构建日期，以及该二进制文件所基于的 API schema 版本。
身份验证
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
它能做什么
命令体系对应帮助台的资源族。主要领域包括：
| 领域 | 可以做什么 |
|---|---|
| 工单 | 列出、搜索、分诊、查看、更新、指派、设置状态 / 优先级 / 标签、合并、删除 |
| 消息 | 阅读某工单的消息，发布公开回复或内部备注 |
| 聊天 | 列出并查看会话，发送、关闭、重新打开、加入、离开、标记为已读 |
| 客户 | 列出、搜索、查看、创建、更新、合并 |
| 基础数据 | 部门、状态、优先级、邮箱、标签、用户 |
| 报表 | 总览、工单量、响应时间、按客服统计、积压、细分 |
| 账户 | 当前账户、元数据、当前用户 |
有两处便利值得单独一提：
- 用名称代替 ID。 参数既接受可读名称，也接受 ID——
--status open、--assignee [email protected]或原始标识符都能被解析。这种映射会按账户在本地缓存。 - 具名工作流。
hdmx tickets triage直接运行标准分诊视图（未关闭的开启工单、排除功能请求、按优先级排序），调用方无需每次重新拼装筛选条件。
输出与安全
- 默认面向机器的结构化输出。 通过管道传出的输出是一个 JSON 信封（
ok、data、summary、warnings、error、meta）；在 TTY 下则输出便于阅读的 Markdown。--jq可就地过滤 JSON。数据写入 stdout，诊断信息写入 stderr。 - 会“教人”的错误。 当某个取值被拒绝时，错误会给出有效取值以及一条具体的后续命令——例如状态填错时，会返回真实存在的状态列表和一个调用示例。
- 有上限的响应。 列表类命令有默认页大小和硬性上限；输出被截断时，响应会明确说明，并告诉你如何缩小范围。这能让响应保持在智能体的 token 预算之内。
- 预演与审批关卡。 每个变更操作都接受
--dry-run（只呈现该操作及其预期影响，不实际发送）。破坏性操作需要--force；发布对客户可见的消息或内部备注需要--approve。
了解整套接口
帮助分为三层，面向三类使用者：
hdmx <command> --help—— 自由文本的用法说明和示例（面向人）。hdmx agent-context—— 一份带版本的机器可读 schema，涵盖每条命令、参数、枚举、错误码、默认值和具名工作流（面向需要绑定稳定接口的智能体）。hdmx skills—— 把多条命令串成具名操作手册的组合方案（例如分诊并回复的流程）。
与公共 API 的关系
hdmx 是帮助台公共 API 的第一个非浏览器使用方。它所做的一切都走同一个以 PAT 认证的 GraphQL 端点，遵循同样的权限范围和速率限制——不存在任何特权后门。API schema 就是契约；hdmx 基于固定的 API 版本构建，并遵循该 API 的弃用策略，因此某个 CLI 版本可以继续与任何兼容（无破坏性变更）的服务端 schema 协同工作。