设计本地 AI 的错误提示与恢复动作

直接回答

本地 AI 错误提示应使用用户能采取行动的语言说明失败阶段，把暂时中断与不支持的操作区分开，并且只提供应用实际实现的恢复动作。下载、文件校验、运行时初始化、资源不足、执行后端、权限、用户取消和输出解析都不该只显示一个“AI 失败”。这些状态的负责人和下一步不同。不要把原生异常、堆栈、模型提示词、转录文本、文件路径、签名网址或令牌直接放进用户界面。 应根据稳定的内部失败类别生成文案，而不是直接拼接异常字符串。底层组件可以回报阶段与安全错误码，例如工件不存在、传输中断、缺少摘要、访问被撤销、运行时初始化失败、资源限制、后端不可用、任务已取消或输出无效。界面再把类别映射到简明说明和操作。若产品政策允许，可在受保护的诊断通道保存脱敏异常值。已知证据不够时，不要声称已找到根因：“模型无法加载”比“你的手机不兼容”更准确，后者必须有明确兼容测试支持。 还要区分用户主动控制和真正错误。主动取消工作不一定是错误；可以说明任务已停止，并仅在实现经过测试时解释有效部分文件是否保留。缺少输入属于空状态，不是推理失败。相机或文件权限被拒是权限状态，应指向相关系统授权动作。空间不足的提示不应让用户去删个人文件。商店或下载服务不可用也不能说成模型或设备故障。每条提示都要说明已知事实、仍在检查什么以及用户下一步可以做什么。 状态机必须和提示分类一致。如果 ModelManager 区分未下载、下载中、已下载、加载中、就绪和错误，界面文案就不能把它们折叠成同一种状态。“已下载”不等于“就绪”；文件存在仍可能无法加载；“已取消”不能说成“已损坏”。如果配置没有校验摘要，就不能称完整性验证成功。如果运行时只报告泛化错误，也不能猜测是某个加速后端或内存原因。应获取进一步证据，或直接说明目前无法判断。 恢复文案应有边界并尽量可撤销。只有当阶段确实可能短暂失败，且操作具备幂等性或下载器能证明部分文件身份时才重试。权限问题要说明为何需要访问，并让用户在系统授权后再次尝试。资源限制只有在产品支持时才建议缩小输入；不要承诺关闭其他应用就能解决模型问题。任务不支持时要引导到受支持路径，而不是“再试一次”。问题持续时，可提供脱敏支持记录，其中包括应用构建、工件版本、生命周期阶段和安全错误类别，不包含正文内容。 每条文案都应能追溯到观察证据。错误层不能在没有证据时声称硬件不兼容、隐私泄漏、数据丢失、文件损坏、服务器停机或清理成功。读文件失败可能由文件删除、访问撤销、卷消失或其他 I/O 原因造成。界面可先报告观察结果并给出检查/重试，而不是擅自选定一种原因。同样，下载中断也不能证明数据已丢失；若有效部分文件仍存在，恢复路径可能完全不同。

离线任务中的原生加载失败

用户启动翻译后出现运行时异常。应用只观察到模型加载失败，无法证明设备不兼容，也不知道用户输入是否仍保留。

决策

指出模型初始化阶段，保留实际仍在内存或草稿中的输入，提供经过测试的重试/支持动作，不展示原始异常。

预期结果

用户得到真实的下一步，而不会遭遇虚构硬件诊断或用户文字泄露。

需要收集的证据

只有将以下证据与同一模型文件和测试运行关联起来，结论才可复核：

• 事实卡 COVE-LIFECYCLE-01、PRIVACY-01；ModelManager 生命周期状态与端侧推理的隐私边界。
• Android offline-first 错误处理、Compose 无障碍语义与调试指南。

收到完整字节流还不够；最终落盘、完整性、运行时加载和恢复路径也必须验证。

实施流程

1. 映射错误所有者. 将下载、校验、文件访问、运行时、后端、任务和结果解析分别关联到稳定内部类别及能观察该事件的代码组件。
2. 区分观察与原因. 记录观察到的阶段和安全错误码，不从通用异常、超时或文件缺失猜测硬件不兼容、损坏、隐私泄露或数据删除。
3. 定义安全下一步. 只有在真实实现且适用于该错误类别时，才提供重试、重新选文件、权限入口、清理应用所属文件、其他任务或支持联系动作。
4. 撰写可访问的本地化文案. 提供简短标题、事实说明和一项明确操作，通过语义播报状态变化；不让颜色或无法解释的底层术语承担全部沟通。
5. 脱敏后保存诊断. 保存前删除提示词、转录、图片、绝对路径、签名链接、请求头和令牌，仅保留必要的构建、工件、阶段与类别。
6. 注入故障检查文案. 测试中断、无输入、权限拒绝、缺文件、摘要缺失、加载错误、资源限制、不支持任务、取消和输出异常，并核对状态、文字和动作一致。

让每个阶段的状态都可观察。失败信息应指出阶段、模型、运行时和恢复动作，同时避免记录用户私密内容。

验收标准

• 每条提示对应真实观察到的阶段，不添加组件无法证实的根因。
• 空状态、用户取消、临时中断、权限拒绝、不支持操作及实际加载失败各有独立表达。
• 恢复动作确实存在、针对当前类别、尽量可撤回且经过测试。
• 界面、日志与支持文件不暴露用户内容或敏感异常数据。

决策对照表

需要避免的失败模式

• 不得根据泛化异常推断手机不兼容、文件损坏、数据丢失或隐私泄漏。
• 不得将提示词、转录、文件路径、签名网址、授权头或原始堆栈直接展示给用户。

还要避免静默回退、版本未固定、缺少取消处理，以及把不同配置的结果混在一起下结论。失败运行也应与成功记录一并保存。

最小复现记录

发布检查表

• ☐ 主要搜索问题已回答，且没有未经支持的数字。
• ☐ 所有模型文件和运行时版本均已固定。
• ☐ 代表性任务和失败处理策略均有说明。
• ☐ 生命周期、取消、清理和回退均已测试。
• ☐ 用户内容与网络边界均有说明。
• ☐ 结论只适用于被记录的配置。
• ☐ 新增测试结果时链接到原始方法或证据。

来源与相关证据

• 构建 offline-first 应用：错误处理
• Compose 无障碍语义
• Android Studio 调试应用

中文部署与排错专题见。奇连 AI 端侧专题。

常见问题