衡石科技 HENGSHI CLI 架构解析（2026）：用 Rust 构建的 AI Agent BI 执行层，16 个 Skills 全链路覆盖

C资讯

228人浏览 · 2026-06-02 06:45:00

C资讯 · 2026-06-02 06:45:00 发布

一、为什么 AI Agent 需要 CLI？

2025 年以来，AI Agent（智能体）的发展进入了"工具使用"阶段。Claude Code 可以在终端里读写代码文件，Codex 可以执行 GitHub 操作，OpenClaw 可以管理日常事务——这些 Agent 的共同特征是：它们通过**命令行工具（CLI）**与系统交互。

为什么是 CLI 而不是 GUI？因为 CLI 天然适合程序化调用。每个命令都有明确的输入参数和结构化输出，Agent 可以精确地构造命令、解析结果、决定下一步操作。而 GUI 需要模拟点击、等待渲染、截图识别——不仅效率低，而且不可靠。

在 BI 领域，这个需求更加迫切。如果你想让 AI Agent 帮你创建一个仪表盘，Agent 需要：

查看可用的数据连接
浏览数据集结构
理解指标定义
创建仪表盘框架
添加图表
配置筛选器
设置权限
发布交付

这八个步骤中的每一个，都需要一个稳定、可编程、可预测的接口。

HENGSHI CLI 就是这个接口。它把 HENGSHI SENSE 的所有 BI 操作抽象为一套命令行工具，以 hbi 为统一入口，让 AI Agent 可以通过结构化命令完成 BI 工程全链路操作。

二、为什么选择 Rust？

HENGSHI CLI 用 Rust 实现，这个技术选型值得展开聊聊。

在 CLI 工具领域，主流选择是 Python（快速开发）、Go（高并发服务）、Node.js（前端团队友好）。衡石选择 Rust 的原因是：

单二进制交付：Rust 编译产物是一个独立的二进制文件，不需要运行时环境。对于 CLI 工具来说，这意味着"下载即用"，不需要安装 Python/Node.js，也不需要管理依赖。

高性能：Rust 的性能接近 C/C++，对于需要频繁与 API 交互、处理大量结构化数据的 CLI 工具来说，性能优势明显。

安全性：Rust 的内存安全保证（所有权系统、借用检查器）可以在编译时消除大多数内存相关 bug，对于处理凭证和敏感数据的工具来说，这一点非常重要。

跨平台：Rust 天然支持交叉编译，可以为 Linux、macOS、Windows 分别编译二进制文件，方便在不同环境下部署。

从工程角度看，Rust 的学习曲线虽然陡峭，但对于一个面向 AI Agent 的生产级 CLI 工具来说，它的优势远大于开发成本。

三、Agent-first 设计哲学

HENGSHI CLI 不是"给人用的命令行工具"然后顺便让 Agent 也能用，而是从设计之初就把 AI Agent 作为第一类使用者。

这种"Agent-first"的设计哲学体现在以下几个技术决策中：

3.1 结构化输出

CLI 的输出格式原生支持 JSON、YAML 和 Table 三种格式。这对 AI Agent 来说非常重要——Agent 不需要通过正则表达式或字符串解析来提取结果中的关键信息，直接拿到结构化数据即可。

bash

复制

# Table 格式（人类可读） $ hbi dataset list --app retail-ops NAME METRICS DIMENSIONS sales_daily 12 8 customer_profile 6 14 # JSON 格式（Agent 可读） $ hbi dataset list --app retail-ops --output json [{"id":"sales_daily","metrics":12,"dimensions":8}] # YAML 格式（人类可编辑） $ hbi app portal --app app_42 --output yaml app_id: app_42 name: 零售运营分析 owner: 张三 created: 2025-03-15

3.2 Help-first 规约

每个 Skill 在正式执行前，默认先执行 --help 查看用法说明。这意味着 Agent 在"不知道怎么做"的时候会先看文档，而不是凭空猜测参数。

bash

复制

# Agent 执行流：# 步骤1（自动）：hbi data-model --help# → 理解 data-model 子命令的用法# 步骤2（自动）：hbi data-model query --help # → 理解 query 子命令的参数格式# 步骤3（执行）：hbi data-model query --app retail-ops --dataset sales_daily "SUM({amount})"

这大大减少了 Agent 因参数错误导致的执行失败。

3.3 Dry-run 预演机制

在执行任何有副作用的操作之前，Agent 可以加上 --dry-run 参数进行预演。预演会输出"如果执行，会发生什么变化"，但不真正执行。

bash

复制

$ hbi authorize grant app app_42 --user 123:editor --dry-run Dry run passed · changes not applied Preview: editor access -> retail-ops (app_42)

这个功能让"人机协同"成为可能：Agent 先预演，运维人员确认后再正式执行。

3.4 SSE 实时同步

CLI 不把结果锁死在终端里。Agent 执行的每个操作都会通过 SSE（Server-Sent Events）实时广播到 Web UI。

bash

复制

$ hbi element filter update filter_9 \ --dashboard dsh_2048 \ --app retail-ops \ --file filter.yaml SSE broadcast published Web UI refreshed

