常见错误提示
AI 请求失败或网络波动时，聊天页会先显示「正在重试 N/6」的气泡，气泡首行标注本次重试的原因；重试耗尽仍失败时，错误会以红色气泡展示。本文说明这些提示的分类含义与排查思路。
重试提示分类
请求中途断线或服务端暂时异常时，Muse 会自动重试（最多 6 次、指数退避）。每次重试前气泡会先显示失败原因：
| 气泡提示 | 触发条件 | 可能原因与排查 |
|---|---|---|
| 速率限制 (429) | 服务端返回 429 | 请求过于频繁，或套餐额度将尽。稍候自动重试即可；频繁出现请到供应商后台查看用量 |
| 服务器负载过高 (503) | 服务端返回 503 | 模型服务或中转站负载过高，属临时故障，等待自动重试即可 |
| 服务端错误 (5xx) | 服务端返回 500 / 502 / 504 等 | 服务端异常或网关问题，与你的配置无关，稍后重试 |
| 连接超时 | 建立连接或等待响应超时 | 网络较慢、服务无响应，或中转站响应慢。检查网络，必要时更换网络或节点 |
| 连接被拒绝 | 目标端口没有服务在监听 | 供应商 Base URL 填错（域名 / IP 或端口不对），或服务未启动，到「设置 → AI 供应商」核对 |
| DNS 解析失败 | 域名解析失败 | 网络未连通，或自定义 Base URL 的域名拼写错误 |
| 连接中断 | 连接建立后被断开、流被中断 | 网络抖动、代理不稳定或服务端主动断开。自动重试即可；反复出现请检查网络与代理设置 |
| SSL 握手失败 | TLS 证书校验失败 | 自定义 Base URL 时确认协议（https）与证书正确，或服务端证书异常 |
| 网络连接断开 | 其它网络层故障 | 移动网络切换、弱网环境，检查网络后手动重试 |
| 网络异常 | 无法归类的错误 | 查看具体错误文本，仍无法解决时可附日志反馈 |
常见 HTTP 错误码
请求失败时，重试气泡和最终错误气泡会附上 HTTP 状态码。常见状态码含义如下：
| 状态码 | 含义 | 可能原因 |
|---|---|---|
| 401 | 鉴权失败 | API Key 错误、已过期或被吊销，到「设置 → AI 供应商」检查密钥 |
| 403 | 权限不足 | 密钥没有该模型或接口的权限、地域限制、余额为 0 |
| 404 | 接口不存在 | 自定义 Base URL 路径填错（如漏了 /v1），到供应商设置核对 |
| 429 | 速率限制 | 请求过于频繁或额度用尽，稍候重试或升级套餐 |
| 500 | 服务端内部错误 | 服务端临时故障，与配置无关 |
| 502 | 网关错误 | 中转站上游不可用 |
| 503 | 服务过载 | 服务端负载过高，稍候重试 |
| 504 | 网关超时 | 上游响应超时 |
工具返回的错误码
AI 调用工具失败时，聊天里的工具卡片会显示失败原因，其中一部分带固定错误码。与文件编辑相关的几个如下：
| 错误码 | 含义 | 怎么处理 |
|---|---|---|
STALE_FILE | 要改的文件已被其他会话或用户改过，AI 手上的内容已过期，本次修改没有写入 | 不用管，AI 会重新读取该文件后重做。若反复出现，说明确实有另一个会话在同时改这个文件，建议先停掉其中一个 |
FILE_NOT_FOUND | 目标文件不存在 | 确认路径；AI 通常会改用 writeFile 新建 |
NO_MATCH | editFile 要替换的原文在文件里找不到 | 文件内容与 AI 的预期不一致，AI 会重读后重试 |
MULTIPLE_MATCHES | 要替换的原文在文件中出现多次，无法确定改哪一处 | AI 会补充更多上下文后重试 |
FILE_EXISTS | 写入时目标已存在且不允许覆盖 | 正常保护行为，AI 会改用 editFile 局部修改 |
多会话同时改同一个文件
Muse 支持多个会话（含子代理）并行工作。两个会话同时修改同一个文件时，如果放任不管，后写入的一方会静默覆盖前一方的改动，且双方都以为成功了。
为避免这种情况，Muse 做了三层保护：
- 同时刻：同一文件的写入会被串行化，不会出现两个会话交错写同一个文件。
- 跨时刻：AI 写完文件会记住版本；下次再改同一文件前会先比对，若期间文件已被改过就拒绝写入并提示重新读取（即上面的
STALE_FILE）。 - 原子写：写文件时先写临时文件再整体替换，因此并发读取不会读到"写了一半"的内容，写入中途失败也不会留下半个文件。
你通常不需要干预。需要留意的是：你自己在编辑器里改完文件后，AI 的写入也可能被判为过期——这是预期行为，它会重新读取后再改，不会覆盖你的修改。反过来，若 AI 刚改过某文件而你在编辑器里保存，编辑器会提示冲突，让你选择覆盖还是放弃自己的修改。
撤销代码时的表现
「撤销到某个检查点」会尽量还原当时的文件内容，但不会覆盖它不认识的改动：
- 文件在检查点之后被其他会话改过 → 该文件被跳过，并在提示里列出，改动保留。
- 文件是当前会话自己改的 → 照常还原（这正是撤销的用途）。
已知局限：如果某个文件是这次对话中新建的，撤销时一律删除它，即使期间别的会话往里写过内容。删除前无法可靠判断，因此撤销这类文件时请留意提示。
想减少冲突
让并行的会话尽量负责不同的文件。若两个会话确实要长期改同一批文件，建议错开执行，而不是同时跑。
与多 Key 切换的关系
「设置 → AI 供应商」开启多 Key 后，只有密钥本身有问题的错误（鉴权失败、权限不足、限流、余额用尽）才会消耗失败计数并触发 Key 切换；服务器 5xx、请求超时、网络不可达等错误换 Key 也无法解决，因此不会误切换。未开启多 Key 时，限流（429）没有可切换的密钥，会像其它瞬时故障一样退避重试。详见 AI 供应商与模型 → 多 Key。