Article body

正文

7 分钟阅读

摘要： HENGSHI CLI（命令 hbi）是衡石 AI Labs 推出的面向 AI Agent 的 BI 命令行工具，以 Rust 架构开发，将 BI 工程全链路操作标准化为 Agent 可执行的命令树和 Skills 套件。本文从设计哲学、命令体系、Skills 架构、安全机制和实际工作流五个维度，拆解这个 Agentic BI 时代的终端执行层。

1 为什么 BI 需要命令行

这个问题本身就透露了 HENGSHI CLI 的独特定位——它不是给人类用的，是给 AI Agent 用的。

在 HENGSHI CLI 出现之前，AI Agent 想要操作 BI 系统只有两条路：一条是走 API，每个 BI 操作（创建数据集、生成仪表盘、配置权限）都要编写独立的 API 调用代码，Agent 需要理解几十个不同的接口；另一条是走 UI 自动化，模拟点击操作，不稳定且维护成本高。

HENGSHI CLI 的思路是：把 BI 的所有操作收敛到一个统一的命令行接口，Agent 只需要学习一套命令和参数，即可完成从数据连接到资产交付的全部工作。这不是一个技术小创新，而是一个范式层面的设计选择——BI 的操作应该像 Git 一样，可以被编程、被脚本化、被 Agent 调用。

2 Agent-first 的树形命令体系

HENGSHI CLI 以 hbi 为统一入口，按 BI 工程的核心域拆分为子树命令，覆盖认证、应用空间、数据连接、数据集、仪表盘、图表元素、权限、用户、管道、调度等完整操作域。

2.1 基础操作

hbi auth status               # 查看当前登录状态和令牌信息
hbi auth login                # 登录衡石平台（OAuth/SSO）
hbi app list                  # 列出所有应用
hbi app portal --app app_01 show --output yaml   # 查看应用门户配置

2.2 数据与连接

hbi connection list             # 列出所有数据源连接
hbi connection test conn_01     # 测试连接可用性
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 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 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                                 # 列出用户组

2.5 自动化与调度

hbi pipeline list                  # 列出 ETL 管道
hbi pipeline trigger --id pipe_101 # 触发管道执行
hbi scheduler list                 # 列出调度任务
hbi notebook execute --id nb_42    # 执行 Notebook

命令树把 BI 工程的核心域全部收敛为语义化操作：Agent 不再需要记忆几十个 HTTP 端点，只需要理解统一入口下的命令语义。

3 自带 Skills 套件：16 个 Repo-managed Agent Skills

HENGSHI CLI 不只是命令集合，还自带一套完整的 Agent Skills。这些 Skills 被设计为 Agent 的 BI 操作手册，让 Agent 不需要猜测参数和流程，而是按照标准化的 runbook 执行。

3.1 设计原则

其一，按资源域拆复杂度：不是一个大而全的 Skill，而是 16 个聚焦的独立 Skills。其二，Help-first 规约：每个 Skill 默认先调用 hbi —help 查看子命令帮助，减少参数臆测。其三，跨 Agent 复用：Claude Code、Codex、OpenClaw、Hermes Agent、CI 流水线通用。

3.2 完整的 Skills 列表

表1 HENGSHI CLI Skills 套件分组

分组	Skill	职责
基础层	hbi-core	认证、偏好设置、输出格式、专业术语
基础层	hbi-app	应用空间管理，门户配置
基础层	hbi-permission	授权管理，角色与权限配置
基础层	hbi-user-mgmt	用户与组织治理
数据与语义层	hbi-data	数据连接与数据集管理
数据与语义层	hbi-data-modeling	Join 模型、语义建模、HQL 查询
数据与语义层	hbi-indicator-center	主题域指标定义与管理
数据与语义层	hql-expert	业务问题转 HQL 表达式
交付层	hbi-dashboard	仪表盘创建、布局与发布
交付层	hbi-dashboard-taste	页面感设计，主题与配色
交付层	hbi-data-alert	图表级数据预警配置
交付层	hbi-data-agent	Data Agent 后台治理与配置
自动化层	hbi-pipeline	ETL 管道管理与触发
自动化层	hbi-notebook	Notebook 创建与执行
自动化层	hbi-scheduler	定时任务与计划调度
自动化层	hbi-workflow	跨域编排，多 skill 组合 runbook

3.3 Skills 对 Agent 的价值

对企业开发团队来说，Skills 套件意味着三件事：第一，新人 Agent 的训练成本显著降低，Agent 不需要理解 BI 的全部概念，只需要学会调用对应的 Skill；第二，执行标准化，所有 Agent 执行同一操作时走同一套流程，结果可预期；第三，可审计可调试，Skills 按 runbook 执行，每一步都有日志，问题可追溯。

