故障排查

当你在使用 WesCraft 时遇到问题，本文档可以帮助你诊断和解决。我们按照常见问题类别组织内容，包括常见错误、索引问题、同步问题、性能问题，以及日志查看和重置方法。

常见错误

AI 模型连接失败

症状：AI 功能无法使用，提示「模型服务不可用」或「连接超时」。

排查步骤：

1. 检查 API Key：进入 设置 → AI 模型，确认 API Key 已正确填入
2. 测试连接：点击 测试连接 按钮，查看具体错误信息
3. 检查网络：确认你的网络能访问 AI 提供商的 API 地址
4. 检查代理：如果使用网络代理，确认代理设置正确
5. 检查余额：对于按量付费的 API，确认账户余额充足

常见错误码：

页面无法保存

症状：编辑内容后，页面显示保存失败或内容丢失。

排查步骤：

1. 检查磁盘空间：确认数据目录所在磁盘有足够空间
2. 检查文件权限：确认 WesCraft 对数据目录有写入权限
3. 检查数据库状态：查看日志中是否有 SQLite 相关错误
4. 尝试重启：关闭并重新打开 WesCraft

临时措施：如果页面无法保存，可以先将内容复制到剪贴板，重启后再粘贴回来。

应用无法启动

症状：WesCraft 打开后白屏、闪退或卡在加载界面。

排查步骤：

1. 清除缓存启动：

   • macOS：按住 Option 键启动 WesCraft
   • Windows：在启动快捷方式中添加 --clear-cache 参数
   • Linux：运行 wescraft --clear-cache

2. 检查日志：查看 $DATA_DIR/logs/ 下的错误日志

3. 检查系统资源：确认系统内存和 CPU 不超载

4. 重新安装：如果以上方法无效，尝试卸载后重新安装（数据不会丢失，除非手动删除数据目录）

浏览器扩展不工作

症状：浏览器扩展无法剪藏内容到收集箱。

排查步骤：

1. 确认 WesCraft 桌面应用正在运行
2. 检查扩展是否已启用（浏览器扩展管理页面）
3. 尝试重新安装浏览器扩展
4. 检查是否有其他扩展冲突

索引问题

文件索引不更新

症状：新增或修改的文件在搜索中找不到。

排查步骤：

1. 检查索引状态：在 文件 页面查看关注目录的索引状态

   • 🟢 已就绪 — 正常
   • 🟡 索引中 — 正在处理，请等待
   • 🔴 异常 — 点击查看错误详情

2. 确认文件在关注目录内：文件必须在已添加的关注目录下才会被索引

3. 检查排除规则：确认文件没有被排除规则过滤掉

4. 手动触发重建：在关注目录设置中，点击 重建索引

5. 检查文件类型：确认文件类型在支持列表中（参见文件智能）

索引占用过多磁盘空间

症状：数据目录体积异常增大。

解决方法：

1. 在 设置 → 数据管理 中查看各类数据的空间占用
2. 移除不再需要的关注目录
3. 调整索引深度：关闭语义索引可显著减少空间占用
4. 清理旧的索引缓存：设置 → 数据管理 → 清理索引缓存

搜索结果不准确

症状：搜索返回不相关的结果，或遗漏了应该匹配的内容。

解决方法：

1. 等待索引完成：新内容需要索引完成后才能准确搜索
2. 重建索引：如果索引损坏，尝试重建
3. 使用精确搜索：用引号 "精确短语" 限定匹配
4. 检查搜索范围：确认搜索范围设置正确

同步问题

数据一致性

症状：不同功能之间的数据不一致（如侧边栏显示的页面列表与搜索结果不同）。

解决方法：

1. 刷新界面：按 Ctrl/Cmd + Shift + R 强制刷新
2. 重启应用：关闭并重新打开 WesCraft
3. 检查数据库：在日志中查看是否有数据库错误

多窗口数据冲突

症状：在多个窗口中编辑同一页面时出现冲突。

说明：WesCraft 目前不支持多窗口同时编辑同一页面。如果需要同时查看多个页面，请使用 Tab 系统而非多窗口。

解决方法：

1. 只在一个窗口中编辑
2. 如果出现冲突，以最后保存的版本为准
3. 使用页面版本历史恢复之前的版本

外部文件变更未反映

症状：在其他应用中修改了关注目录中的文件，WesCraft 未更新索引。

解决方法：

1. 等待几秒——文件系统监控有短暂延迟
2. 手动触发扫描：在文件页面点击 刷新
3. 检查文件系统监控是否正常（查看日志）

性能问题

编辑卡顿

症状：输入文字有明显延迟，编辑器响应缓慢。

