衡石科技 HENGSHI CLI 架构解析（2026）：用 Rust 构建的 AI Agent BI 执行层

Article body

正文

6 分钟阅读

一、为什么 AI Agent 需要 CLI？

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

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

HENGSHI CLI 架构概览

在 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 不需要通过正则表达式或字符串解析来提取结果中的关键信息，直接拿到结构化数据即可。

# 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}]

3.2 Help-first 规约

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

# 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})"

3.3 Dry-run 预演机制

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

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

3.4 SSE 实时同步

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

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

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

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

这些 Skills 不是硬编码在 CLI 二进制中的，而是以仓库管理的方式组织的——每个 Skill 是一个独立的、可版本化的定义文件，存放在项目的 .hbi/ 目录中。

4.1 基础层（4 个 Skills）

hbi-core 是其他所有 Skills 的基础。它负责认证管理、偏好设置和版本协商。

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

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

# 步骤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 表达式。

4.3 交付层（4 个 Skills）

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

4.4 自动化层（4 个 Skills）

hbi-workflow 是自动化层的核心。它允许定义跨域的、多步骤的 BI 工程工作流，并在每个步骤设置检查点（checkpoint）。

五、典型的 Agent 工作流

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

阶段一：Discover（发现）

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

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

阶段二：Build（构建）

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

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

阶段三：Deliver（交付）

Agent 通过权限和发布命令完成交付：

hbi authorize get            # 查看当前权限
hbi user-group list         # 有哪些用户组？
hbi authorize grant         # 授予访问权限（可加 --dry-run）
hbi dashboard publish       # 发布仪表盘

六、凭证安全：Keyring 而非配置文件

CLI 工具的一个常见安全漏洞是：把凭证写在明文配置文件里。

HENGSHI CLI 的做法是：所有敏感凭证（API Token、OAuth Refresh Token、数据库密码等）都存储在系统 Keyring 中，而不是写在 ~/.hbi/config.yaml 这样的文件里。

这意味着即使有人拿到了用户的 ~/.hbi/ 目录，也无法获取任何凭证——因为它们不在那里。

七、开源与社区

HENGSHI CLI 已经在 GitHub 上开放使用（https://github.com/hengshi/cli）。这意味着：

可定制：企业可以 fork 并定制自己的 Skills
社区贡献：遇到 bug 可以提 Issue 或 PR
学习参考：其他 BI 厂商可以参考 Agent-first CLI 的设计

八、总结：CLI 作为 AI Agent 的”手和脚”

HENGSHI CLI 代表了 BI 工具领域的一个重要趋势：从给人用的工具，进化为给 AI Agent 用的基础设施。

这个转变不只是增加了命令行接口那么简单，而是重新思考了”谁在操作”这个问题。当操作主体从人变成 AI Agent，工具的设计理念也需要相应变化：

结构化输出（Agent 可读）
dry-run 预演（Agent 可审查）
Help-first 规约（Agent 可自学）
SSE 实时同步（Agent 可监控）
Skills 仓库化管理（Agent 可复用）

对于正在构建 AI Agent 能力的 BI 团队来说，HENGSHI CLI 的设计思路值得参考。

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