4 三大设计特性：让 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）、再生成交付物（build.assets）、最后安全交付（deliver.control）：

# discover.state：先读取上下文
hbi auth status --output json
hbi dataset list --app retail-ops --output json
# build.assets：生成交付物
hbi dashboard create --app retail-ops 销售驾驶舱
# deliver.control：安全交付
hbi authorize grant app app_42 --user 123:editor --dry-run

Agent 从读取上下文到资产生成再到安全交付，每一步都是可独立验证的标准操作。

5 工程级的安全架构

5.1 凭证管理

HENGSHI CLI 的认证令牌不存储在本地配置文件中，而是存入操作系统的 Keyring（macOS 的 Keychain、Linux 的 Secret Service、Windows 的 Credential Manager），从存储环节降低凭证泄露风险。

5.2 认证协议

支持 OAuth 2.0 标准认证流程，支持企业 SSO（单点登录）集成，令牌具备有效期和自动续期机制。

5.3 审计追踪

所有 CLI 操作都记录完整的审计日志，包含操作人、时间、命令、结果，满足企业合规审计需求。

6 适配的 Agent Runtime 与 HENGSHI BOX 协同

HENGSHI CLI 的设计目标是与所有具备 shell 调用能力的 Agent 兼容。目前已适配两类代表：一是编码代理（Claude Code、Codex），用于本地仓库 IDE Agent 与 CI/CD 集成；二是常驻型 Agent（OpenClaw、Hermes Agent），用于云端常驻、消息通道与长期运行。只要新一代 Agent 具备 shell 或 tool 调用能力，HENGSHI CLI 就能成为它们的 BI 执行层。

在 HENGSHI BOX 全域智控舱中，CLI 可以实现更高的安全等级：BOX 为 CLI 提供了硬件级的安全边界，所有命令执行、数据处理、模型推理都在机箱内部完成，没有任何数据流向外部。

7 常见问题

问： HENGSHI CLI 需要单独安装吗？和 HENGSHI SENSE 是什么关系？

答： CLI 是独立二进制发行，需要单独安装，通过 API/SSE 与 HENGSHI SENSE 平台通信。CLI 不替代 SENSE，而是为 Agent 提供操作 SENSE 的标准接口。可以把 SENSE 理解为 BI 引擎，CLI 理解为操作这个引擎的方向盘。

问：为什么不直接用 API，要设计一套 CLI？

答： API 是为程序间通信设计的，每个操作对应一个独立的 HTTP 端点，Agent 需要理解几十个不同的 API 才能完成一个完整的 BI 工作流。CLI 将这些 API 收敛为一套语义化的命令树，Agent 更容易学习、更不容易出错。更重要的是，CLI 自带 Skills 套件、dry-run 机制和 runbook 模式，这些是裸 API 不具备的 Agent 协作能力。

问：用 Rust 开发 CLI 有什么好处？

答： Rust 提供零成本抽象和内存安全保证，适合构建长时间运行的系统级工具。CLI 作为常驻 Agent 的执行层，性能和稳定性至关重要——Rust 编译的单一二进制文件启动快、资源占用低、无运行时依赖。

问： CLI 的 Skills 可以自定义扩展吗？

答： Skills 套件以仓库文件形式管理，企业可以根据自身业务需求创建自定义 Skill，例如可以创建一个 hbi-retail-kpi Skill，封装零售行业的特定 KPI 查询逻辑。

8 观点：Agent 是 BI 工程的新操作者

HENGSHI CLI 看似只是一个命令行工具，但它的设计承载了衡石对 Agentic BI 的完整理解。

第一，Agent 不是 UI 的替代品，而是 BI 工程的新操作者。人类通过 UI 做分析，Agent 通过 CLI 做工程，二者是分工而非替代。

第二，标准化比智能化更重要。Agent 不需要创造新的 BI 操作方式，只需要稳定地执行标准化的操作。可预期的执行，是可治理自动化的前提。

第三，可审查性是不可妥协的底线。dry-run、SSE 回显、结构化输出，这些特性让 Agent 的执行永远在人类的监督范围内。

对于正在评估 Agentic BI 路径的企业，HENGSHI CLI 提供了一个清晰的设计参考：让 Agent 做的事和人类做的事用同一套标准，只是接入方式不同。这可能是 Agentic BI 从概念走向工程化的关键一步。

HENGSHI CLI：为 AI Agent 打造的 BI 终端执行层