AionUi ACP 单聊可靠性工程解析超时处理、启动失败诊断与消息异常恢复的完整落地【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi导读本篇文章围绕 AionUi 开源仓库中 ACP 单聊功能 PRD 的可靠性模块功能编号 F-RELIABILITY-01 ~ 07系统讲解 AI 后端连接超时、回复超时、启动失败提示、本地缓存损坏自动修复、多候选安装策略与发送消息异常恢复的完整设计。你将看到每个功能点的用户故事、正常/异常流程、验收标准以及它们在packages/desktop渲染进程与主进程中的真实源码实现掌握一套自动重试一次 状态机可靠复位 错误分类引导 透明修复的桌面端 AI 会话可靠性设计范式。一、可靠性模块在 ACP 单聊 PRD 中的位置AionUi 将 ACP 单聊功能拆分为 7 个模块 PRD可靠性模块是其中之一。核心文档 reliability.md 由 PM 从prd-acp-scenarios.md抽取覆盖技术场景S-ERR-01 ~ S-ERR-09其中 S-ERR-03 已合并至 F-SESSION-04 意外断连自动处理S-ERR-08/09 已合并至 F-SESSION-10 AI 回复完成处理共 6 个独立功能点功能编号标题状态F-RELIABILITY-01连接超时自动处理已实现F-RELIABILITY-02AI 回复超时自动处理已实现F-RELIABILITY-04启动失败友好提示已实现F-RELIABILITY-05本地缓存损坏自动修复已实现F-RELIABILITY-06多候选安装策略特定后端未实现F-RELIABILITY-07发送消息异常恢复已实现模块索引见 ACP 单聊功能 PRD 索引该表同时给出了 51 个功能点的整体状态统计已实现 43、部分实现 6、未实现 2以及 E2E 测试的 skip 白名单——其中 F-RELIABILITY-06 即因架构改变后可能不适用被列入 skip。可靠性与相邻模块存在明确的衔接关系会话连接的超时阈值定义在 session.md 的 F-SESSION-02约 70 秒Codex 约 150 秒回复超时的15 秒无新内容自动结束兜底逻辑定义在 F-SESSION-10而超时时间本身的用户可配置项定义在 config.md 的 F-CONFIG-06。理解可靠性设计需要以这几个模块为上下文。二、F-RELIABILITY-01连接超时自动处理2.1 用户故事与流程当系统与 AI 后端的连接因网络等原因超时时用户希望得到明确提示而不是无限等待。正常流程为系统开始连接 AI 后端 → 界面显示连接中状态连接超时 → 显示连接超时错误提示用户再次发送消息 → 系统自动尝试重新连接。异常情况首次连接失败时系统自动重试一次用户可能观察到短暂延迟后恢复重试仍失败才显示错误提示。不同 AI 后端的差异部分后端连接等待时间较长最多约 2.5 分钟即 Codex部分后端约 1 分钟。这与会话模块 F-SESSION-02 的描述一致普通后端连接时间约 70 秒Codex 约 150 秒且无需额外认证Claude、Qwen 等后端首次使用可能需要登录授权。验收标准连接超时后显示明确的错误提示首次连接失败自动重试一次超时后用户可通过发送新消息触发重连。2.2 源码实现连接状态机与事件驱动在渲染进程的 ACP 会话管理 Hook useAcpMessage.ts 中连接状态被建模为一组离散状态const [acpStatus, setAcpStatus] useState connecting | connected | authenticated | session_active | disconnected | error | null (null);这七个状态恰好对应 ACP 后端通过agent_status事件推送的连接生命周期。当收到agent_status事件时Hook 会同步更新本地状态并做两类关键复位状态进入authenticated/session_active认证完成、会话就绪时将running置回false表明连接过程结束状态进入error/disconnected时同时清空running与aiProcessing两个加载态并调用markTurnEnded()确保界面不会因连接异常而卡在正在回复状态。这套逻辑直接呼应了超时后用户可通过发送新消息触发重连的验收标准连接状态与回合状态解耦断连只是把界面复位为可用态下一次发送自然触发会话运行时ensureConversationRuntime重新建立连接。另外useAcpMessage通过模块级conversationTurnClockbeginConversationTurn/endConversationTurn记录回合起始时间该时间戳按会话持久化即使切换会话也不会丢失为连接/回复时长的可视化提供了数据源。三、F-RELIABILITY-02AI 回复超时自动处理3.1 用户故事与流程当 AI 长时间无响应时系统应自动取消等待并告知用户而不是无限等待。正常流程用户发送消息 → AI 开始处理AI 在配置的超时时间内无响应 → 系统自动取消等待显示超时提示用户可重新发送消息。三个不触发超时的异常情况是理解本功能的关键AI 正在进行工具调用如读写文件时不会触发超时AI 等待用户审批权限时不会触发超时对应 ACP 的acp_permission事件AI 有持续输出时不会触发超时每次收到内容都会重置超时计时。验收标准AI 无响应超过配置时间后自动取消并提示工具调用和权限审批期间不触发超时AI 有持续输出时不触发超时超时后用户可重新发送消息。3.2 超时时间的可配置性F-CONFIG-06超时阈值并非写死值而是用户可配置项。对应 config.md 的 F-CONFIG-06用户可设置全局默认超时时间用户可为特定后端单独设置超时优先级高于全局超时时间设置过小低于 30 秒时系统自动调整为最小值 30 秒。在配置层clientSettings.ts 中定义了acp.promptTimeout单次回复超时与acp.agentIdleTimeoutAgent 空闲超时两个配置键说明超时体系不仅覆盖单次回复还延伸到会话空闲资源的自动释放与 F-SESSION-05 的默认 5 分钟空闲释放联动。3.3 源码实现回合状态机与自动恢复但不复活已结束回合useAcpMessage.ts通过一组 ref 与事件处理实现了一个可靠的回合状态机turnFinishedRef回合结束守卫。收到finish正常完成、error异常或错误提示类消息isErrorTipMessage时置为true此后任何迟到的流式事件都不会再把running置回truehasContentInTurnRef记录当前回合是否已有正文输出。首个text/content事件到达时置为true并清除aiProcessing加载指示自动恢复start、thought、thinking、text、agent_status、acp_permission等事件都带有若回合未结束则恢复running的兜底分支防止流式事件丢失导致界面停留在未激活态finish的完整复位收到finish后依次执行setRunning(false)、setAiProcessing(false)、markTurnEnded()、清空思考态与活动思考引用并记录请求追踪耗时[RequestTrace] FINISH保证界面立即回到可输入状态。finish分支里还针对思考过程但没有实际内容生成内容但未发完成信号等场景做了说明——这正是 F-SESSION-10 的15 秒无新内容后自动判定回复完成兜底逻辑的渲染侧表现与可靠性模块的 F-RELIABILITY-02 互为表里一个负责用户可配置的硬超时一个负责流式协议层的软兜底。对acp_permission事件的处理则印证了权限审批期间不触发超时该事件不会结束回合只是恢复运行态并合并消息等待用户在审批 UI 上操作。四、F-RELIABILITY-04启动失败友好提示4.1 用户故事与流程当 AI 后端启动失败时用户希望看到有针对性的、可操作的错误提示。正常流程系统尝试启动 AI 后端失败 → 显示针对性提示AI 工具未安装 → 引导安装配置文件错误 → 引导修复配置AI 工具不支持当前模式 → 引导切换模式或更新工具首次启动失败 → 系统自动重试一次短暂延迟后重试仍失败 → 显示最终错误提示。验收标准启动失败后显示用户可理解的错误提示不同原因的启动失败给出不同的针对性提示首次启动失败自动重试一次。4.2 源码实现失败分类器与原因 → 文案 → 处理建议闭环不同原因不同提示在源码中由主进程的失败分类器 backendStartupFailure.ts 实现。classifyBackendStartupFailure按优先级依次匹配多种失败类型返回结构化诊断信息reason 上下文字段目前已覆盖reason触发条件部分backend_package_architecture_mismatch安装包架构与设备架构不符含 Rosetta 转译信息backend_incomplete_installation打包资源缺失缺bundled-aioncore/、运行时二进制等backend_startup_directory_unavailable启动目录权限拒绝EACCES/EPERM或目录不可用ENOENT/mkdir 失败backend_incompatible_runtime检测到缺少的 glibc 版本正则提取GLIBC_x.y并排序backend_local_data_repair_failed本地数据修复失败agent_metadata存在非法 UTF-8backend_transient_concurrent_startup两个 aioncore 实例并发引导同一数据目录的良性竞争backend_database_newer_than_app数据库由更新的版本写入提示升级而非当作损坏backend_recoverable_database_corruption可恢复的数据库损坏backend_data_migration_failed数据库迁移阶段失败backend_startup_pending_slow已监听端口但未就绪慢启动进程保持存活backend_startup_exited/backend_startup_port_report_timeout进程提前退出 / 端口上报超时backend_startup_failed通用兜底从源码注释可以看到两个值得注意的工程细节一是进程被观察到已监听但提前退出会被判为真实启动失败而非资源缺失避免误引导用户重装二是并发启动的良性竞争被单独分类刻意不落入本地数据修复失败的误报源码引用 Sentry 事件说明该误报曾真实发生。该分类器由 backendStartupFailure.test.ts 覆盖诊断信息的采集入口在 backendInstallDiagnostics.ts。用户侧文案集中维护在 i18n 的 conversation.json典型如所选 Agent 未能完成启动握手。请重启或重新连接该 Agent 后重试。含Agent 握手超时标题OpenClaw Gateway 未运行或无法连接到 127.0.0.1:18789…给出可执行的openclaw gateway status/openclaw gateway start命令Agent 在处理本次消息时断开了连接。请重启或重新连接 Agent 后重试。这类文案的共同点是指明问题主体 用户可执行的恢复动作与 PRD用户可理解的错误提示一致。安装完整性校验另有独立的对话框组件 InstallationIntegrityDialog.tsx 兜底。五、F-RELIABILITY-05本地缓存损坏自动修复5.1 用户故事与流程用户不希望因为本地缓存损坏而无法使用 AI 功能。正常流程系统在启动过程中自动检测到本地缓存损坏 → 自动清理损坏的缓存文件清理后自动重新安装依赖整个过程对用户透明用户只会感知到稍长的启动时间。验收标准缓存损坏时自动修复、无需手动操作修复后 AI 功能正常可用修复过程不丢失用户数据。5.2 源码实现可恢复损坏的边界与透明修复该功能在启动链路上体现为边界阶段 可恢复分类两段式设计后端起不来时aioncore 会通过边界阶段backendBoundaryStage与边界码backendBoundaryCode上报具体失败阶段classifyBackendStartupFailure将BOOTSTRAP_DATA_INIT_FAILEDRECOVERABLE_DATABASE_CORRUPTION_BOUNDARY_STAGE组合识别为backend_recoverable_database_corruption——这意味着可恢复的数据库损坏会走修复路径而不是直接判定为死局与之配套启动流程中有独立的数据库损坏恢复模块 recoverCorruptedDatabase.ts并同时覆盖主进程与 preload 两条链路见 recoverCorruptedDatabase.test.ts 与 recoverCorruptedDatabasePreload.test.ts。值得注意的是 PRD 所述自动清理缓存 → 重新安装依赖的完整链路中依赖重新安装部分在 ACP 统一架构下已弱化见下文 F-RELIABILITY-06 的实现差距说明当前仓库重点保障的是数据库/元数据缓存损坏的自动修复与修复不丢用户数据这一硬约束——例如backend_local_data_repair_failed分类只针对可安全修复的agent_metadata非法 UTF-8 场景而数据库比应用新backend_database_newer_than_app则被明确排除在修复路径之外因为此时数据库完好正确动作是引导升级而非修复。这与迁移模块 migrateAssistants.ts 中迁移失败时旧数据保留、绝不清写用户数据的设计一脉相承。六、F-RELIABILITY-06多候选安装策略未实现6.1 PRD 原定义本功能点的用户故事是在使用特定 AI 后端时即使某个安装包不兼容当前操作系统系统也能自动尝试其他兼容包。正常流程系统启动特定 AI 后端 → 按优先级尝试可用的安装包首选包安装失败 → 自动尝试备选包最终成功启动 → 用户无感知。异常情况为所有候选包均失败时显示错误提示。验收标准自动尝试多个候选安装包安装失败自动降级到下一个候选包所有候选失败后给出明确错误。6.2 实现差距与现状该功能点在 reliability.md 中被明确标注为[未实现]且文档给出的差距说明极具参考价值ACP 统一架构下 CLI 由用户预装此功能可能不再适用需与产品确认是否保留。在 ACP 单聊功能 PRD 索引 的 skip 白名单中F-RELIABILITY-06 同样被标记为多候选安装架构改变后可能不适用。也就是说随着 ACP 架构演进为CLI Agent 由用户自行预装由应用代管安装包并做多候选降级的场景基本消失此功能点处于保留 PRD 定义、暂不实现的状态。与之形成对照的是安装相关可靠性能力并未缺席backend_incomplete_installation检测bundled-aioncore/、运行时目录、二进制等资源缺失与backend_package_architecture_mismatch架构不符这两类启动失败分类本质上承担了安装不兼容问题的诊断与引导职责——只是从自动尝试备选包变成了精确指出缺什么、指引用户修复这符合 ACP 架构下CLI 归用户管理的边界。七、F-RELIABILITY-07发送消息异常恢复7.1 用户故事与流程当消息发送过程中出现任何异常时系统应妥善处理并告知用户且不能导致界面卡死。正常流程消息发送过程中发生异常 → 界面显示错误消息AI 已部分输出的内容 → 保留在对话中不丢失界面恢复可用状态 → 用户可以继续发送新消息。验收标准发送异常后显示错误提示消息已部分输出的 AI 回复内容不丢失错误消息和回复结束信号按正确顺序展示先看到错误原因再看到回复结束界面不会卡在正在回复状态。7.2 源码实现发送失败错误分类器发送异常后显示错误提示在渲染进程由 buildSendFailureError.ts 的buildSendFailureError实现。它把原始异常归一化为结构化的AgentStreamErrorInfo核心字段包括code错误码如USER_AGENT_DISCONNECTED、AIONUI_CONVERSATION_BUSY、AIONUI_INTERNAL_ERRORownership错误归属aionui/user_agent/unknown_upstream用于决定用户侧文案与反馈建议retryable是否可重试feedback_recommended是否建议提交反馈resolution可选的处理建议如reconnect_agent→ 引导重启/重连 Agent、wait_for_current_response→ 提示等待当前回复完成workspacePath工作区路径类错误附带具体路径。分类优先级从源码可确认工作区路径类错误normalizeWorkspacePathErrorCode→ 不可重试AionUi 传输层错误MCP_HTTP_RESPONSE_READ_FAILED、MCP_TOOL_REMOTE_ERROR、MCP_TOOL_RESPONSE_UNEXPECTED、MCP_TCP_READ_FAILED、TEAM_SERVICE_UNAVAILABLE→ 可重试、建议反馈团队助手类错误TEAM_ASSISTANT_ID_REQUIRED等→ 不可重试Agent 断连后端消息包含 acp protocol is not connected→USER_AGENT_DISCONNECTED可重试建议重启/重连 AgentBAD_GATEWAY→UNKNOWN_UPSTREAM_ERROR上游网关异常可重试会话繁忙classifyConversationBusyError→AIONUI_CONVERSATION_BUSY建议等待当前回复兜底 →AIONUI_INTERNAL_ERROR附带脱敏后的原始错误摘要以便 Sentry 定位。7.3 错误脱敏与消息顺序保障先看到错误原因再看到回复结束以及界面不卡死对应useAcpMessage.ts中的错误处理路径收到error事件时Hook 置turnFinishedRef true同时清空running、aiProcessing调用markTurnEnded()并记录[RequestTrace] ERROR日志——所有加载态一次性复位杜绝界面卡在正在回复错误提示类消息isErrorTipMessage走同样的完整复位路径随后将转换后的错误消息mergeLiveMessage合并进对话流保证错误消息与回合终态按事件到达顺序正确呈现由于finish/error的复位都基于同一套turnFinishedRef守卫迟到的流式事件无法复活已结束的回合从机制上保证顺序正确性。错误上报的安全性由 errorDiagnostics.ts 的脱敏层兜底redactErrorText会对 API Keysk-前缀、GoogleAIza、AWSAKIA/ASIA、JWT、Bearer Token、连接串密码、keyvalue密钥、邮箱、用户主目录路径等执行正则脱敏并将消息截断到 500 字符、堆栈截断到 1000 字符确保原始错误摘要可以安全进入遥测。相关行为由 buildSendFailureError.test.ts 验证。八、测试体系与验收闭环可靠性功能在仓库中拥有成体系的单元测试支撑除上文提到的外启动可靠性相关还包括backendStartupFailure.test.ts失败分类器的各类 reason 判定backendInstallDiagnostics.test.ts安装诊断信息采集recoverCorruptedDatabase.test.ts 与 recoverCorruptedDatabasePreload.test.ts数据库损坏恢复的主进程与 preload 双链路backendStartup.test.ts / backendStartupFailure.test.ts启动成功与失败路径。E2E 层面ACP 单聊功能 PRD 索引 的 skip 白名单给出了明确的验收边界F-RELIABILITY-06多候选安装因架构改变跳过F-SESSION-10 的 turn 完成边界、F-DISPLAY-07 的 token 统计双路径等处于待确认状态所有首次认证流程与 Gemini 专属差异在 E2E 中被跳过。这套PRD 定义 → 单元测试锁定实现 → E2E 白名单标注差距的三层机制保证了可靠性声明与代码事实的一致性。九、总结从 PRD 到实现的可靠性设计模式回顾 F-RELIABILITY-01 ~ 07 的落地可以提炼出四条可复用的设计模式自动重试一次的默认策略连接失败、启动失败都采用首次失败自动重试一次二次失败才提示的节奏既容忍瞬时抖动又避免无限重试拖垮体验回合状态机的硬复位保证running/aiProcessing的置回由turnFinishedRef守卫finish/error/ 错误提示三类终态统一复位配合 15 秒无活动兜底F-SESSION-10从机制上保证界面绝不卡死错误分类 → 结构化信息 → 针对性文案从classifyBackendStartupFailure的十余种 reason到buildSendFailureError的 ownership / retryable / resolution 三要素再到 i18n 中主体 可执行动作的文案形成用户可理解的诊断闭环透明修复与数据安全优先缓存/数据库损坏走自动修复路径但严格限定可安全修复的场景非法 UTF-8 元数据、可恢复损坏数据库比应用新等场景明确引导升级而非修复始终不触碰用户数据。对于希望深入源码的读者建议从 useAcpMessage.ts回合状态机、buildSendFailureError.ts错误分类与 backendStartupFailure.ts启动失败分类三个文件切入即可完整串联起本模块从PRD 验收标准到生产级实现的整条链路。【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AionUi ACP 单聊可靠性工程解析：超时处理、启动失败诊断与消息异常恢复的完整落地
AionUi ACP 单聊可靠性工程解析超时处理、启动失败诊断与消息异常恢复的完整落地【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi导读本篇文章围绕 AionUi 开源仓库中 ACP 单聊功能 PRD 的可靠性模块功能编号 F-RELIABILITY-01 ~ 07系统讲解 AI 后端连接超时、回复超时、启动失败提示、本地缓存损坏自动修复、多候选安装策略与发送消息异常恢复的完整设计。你将看到每个功能点的用户故事、正常/异常流程、验收标准以及它们在packages/desktop渲染进程与主进程中的真实源码实现掌握一套自动重试一次 状态机可靠复位 错误分类引导 透明修复的桌面端 AI 会话可靠性设计范式。一、可靠性模块在 ACP 单聊 PRD 中的位置AionUi 将 ACP 单聊功能拆分为 7 个模块 PRD可靠性模块是其中之一。核心文档 reliability.md 由 PM 从prd-acp-scenarios.md抽取覆盖技术场景S-ERR-01 ~ S-ERR-09其中 S-ERR-03 已合并至 F-SESSION-04 意外断连自动处理S-ERR-08/09 已合并至 F-SESSION-10 AI 回复完成处理共 6 个独立功能点功能编号标题状态F-RELIABILITY-01连接超时自动处理已实现F-RELIABILITY-02AI 回复超时自动处理已实现F-RELIABILITY-04启动失败友好提示已实现F-RELIABILITY-05本地缓存损坏自动修复已实现F-RELIABILITY-06多候选安装策略特定后端未实现F-RELIABILITY-07发送消息异常恢复已实现模块索引见 ACP 单聊功能 PRD 索引该表同时给出了 51 个功能点的整体状态统计已实现 43、部分实现 6、未实现 2以及 E2E 测试的 skip 白名单——其中 F-RELIABILITY-06 即因架构改变后可能不适用被列入 skip。可靠性与相邻模块存在明确的衔接关系会话连接的超时阈值定义在 session.md 的 F-SESSION-02约 70 秒Codex 约 150 秒回复超时的15 秒无新内容自动结束兜底逻辑定义在 F-SESSION-10而超时时间本身的用户可配置项定义在 config.md 的 F-CONFIG-06。理解可靠性设计需要以这几个模块为上下文。二、F-RELIABILITY-01连接超时自动处理2.1 用户故事与流程当系统与 AI 后端的连接因网络等原因超时时用户希望得到明确提示而不是无限等待。正常流程为系统开始连接 AI 后端 → 界面显示连接中状态连接超时 → 显示连接超时错误提示用户再次发送消息 → 系统自动尝试重新连接。异常情况首次连接失败时系统自动重试一次用户可能观察到短暂延迟后恢复重试仍失败才显示错误提示。不同 AI 后端的差异部分后端连接等待时间较长最多约 2.5 分钟即 Codex部分后端约 1 分钟。这与会话模块 F-SESSION-02 的描述一致普通后端连接时间约 70 秒Codex 约 150 秒且无需额外认证Claude、Qwen 等后端首次使用可能需要登录授权。验收标准连接超时后显示明确的错误提示首次连接失败自动重试一次超时后用户可通过发送新消息触发重连。2.2 源码实现连接状态机与事件驱动在渲染进程的 ACP 会话管理 Hook useAcpMessage.ts 中连接状态被建模为一组离散状态const [acpStatus, setAcpStatus] useState connecting | connected | authenticated | session_active | disconnected | error | null (null);这七个状态恰好对应 ACP 后端通过agent_status事件推送的连接生命周期。当收到agent_status事件时Hook 会同步更新本地状态并做两类关键复位状态进入authenticated/session_active认证完成、会话就绪时将running置回false表明连接过程结束状态进入error/disconnected时同时清空running与aiProcessing两个加载态并调用markTurnEnded()确保界面不会因连接异常而卡在正在回复状态。这套逻辑直接呼应了超时后用户可通过发送新消息触发重连的验收标准连接状态与回合状态解耦断连只是把界面复位为可用态下一次发送自然触发会话运行时ensureConversationRuntime重新建立连接。另外useAcpMessage通过模块级conversationTurnClockbeginConversationTurn/endConversationTurn记录回合起始时间该时间戳按会话持久化即使切换会话也不会丢失为连接/回复时长的可视化提供了数据源。三、F-RELIABILITY-02AI 回复超时自动处理3.1 用户故事与流程当 AI 长时间无响应时系统应自动取消等待并告知用户而不是无限等待。正常流程用户发送消息 → AI 开始处理AI 在配置的超时时间内无响应 → 系统自动取消等待显示超时提示用户可重新发送消息。三个不触发超时的异常情况是理解本功能的关键AI 正在进行工具调用如读写文件时不会触发超时AI 等待用户审批权限时不会触发超时对应 ACP 的acp_permission事件AI 有持续输出时不会触发超时每次收到内容都会重置超时计时。验收标准AI 无响应超过配置时间后自动取消并提示工具调用和权限审批期间不触发超时AI 有持续输出时不触发超时超时后用户可重新发送消息。3.2 超时时间的可配置性F-CONFIG-06超时阈值并非写死值而是用户可配置项。对应 config.md 的 F-CONFIG-06用户可设置全局默认超时时间用户可为特定后端单独设置超时优先级高于全局超时时间设置过小低于 30 秒时系统自动调整为最小值 30 秒。在配置层clientSettings.ts 中定义了acp.promptTimeout单次回复超时与acp.agentIdleTimeoutAgent 空闲超时两个配置键说明超时体系不仅覆盖单次回复还延伸到会话空闲资源的自动释放与 F-SESSION-05 的默认 5 分钟空闲释放联动。3.3 源码实现回合状态机与自动恢复但不复活已结束回合useAcpMessage.ts通过一组 ref 与事件处理实现了一个可靠的回合状态机turnFinishedRef回合结束守卫。收到finish正常完成、error异常或错误提示类消息isErrorTipMessage时置为true此后任何迟到的流式事件都不会再把running置回truehasContentInTurnRef记录当前回合是否已有正文输出。首个text/content事件到达时置为true并清除aiProcessing加载指示自动恢复start、thought、thinking、text、agent_status、acp_permission等事件都带有若回合未结束则恢复running的兜底分支防止流式事件丢失导致界面停留在未激活态finish的完整复位收到finish后依次执行setRunning(false)、setAiProcessing(false)、markTurnEnded()、清空思考态与活动思考引用并记录请求追踪耗时[RequestTrace] FINISH保证界面立即回到可输入状态。finish分支里还针对思考过程但没有实际内容生成内容但未发完成信号等场景做了说明——这正是 F-SESSION-10 的15 秒无新内容后自动判定回复完成兜底逻辑的渲染侧表现与可靠性模块的 F-RELIABILITY-02 互为表里一个负责用户可配置的硬超时一个负责流式协议层的软兜底。对acp_permission事件的处理则印证了权限审批期间不触发超时该事件不会结束回合只是恢复运行态并合并消息等待用户在审批 UI 上操作。四、F-RELIABILITY-04启动失败友好提示4.1 用户故事与流程当 AI 后端启动失败时用户希望看到有针对性的、可操作的错误提示。正常流程系统尝试启动 AI 后端失败 → 显示针对性提示AI 工具未安装 → 引导安装配置文件错误 → 引导修复配置AI 工具不支持当前模式 → 引导切换模式或更新工具首次启动失败 → 系统自动重试一次短暂延迟后重试仍失败 → 显示最终错误提示。验收标准启动失败后显示用户可理解的错误提示不同原因的启动失败给出不同的针对性提示首次启动失败自动重试一次。4.2 源码实现失败分类器与原因 → 文案 → 处理建议闭环不同原因不同提示在源码中由主进程的失败分类器 backendStartupFailure.ts 实现。classifyBackendStartupFailure按优先级依次匹配多种失败类型返回结构化诊断信息reason 上下文字段目前已覆盖reason触发条件部分backend_package_architecture_mismatch安装包架构与设备架构不符含 Rosetta 转译信息backend_incomplete_installation打包资源缺失缺bundled-aioncore/、运行时二进制等backend_startup_directory_unavailable启动目录权限拒绝EACCES/EPERM或目录不可用ENOENT/mkdir 失败backend_incompatible_runtime检测到缺少的 glibc 版本正则提取GLIBC_x.y并排序backend_local_data_repair_failed本地数据修复失败agent_metadata存在非法 UTF-8backend_transient_concurrent_startup两个 aioncore 实例并发引导同一数据目录的良性竞争backend_database_newer_than_app数据库由更新的版本写入提示升级而非当作损坏backend_recoverable_database_corruption可恢复的数据库损坏backend_data_migration_failed数据库迁移阶段失败backend_startup_pending_slow已监听端口但未就绪慢启动进程保持存活backend_startup_exited/backend_startup_port_report_timeout进程提前退出 / 端口上报超时backend_startup_failed通用兜底从源码注释可以看到两个值得注意的工程细节一是进程被观察到已监听但提前退出会被判为真实启动失败而非资源缺失避免误引导用户重装二是并发启动的良性竞争被单独分类刻意不落入本地数据修复失败的误报源码引用 Sentry 事件说明该误报曾真实发生。该分类器由 backendStartupFailure.test.ts 覆盖诊断信息的采集入口在 backendInstallDiagnostics.ts。用户侧文案集中维护在 i18n 的 conversation.json典型如所选 Agent 未能完成启动握手。请重启或重新连接该 Agent 后重试。含Agent 握手超时标题OpenClaw Gateway 未运行或无法连接到 127.0.0.1:18789…给出可执行的openclaw gateway status/openclaw gateway start命令Agent 在处理本次消息时断开了连接。请重启或重新连接 Agent 后重试。这类文案的共同点是指明问题主体 用户可执行的恢复动作与 PRD用户可理解的错误提示一致。安装完整性校验另有独立的对话框组件 InstallationIntegrityDialog.tsx 兜底。五、F-RELIABILITY-05本地缓存损坏自动修复5.1 用户故事与流程用户不希望因为本地缓存损坏而无法使用 AI 功能。正常流程系统在启动过程中自动检测到本地缓存损坏 → 自动清理损坏的缓存文件清理后自动重新安装依赖整个过程对用户透明用户只会感知到稍长的启动时间。验收标准缓存损坏时自动修复、无需手动操作修复后 AI 功能正常可用修复过程不丢失用户数据。5.2 源码实现可恢复损坏的边界与透明修复该功能在启动链路上体现为边界阶段 可恢复分类两段式设计后端起不来时aioncore 会通过边界阶段backendBoundaryStage与边界码backendBoundaryCode上报具体失败阶段classifyBackendStartupFailure将BOOTSTRAP_DATA_INIT_FAILEDRECOVERABLE_DATABASE_CORRUPTION_BOUNDARY_STAGE组合识别为backend_recoverable_database_corruption——这意味着可恢复的数据库损坏会走修复路径而不是直接判定为死局与之配套启动流程中有独立的数据库损坏恢复模块 recoverCorruptedDatabase.ts并同时覆盖主进程与 preload 两条链路见 recoverCorruptedDatabase.test.ts 与 recoverCorruptedDatabasePreload.test.ts。值得注意的是 PRD 所述自动清理缓存 → 重新安装依赖的完整链路中依赖重新安装部分在 ACP 统一架构下已弱化见下文 F-RELIABILITY-06 的实现差距说明当前仓库重点保障的是数据库/元数据缓存损坏的自动修复与修复不丢用户数据这一硬约束——例如backend_local_data_repair_failed分类只针对可安全修复的agent_metadata非法 UTF-8 场景而数据库比应用新backend_database_newer_than_app则被明确排除在修复路径之外因为此时数据库完好正确动作是引导升级而非修复。这与迁移模块 migrateAssistants.ts 中迁移失败时旧数据保留、绝不清写用户数据的设计一脉相承。六、F-RELIABILITY-06多候选安装策略未实现6.1 PRD 原定义本功能点的用户故事是在使用特定 AI 后端时即使某个安装包不兼容当前操作系统系统也能自动尝试其他兼容包。正常流程系统启动特定 AI 后端 → 按优先级尝试可用的安装包首选包安装失败 → 自动尝试备选包最终成功启动 → 用户无感知。异常情况为所有候选包均失败时显示错误提示。验收标准自动尝试多个候选安装包安装失败自动降级到下一个候选包所有候选失败后给出明确错误。6.2 实现差距与现状该功能点在 reliability.md 中被明确标注为[未实现]且文档给出的差距说明极具参考价值ACP 统一架构下 CLI 由用户预装此功能可能不再适用需与产品确认是否保留。在 ACP 单聊功能 PRD 索引 的 skip 白名单中F-RELIABILITY-06 同样被标记为多候选安装架构改变后可能不适用。也就是说随着 ACP 架构演进为CLI Agent 由用户自行预装由应用代管安装包并做多候选降级的场景基本消失此功能点处于保留 PRD 定义、暂不实现的状态。与之形成对照的是安装相关可靠性能力并未缺席backend_incomplete_installation检测bundled-aioncore/、运行时目录、二进制等资源缺失与backend_package_architecture_mismatch架构不符这两类启动失败分类本质上承担了安装不兼容问题的诊断与引导职责——只是从自动尝试备选包变成了精确指出缺什么、指引用户修复这符合 ACP 架构下CLI 归用户管理的边界。七、F-RELIABILITY-07发送消息异常恢复7.1 用户故事与流程当消息发送过程中出现任何异常时系统应妥善处理并告知用户且不能导致界面卡死。正常流程消息发送过程中发生异常 → 界面显示错误消息AI 已部分输出的内容 → 保留在对话中不丢失界面恢复可用状态 → 用户可以继续发送新消息。验收标准发送异常后显示错误提示消息已部分输出的 AI 回复内容不丢失错误消息和回复结束信号按正确顺序展示先看到错误原因再看到回复结束界面不会卡在正在回复状态。7.2 源码实现发送失败错误分类器发送异常后显示错误提示在渲染进程由 buildSendFailureError.ts 的buildSendFailureError实现。它把原始异常归一化为结构化的AgentStreamErrorInfo核心字段包括code错误码如USER_AGENT_DISCONNECTED、AIONUI_CONVERSATION_BUSY、AIONUI_INTERNAL_ERRORownership错误归属aionui/user_agent/unknown_upstream用于决定用户侧文案与反馈建议retryable是否可重试feedback_recommended是否建议提交反馈resolution可选的处理建议如reconnect_agent→ 引导重启/重连 Agent、wait_for_current_response→ 提示等待当前回复完成workspacePath工作区路径类错误附带具体路径。分类优先级从源码可确认工作区路径类错误normalizeWorkspacePathErrorCode→ 不可重试AionUi 传输层错误MCP_HTTP_RESPONSE_READ_FAILED、MCP_TOOL_REMOTE_ERROR、MCP_TOOL_RESPONSE_UNEXPECTED、MCP_TCP_READ_FAILED、TEAM_SERVICE_UNAVAILABLE→ 可重试、建议反馈团队助手类错误TEAM_ASSISTANT_ID_REQUIRED等→ 不可重试Agent 断连后端消息包含 acp protocol is not connected→USER_AGENT_DISCONNECTED可重试建议重启/重连 AgentBAD_GATEWAY→UNKNOWN_UPSTREAM_ERROR上游网关异常可重试会话繁忙classifyConversationBusyError→AIONUI_CONVERSATION_BUSY建议等待当前回复兜底 →AIONUI_INTERNAL_ERROR附带脱敏后的原始错误摘要以便 Sentry 定位。7.3 错误脱敏与消息顺序保障先看到错误原因再看到回复结束以及界面不卡死对应useAcpMessage.ts中的错误处理路径收到error事件时Hook 置turnFinishedRef true同时清空running、aiProcessing调用markTurnEnded()并记录[RequestTrace] ERROR日志——所有加载态一次性复位杜绝界面卡在正在回复错误提示类消息isErrorTipMessage走同样的完整复位路径随后将转换后的错误消息mergeLiveMessage合并进对话流保证错误消息与回合终态按事件到达顺序正确呈现由于finish/error的复位都基于同一套turnFinishedRef守卫迟到的流式事件无法复活已结束的回合从机制上保证顺序正确性。错误上报的安全性由 errorDiagnostics.ts 的脱敏层兜底redactErrorText会对 API Keysk-前缀、GoogleAIza、AWSAKIA/ASIA、JWT、Bearer Token、连接串密码、keyvalue密钥、邮箱、用户主目录路径等执行正则脱敏并将消息截断到 500 字符、堆栈截断到 1000 字符确保原始错误摘要可以安全进入遥测。相关行为由 buildSendFailureError.test.ts 验证。八、测试体系与验收闭环可靠性功能在仓库中拥有成体系的单元测试支撑除上文提到的外启动可靠性相关还包括backendStartupFailure.test.ts失败分类器的各类 reason 判定backendInstallDiagnostics.test.ts安装诊断信息采集recoverCorruptedDatabase.test.ts 与 recoverCorruptedDatabasePreload.test.ts数据库损坏恢复的主进程与 preload 双链路backendStartup.test.ts / backendStartupFailure.test.ts启动成功与失败路径。E2E 层面ACP 单聊功能 PRD 索引 的 skip 白名单给出了明确的验收边界F-RELIABILITY-06多候选安装因架构改变跳过F-SESSION-10 的 turn 完成边界、F-DISPLAY-07 的 token 统计双路径等处于待确认状态所有首次认证流程与 Gemini 专属差异在 E2E 中被跳过。这套PRD 定义 → 单元测试锁定实现 → E2E 白名单标注差距的三层机制保证了可靠性声明与代码事实的一致性。九、总结从 PRD 到实现的可靠性设计模式回顾 F-RELIABILITY-01 ~ 07 的落地可以提炼出四条可复用的设计模式自动重试一次的默认策略连接失败、启动失败都采用首次失败自动重试一次二次失败才提示的节奏既容忍瞬时抖动又避免无限重试拖垮体验回合状态机的硬复位保证running/aiProcessing的置回由turnFinishedRef守卫finish/error/ 错误提示三类终态统一复位配合 15 秒无活动兜底F-SESSION-10从机制上保证界面绝不卡死错误分类 → 结构化信息 → 针对性文案从classifyBackendStartupFailure的十余种 reason到buildSendFailureError的 ownership / retryable / resolution 三要素再到 i18n 中主体 可执行动作的文案形成用户可理解的诊断闭环透明修复与数据安全优先缓存/数据库损坏走自动修复路径但严格限定可安全修复的场景非法 UTF-8 元数据、可恢复损坏数据库比应用新等场景明确引导升级而非修复始终不触碰用户数据。对于希望深入源码的读者建议从 useAcpMessage.ts回合状态机、buildSendFailureError.ts错误分类与 backendStartupFailure.ts启动失败分类三个文件切入即可完整串联起本模块从PRD 验收标准到生产级实现的整条链路。【免费下载链接】AionUiOpen-source 24/7 Cowork app for OpenClaw, Hermes, Claude Code, Codex, OpenCode and 20 more CLI Agent | Customize your assistants | Team them upStar if you like it!项目地址: https://gitcode.com/GitHub_Trending/ai/AionUi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考