HENGSHI CLI
概述
HENGSHI CLI 是 HENGSHI 官方命令行工具，也是面向人类与 AI Agent 的统一命令入口。它把原本分散在界面点击、后台 API、临时脚本里的操作，整理成稳定、可审查、可自动化的命令工作流。
CLI 当前覆盖的核心能力包括：
- 数据连接与数据集接入
- HQL / HE 查询与数据预览
- 仪表盘、报表与元素创建 / 配置
- 权限查询、授权与回收
- 系统配置、环境检查与运维动作
- 与官方 skills 配套的 Agent 执行工作流
NOTE
从 2.0.0 开始，公开命令入口为 hbi，文档默认使用 hbi 与 HBI_*。为避免混淆，本页不展开旧命名空间的兼容细节；如你的环境仍在使用旧命令/变量，请以实际安装包与升级脚本输出为准。
作为 HENGSHI SENSE 与 Agent 之间的桥梁
HENGSHI CLI 的角色，不是替代 HENGSHI SENSE 页面，而是把 HENGSHI SENSE 的核心能力转成可稳定调用、审查和复用的命令入口。它既适合人工在终端直接使用，也适合被 OpenClaw 等 Agent、CI 流水线和自动化脚本调用。
在这条链路里，常见分工是：
| 层级 | 角色 | 典型职责 |
|---|---|---|
| 人 | 任务提出者与审核者 | 提要求、确认边界、审结果 |
| Agent / 自动化流程 | 编排层 | 拆步骤、组织顺序、决定下一步调用哪条命令 |
| HENGSHI CLI + skills | 桥梁与执行层 | 把 HENGSHI SENSE 的业务能力转换成结构化命令、输出与 --dry-run 预演 |
| HENGSHI SENSE 服务端 | 业务能力层 | 真正完成连接、查询、建模、授权、发布等动作 |
如果你在为 OpenClaw 或其他 Agent 设计可复用工作流，CLI 通常就是这座桥本身：上接 Agent 的任务编排，下接 HENGSHI SENSE 的真实业务能力，而不是让 Agent 自己去猜页面路径或临时拼 API。
CLI 适合解决什么问题
| 场景 | CLI 带来的价值 |
|---|---|
| 让 Agent 代做 BI 交付动作 | 统一命令与输出格式，避免“每个 Agent 猜一套 API” |
| 把高风险改动放进审批流 | --dry-run 先预演，再决定是否真正执行 |
| 把结果回传给人或其他系统 | json / yaml / table 输出更容易被读取、记录和二次处理 |
| 做批量化、可重复的运维任务 | 单命令、脚本、CI、Agent 都能复用同一条执行路径 |
| 让界面外产生的变更回到前端体验里 | 通过 SSE / Autopilot 指示器补上实时回显链路 |
命令面一览
HENGSHI CLI 不是单一功能命令，而是一整套面向 BI 交付主链路的命令树。
| 命令域 | 说明 | 示例 |
|---|---|---|
app | 应用、空间、门户、公共维度 | hbi app list --area personal-area --root |
dataset | 数据集接入与列表查看 | hbi dataset list --app 4812 --output json |
data-model | HQL / HE 查询与数据预览 | hbi data-model query --app 4812 --dataset 3 "SUM({amount})" |
dashboard | 仪表盘、报表、主题 | hbi dashboard create --app 4812 "区域销售驾驶舱" |
element | 图表、筛选器、容器、按钮、iframe 等元素，支持自定义标题与内容识别（链接/邮箱/图片）开关 | hbi element chart create --dashboard 2048 --app 4812 --dataset 3 table --identify-link true --identify-email true --identify-image true |
connection | 数据源连接创建与管理 | hbi connection list |
authorize | 统一授权 API | hbi authorize grant app 42 --user 123:editor --dry-run |
preferences | 系统配置查看与变更预演 | hbi preferences everest --output json |
HQL 表达式支持
CLI 的 --dimension、--measure 和 --where 参数接受 HQL (HENGSHI Query Language) 表达式，不限于简单字段名。
- 时间分组：建议使用日历 HQL 函数（如
day()、month()、trunc_month()），避免substring/date_format等字符串截断 - 跨期函数：HQL 还提供
moy()、dom()、dow()、doy()、woy()、qoy()等跨期函数，实现月跨年、天跨月、季度跨年等连续时间聚合——这与前端 UI 的"月(跨年)"、"天(跨月)"选项在语义上完全等价 - 表达式验证：使用
hbi dataset expression-rewrite验证和重写表达式
详见 element chart create --dimension 的说明。
官方 skills 与 Agent 执行
CLI 会和官方 bundled skills 一起交付。官方 skills 通常按能力域分层；对外说明时，推荐同时保留 skill 名称 与 职责描述：
hbi-core：认证、配置、输出与术语规则hbi-data、hbi-data-modeling、hbi-pipeline、hbi-notebook：数据连接、数据集、建模、执行与指标工作流hbi-dashboard、hbi-dashboard-taste、hbi-app：仪表盘规划、页面布局、元素配置与应用承载hbi-permission、hbi-user-mgmt：权限查询、授权回收与用户组织治理hbi-workflow：跨领域编排与顺序控制
这些 skills 的作用不是替代 CLI，而是把“什么时候调用哪条命令、应该先读什么、哪些动作必须先 --dry-run”这样的执行经验沉淀成可复用的标准流程。
阅读路径
如果你是第一次接触 HENGSHI CLI，建议按下面顺序阅读：
- 安装与升级
- 认证与连接
- Agent 接入与 skills
- 常用工作流
- 命令参考 — 已为高频命令域补充最小可用示例与典型输出，适合第一次上手
- 实时回显与 Autopilot
- 排障与 FAQ
建议
如果你的目标是让 Agent 稳定执行动作，而不是人工逐条敲命令，优先看 Agent 接入与 skills 与 常用工作流。如果你想快速上手某个命令域，直接进入 命令参考；高频命令域已经补充了最小可用示例和典型输出。