排查与解决：

1. 减少页面长度：将超长页面拆分为多个子页面（建议每页不超过 500 个块）
2. 关闭 Ghost Write：暂时关闭 AI 续写功能减少计算开销
3. 检查后台任务：查看是否有后台 AI 任务占用资源
4. 清理内存：关闭不需要的 Tab
5. 重启应用：长时间运行后重启释放内存

启动缓慢

症状：WesCraft 启动时间过长。

排查与解决：

1. 减少启动项：关闭不需要的启动时自动打开的页面
2. 清理数据：清理回收站中的过期页面
3. 检查索引：大量关注目录会增加启动时间
4. 更新版本：确保使用最新版本的 WesCraft

内存占用高

症状：WesCraft 占用过多系统内存。

排查与解决：

AI 响应慢

症状：AI 功能响应时间长。

排查与解决：

1. 检查网络：AI 功能依赖网络连接（本地模型除外）
2. 切换模型：小型模型响应更快（如 DeepSeek 等）
3. 减少上下文：长页面的 AI 操作可能较慢
4. 检查 API 状态：查看 AI 提供商是否有服务降级

日志查看

日志文件位置

WesCraft 的日志文件位于数据目录下：

日志文件类型

查看日志

方法一：应用内查看

1. 打开 设置 → 关于 → 查看日志
2. 选择日志类型
3. 查看最近的日志条目
4. 可按级别筛选（INFO / WARNING / ERROR）

方法二：直接打开文件

1. 打开 设置 → 关于 → 打开数据目录
2. 进入 logs/ 子目录
3. 用文本编辑器打开日志文件

日志级别

报告问题

如果需要报告 bug，请附上相关日志：

1. 在 设置 → 关于 → 导出诊断信息
2. 系统会生成一个包含脱敏日志的压缩包
3. 将压缩包发送给技术支持
4. 诊断信息不包含你的页面内容和个人数据

重置方法

重置设置

恢复所有设置为默认值：

1. 打开 设置 → 通用 → 重置设置
2. 确认操作
3. 重启 WesCraft

注意：这只重置设置，不影响你的页面和数据。

重置 AI 记忆

清除 AI 学习到的偏好和记忆：

1. 打开 设置 → AI → 清除记忆
2. 选择要清除的范围：
   • 全部记忆
   • 仅环境信息
   • 仅个人偏好
   • 仅角色记忆
3. 确认操作

重建索引

重建全文搜索和语义索引：

1. 打开 设置 → 数据管理 → 重建索引
2. 选择范围：
   • 页面索引
   • 文件索引
   • 全部索引
3. 确认并等待重建完成（可能需要几分钟到几小时，取决于数据量）

清除缓存

清除应用缓存数据：

1. 打开 设置 → 数据管理 → 清除缓存
2. 选择要清除的缓存类型：
   • 渲染缓存
   • 搜索缓存
   • AI 缓存
   • 全部缓存
3. 确认操作

完全重置（数据保留）

重置应用状态但保留所有数据：

1. 关闭 WesCraft
2. 删除数据目录中的以下文件：
   • config.yaml（设置文件）
   • cache/（缓存目录）
3. 重新启动 WesCraft
4. 完成首次配置向导

完全重置（数据清除）

⚠️ 警告：此操作将删除所有数据，包括页面、收集箱、索引和设置。不可恢复。

1. 关闭 WesCraft
2. 删除整个数据目录：
   • macOS：rm -rf ~/Library/Application\ Support/wescraft/
   • Linux：rm -rf ~/.local/share/wescraft/
   • Windows：删除 %APPDATA%\wescraft\ 目录
3. 重新启动 WesCraft
4. 从零开始配置

数据备份与恢复

在执行任何重置操作前，建议先备份数据：

1. 打开 设置 → 数据管理 → 备份
2. 选择备份位置
3. 等待备份完成

恢复数据：

1. 打开 设置 → 数据管理 → 恢复
2. 选择备份文件
3. 确认恢复

获取帮助

如果以上方法无法解决你的问题：

• 社区论坛：在 weisyn 社区发帖求助
• GitHub Issues：报告 bug 或功能建议
• 邮箱支持：发送问题描述和诊断信息到 wx@wesing.xyz

提供以下信息有助于更快解决问题：

• WesCraft 版本号（设置 → 关于 中查看）
• 操作系统版本
• 问题的详细描述和复现步骤
• 相关日志（使用 导出诊断信息 功能）

相关文档

• 快速开始 — 安装和初始配置
• 文件智能 — 文件索引的详细说明
• 快捷键 — 快捷键参考