文档 / 参考
故障排除
出现问题时该怎么办：启动、索引、AI、Claude Code、Git、数据库和构建。
首先，有两个工具任何时候都能帮上忙：
- 帮助 → 错误日志… 显示 IDE 最近的错误。
- 帮助 → 报告问题… 会生成一个
.zip，包含诊断所需的信息，但不含你的代码和对话。复制摘要 可得到可直接粘贴的文本。
问问智能体“哪里出问题了？”。它会通过 yuli_health 一次性检查问题、运行、测试、终端和 Yuli 的日志。
安装与启动
| 症状 |
处理方法 |
| 运行安装程序时 Windows 发出警告 |
确认你是从官方渠道下载的，并且证书发布者为“Yuli Code”。 |
| Linux 上 AppImage 无法打开 |
使用 chmod +x 为其添加执行权限。 |
| 便携版首次启动较慢 |
这是正常的：每个版本只需解压一次应用。之后即可秒开。 |
| 界面显示为其他语言 |
全局选项 → 外观 → 语言。参见语言。 |
| 想分析启动为何较慢 |
帮助 → 启动性能…。 |
索引与代码智能
| 症状 |
处理方法 |
| 缺少引用或导航不完整 |
等待索引完成（编辑器顶部的进度条）。 |
| Lombok 或依赖无法解析 |
项目可能处于受限模式。全局选项 → 安全 → 受信任的项目 → 信任。 |
| 出现“{language} 没有语言服务器”提示 |
点击 安装… 并授权下载。 |
| 索引似乎已过时 |
工具 → 清除缓存… 会删除索引和已保存的状态；Yuli 会重新生成它们。 |
| 缺少 JDK、Maven 或 Gradle |
Yuli 会提供下载。在 项目 → 构建、运行和调试… 中进行配置。 |
AI 没有响应
| 症状 |
处理方法 |
| Platform 模式下出现认证错误 |
在模型配置中检查 API key，然后点击 测试连接。 |
| 本地模型没有响应 |
确认服务器正在运行，并且 服务器 URL 正确。 |
| 提供商服务中断 |
Yuli 会遵循提供商的 retry-after。请等待或更换提供商。 |
| 后台任务停止了 |
已达到令牌或成本上限：提高限制并恢复。 |
| 智能体团队暂停了 |
已达到预算上限。在 更多操作 → 智能体团队 中提高预算。 |
Claude Code、Kiro、Codex 和 Antigravity
| 症状 |
处理方法 |
| Yuli 找不到智能体 |
使用其官方安装程序安装，然后点击 重新检测。 |
| “等待 Claude Code 使用 Yuli 的工具” |
批准 yuli 服务器，或点击 立即批准。用 /mcp 检查。 |
/mcp 显示 yuli 出错 |
在 Yuli 中打开该项目：工具只有在 Yuli 打开时才能工作。yuli_status 会说明原因。 |
| 规则没有变化 |
规则在会话启动时加载：从智能体栏重启会话。 |
| Codex 提示缺少适配器 |
安装 codex-acp：npm install -g @openai/codex @agentclientprotocol/codex-acp。 |
| Kiro 要求更新 |
Yuli 需要 Kiro CLI 1.28.2 或更高版本。 |
| 不希望 Yuli 阻止任何操作 |
关闭 强制执行规则（“仅提醒”）。Git 和机密始终受到保护。 |
智能体没有执行某项操作
| 症状 |
原因 |
处理方法 |
| 不提交也不推送 |
只有明确提出请求才会启用 Git。 |
直接提出：“提交并推送”。逐个批准每个操作。 |
| 不创建分支 |
分支需要单独提出。 |
明确要求创建分支。 |
| 不读取某个文件 |
这是机密文件（.env、密钥、凭据）。 |
这是有意为之。请在不包含机密的情况下提供所需数据。 |
| 无法在项目外写入 |
沙箱将其限制在项目内。 |
项目 → 文件夹访问… |
| 不在数据库中执行语句 |
该连接没有针对该类语句的超级权限。 |
调整该连接的 智能体访问。 |
| 不进入测试阶段 |
度量尚未完成，或要求继续迭代。 |
查看质量面板中的 度量 标签页。 |
| 不结束本轮 |
验证尚未通过。 |
在运行、测试或问题中查看失败原因。 |
Git
| 症状 |
处理方法 |
| 某个操作耗时过长 |
超时后会出现 重试。 |
| 内部服务器出现证书错误 |
勾选信任其证书；Yuli 会按服务器记住该决定。 |
| 因 gate 无法提交 |
查看未通过的检查（机密、测试完整性、规模、受保护的路径）。修正它，或申请一个带到期日的豁免。 |
| Yuli 的 hooks 没有安装 |
core.hooksPath 中已有其他工具（例如 husky）。Yuli 不会替换它。 |
数据库
| 症状 |
处理方法 |
| “连接 Oracle 需要安装 Oracle Instant Client” |
安装 Instant Client 19c 或更高版本，并将其添加到 PATH。 |
| 证书错误 |
在连接中勾选 信任服务器证书。 |
| 智能体看不到某个连接 |
其访问权限为 无访问。 |
| 智能体的查询被中断 |
超过了 45 秒，或其执行计划预计扫描量过大。请缩小查询范围。 |
容器
| 症状 |
处理方法 |
| “Docker 不可用。” |
启动 Docker，然后点击 重试。 |
| “kubectl 未配置” |
安装 kubectl 并配置一个上下文（kubeconfig）。 |
仍然无法解决
- 帮助 → 报告问题…
- 描述你当时在做什么，以及你期望的结果。
- 在 GitHub 上分享
.zip 或摘要。