前端报错无法区分"后端已死"与"网络瞬断"——建议 /health 心跳 + 崩溃引导

[sunwindy91]

现象（崩溃场景实录）

DSH 网页版（http://127.0.0.1:3080）在一次多窗口并发使用中因内存耗尽崩溃（系统可用内存 2.1GB/15.7GB，崩溃时 3080 无监听、node 进程为空）。崩溃期间前端表现：

顶部出现 "自动保存失败：failed to fetch"；

刷新后 3080 完全无法访问；

用户无法区分"服务已死"和"网络瞬断"——只能靠猜（重启服务、检查端口、翻日志逐个排查）。

这是发现 4（前端误导性报错）的完整背景。核心问题：failed to fetch 是浏览器层网络错误，不携带任何"后端进程是否存在"的信息——前端和后端故障在产品体验上完全同形。

建议：前端探活（/health 心跳 + 崩溃引导）

1. 复用 / 新增健康端点

后端已有 GET /api/health（返回 {"ok": true}，且免鉴权）；

前端加周期性心跳（如每 30s 探测一次），并在任何 fetch 失败时立即探活一次，区分三种状态：

ECONNREFUSED / 连接失败 → "服务未运行"；

超时 → "服务无响应"；

其他网络错误 → "网络异常"。

2. 崩溃引导（替代裸的 failed to fetch）

探活判定"服务未运行"时，显示明确引导："DSH 服务未运行，请重启后重试" + 一键复制重启命令（或给出重启指引链接）；

避免用户在"刷新 / 重启 / 检查配置"之间盲目试错。

3. 崩溃前预警（可选，P0 级）

本机内存耗尽为崩溃确证根因（15.7GB 机器，可用跌至 2.1GB）；

可在服务端监控可用内存，低于阈值（如 3GB）时主动提示"内存不足，建议关闭其他窗口/应用"，而非等崩溃后用户自诊断。

4. 报错分级（长期）

把前端统一错误文案拆成：后端未运行 / 后端无响应 / 权限失败 / 网络异常 / 未知；

每类给不同的恢复指引，减少"failed to fetch 万能背锅"。

为什么值得做

崩溃/断连是 agent 产品最高频的信任杀手——用户无法自诊断时，第一反应是"产品坏了"而非"环境问题"；

前端已能看到健康端点存在，成本极低（心跳 + 文案替换），收益是故障可诊断性从 0 到 1；

内存预警可复用现有系统信息（无需新增埋点）。

实测证据

崩溃事件完整回放：DSH事件说明_20260814.md（崩溃时 3080 无监听 / node 进程为空 / 内存 2.1GB/15.7GB）；

前端报错原文："自动保存失败：failed to fetch"+"暂时无法保存确认状态"。

备注

与 #3207（Windows 沙箱 schannel 失败链路）不同族——这是纯 UI/UX 层的故障可诊断性问题；

如果您认为前端探活属于某个现有 roadmap 项，请指路，我们可补测试数据。

[argszero]

方案方向完全赞成——"failed to fetch 万能背锅"是 agent 产品故障可诊断性的真实痛点，你的崩溃实录（内存 2.1GB/15.7GB + 3080 无监听 + 前端误导文案）把问题讲得很清楚。补几个源码侧事实与实现细节，让提案落得更准：

1. 关键事实修正：rc.8 源码里并没有 GET /api/health

我全文检索了 rc.8 的 packages/host/apiproxy/src/（fetch 客户端、api 子模块）与 apps/web，没有找到 /api/health 端点——提案里"后端已有 GET /api/health（返回 {"ok": true}，且免鉴权）"与源码不符。这个端点大概率是提案者记错的（可能是别的工具/之前版本），或者只存在于设想中。这意味着：

• 前端探活没有可复用的现成端点，需要后端新增（或确认实际存在的位置）；
• 好消息是新增成本极低：apiproxy 已有 /api/* 路由骨架，加一个免鉴权 GET /api/health 返回 {"ok": true} 即可（注意别放进需要鉴权的 RPC 面——探活端点必须独立于凭据，否则"后端活着但鉴权失败"会被误判成"后端死了"）。

2. 错误分类器可以复用现成的 errorChain 渲染先例

packages/llm/llm 已经有一个专门解决"传输包装层遮蔽底层错误"的设施：errorChain(value)（README:80）会把 undici 的 TypeError: fetch failed 展开成底层 connect ECONNREFUSED 127.0.0.1:443（tests/service.spec.ts:131-142 有完整用例）。前端心跳的分类逻辑（ECONNREFUSED → 服务未运行 / 超时 → 无响应 / 其他 → 网络异常）底层正是这套 cause 链展开——提案第 4 点"报错分级"在技术上就是 errorChain 的浏览器端对应物。实现时可以直接对齐它的语义，避免两套"错误分类"标准漂移。文档还强调了一个关键纪律："route on code, never by parsing the result"——前端分类同样应该按稳定的错误码/cause 类型判断，而不是匹配错误文案字符串。

3. 心跳的触发时机建议（比纯 30s 周期更省）

"任何 fetch 失败时立即探活一次 + 30s 周期兜底"方向对，但可以更省：只在 fetch 失败时探活（被动式），成功路径零开销；30s 周期只在"当前无活动但需要确认服务仍活着"的场景（如多窗口）才有价值。另外心跳本身要短超时 + 不重试（探活请求自己挂了会二次误导）。崩溃前预警（内存监控）同意 P0——崩溃是信任杀手，预警是唯一能赶在崩溃前的缓解。

4. 最小可行形态（不阻塞）

后端加免鉴权 /api/health + 前端 fetch 失败时探活 + 三态文案（未运行/无响应/网络异常）+ 崩溃引导（"重启命令一键复制"）。报错分级（第 4 点）可以作为第二步单独做，不必等它。

如果官方有前端探活的既有 roadmap 位置，欢迎指路；否则这个提案从"新增免鉴权 /api/health + 被动探活"起步完全自洽。