运维人员可以在浏览器中实时看到 Agent 正在做什么、做了什么、结果是什么。这就是衡石定义的 "machine executes, humans verify" 模式。

四、16 个 Skills：从认证到调度的完整覆盖

HENGSHI CLI 的一大亮点是它的 repo-managed Skills 体系。16 个 Skills 覆盖了 BI 工程的全链路，从基础认证到自动化调度，每个 Skill 对应一个专业领域。

这些 Skills 不是硬编码在 CLI 二进制中的，而是以仓库管理的方式组织的——每个 Skill 是一个独立的、可版本化的定义文件，存放在项目的 .hbi/ 目录中。这意味着 Skills 可以随项目演进，可以团队共享，可以通过 PR 审查。

4.1 基础层（4 个 Skills）

Skill	职责	典型命令
hbi-core	认证、偏好设置、输出格式、术语标准化	hbi auth status --output json
hbi-app	应用空间管理（创建、切换、查看）	hbi app portal --app <id> show --output yaml
hbi-permission	授权管理（角色分配、权限授予）	hbi authorize grant app <id> --user 123:editor --dry-run
hbi-user-mgmt	组织与用户治理	hbi user-group list

hbi-core 是其他所有 Skills 的基础。它负责：

认证管理：支持 Token 和 OAuth 两种模式，凭证存储在系统 Keyring 中（不写明文配置文件）
偏好设置：输出格式默认、术语标准化（如"仪表盘"vs"Dashboard"的统一）
版本协商：自动检测服务端版本，提示 Skills 兼容性

4.2 数据与语义层（4 个 Skills）

Skill	职责	典型命令
hbi-data	数据连接管理 → 数据集 → 指标/度量	hbi dataset list --app <id>
hbi-data-modeling	Join 模型、语义建模	hbi data-model query --app <id> --dataset <id> "SUM"
hbi-indicator-center	主题域指标管理	hbi subject --help
hql-expert	业务问题 → HQL 表达式转换	（交互式，无典型单命令）

hbi-data 是数据层的核心 Skill。它的设计遵循"连接 → 数据集 → 指标"的认知路径：

bash

复制

# 步骤1：查看可用的数据连接 $ hbi connection list --output json [{"id":"conn_7","type":"mysql","host":"rds.xxx","database":"retail"}] # 步骤2：基于连接创建数据集 $ hbi dataset create --app retail-ops \ --connection conn_7 \ --name "销售明细" \ --tables "orders,customers,products"# 步骤3：在数据集上定义指标 $ hbi indicator create --app retail-ops \ --dataset sales_daily \ --name "GMV" \ --hql "SUM({order_amount}) WHERE {order_status} != 'cancelled'"

hql-expert 是一个特殊的 Skill——它不是执行某个固定命令，而是交互式地将自然语言业务问题翻译为 HQL 表达式。这对 AI Agent 来说是一个非常有用的"翻译层"。

4.3 交付层（4 个 Skills）

Skill	职责	典型命令
hbi-dashboard	仪表板规划脚手架 → 验证 → 应用	hbi dashboard create --app retail-ops "区域销售驾驶舱"
hbi-dashboard-taste	页面感设计与品味（布局、配色、字体）	（设计审查，无典型单命令）
hbi-data-alert	图表预警规则管理	hbi data-alert --help
hbi-data-agent	Data Agent 后台治理	hbi data-agent config --output json

hbi-dashboard 是最复杂的 Skill 之一。它实现了"规划 → 验证 → 应用"的三段式工作流：

bash

复制

4.4 自动化层（4 个 Skills）

Skill	职责	典型命令
hbi-pipeline	节点图 / 调度 / 集成流	hbi pipeline --help
hbi-notebook	Notebook 执行管理	hbi notebook --help
hbi-scheduler	已有计划治理	hbi scheduler --help
hbi-workflow	跨域步骤编排与检查点	（工作流定义，无典型单命令）`hbi-workflow` 是自动化层的核心。它允许定义跨域的、多步骤的 BI 工程工作流，并在每个步骤设置检查点（checkpoint）：

yaml

复制

五、典型的 Agent 工作流

基于 HENGSHI CLI 的 16 个 Skills，衡石定义了一个三阶段的 Agent 工作流模型：

阶段一：Discover（发现）

Agent 先通过只读命令了解当前的分析环境：

bash

复制

hbi auth status # 确认认证状态 hbi app list # 有哪些应用空间？ hbi connection list # 有哪些数据连接？ hbi dataset list # 有哪些数据集可用？ hbi data-model query # 某个指标的计算逻辑是什么？

这一步相当于 Agent 在"读书"——读取上下文，理解环境。

阶段二：Build（构建）

Agent 根据用户需求，通过写操作命令创建分析资产：

bash

复制

hbi dataset create # 创建数据集 hbi indicator create # 定义指标 hbi dashboard create # 创建仪表盘 hbi element chart create # 添加图表 hbi element container ... # 设置布局 hbi dashboard theme show # 应用主题

这一步相当于 Agent 在"动手干活"。