前端识别错误信息的核心是结构化错误数据：AionClaw响应必须含固定错误码（如ERR_SKILL_017）、英文message、scope模块标识、recoverable布尔值及16位trace_id，前端据此精准分支处理与用户提示。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
前端识别错误信息的核心设计逻辑
让前端能快速定位、分类、响应 AionClaw 抛出的异常，关键不是堆砌日志，而是从源头结构化错误数据。AionClaw 的错误响应必须携带可解析的类型标识、明确的作用域范围和可操作的修复线索，否则前端只能做模糊提示或静默失败。
定义标准化错误码体系
在 AionClaw 的 Hermes Agent 执行引擎中，所有技能运行时的异常必须映射到统一错误码前缀体系：【ERR_SKILL_XXX】 表示技能执行层错误，【ERR_MODEL_XXX】 表示大模型调用链路异常，【ERR_FS_XXX】 表示本地文件系统权限或路径问题。每类错误码对应唯一数字后缀（如 ERR_SKILL_017），禁止使用动态拼接字符串替代固定码值。
这一步不可跳过——前端靠错误码做 switch 分支处理，而非正则匹配中文描述。
构造带上下文的 JSON 错误响应体
当技能执行失败时，AionClaw 必须返回标准 JSON 格式响应，且严格包含以下字段：
立即学习“前端免费学习笔记（深入）”；
• code：必须为上一步定义的固定错误码（如 "ERR_SKILL_017"）
• message：面向开发者的简明英文说明（如 "File path exceeds max allowed depth"）
• scope：标明错误发生的具体模块（值为 "file_io"、"wechat_api"、"model_router" 之一）
• recoverable：布尔值，true 表示前端可引导用户重试（如网络抖动），false 表示需人工干预（如权限被系统拒绝）
• trace_id：该次请求唯一追踪 ID，长度固定 16 位小写字母+数字组合，便于前后端日志串联
前端对接实操步骤
第一步：在前端请求拦截器中统一捕获 AionClaw 响应
第二步：检查 response.status 是否为 4xx 或 5xx，且 response.headers.get("X-AionClaw-Error") === "true"
第三步：解析 response.json()，提取 code 字段 → 查表匹配预置的错误处理策略
第四步：根据 recoverable 字段决定是否显示「重试」按钮；若为 false，则展示 scoped 提示文案（例如 scope 为 "wechat_api" 时，提示「请检查飞书桌面端是否已登录并开启消息接收权限」）
第五步：将 trace_id 写入前端埋点日志，并同步上报至 Sentry 实例，确保错误可回溯
