Article body
正文
摘要： HENGSHI CLI 的对外命令是 hbi。它把 HENGSHI SENSE 中一部分数据、建模、仪表盘、权限与运维动作放进可发现的命令面，供人工终端、自动化脚本和具备工具调用能力的 Agent 使用。网页与 API 继续覆盖各自的使用场景；CLI 将相关 BI 操作整理为命令、参数和结构化结果，帮助团队在执行前检查计划、执行后核验状态。
开放接口先解决命令发现与调用边界
网页、API 和命令行解决的是不同问题。具备浏览器工具的 Agent 可以完成页面操作，业务人员也需要在界面中审阅图表、布局和交互。API 仍适合已有服务的直接集成。CLI 的位置是为终端和工具调用提供稳定的命令入口：先从帮助中识别资源域和参数，再用结构化输出把结果交给脚本、Agent 或人工继续判断。
当前 hbi 的顶层帮助列出了 app、dataset、data-model、metric、measure、dashboard、permission、authorize、pipeline、scheduler 等命令域。这是一条较宽的 BI 工程操作面。目标实例的版本、已启用能力和当前身份的权限，共同决定一条命令是否可用，以及它能看到或改变什么。
| 接口 | 适合解决的问题 | Agent 需要先确认的信息 | 常见控制点 |
|---|---|---|---|
| Web UI | 视觉探索、图表和交互验收、人工协作 | 页面状态、登录态、目标环境与可见资源 | 页面权限、人工复核、浏览器会话 |
| API | 服务到服务集成、已有系统中的固定契约 | 接口版本、请求模型、鉴权和错误处理 | 调用方密钥、限流、服务日志 |
| HENGSHI CLI | 终端执行、脚本化工作流、Agent 工具调用 | 命令帮助、SENSE host、资源 ID、当前身份与授权 | 结构化输出、写前预演、执行后的状态复查 |
分清平台、语义模型与执行者的职责
HENGSHI SENSE 管平台资源，CLI 负责明确调用
hbi 通过 HBI_HOST 或 —api-url 指向具体的 HENGSHI SENSE 实例。SENSE 承载应用、数据集、数据模型、仪表盘、组织和权限等平台资源；CLI 把这些资源域的读取或操作请求发送到指定实例，并以 table、JSON 或 YAML 返回结果。资源归属、身份校验和权限判断始终由目标实例决定。
数据模型、原子指标、业务指标与主题域分别有对应命令域。Agent 在生成 HQL、创建图表或调整模型前，应先读取已有数据集、模型关系、指标定义和权限范围。语义模型提供的是已经定义的业务对象与计算口径，Agent 仍需要核对任务中的时间范围、筛选条件和目标资产；CLI 不能替 Agent 判断业务问题是否被正确理解。
Agent 决定流程，skills 约束顺序，CLI 执行动作
官方文档把人的需求与风险确认、Agent 的任务拆解、skills 的领域流程、CLI 的实际读取与写入分开。Agent 负责选择先查数据还是先看资产，skills 提醒资源域、帮助探测和检查点，CLI 接收明确参数并返回结果。人负责确认写入对象、授权范围和交付结果。
访问边界也应写进流程。hbi 将 permission 标为只读权限查询，而 authorize 提供 get、grant、revoke；本机帮助显示 grant 的目标可包括 app、folder、api-set、connection 和 kanban。先查询再变更，有助于把“我能否操作”与“我要授予什么”分开。若使用 —as-user，还需要当前 OAuth client 具备 sudo scope，不能把它当作普通的展示参数。
用执行前后的状态验证结果
对支持预演的写入命令，可用 —dry-run 检查目标和参数，具体行为以当前命令帮助为准。预演不会替代真实执行后的状态核查，也不能证明执行时的权限、依赖与目标状态仍然满足要求。团队应将预演结果、必要审批和执行回执一起纳入变更记录。
JSON、YAML 和 table 输出让后续步骤能读取同一份结果；同时，—write-output 可以把结果写入本地文件。输出中可能含有资源元数据甚至查询结果，因此本地目录权限、流水线日志、临时文件保留期和人工导出的副本都属于数据治理范围。不能把“CLI 是通道”推导成“任意运行环境都不会留下业务数据”。
凭据有多条支持路径。官方文档列出 device login、client credentials、HBI_TOKEN 或 —token 的临时覆盖，以及交互式登录写入 CLI 本地凭据存储等方式。系统 Keyring 是支持的保护方式之一。自动化环境应通过受控的密钥注入与最小权限账户提供凭据，避免把 secret 写入命令行、脚本正文或可长期保存的日志。
把读取、计划、写入和回读连成一条证据链
结构化输出解决的是机器读取问题，不会自动给出业务结论。Agent 应把输出中的资源 ID、名称、所属应用、当前状态和查询条件，与任务中已批准的目标逐项对应。JSON 便于程序解析，YAML 便于审阅配置草稿，table 适合人在终端快速检查；不同子命令和版本的字段仍应以当次 help 与实际响应为准，不能把网站演示中的示例 ID 或字段当成固定协议。
读阶段应从最小范围开始。先确认目标 host 和身份，再收窄到指定应用、数据集或数据模型，检查当前可见资源、定义与权限。计划阶段需要把待变更的资源、角色、字段或布局写清楚，并让业务负责人确认口径。写阶段才携带明确的资源 ID；高风险动作先预演。回读阶段使用与目标相对应的查询命令检查状态，例如在授权后复查授权信息，在创建或更新后复查对象的定义和归属。前后两次读取使用相同的目标和检查维度，才能判断变化是否符合计划。
这条链也为异常处理留下入口。若写前读取已显示资源不存在、身份不可见或数据模型无法回答问题，Agent 应停止进入写阶段，并把已确认的上下文和缺失条件交给人处理。若写后状态与预演目标不一致，应保存最小必要的输入和结果，按团队的变更流程排查或回退。CLI 的结构化命令让这些检查可以复用，最终的业务验收仍由任务目标和平台实际状态决定。
从帮助发现开始，再查验变更前后状态
面对不熟悉的资源域，先运行本地帮助，建立命令、参数和风险范围的共同事实。下面三条只读帮助命令可用于查看当前安装版本的命令树和选项，不访问 SENSE 业务资源，也不会变更 BI 数据。
hbi --help
hbi data-model --help
hbi authorize grant --help根帮助用于确认当前 CLI 版本提供哪些资源域；data-model 帮助会进一步显示 list、show、preview、query、lineage、tree 与联表相关操作；authorize grant 帮助会显示目标类型、角色格式和授权参数。帮助页解释调用方式。资源是否存在、当前身份能否读取或写入，仍需通过目标实例的实际查询确认。
一次可审查的写入流程应保持短而完整：先明确 SENSE host 和身份，再用 auth status、应用与数据集查询确认目标存在且当前身份可见；读取现有配置和权限；对高风险写入执行 dry-run；在已批准的权限内执行；最后用对应的查询命令复查资源状态，并保存经过脱敏和范围控制的证据。创建仪表盘、变更授权或调整数据模型都应遵循这条顺序，避免只凭“命令返回成功”宣布交付完成。
开放接口的重点是可组合，也要可约束
具备 shell 或工具调用能力的 Agent 可以把 hbi 纳入自己的工作流。对企业来说，接入前应先固定目标实例、认证方式、可调用资源域、审批点与输出留存规则。这样，CLI 可以把 SENSE 的 BI 能力带入自动化链路，并保留业务口径、读写权限和交付验收应有的边界。