排障与 FAQ

HENGSHI CLI 主要给谁用？

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

skills 是必须的吗？

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

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

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

我应该怎么选认证方式？

通常可以按下面方式选：

1. 本地人工终端：优先 hbi auth login --device-login
2. Agent runtime / CI：优先 HBI_HOST + HBI_CLIENT_ID + HBI_CLIENT_SECRET
3. 已有现成访问令牌：最后才用 HBI_HOST + HBI_TOKEN 或一次性的 --token

如果需要最明确的一次性登录入口，推荐直接运行：

HBI_HOST="<你的-hengshi-sense-实例>" hbi auth login --device-login

这里的 HBI_HOST 不要求写完整 URL；裸 host 和 platform.hengshi.org/bi 这类带路径的写法都可以。省略 scheme 时 CLI 会先探测 https://，失败后再试 http://。

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

先跑这三条：

hbi --version
hbi --help
hbi auth status

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

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

会。

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

为什么总弹系统钥匙串，或者我想在容器 / 远程环境里避开 keyring？

如果当前运行环境不适合使用系统钥匙串（例如容器、远程开发机、CI 或不完整的桌面会话），可以显式关闭 keyring 集成：

export HBI_DISABLE_KEYRING=true

然后优先使用显式的 HBI_HOST + HBI_CLIENT_ID + HBI_CLIENT_SECRET 注入（或一次性的 HBI_TOKEN），不要依赖交互式的本地凭据保存。

device login 生成的个人 Client 去哪里看？

在 个人中心 > 个人访问令牌。

首次成功完成 device login 后，系统会为当前用户创建或复用一个个人 Client。该面板展示 Client ID 和 Client Secret，但不会展示 access token；access token 仍由 CLI 在本地缓存和续用。

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

优先检查：

1. HBI_HOST 或当前保存的本机默认 host 指向的是不是正确实例
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_HOST（如果依赖本机默认 host / instance alias，也一起说明）
• 认证方式（device login / client credentials / 访问令牌临时注入）
• 执行的命令
• 是否带了 --dry-run
• 最好附一份 --output json 的结果
• 如果涉及 UI 回显，再补充页面路径、Autopilot 状态和是否为移动端

推荐的排障顺序

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

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