故障排查

本指南帮助您解决 IfAI 的常见问题。

快速诊断

如果您遇到问题，请先尝试这些操作：

1. 检查日志：Cmd+Shift+P > "开发者：显示日志"
2. 重启 IfAI：关闭并重新打开应用程序
3. 清除缓存：Cmd+Shift+P > "开发者：清除缓存"
4. 检查版本：Cmd+Shift+P > "IfAI: 检查更新"

安装问题

macOS："App can't be opened because it is from an unidentified developer"

解决方案：

# 移除隔离属性
xattr -cr /Applications/IfAI.app

# 或在系统偏好设置中允许
# 系统偏好设置 > 安全性与隐私 > 通用 > "仍要打开"

Windows："Windows Defender SmartScreen prevented an unrecognized app"

解决方案：

1. 点击"更多信息"
2. 点击"仍要运行"
3. 或暂时禁用 SmartScreen（不推荐）

Linux：AppImage 无法执行

解决方案：

# 使其可执行
chmod +x ifai-*.AppImage

# 运行
./ifai-*.AppImage

如果出现 FUSE 错误，解压 AppImage：

./ifai-*.AppImage --appimage-extract
./squashfs-root/ifai

AI 连接问题

"无法连接到 AI 提供商"

诊断：

1. 在设置（Cmd+,）中检查您的 API 密钥
2. 验证网络连接
3. 检查 API 服务状态

解决方案：

# 测试 API 连接
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

# 对于 Claude
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY"

"超出速率限制"

解决方案：

• 等待几分钟后再重试
• 考虑升级您的 API 计划
• 切换到不同的提供商
• 使用本地 LLM 作为后备

本地 LLM 不工作

症状：

• Ollama 连接失败
• 未找到模型
• 响应缓慢

解决方案：

# 检查 Ollama 是否正在运行
ollama list

# 重启 Ollama
# macOS: brew services restart ollama
# Linux: systemctl restart ollama

# 如果缺失则拉取模型
ollama pull llama3.2

IfAI 设置：

1. 打开设置 > AI 提供商
2. 启用"本地 LLM"
3. 设置 Ollama URL：http://localhost:11434
4. 从下拉列表中选择模型

编辑器问题

文件无法保存

症状：

• 保存无效
• "文件为只读"错误

解决方案：

1. 检查文件权限：

   ls -l path/to/file
   chmod +w path/to/file

2. 检查磁盘空间：

   df -h

3. 如果在 Git 仓库中，检查文件是否被忽略：

   git check-ignore -v path/to/file

语法高亮缺失

解决方案：

1. 检查文件扩展名是否正确
2. 手动设置语言：
   • 在编辑器中右键点击
   • "设置语言" > 选择语言
3. 如果使用不常见的语言，可能尚不支持

编辑器冻结或崩溃

诊断：

1. 检查文件大小（大于 10MB 的文件可能导致问题）
2. 检查内存使用：活动监视器 / 任务管理器
3. 检查日志中的错误

解决方案：

• 大文件：IfAI 最优处理高达 10MB 的文件
• 内存：关闭其他应用程序
• 扩展：禁用任何第三方扩展

性能问题

启动缓慢

可能原因：

• 包含许多文件的大型工作区
• 符号索引正在进行中
• 杀毒软件扫描

解决方案：

1. 等待初始索引完成
2. 从杀毒软件中排除项目目录
3. 减少工作区大小

AI 响应缓慢

诊断：

1. 在 AI 聊天面板中检查响应时间
2. 检查网络速度
3. 检查令牌数量

解决方案：

• 云端 API：检查提供商状态页面
• 本地 LLM：使用更小的模型（例如 qwen2.5-coder:3b）
• 减少上下文：清除聊天历史
• 切换提供商：尝试替代 API

内存使用量高

正常使用：

• 空闲：~200MB
• 编辑小型项目：~500MB
• 大型项目：1-2GB

如果过高：

1. 重启 IfAI
2. 清除缓存：Cmd+Shift+P > "开发者：清除缓存"
3. 关闭未使用的文件
4. 限制符号索引范围

Git 集成问题

Git 命令不工作

症状：

• Git 状态不显示任何内容
• 提交/推送按钮被禁用

解决方案：

1. 检查是否安装了 Git：

   git --version

2. 检查 IfAI 是否有 Git 路径设置

3. 如需要初始化仓库：

   git init

合并冲突

解决方案：

IfAI 将在文件树中显示冲突文件。使用 AI 帮助解决：

帮助我解决 src/auth.ts 中的这些合并冲突

或手动解决：

1. 打开冲突文件
2. 查找 <<<<<<<、=======、>>>>>>> 标记
3. 编辑以解决
4. 标记为已解决：git add path/to/file

终端问题

终端无响应

解决方案：

1. 重启终端：Ctrl+ ` 然后关闭/重新打开

2. 终止卡住的进程：

   # 查找进程
   ps aux | grep process_name
   
   # 终止它
   kill -9 PID

3. 重置终端设置：

   • 终端 > 重置（从下拉菜单）

PATH 未找到

症状：

• 命令未找到错误
• 工具不可用

解决方案：

1. 检查 shell 配置文件：

   echo $PATH
   cat ~/.zshrc  # 或 ~/.bashrc

2. 重新加载 shell：

   source ~/.zshrc

3. 在 IfAI 设置中更新 PATH：

   • 设置 > 终端 > Shell PATH

符号索引问题

"未找到符号"错误

解决方案：

1. 等待索引完成（检查状态栏）
2. 重新索引项目：
   • Cmd+Shift+P > "IfAI: 重新索引项目"
3. 检查语言是否支持
4. 验证文件没有语法错误

索引卡住

诊断：

1. 检查状态栏中的进度
2. 检查日志中的错误

解决方案：

1. 重启 IfAI
2. 清除索引缓存：
   • Cmd+Shift+P > "开发者：清除索引缓存"
3. 排除大型/生成的目录：
   • 设置 > 项目 > 索引排除

错误消息

"发生未知错误"

操作：

1. 检查日志：Cmd+Shift+P > "开发者：显示日志"
2. 记下错误详细信息
3. 在 GitHub 上报告

"加载扩展失败"

解决方案：

1. 检查扩展与当前 IfAI 版本的兼容性
2. 禁用扩展：
   • 设置 > 扩展 > 切换关闭
3. 更新扩展或 IfAI

获取更多帮助

如果这些解决方案都不起作用：

1. 检查现有问题

GitHub Issues - 可能有人已经报告了

2. 收集调试信息

运行诊断：

# IfAI 版本
Cmd+Shift+P > "IfAI: 显示版本信息"

# 系统信息
Cmd+Shift+P > "IfAI: 显示系统信息"

3. 报告问题

报告时，请包括：

• IfAI 版本
• 操作系统和版本
• 重现步骤
• 预期与实际行为
• 相关日志（编辑敏感信息）
• 如适用的屏幕截图

4. 社区资源

• GitHub 讨论

紧急恢复

重置所有设置

如果 IfAI 完全损坏：

# macOS
rm -rf ~/Library/Application\ Support/IfAI

# Windows
rm -rf %APPDATA%\IfAI

# Linux
rm -rf ~/.config/IfAI

警告：这将删除您的所有设置和偏好。

重置前导出设置

# 设置 > 导出设置
# 保存导出的文件
# 然后如需要则重置

---

仍有问题？在 GitHub 上打开问题