Back to Aionui

ACP 单聊 - 可靠性与错误处理 (F-RELIABILITY)

docs/prds/conversations/acp/reliability.md

1.9.254.9 KB
Original Source

ACP 单聊 - 可靠性与错误处理 (F-RELIABILITY)

本文档由 PM 从 prd-acp-scenarios.md 抽取,保持与源同步。 覆盖技术场景:S-ERR-01 ~ S-ERR-09(排除 S-ERR-03 已合并至 F-SESSION-04,S-ERR-08/09 已合并至 F-SESSION-10)


(F-RELIABILITY-01) 连接超时自动处理 [已实现]

用户故事:作为用户,当系统与 AI 后端的连接因网络问题等原因超时时,我希望系统能给出明确提示,而不是无限等待。

正常流程(用户视角):

  1. 系统开始连接 AI 后端 -> 显示"连接中"状态
  2. 连接超时 -> 显示"连接超时"错误提示
  3. 用户再次发送消息 -> 系统自动尝试重新连接

异常情况

  • 首次连接失败:系统自动重试一次(用户可能观察到短暂延迟后恢复)
  • 重试仍失败:显示错误提示

不同 AI 后端的差异

  • 部分后端的连接等待时间较长(最多约 2.5 分钟),部分后端约 1 分钟

验收标准

  • 连接超时后显示明确的错误提示
  • 首次连接失败自动重试一次
  • 超时后用户可通过发送新消息触发重连

(F-RELIABILITY-02) AI 回复超时自动处理 [已实现]

用户故事:作为用户,当 AI 长时间没有响应时,我希望系统能自动取消等待并告知我,而不是让我无限等待。

正常流程(用户视角):

  1. 用户发送消息 -> AI 开始处理
  2. AI 在配置的超时时间内无响应 -> 系统自动取消等待,显示超时提示
  3. 用户可以重新发送消息

异常情况

  • AI 正在进行工具调用(如读写文件)时不会触发超时
  • AI 等待用户审批权限时不会触发超时
  • AI 有持续输出时不会触发超时(每次收到内容都会重置超时计时)

验收标准

  • AI 无响应超过配置时间后自动取消并提示
  • 工具调用和权限审批期间不触发超时
  • AI 有持续输出时不触发超时
  • 超时后用户可重新发送消息

(F-RELIABILITY-04) 启动失败友好提示 [已实现]

用户故事:作为用户,当 AI 后端启动失败时,我希望看到有用的错误提示,以便我知道如何解决问题。

正常流程(用户视角):

  1. 系统尝试启动 AI 后端失败 -> 显示针对性的错误提示:
    • "AI 工具未安装":引导安装
    • "配置文件错误":引导修复配置
    • "AI 工具不支持当前模式":引导切换模式或更新工具
  2. 首次启动失败 -> 系统自动重试一次(短暂延迟后)
  3. 重试仍失败 -> 显示最终错误提示

验收标准

  • 启动失败后显示用户可理解的错误提示
  • 不同原因的启动失败给出不同的针对性提示
  • 首次启动失败自动重试一次

(F-RELIABILITY-05) 本地缓存损坏自动修复 [已实现]

用户故事:作为用户,我不希望因为本地缓存损坏而无法使用 AI 功能,系统应该能自动修复这种问题。

正常流程(用户视角):

  1. 系统检测到本地缓存损坏(启动过程中自动检测)-> 自动清理损坏的缓存文件
  2. 清理后自动重新安装依赖
  3. 整个过程对用户透明,用户只会感知到稍长的启动时间

验收标准

  • 缓存损坏时自动修复,无需用户手动操作
  • 修复后 AI 功能正常可用
  • 修复过程不丢失用户数据

(F-RELIABILITY-06) 多候选安装策略(特定后端)[未实现]

实现差距:ACP 统一架构下 CLI 由用户预装,此功能可能不再适用,需与产品确认是否保留

用户故事:作为用户,我希望在使用特定 AI 后端时,即使某个安装包不兼容我的操作系统,系统也能自动尝试其他兼容包。

正常流程(用户视角):

  1. 系统启动特定 AI 后端 -> 按优先级尝试可用的安装包
  2. 首选包安装失败 -> 自动尝试备选包
  3. 最终成功启动 -> 用户无感知

异常情况

  • 所有候选包均失败:显示错误提示

验收标准

  • 自动尝试多个候选安装包
  • 安装失败自动降级到下一个候选包
  • 所有候选失败后给出明确错误

(F-RELIABILITY-07) 发送消息异常恢复 [已实现]

用户故事:作为用户,当消息发送过程中出现任何异常时,我希望系统能妥善处理并告知我,不会导致界面卡死。

正常流程(用户视角):

  1. 消息发送过程中发生异常 -> 界面显示错误消息
  2. AI 已部分输出的内容 -> 保留在对话中,不丢失
  3. 界面恢复可用状态 -> 用户可以继续发送新消息

验收标准

  • 发送异常后显示错误提示消息
  • 已部分输出的 AI 回复内容不丢失
  • 错误消息和回复结束信号按正确顺序展示(先看到错误原因,再看到回复结束)
  • 界面不会卡在"正在回复"状态