第二十七节 故障排查与常见问题
27.1 启动相关
- 应用无法启动：先看日志（设置 → 数据 → 打开日志目录；或在卸载并重装后再次尝试）。
- 应用启动后白屏：通常是系统自带网页视图组件版本过旧，参考第二节系统要求升级。
27.2 登录相关
- SSO 浏览器回跳后桌面端没有反应：通常是浏览器代理 / VPN 拦截了本地回调端口，关闭代理后重试。
- 登录后没有可用模型：设置 → 模型 中点「刷新」；或重新登录。
27.3 会话相关
- 会话突然不响应：点击 停止 按钮，再发新消息即可恢复。
- 会话历史似乎被截断：可能触发了历史折叠；点击折叠摘要展开即可看到原文。
- 错误："服务未就绪"：等待 30 秒；持续未恢复请打开 设置 → Hooks → 错误抽屉 查看具体原因。
27.4 工具相关
- 工具调用一直在转圈：通常是后台执行任务被模型调度但未拉取输出；点开任务卡片查看实时日志。
- 某工具被拒绝：检查智能体管理器 →「配置工具」中该工具在当前模式下的权限设置。
- 外部服务连不上：检查接入地址与凭证；查看错误抽屉里服务端原始返回。
27.5 安全分析相关
- 样本扫描返回空结果：默认安装可能未包含完整规则集，请联系内部分发渠道获取完整版本。
- 反编译耗时长：反编译涉及模型调用，复杂样本可能耗时数十秒甚至更久；可以让助手把任务转后台。
27.6 随行通讯相关
- 微信扫码后桌面端没反应：通讯通道初始化最长 30 秒，再次刷新二维码重试。
- 配对码失败：10 分钟过期；重新生成。
- 审批卡片在微信里没出现：检查通道是否还在线（设置中可看连接状态）。
27.7 性能相关
- CPU 占用高：若你启用了多个后台任务，注意并发上限；可在 设置 → Hooks 中查看在跑任务列表。
- 磁盘占用大：通常是会话历史或样本目录大；设置 → 数据 → 数据目录 中可看到具体大小，按需归档旧会话。
27.7.1 模型调用错误的精准提示
服务端返回的各类错误现在能精准归类，提示直接告诉你该怎么办，不再一律给笼统或误导性的信息：
| HTTP | 含义 | 提示 |
|---|---|---|
| 402 | 点数不足 | 「点数不足，前往购券」（购券口径；与账号用量展示、服务端计费一致，不再用「充值 / 重置 / 余额」等不一致表述；不再当成可重试错误反复重试） |
| 429 | 套餐额度用尽 | 「套餐额度已用尽，等配额刷新或升级套餐」（不再误判成限流） |
| 401 / 403 | 鉴权失败 / 需要登录 | 「重新登录或重发 key」（不再让你去查配置） |
| — | 输入超出 token 上限 | 归类为「上下文过长」并如实提示 |
| 503 | 当前模型暂无可用通道 | 「稍后重试或切换模型」 |
| 502 / 529 / overloaded | 上游服务异常 / 繁忙 | 如实说明是上游问题（尤其上游鉴权失败时不再误导你去查自己的 key） |
| 404 | 端点不存在 | 单独分类为 endpoint_not_found_error；提示「检查 Provider Base URL」（与"API JSON 返回的 404 模型不存在"分流） |
未配置模型发送不再卡住：删除了正在使用的模型供应商后直接发送，过去会卡住；现改为在消息流内行内确认，引导你切换到可用模型再发。启动失败时也会复位运行状态，不再一直停在「运行中」。
27.7.2 macOS App Translocation 升级失败
如果你没把应用拖进 应用程序，直接从「下载」或「桌面」双击运行，点检查更新会被 macOS 的 App Translocation 机制锁住（应用被放进只读临时镜像运行）。本版已识别这种「只读位置」并快速失败给出明确引导：
「请退出应用 → 把它拖进『应用程序』文件夹 → 重新打开 → 再检查更新」
其它只读卷 / 受管目录等写盘失败也统一兜底成同样的友好提示。
27.7.2.5 Windows 后台进程稳定性
Windows 上的后台服务（zWorkspace / zMCP）做了系统性根治：
- 进程存活探测改用系统级句柄等待，不再把活着的子进程误判为已退出（mac / Linux 行为不变）。修了"每次重开工作区都启动一个、旧的变成孤儿进程"。
- GUI 程序下子进程 stderr 采集修复，启动失败诊断报告里的「原始错误」恢复有内容，根因判断更准。
- MCP 配置读写不再丢字段：之前在「配置工具」面板里增删 / 启停某个 MCP 后端时，保存可能意外把其它 stdio 后端的启动命令抹掉，导致下次 zMCP 因「缺命令」整个挂掉。
- 单后端故障不再拖垮整体：某个后端结构错误 / 连不上 / 被禁用时，zMCP 仍能起，坏的那个跳过并告警，其余照常可用。
- 后端连接异步化 + 有界重试：电脑重启 / 网络未就绪时，慢 / 不可达后端不再阻塞整个网关启动；后端在后台并发探活、有界次数重试，网络好了自动补连上。修了「重启后某个远程或局域网后端连不上就把整个工具网关拖垮、工具全用不了」。
- 应用退出兜底：用 OS 级进程组绑定，App 崩溃 / 强杀 / 升级时连带清理整棵进程树；子进程侧改用更可靠的父进程退出监听，不再残留孤儿进程。
- zAgent 崩溃日志完整保留：后台对话进程（zAgent）意外崩溃时捕获原生异常并把崩溃前的 stderr 完整保留，不再悄无声息退出（如「退出码 2」这类难查的情况）。日志齐了，疑难问题更快定位。写入人设或向子代理喂送数据遇到管道中断（broken pipe）时，也会上报 zAgent 的真实退出原因，而不是笼统的症状文案。
27.7.2.6 试用 / 授权过期锁界面可直接退出
试用过期 / 授权失效的全屏锁定界面底部常驻「退出应用」按钮 — 此前点关闭只是隐藏到托盘（等于没退出），现在任何状态都能干净退出进程。界面里的官网 / 主页链接为 avlcode.cn。
27.7.3 后台工作区服务启动失败自动诊断
后台工作区服务（zMCP）启动失败时，AVL Code 会在本机自动采集诊断信息（自连端口对比、进程存活探测等），直接在错误抽屉里给出根因结论 + 建议动作，无需任何手动操作。
- 同时落一份诊断报告文件（最多保留最近 20 份）。
- 「未找到 zWorkspace / zAgent 二进制」根因上浮：若启动时定位不到内置的 zWorkspace / zAgent 组件，不再只提示「未找到二进制」，而是把嵌入组件释放失败的真实根因一并上报，并附按平台区分的排查建议。（相关的：内置组件解压上限由 64 MiB 提升到 256 MiB，修复部分 Intel 机型因组件体积增长被安全护栏误拦、释放失败导致启动失败的问题。）
- 全程零操作、不外发数据。
- 这份诊断报告可一键作为「意见反馈」的附件带给我们，加速排查。
27.7.4 在线文档入口
随时需要查文档：
- 侧边栏「帮助」按钮：一键用系统默认浏览器打开 avlcode.cn/docs.html。
- macOS 帮助菜单 → 在线文档：同一目标地址，紧跟在「命令列表」后面。
27.8 日志
应用日志位置可在 设置 → 数据 → 打开日志目录 一键访问，崩溃栈也会同步出现在错误抽屉里，无需打开终端。