常用工作流

本页不追求覆盖全部命令，而是给出最常见、最容易复用的几类工作流。它既适合人工终端使用，也适合 Agent 作为稳定执行路径复用。

工作流一：先读取上下文，再开始做事

任何写动作前，建议先读取当前实例、应用和数据集上下文。

hbi auth status --output json
hbi app list --area personal-area --root --output json
hbi dataset list --app retail-ops --output json

这一步的目的不是“多打一条命令”，而是先确认：

• 当前身份已登录
• 当前实例可达
• 目标应用是否真的存在
• 当前身份是否看得到后续要操作的数据集

工作流二：查询数据模型或验证表达式

当需求还处在“先看看这份数据能不能回答问题”的阶段，可以先用 data-model query 做轻量验证。

hbi data-model query --app <app-id> --dataset <dataset-id> "SUM({amount})"

适合的场景包括：

• 先验证指标口径
• 让 Agent 在建图前先确认数据模型能回答问题
• 把 HQL / HE 片段作为后续仪表盘配置的输入

工作流三：创建 dashboard / report

最典型的交付动作之一，就是从应用里新建一个仪表盘或报表。

# 创建 analytic / page dashboard
hbi dashboard create --app <app-id> "区域销售驾驶舱"

# 创建 report（需要显式绑定数据应用和数据集）
hbi dashboard create --app <report-app-id> "销售报表" \
  --dashboard-type report \
  --data-app <data-app-id> \
  --dataset <dataset-id>

说明

--data-app 和 --dataset 只用于 --dashboard-type report。普通 analytic/page dashboard 一般在后续图表、筛选器或 dashboard plan apply 阶段再绑定数据。

工作流四：继续完善图表与其他元素

建完 dashboard 后，可以继续落图表、容器、筛选器、按钮、iframe 等元素。

hbi element chart create \
  --dashboard <dashboard-id> \
  --app <app-id> \
  --dataset <dataset-id> \
  line

hbi element container create \
  --dashboard <dashboard-id> \
  --app <app-id> \
  --file container.yaml

hbi element filter update \
  <filter-uid> \
  --dashboard <dashboard-id> \
  --app <app-id> \
  --file filter.yaml

这类命令特别适合 Agent 使用，因为：

• 输入边界清楚
• 可搭配 YAML 规格文件
• 结果可以回写到后续流程里

工作流五：在浏览器里确认 dashboard / report 结果

当你已经通过 CLI 创建或更新了 dashboard / report，建议马上回到对应页面做一次结果确认。

推荐顺序：

1. 打开对应的仪表盘或报表页面
2. 确认当前页面就是这次变更的目标对象
3. 查看 Autopilot 是否处于已连接状态
4. 判断这次变化是否应该直接回到当前页面

如果你的关注点是“浏览器外改动能不能回到当前画面”，这一步通常比继续追加命令更重要。相关说明可继续看 实时回显与 Autopilot。

工作流六：预演权限变更

权限变更是最适合先做 --dry-run 的动作之一。

# 查看权限
hbi authorize get app <id>

# 预演授权
hbi authorize grant app <id> --user 123:editor --dry-run

# 真正授权
hbi authorize grant app <id> --user 123:editor

# 回收权限
hbi authorize revoke app <id> --user 123

推荐把这类动作放进明确的两步流：

1. Agent 先给出 --dry-run 结果
2. 人确认后再执行真实授权

工作流七：读取或预演系统配置

CLI 不只用于业务对象，也可以读取系统配置，并在更新前先预演。

hbi preferences get --output json
hbi preferences everest --output json
hbi preferences smtp --output json

hbi preferences everest update --file everest.yaml --dry-run
hbi preferences smtp verify --file smtp.yaml --dry-run

这类命令适合：

• 环境核对
• 配置巡检
• 变更前预演
• Agent 协助输出配置差异说明

推荐输出格式

当 CLI 被人类直接使用时，table 输出更容易快速浏览；当 CLI 被 Agent、脚本或 CI 使用时，更推荐：

--output json
--output yaml

推荐原因：

• 结构稳定
• 便于后续程序解析
• 能把中间结果传给下一步命令或其他系统

给 Agent 的工作流约束

为了让 Agent 更稳定地复用这些命令，建议把下面这些规则作为默认约束：

1. 读取上下文优先于写动作
2. 高风险动作优先 --dry-run
3. 默认使用结构化输出
4. 把关键命令、关键输出和未完成事项一并回传

如果你的目标是“让 Agent 能连续完成一个 BI 任务”，那真正要沉淀的不是某条孤立命令，而是这些工作流之间的顺序关系。