错误处理与诊断

wescode 通过多种机制帮助你理解和处理 AI 交互中的各类错误。

AI 回复中的错误

错误类型分类

严重度显示方式重试按钮适用场景
默认（可重试）红色错误块✅ 显示Provider 瞬时错误、认知内部错误
信息性（不可重试）柔和提示❌ 隐藏安全策略阻止、预算用尽
静默不渲染❌ 不渲染引擎自愈中的瞬态

可重试错误

同样请求再发一次可能成功：

不可重试错误

重发同样内容只会得到同样拒绝：

对于这类错误，建议换一种表述或开启新对话。

用户中断

context_cancelled 和 interrupted 不会渲染任何错误块。

Provider 相关错误

API Key 问题

症状原因解决
401 UnauthorizedKey 无效或过期在设置中更新 Key
403 Forbidden无权限访问该模型检查账户权限
429 Rate Limited请求频率过高等待后重试

模型不可用

"vision_not_supported"
→ 当前模型不支持图片输入
→ 切换到支持 Vision 的模型

WES 欠费

工具执行错误

exec 错误

命令执行失败时，AI 会：

  1. 读取错误输出
  2. 分析失败原因
  3. 尝试修复并重试
  4. 报告最终结果

文件操作错误

错误原因AI 行为
权限不足文件只读提示更改权限
路径不存在目录缺失创建目录后重试
文件过大超过读取限制分段读取

CycleDetector

当 AI 陷入重复操作时：

  1. 首次触发：注入纠正消息，给 AI 第二次机会
  2. 再次触发：HITL 询问用户怎么办
  3. 超时：60 秒后自动终止并保存进度

引擎状态诊断

健康检查

在状态栏查看引擎状态：

状态含义
AI 就绪引擎正常
AI 启动中引擎正在初始化
AI 不可用引擎未启动或崩溃

引擎日志

日志位置：

~/Library/Application Support/wescode/
  logs/wescode.log      ← Go 后端日志（INFO+）

常见引擎问题

问题排查步骤
Chat 无响应检查状态栏 → 查看日志 → 重启窗口
索引卡住检查索引进度条 → 查看 CKG 状态
记忆丢失确认工作区正确 → 检查 Cell 数据

治理策略错误

Hardline 拦截

以下命令永远被拦截（18 条灾难正则）：

rm -rf /
fork bomb
shutdown
kill engine
...

显示为信息性提示，不可重试。

Sandbox 限制

当 NetworkPolicy=deny 时：

"网络命令被安全策略阻止"
→ curl/wget/nc 等命令被拦截
→ 调整治理策略或切换到编程模式

DenyPaths

写入被禁止的路径：

"写入路径被治理策略拒绝"
→ 检查当前治理模式
→ 确认目标路径是否在允许范围内

连接性问题

Provider 连通性测试

在设置中测试 Provider：

  1. 打开设置 → AI 服务
  2. 点击 Provider 旁的测试按钮
  3. 查看测试结果（chat / embedding / vision）

网络排查

用户："Provider 连接失败"

排查步骤：
1. 检查 API Key 是否有效
2. 检查 base_url 是否正确
3. 测试网络连通性
4. 查看 Provider 服务状态
5. 检查代理设置

数据恢复

Cell 数据损坏

wesgine 的三层数据韧性保证：

Boot 永远成功

Cell 启动时自动处理：

手动恢复

如果数据出现问题：
1. 检查 ~/Library/Application Support/wescode/cells/ws-{hash}/
2. 损坏的 DB 在 corrupt/ 目录
3. 删除 Cell 数据后重新索引（CKG 可重建）
4. 记忆数据不可重建——定期导出

最佳实践

遇到错误时

  1. 查看错误类型：可重试 vs 不可重试
  2. 检查状态栏：引擎是否健康
  3. 查看日志：logs/wescode.log
  4. 重启窗口：解决大部分瞬态问题

预防措施