排障与 FAQ

HENGSHI CLI 主要给谁用？

严格来说，CLI 既可以给人直接用，也可以给 Agent 用；在很多实际场景里，它也很适合作为 Agent 或自动化流程的稳定命令入口。

skills 是必须的吗？

对 Agent 来说，基本可以认为是。

• 如果你要让 OpenClaw 等 Agent 稳定复用 HENGSHI CLI 工作流，官方 skills 很重要
• 它们负责把执行顺序、--dry-run 策略和输出约束沉淀成可复用的标准流程

对人工直接在终端里执行命令来说，CLI 本身可以工作，因此不是硬性前置条件。

我应该怎么选认证方式？

通常可以按下面方式选：

1. 本地人工终端：优先 hbi auth login --interactive
2. Agent runtime / CI：优先 HBI_CLIENT_ID + HBI_CLIENT_SECRET
3. 已有现成 token：直接使用 HBI_TOKEN

如果只是想先完成一次显式登录，也可以直接运行：

hbi auth login --client-id <client_id> --client-secret <client_secret>

怎么确认 CLI 本身安装没问题？

先跑这三条：

hbi --version
hbi --help
hbi auth status

如果前两条正常，而第三条只是提示未登录，说明 CLI 本体已可用。

登录后，CLI 会自动复用 token 吗？

会。

在常见登录路径下，CLI 会把 access token 缓存到本地，后续命令会自动复用；如果当前环境里还能拿到有效的 client credentials，后续需要认证的命令也可以继续自动换取或刷新 token。

为什么登录了却还是看不到目标资源？

优先检查：

1. HBI_API_URL 指向的是不是正确实例
2. 当前账号对目标应用、数据集、数据连接是否真的有权限
3. Agent 运行时继承的环境变量是不是和你当前终端一致

为什么 Agent 执行高风险动作前总被建议先 --dry-run？

因为授权、配置更新、部分写动作本身就更适合进入审查流。--dry-run 的价值不是“多一步”，而是让 Agent 先把它准备改什么、改到哪里、影响什么讲清楚，再决定是否真正落库。

为什么页面上看不到 Autopilot 指示器？

最常见的原因有：

1. 管理员已在系统环境中关闭 GENERAL_CONFIG_ENABLE_SSE，当前实例不再展示 Autopilot / SSE 实时回显 UI（前端系统偏好里会体现为 enableSse=false）
2. 当前页面不在支持实时回显的页面范围里
3. 当前是移动端，或该页面本身不展示顶部状态提示
4. 当前会话并没有建立可用的 SSE 连接
5. 当前用户尚未登录或当前页面本身没有进入实时回显路径

当前页面支持边界，可以直接参考 实时回显与 Autopilot 里的“当前页面支持边界”。

为什么 CLI / Agent 改了资源，页面却没有自动刷新？

这通常不意味着 CLI 没生效，更常见的是下面几类原因：

1. 管理员已在系统环境中关闭 GENERAL_CONFIG_ENABLE_SSE
2. 当前页面不在实时回显覆盖范围里
3. 变更资源不属于当前 detail 页或当前活跃列表
4. 当前动作本身属于执行、执行记录或 DAG 这类以同步等待 / 轮询为主的路径
5. 当前连接中断，Autopilot 指示器已断开
6. 反向代理或网关打断了 /api/sse/subscribe 长连接，或把 SSE 响应缓冲了
7. 页面存在本地未保存编辑，不适合被外部更新直接覆盖

排障时应该带哪些信息

建议至少附带下面这些信息：

• CLI 版本
• 安装方式（静态分发 / 发布资产）
• 操作系统
• HBI_API_URL
• 认证方式（交互式登录 / client credentials / token）
• 执行的命令
• 是否带了 --dry-run
• 最好附一份 --output json 的结果
• 如果涉及 UI 回显，再补充页面路径、Autopilot 状态和是否为移动端

推荐的排障顺序

1. 先确认 CLI 本体是否正常
2. 再确认目标实例与认证
3. 再确认当前实例、目标资源与权限
4. 最后才看 UI 实时回显是不是落在当前页面范围里

这样排查会比一上来只盯着浏览器页面更快。