Troubleshooting · 故障排查

按"症状 → 诊断 → 修复"组织。每节自包含。

---

鉴权类

401 Unauthorized

症状：所有请求返回 {"code":401,"message":"agent.error.invalidCredentials"}

可能原因：

1. Authorization 头格式错误 —— 必须是 Bearer <key>，注意空格
2. API Key 已撤销
3. API Key 复制时多了空格 / 换行
4. 使用了过期的 access token（应先调用 /api/auth/refresh）

修复：

# 验证 Key 是否生效
curl -X GET https://api.volo.ai/api/auth/me \
  -H "Authorization: Bearer $VOLO_API_KEY"

返回 200 即正常。否则到 console.volo.ai Settings → API Keys 重新生成。

---

设备验证失败 / 401 deviceVerifyFailed

症状：refresh 返回 auth.error.deviceVerifyFailed

原因：后端对 refresh 做了 IP + User-Agent 绑定校验，换设备或 VPN IP 变更触发拒绝。

修复：重新走完整登录流程（POST /api/auth/login 或 /login/email）。

---

速率与配额

429 Too Many Requests

症状：返回 429 + Retry-After 头

默认限制：

• 60 次 / 分钟 / 用户
• 1000 次 / 会话
• 登录端点：5 次 / 分钟 / IP

修复：

• 客户端实现指数退避：sleep(2 ** retries)
• 长任务用 MAX 单 turn 而非循环短请求
• Pro/Team plan 上调 RPM
• 联系销售开企业速率

---

403 配额耗尽

症状：{"code":403,"message":"quota.exhausted"}

修复：

1. 控制台 Billing 查看剩余 credits
2. 等月度重置（每月 1 号 UTC+8）
3. 升级订阅
4. 优化 prompt 长度 / 用 FAST 替代 MAX

---

SSE 断连

流中途无原因结束

症状：未收到 COMPLETE 事件就断开

可能原因：

原因	诊断	修复
代理超时	Nginx 默认 60s	配置 proxy_read_timeout 300s
CDN 缓冲	Cloudflare / CloudFront	关闭对 SSE 路径的缓存与缓冲
浏览器 ReadableStream 卡死	长时间无数据	后端定期发 PROGRESS 心跳事件
客户端超时设置过短	timeout: 5000	调高到 60000+

修复：客户端开启自动重连（SDK 已封装）+ 后端配置：

location /api/agent/chat/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;            # 关键
    proxy_read_timeout 300s;        # SSE 默认时长
    proxy_set_header X-Accel-Buffering no;
}

后端已注入 SSE 响应头

SseResponseHeaderFilter 自动注入 Cache-Control: no-cache + X-Accel-Buffering: no + Connection: keep-alive。但前置 Nginx/CDN 仍需独立配置。

---

浏览器看到的事件不全

症状：终端 curl 正常，浏览器只看到部分事件

原因：

• 浏览器内存压力下会主动暂停渲染
• DevTools Network 面板的 EventSource 帧显示有 bug

修复：

• 用 chrome://net-export/ 抓真实网络流，确认服务端在发
• 用 fetch + ReadableStream 替代 EventSource（更可控）

---

工具调用与协议

TOOL_START 但没有 TOOL_END

症状：工具卡住，Agent 无响应

可能原因：

1. 工具内部异常未被 onErrorResume 兜住
2. 工具执行 > 30s 触发后端超时
3. 工具调用了第三方 API 但 API 限流

诊断：

# 查看 session 历史
curl "https://api.volo.ai/api/agent/chat/volo-ai/$SESSION_ID/messages" \
  -H "Authorization: Bearer $VOLO_API_KEY"

查找最后一条 ToolMessage 的 errorMessage 字段。

---

双气泡重复渲染

症状：聊天界面同一内容显示两次

原因：误把 TOOL 事件当独立协议事件渲染（违反 事件协议正交性）

修复：

• TOOL 事件子类型只渲染轻量执行链路标记（如"渲染了 表格"≤30 字符 + 图标）
• 独立协议事件（UI/INTERACTION/WEB_SEARCH/WEB_FETCH）走自己的 Message 气泡

详见 docs/specs/EVENT_PROTOCOL_ORTHOGONALITY.md。

---

Memory 上传

上传失败 · 文件过大

症状：413 Payload Too Large

限制：

• 单文件最大 50MB
• 图片自动经 COS 处理生成缩略图（无需客户端预处理）
• 视频 / 音频路由到外部转码服务

修复：

• 大视频先经客户端压缩
• 长文档拆分后上传
• 直接走 COS 预签名上传链接（[TODO: 端点待暴露]）

---

语义搜索返回空

症状：search 调用成功但结果为空

可能原因：

1. minScore 设置过高（默认 0.5，调低试试）
2. Memory 刚上传，向量化还没完成（异步任务，~5s 延迟）
3. 用户的 Memory 库为空

修复：调低阈值或等待几秒重试。

---

性能类

首 token 延迟过高（> 3s）

可能原因：

原因	诊断	修复
MAX 模式 + 思考链	event PROGRESS 持续但无 ASSISTANT_DELTA	改用 FAST 或 AUTO
工具链路过长	多次 TOOL_START	简化 prompt 或拆分任务
模型 cold start	第一次调用某模型	控制台预热（[TODO: 预热端点]）
网络问题	curl 也慢	检查到 api.volo.ai 的延迟

---

流速度卡顿

症状：ASSISTANT_DELTA 不连续，一秒一爆

原因：客户端代码每个 token 触发 React/Vue rerender，主线程被卡

修复：批量合并 token，每 50ms 刷新一次 UI：

let buffer = ''
let flushTimer: NodeJS.Timer | null = null

for await (const event of stream) {
  if (event.type === 'ASSISTANT_DELTA') {
    buffer += event.content
    if (!flushTimer) {
      flushTimer = setTimeout(() => {
        renderText(buffer)
        buffer = ''
        flushTimer = null
      }, 50)
    }
  }
}

---

集成类

Vue 3 + volo-ai-ctrl-kit 元素不可见

症状：注册的元素后端 AI"看不见"

原因：volo-ai-ctrl-kit 渐进式披露——仅暴露视口内可见元素

修复：

• 确认元素在视口内（IntersectionObserver 监测）
• 确认元素未被 display:none / visibility:hidden 隐藏
• useCtrl().getContext() 调试查看实际 elements 列表

---

字幕乱码 / 中文显示问号

原因：响应头 charset 未设置或 client 解析时未指定 UTF-8

修复：

const decoder = new TextDecoder('utf-8')
// 而非 TextDecoder() 默认或 'gbk'

后端响应头已强制 Content-Type: text/event-stream;charset=UTF-8。

---

还没解决？

• FAQ — 看看常见问题
• Contact — 联系支持团队