--- url: /v6.2/cli-workflows.md --- # 常用工作流 本页不追求覆盖全部命令，而是给出最常见、最容易复用的几类工作流。它既适合人工终端使用，也适合 Agent 作为稳定执行路径复用。 ## 工作流一：先读取上下文，再开始做事 任何写动作前，建议先读取当前实例、应用和数据集上下文。 ```bash 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` 做轻量验证。 ```bash hbi data-model query --app --dataset "SUM({amount})" ``` 适合的场景包括： * 先验证指标口径 * 让 Agent 在建图前先确认数据模型能回答问题 * 把 HQL / HE 片段作为后续仪表盘配置的输入 * HQL 表达式支持 SUM、AVG、COUNT 等聚合函数，YEAR、MONTH、PERIODCOMPARE 等时间函数，以及 IF、CASE 等条件逻辑。完整函数列表参考 [HQL 函数参考](https://api.hengshi.com/function_reference.html) ## 工作流三：创建 dashboard / report 最典型的交付动作之一，就是从应用里新建一个仪表盘或报表。 ```bash # 创建 analytic / page dashboard hbi dashboard create --app "区域销售驾驶舱" # 创建 report（需要显式绑定数据应用和数据集） hbi dashboard create --app "销售报表" \ --dashboard-type report \ --data-app \ --dataset ``` > \[!TIP] 说明 > `--data-app` 和 `--dataset` 只用于 `--dashboard-type report`。普通 analytic/page dashboard 一般在后续图表、筛选器或 dashboard plan apply 阶段再绑定数据。 ## 工作流四：继续完善图表与其他元素 建完 dashboard 后，可以继续落图表、容器、筛选器、按钮、iframe 等元素。 ```bash hbi element chart create \ --dashboard \ --app \ --dataset \ table \ --identify-link true \ --identify-email true \ --identify-image true hbi element container create \ --dashboard \ --app \ --file container.yaml hbi element filter update \ \ --dashboard \ --app \ --file filter.yaml ``` 这类命令特别适合 Agent 使用，因为： * 输入边界清楚 * 可搭配 YAML 规格文件 * 结果可以回写到后续流程里 ## 工作流五：在浏览器里确认 dashboard / report 结果 当你已经通过 CLI 创建或更新了 dashboard / report，建议马上回到对应页面做一次结果确认。 推荐顺序： 1. 打开对应的仪表盘或报表页面 2. 确认当前页面就是这次变更的目标对象 3. 查看 Autopilot 是否处于已连接状态 4. 判断这次变化是否应该直接回到当前页面 如果你的关注点是“浏览器外改动能不能回到当前画面”，这一步通常比继续追加命令更重要。相关说明可继续看 [实时回显与 Autopilot](cli-autopilot.md)。 ## 工作流六：预演权限变更 权限变更是最适合先做 `--dry-run` 的动作之一。 ```bash # 查看权限 hbi authorize get app # 预演授权 hbi authorize grant app --user 123:editor --dry-run # 真正授权 hbi authorize grant app --user 123:editor # 回收权限 hbi authorize revoke app --user 123 ``` 推荐把这类动作放进明确的两步流： 1. Agent 先给出 `--dry-run` 结果 2. 人确认后再执行真实授权 ## 工作流七：读取或预演系统配置 CLI 不只用于业务对象，也可以读取系统配置，并在更新前先预演。 ```bash 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 使用时，更推荐： ```bash --output json --output yaml ``` 推荐原因： * 结构稳定 * 便于后续程序解析 * 能把中间结果传给下一步命令或其他系统 ## 给 Agent 的工作流约束 为了让 Agent 更稳定地复用这些命令，建议把下面这些规则作为默认约束： 1. 读取上下文优先于写动作 2. 高风险动作优先 `--dry-run` 3. 默认使用结构化输出 4. 把关键命令、关键输出和未完成事项一并回传 如果你的目标是“让 Agent 能连续完成一个 BI 任务”，那真正要沉淀的不是某条孤立命令，而是这些工作流之间的顺序关系。