故障排查

WesCraft 使用过程中常见问题的排查指南。

Go 后端启动失败

检查日志

WesCraft Go 后端日志位于 XDG 数据目录下：

# macOS
~/Library/Application Support/wescraft/logs/

# Linux
~/.local/share/wescraft/logs/

常见原因

症状	可能原因	解决方案
进程立即退出	配置文件缺失	运行 `wescraft init` 创建默认配置
端口冲突	:3100 被占用	检查端口占用或修改配置
数据目录不可写	权限问题	检查目录权限
Provider 加载失败	API Key 无效	检查 `config.yaml` 中的 Provider 配置

配置文件位置

# 配置目录
$XDG_CONFIG_HOME/wescraft/config.yaml

# 环境变量覆盖
WESCRAFT_DATA_DIR    # 数据目录
WESCRAFT_CONFIG      # 配置文件路径

初始化修复

# 重新初始化配置
wescraft init

# 检查配置是否有效
cat ~/.config/wescraft/config.yaml

FileIntelligence 索引异常

检查关注目录

FileIntelligence 的关注目录列表存储在 per-cell 的 wc_watched_paths 表中：

-- 检查当前 Cell 的关注目录
SELECT * FROM wc_watched_paths WHERE cell_id = 'personal';

索引不更新

检查 fsnotify 事件：确认文件变更事件是否被正确捕获
检查索引 DB：目前索引仍在共享 wescraft.db 中
手动触发重建：通过设置页面的"重建索引"按钮

清理已删除文件的索引

// PruneDeleted() 清理磁盘已删文件的残留索引（修复 R-4）
fileintel.PruneDeleted()

如果索引中出现"幽灵文件"（磁盘已删但索引残留），等待下次自动扫描或手动触发 PruneDeleted()。

路径校验失败

如果出现路径校验错误，可能是符号链接问题（修复 W-1）：

// PathValidator 使用 filepath.EvalSymlinks 解析真实路径
// 使用 os.UserHomeDir() 而非 filepath.Abs("~") 展开 home

macOS 上 /var → /private/var 的符号链接可能导致路径不匹配。

知识管线不工作

检查 Pipeline 触发

知识管线使用 time.AfterFunc + per-pageID timer（修复 R-3），不再使用 go func() { sleep(5s) }：

// 正确的触发方式：每个 pageID 一个 timer，防止 goroutine 爆炸
pipeline.Trigger(pageID)  // 内部使用 time.AfterFunc

查看每 Stage 日志

# 每个 Stage 完成后都有 slog.Info 日志
grep "knowledge.pipeline" ~/Library/Application\ Support/wescraft/logs/*.log

常见问题

阶段	症状	排查
Stage 1 采集	内容未被采集	检查来源连接（扩展/文件/URL）
Stage 3 分块	分块异常	检查文件格式是否支持
Stage 4 索引	搜索无结果	检查 FTS5 索引状态
Stage 5 标签	标签不准	检查 AI 模型连接
Stage 6 关联	无关联	需要足够的内容量

AI 交互无响应

步骤一：检查 Provider 配置

# 测试 Provider 连通性
POST /cells/{cellID}/providers/test
{
  "mode": "chat"  // chat / embedding / vision
}

步骤二：检查 Agent 配置

# 列出已注册的 Agent
GET /cells/{cellID}/agents

步骤三：检查 Cell 状态

确认当前 activeCell 是否正常运行，检查 Cell 温度状态（Hot/Warm/Cool/Cold）。

步骤四：检查模型配置

确认 config.yaml 中的模型声明包含 ContextWindow 字段：

providers:
  - name: my-provider
    type: openai
    models:
      - name: gpt-4o
        context_window: 128000  # 必须声明

浏览器扩展不工作

排查清单

扩展已安装：在浏览器扩展管理页面确认扩展已启用
后端运行中：确认 WesCraft 桌面端正在运行（检查 :3100 端口）
网络连接：确认浏览器能访问 http://localhost:3100
权限授予：确认扩展已获得必要权限
Content Security Policy：某些网站的 CSP 策略可能阻止扩展注入

手动测试

# 检查后端是否可达
curl http://localhost:3100/health

页面删除不彻底

问题描述

删除页面后，子页面和版本记录可能残留（修复 R-1）。

正确的删除流程

// 递归 SoftDeletePage 子页面
// PurgePage 同时删除 wc_page_versions
contentEngine.DeletePage(ctx, pageID)
// 内部递归：
// 1. SoftDeletePage(pageID) — 标记当前页面
// 2. SoftDeletePage(childIDs...) — 递归标记子页面
// 3. PurgePage — 物理删除 + 清理 wc_page_versions

手动清理

如果发现残留数据，可以在设置中使用"数据库维护"功能清理孤儿记录。

搜索结果不全

WesCraft 有三种搜索源，需要分别检查：

搜索源	索引方式	检查方式
FTS5 全文搜索	SQLite FTS5 虚拟表	检查 FTS5 trigger 和索引完整性
FileIntelligence	本地文件索引	检查关注目录和索引更新
语义搜索	Embedding 向量	检查 Embedding Provider 是否配置

重建搜索索引

// per-boot 安全网：RebuildFTS
store.RebuildFTS()

SavePage 错误被静默

问题描述

早期版本中 SyncPageFTS 和 saveVersion 的错误被 _ 忽略（修复 R-2）。

现在的行为

// 错误通过 slog.Warn 输出，不再静默忽略
if err := store.SyncPageFTS(ctx, pageID); err != nil {
    slog.Warn("sync page FTS failed", "page_id", pageID, "error", err)
}
if err := store.saveVersion(ctx, pageID, content); err != nil {
    slog.Warn("save version failed", "page_id", pageID, "error", err)
}

如果在日志中看到这些警告，说明 FTS 同步或版本保存有问题，需要检查数据库状态。

数据迁移问题

INV-MIGRATE-01 机制

WesCraft 使用 MigrationStep 管理 schema 变更：

// internal/store/appdb_migrations.go
// 每步一个事务：DDL + PRAGMA user_version = N + commit
// 步骤编号从 1 开始连续递增

迁移失败的降级策略

1. 迁移步骤失败
2. → 关闭 DB
3. → 归档旧文件为 .migration-failed
4. → 清除 -wal / -shm
5. → 重新打开全新 DB
6. → 再次执行完整迁移链
7. → 第二次失败才返回 fatal error

代价：丢失页面、数据库、采集箱、任务、文件索引等数据。远好过启动崩溃。

手动修复

如果自动迁移失败，可以：

备份 wescraft.db 文件
删除数据库文件
重启 WesCraft（自动创建新库）
从备份中手动恢复需要的数据