中文 (简体)

English (US)

中文 (简体)

English (US)

主题

CLI 实时回显与 Autopilot ​

当你用 HENGSHI CLI、Agent 或脚本在浏览器外修改资源时，最常见的问题不是“命令有没有执行成功”，而是：

这次变化什么时候会回到当前页面？

Autopilot 就是这条“CLI / Agent 改动 → UI 回显”链路在前端的可视化状态提示。本页重点解释三件事：

  1. Autopilot 能帮你判断什么
  2. 哪些场景适合期待实时回显
  3. 哪些场景其实仍然以同步执行或轮询为主

为什么 CLI 文档要单独讲 Autopilot ​

HENGSHI CLI 是浏览器外的统一命令入口；Autopilot 是浏览器内的实时连接提示。两者配合起来，才构成一条完整的交付闭环：

text
CLI / Agent / Script
→ 服务端接受变更
→ SSE 推送相关资源更新
→ 当前页面收到回显
→ Autopilot 提示你连接是否仍然在线

所以，Autopilot 的价值不只是“页面上多了一个状态条”，而是帮你更快回答下面这些问题：

  • 当前页面是不是还在接收实时更新
  • 浏览器外刚发生的变更，是否有机会回到当前页面
  • 当页面没有变化时，更像是连接问题、范围问题，还是页面本地状态本来就不适合被覆盖

Autopilot 是什么，不是什么 ​

它是什么 ​

Autopilot 指示器是页面顶部的一段实时连接状态提示，用来告诉你当前页面是否仍在接收系统里的实时更新。

技术上，这条能力基于 SSE（Server-Sent Events）实现；但日常使用里，你通常只需要关注页面上的连接状态即可。

它不是什么 ​

Autopilot 很有用，但它不等于下面这些东西：

  • 不是“所有页面都会自动刷新”
  • 不是“所有后台动作都会立刻回到当前页面”
  • 不是“执行状态本身”，它只表示实时连接是否在线，不替代任务状态、执行记录或日志
  • 不是“强制覆盖本地编辑”，当前页面有未保存修改时，外部更新不一定会直接合并进来

SSE 系统开关与 Autopilot 显示 ​

管理员可以在系统环境里通过 GENERAL_CONFIG_ENABLE_SSE 控制实例是否启用 SSE 实时推送；默认值是开启。这个系统环境值在前端系统偏好接口中会体现为 enableSse 字段。

这项开关会直接影响前端是否建立 SSE 长连接，以及 Autopilot UI 是否显示：

  • 开启时：支持的桌面页面会建立 /api/sse/subscribe 实时连接，并按页面边界显示 Autopilot 指示器
  • 关闭时：前端不会启动 SSE transport，Autopilot 指示器不会显示，也不应再期待基于这条链路的实时回显

当前公开文档里提到的 Autopilot 与实时回显范围，都默认建立在 GENERAL_CONFIG_ENABLE_SSE 仍处于开启状态 的前提上。

这项开关控制的是 SSE / Autopilot 实时回显链路，不等于 ChatBI / Agent 能力本身是否可用，也不代表所有页面都会自动刷新。

哪些场景最适合期待实时回显 ​

在公开产品文档里，最值得优先强调的对象其实是仪表盘 / 报表页面，尤其是查看页和编辑页。

因为对大多数 CLI + Agent 交付场景来说，用户真正关心的通常不是“某个列表有没有刷新”，而是下面这些变化能不能及时回到当前画面：

  • CLI / Agent 新建或更新了 dashboard / report
  • 在浏览器外创建或更新了图表、筛选器、文本、按钮、图片、容器等元素
  • 应用了 dashboard plan，想确认改动有没有回到当前画布

资源列表页、Notebook / Pipeline 这类 detail 页同样属于这条机制的覆盖范围，但它们更适合作为补充场景理解；Autopilot 在交付与验收阶段最有感知价值的，仍然是仪表盘 / 报表页面。

场景更适合期待什么典型例子
仪表盘 / 报表查看页、编辑页浏览器外的创建或更新结果回到当前画布或当前页面dashboard plan apply、chart/filter/text/container 变更、report 页面更新
列表页浏览器外 create / delete / update 回到当前列表应用、数据科学、数据集成等列表页
其他 detail 页当前资源内部结构变化回到当前 detail 页Notebook 段落变更、Pipeline 节点增删改

更准确地说，Autopilot 最擅长帮助你验证的是：

  1. 当前打开的仪表盘 / 报表页面，是否正好就是这次外部变更的目标页面
  2. 当前页面和浏览器外变更，是不是针对同一个资源
  3. 当前页面是不是属于已经接入实时回显的页面
  4. 当前连接是不是仍然可用

当前页面支持边界 ​

下面这张表把两件事情拆开来看：

  • Autopilot 指示器会不会出现
  • 当前页面有没有明确接入资源级回显

这两件事并不总是等价。页面上看得到指示器，不代表当前页面就一定已经接上了这类资源的实时刷新。

另外，这张表默认假设系统环境里的 GENERAL_CONFIG_ENABLE_SSE 没有被关闭；如果实例级 SSE 已禁用，那么下面这些页面也不会再显示 Autopilot 指示器。

