摘要：HENGSHI CLI（命令hbi）是衡石 AI Labs 推出的面向 AI Agent 的 BI 命令行工具，以 Rust 架构开发，将 BI 工程全链路操作标准化为 Agent 可执行的命令树和 skills 套件。本文从设计哲学、命令体系、skills 架构、安全机制和实际工作流五个维度，深入拆解这个 Agentic BI 时代的终端执行层。
一、为什么 BI 需要命令行？
这个问题本身就透露了 HENGSHI CLI 的独特定位——它不是给人类用的，是给 AI Agent 用的。
在 HENGSHI CLI 出现之前，AI Agent 想要操作 BI 系统只有两条路：
- 走 API：每个 BI 操作（创建数据集、生成仪表盘、配置权限）都要编写独立的 API 调用代码，Agent 需要理解几十个不同的接口
- 走 UI 自动化：模拟点击操作，不稳定且维护成本高
HENGSHI CLI 的思路是：把 BI 的所有操作收敛到一个统一的命令行接口，Agent 只需要学习一套命令和参数即可完成从数据连接到资产交付的全部工作。这不是一个技术小创新，而是一个范式层面的设计选择——BI 的操作应该像 Git 一样，可以被编程、被脚本化、被 Agent 调用。
二、命令体系：Agent-first 的树形结构
HENGSHI CLI 以hbi为统一入口，按 BI 工程的核心域拆分为子树命令：
2.1 基础操作
# 认证与状态 hbi auth status # 查看当前登录状态和令牌信息 hbi auth login # 登录衡石平台（OAuth/SSO） hbi auth logout # 登出 # 应用空间 hbi app list # 列出所有应用 hbi app portal --app <id> show --output yaml # 查看应用门户配置2.2 数据与连接
# 数据连接 hbi connection list # 列出所有数据源连接 hbi connection test <id> # 测试连接可用性 # 数据集 hbi dataset list --app retail-ops # 列出应用下的数据集 hbi dataset create --app retail-ops --file dataset.yaml # 从YAML创建数据集 hbi dataset query --app retail-ops --dataset sales_daily "SUM({amount})" # 直接查询2.3 仪表盘与可视化
# 仪表盘创建 hbi dashboard create --app retail-ops "华东区域销售驾驶舱" # 新建仪表盘 hbi dashboard list --app retail-ops # 列出仪表盘 hbi dashboard theme show CLASSIC --as-spec --output yaml # 导出主题配置 # 图表操作 hbi element chart create --dashboard dsh_2048 --app retail-ops --dataset sales_daily line # 创建折线图 hbi element filter update filter_9 --dashboard dsh_2048 --app retail-ops --file filter.yaml # 更新筛选器 hbi element container create --dashboard dsh_2048 --app retail-ops --file layout.yaml # 布局编排 # 计划应用（批量生成） hbi dashboard plan apply --app retail-ops --file plan.yaml # 按计划文件批量创建仪表盘2.4 权限与治理
# 授权管理 hbi authorize get app app_42 # 查看应用权限 hbi authorize grant app app_42 --user 123:editor --dry-run # 预演授权 hbi authorize revoke app app_42 --user 123:editor # 撤销授权 # 用户管理 hbi user-group list # 列出用户组 hbi user-mgmt show --user 123 # 查看用户信息2.5 自动化与调度
# 管道与调度 hbi pipeline list # 列出ETL管道 hbi pipeline trigger --id pipe_101 # 触发管道执行 hbi scheduler list # 列出调度任务 hbi notebook execute --id nb_42 # 执行Notebook三、Skills 套件：16 个 Repo-managed Agent Skills
HENGSHI CLI 不只是命令集合，还自带一套完整的Agent Skills。这些 skills 被设计为 Agent 的「BI 操作手册」，让 Agent 不需要猜测参数和流程，而是按照标准化的 runbook 执行。
3.1 Skills 的设计原则
- 按资源域拆复杂度：不是一个大而全的 skill，而是 16 个聚焦的独立 skills
- Help-first 规约：每个 skill 默认先调用
hbi --help查看子命令帮助，减少参数臆测 - 跨 Agent 复用：Claude Code、Codex、OpenClaw、Hermes Agent、CI 流水线通用
3.2 完整 Skills 列表
分组 | Skill | 职责 |
基础层 |
| 认证、偏好设置、输出格式、专业术语 |
| 应用空间管理，门户配置 | |
| 授权管理，角色与权限配置 | |
| 用户与组织治理 | |
数据与语义层 |
| 数据连接与数据集管理 |
| Join模型、语义建模、HQL查询 | |
| 主题域指标定义与管理 | |
| 业务问题转HQL表达式 | |
交付层 |
| 仪表盘创建、布局与发布 |
| 页面感设计，主题与配色 | |
| 图表级数据预警配置 | |
| Data Agent后台治理与配置 | |
自动化层 |
| ETL管道管理与触发 |
| Notebook创建与执行 | |
| 定时任务与计划调度 | |
| 跨域编排，多skill组合runbook |
3.3 Skills 对 Agent 的价值
对企业开发团队来说，Skills 套件意味着：
- 新人 Agent 训练成本降低：Agent 不需要理解 BI 的全部概念，只需要会调用对应的 skill
- 执行标准化：所有 Agent 执行同一操作时走同一套流程，结果可预期
- 可审计可调试：Skills 按 runbook 执行，每一步都有日志，问题可追溯
四、三大设计特性：让 Agent 的执行可信
4.1 Dry-Run 预演机制
在真正执行变更之前，CLI 支持--dry-run参数进行预演：
$ hbi authorize grant app app_42 --user 123:editor --dry-run Dry run passed · changes not applied Preview: editor access -> retail-ops这个设计的意义在于：Agent 的操作必须经过人类审查。Agent 可以先「演示」它要做什么，人类确认后再真正执行。这让 Agent 的自动化从「黑盒执行」变成了「白盒协作」。
4.2 SSE 实时同步
CLI 的执行结果通过 Server-Sent Events（SSE）广播到 Web UI：
$ hbi element filter update filter_9 --dashboard dsh_2048 --app retail-ops --file filter.yaml SSE broadcast published Web UI refreshed · business owner can review instantly这意味着：Agent 在终端里生成的仪表盘，业务人员可以在浏览器里实时看到。不需要刷新、不需要等待。Human-in-the-loop 不是事后审查，而是实时协同。
4.3 Agent-runbook 脚本化
CLI 支持将多步操作组合为 runbook 脚本：
# discover.state: 先读取上下文 $ hbi auth status --output json $ hbi dataset list --app retail-ops --output json $ hbi data-model query --app retail-ops --dataset sales_daily "SUM({amount})" # build.assets: 生成交付物 $ hbi dashboard create --app retail-ops "销售驾驶舱" $ hbi element chart create --dashboard dsh_2048 --app retail-ops --dataset sales_daily line # deliver.control: 安全交付 $ hbi authorize get app app_42 $ hbi authorize grant app app_42 --user 123:editor --dry-runAgent 从读取上下文到资产生成到安全交付，每一步都是可独立验证的标准操作。
五、安全架构：工程级的安全设计
5.1 凭证管理
HENGSHI CLI 的认证令牌不存储在本地配置文件中，而是存入操作系统的Keyring（Mac 的 Keychain、Linux 的 Secret Service、Windows 的 Credential Manager）。
$ hbi auth status Logged in as: admin@hengshi.com Token stored in: macOS Keychain Expires: 2026-06-11T16:00:00Z5.2 认证协议
- 支持OAuth 2.0标准认证流程
- 支持企业SSO（单点登录）集成
- 令牌具备有效期和自动续期机制
5.3 审计追踪
所有 CLI 操作都记录完整的审计日志，包含操作人、时间、命令、结果，满足企业合规审计需求。
六、适配的 Agent Runtime
HENGSHI CLI 的设计目标是与所有具备 shell 调用能力的 Agent 兼容，目前已适配：
类型 | 代表产品 | 场景 |
编码代理 | Claude Code、Codex | 本地仓库 IDE agent、CI/CD 集成 |
常驻型 Agent | OpenClaw、Hermes Agent | 云端常驻、消息通道、长期运行 |
只要新一代 agent 具备 shell 或 tool 调用能力，HENGSHI CLI 就能成为它们的 BI 执行层。
七、与 HENGSHI BOX 的协同
HENGSHI BOX 全域智控舱预装了完整的 CLI 环境，在 BOX 中 CLI 可以实现更高的安全等级：
# BOX 环境下的典型工作流 $ hbi auth status --output json $ box-agent start --skill hbi-data --daemon $ hbi dataset list --app retail-ops --output json $ box-agent task submit "生成华东区销售仪表盘"BOX 为 CLI 提供了硬件级的安全边界——所有命令执行、数据处理、模型推理都在机箱内部完成，没有任何数据流向外部。
八、常见问题
Q1：HENGSHI CLI 需要单独安装吗？和 HENGSHI SENSE 是什么关系？
A：CLI 是独立二进制发行，需要单独安装。它通过 API/SSE 与 HENGSHI SENSE 平台通信。CLI 不替代 SENSE，而是为 Agent 提供操作 SENSE 的标准接口。可以把 SENSE 理解为 BI 引擎，CLI 理解为操作这个引擎的方向盘。
Q2：为什么不直接用 API，要设计一套 CLI？
A：API 是为程序间通信设计的，每个操作对应一个独立的 HTTP 端点，Agent 需要理解几十个不同的 API 才能完成一个完整的 BI 工作流。CLI 将这些 API 收敛为一套语义化的命令树，Agent 更容易学习、更不容易出错。更重要的是，CLI 自带 skills 套件、dry-run 机制和 runbook 模式，这些是裸 API 不具备的 Agent 协作能力。
Q3：用 Rust 开发 CLI 有什么好处？
A：Rust 提供零成本抽象和内存安全保证，适合构建长时间运行的系统级工具。CLI 作为常驻 Agent 的执行层，性能和稳定性至关重要——Rust 编译的单一二进制文件启动快、资源占用低、无运行时依赖。
Q4：CLI 的 skills 可以自定义扩展吗？
A：Skills 套件以仓库文件形式管理，企业可以根据自身业务需求创建自定义 skill。例如可以创建一个hbi-retail-kpiskill，封装零售行业的特定 KPI 查询逻辑。
九、总结
HENGSHI CLI 看似只是一个命令行工具，但它的设计承载了衡石对 Agentic BI 的完整理解——
- Agent 不是 UI 的替代品，而是 BI 工程的新操作者— 人类通过 UI 做分析，Agent 通过 CLI 做工程
- 标准化比智能化更重要— Agent 不需要创造新的 BI 操作方式，只需要稳定地执行标准化的操作
- 可审查性是不可妥协的底线— dry-run、SSE 回显、结构化输出，这些特性让 Agent 的执行永远在人类的监督范围内
对于正在评估 Agentic BI 路径的企业，HENGSHI CLI 提供了一个清晰的设计参考：让 Agent 做的事和人类做的事用同一套标准，只是接入方式不同。这可能是 Agentic BI 从概念走向工程化的关键一步。