页面类型Autopilot 指示器当前已明确接入的回显说明
桌面常规页面（主头部显示）支持取决于页面自身是否接入实时回显常见例子包括应用 / 文件夹列表、数据集列表、仪表盘列表、数据科学列表、数据集成列表等
仪表盘 / 报表查看页、编辑页（自有头部）支持支持仪表盘资源级回显这是当前最核心的交付场景；发布态、分享态、预览态和嵌入容器不在这层边界内
数据科学 Notebook 详情页依赖页面主头部支持 notebook 资源级回显本地 paragraph 有未保存修改时，外部变化会先排队，不直接覆盖
数据集成 Pipeline 详情页依赖页面主头部支持 pipeline 资源级回显节点增删改已接入；本地图编辑未保存时，外部变化会先排队
Kanban 顶层页面不属于当前这批独立顶栏提示页面支持 kanban 资源级回显draft / analysis / share / ChatBI / screenshot 等派生形态不在当前订阅边界内
执行记录 / DAG / 日志类页面可能看到指示器不建议按 SSE-first 理解这类页面当前更常见的是同步等待或轮询
移动端 / 浮层页面不保证支持不应默认期待移动端不显示指示器；Kanban、业务指标、ChatBI 等浮层页面不在当前独立顶栏提示范围内

如果把范围再说得更具体一点，截至当前版本，可以明确写进这张表的页面至少包括：

  • 应用 / 文件夹列表（含 app、public、datamart 的根列表与 folder 路径）
  • 数据集列表
  • 仪表盘 / page / report 列表
  • 数据科学列表
  • 数据科学 Notebook 详情页
  • 数据集成列表
  • 数据集成 Pipeline 详情页
  • 仪表盘 / 报表查看页、编辑页

这张表的重点不是承诺“所有这些页面都会自动刷新一切”，而是帮助你先判断：当前页面到底在不在 Autopilot 与实时回显的已知边界里。

哪些场景不该把它当成主通道 ​

下面这些场景，即使页面上有 Autopilot，也不应该把“有没有 SSE 推送”当成第一判断标准。

1. 执行类动作 ​

以数据集成为例，详情页里的“立即执行”更接近同步执行路径：前端发起执行后，会等待后端返回当前这次执行的状态，而不是只打一枪再完全依赖 SSE 推送。

这意味着：

  • 执行按钮能否返回结果，优先看执行本身是否成功
  • 不应该把“没有立刻看到实时推送”直接判断成执行失败

2. 执行记录 / DAG / 日志类页面 ​

这一类页面当前更常见的是轮询刷新，而不是把 Autopilot 当成主刷新机制。

例如：

  • 执行记录页
  • DAG 页
  • 部分日志 / 历史记录页

这类页面即使能看到状态变化，也更可能来自同步等待或轮询，而不是当前资源详情页那种直接的实时回显。

3. 本地存在未保存编辑的页面 ​

如果当前页面已经有未保存的本地修改，外部更新通常不会被粗暴覆盖。

这是一个保护机制，不是实时回显失效。对这类页面，更应该先区分：

  • 页面是不是故意阻止外部变化覆盖本地草稿
  • 还是当前连接本身已经断开

常见状态 ​

Autopilot 常见状态包括：

状态含义
Autopilot 连接中正在建立实时连接
Autopilot 已连接当前页面可接收实时更新
Autopilot 重连中连接中断后正在尝试恢复
Autopilot 已断开当前没有可用连接，需要人工关注

当指示器处于断开状态时，页面通常会提供重试入口。

推荐的验证顺序 ​

当你在验证“CLI / Agent 改动是否已经回到 UI”时，建议按这个顺序判断：

  1. 先看命令本身是否真的成功
    • 优先看 CLI 返回值、结构化输出和报错
    • 不要一上来只盯浏览器
  2. 再看当前页面是不是同一个资源
    • 当前列表或 detail 页是否正好覆盖这次改动的资源
  3. 再看 Autopilot 是否已连接
    • 如果连接本身已断开，页面落后是合理现象
  4. 区分这次动作属于“资源变更”还是“执行过程”
    • 资源变更更适合期待实时回显
    • 执行过程、执行记录、DAG 更常见的是同步等待或轮询
  5. 最后才判断是连接问题、范围问题，还是本地草稿保护

这样排障会比“命令一成功就立刻怀疑 UI 异常”更快。

环境与代理要求 ​

如果你的实例前面有 Nginx、Ingress、TongWeb 或其他反向代理，/api/sse/subscribe 这条链路需要额外关注。最常见的问题不是业务逻辑错误，而是长连接被代理提前切断，或被缓冲后失去实时性。

至少需要保证：

  • SSE 路径允许长时间保持连接
  • 关闭代理层的 response buffering / proxy buffering
  • 不要缓存 SSE 响应
  • 读写超时不要太短

典型的 Nginx 反向代理配置可以参考：

nginx
location /api/sse/subscribe {
  proxy_http_version 1.1;
  proxy_set_header Connection "";
  proxy_buffering off;
  proxy_cache off;
  proxy_read_timeout 3600s;
  proxy_send_timeout 3600s;
}

如果你使用的是 ingress-nginx、TongWeb 或其他网关，也需要配置等价能力：长连接、关闭缓冲、放宽超时。

下面这些现象通常都值得优先检查代理层：

  • Autopilot 一直停在“重连中”或频繁断开
  • CLI 明明成功了，但页面始终收不到任何实时变化
  • 同一页面在直连环境正常，走网关后失去实时回显

页面示意 ​

下面是本地示例环境里“应用集市”页面顶栏上的 Autopilot 指示器：

Autopilot indicator

一句话记忆 ​

可以把这页内容压缩成一句话：

Autopilot 负责告诉你“实时连接还在不在”，不是替你判断“所有页面都会自动刷新”。

如果你想继续排查“为什么看不到实时变化”，请直接看 排障与 FAQ。

衡石分析平台使用手册

版权所有 © 2016-present hengshi.com