故障排查

wescode 常见问题的诊断与解决方法。

Go 后端启动失败

症状

Chat 面板显示「后端未就绪」或状态栏显示「AI 未就绪」。

诊断步骤

1. 查看 Go 后端日志

macOS: ~/Library/Application Support/wescode/logs/wescode.log
Linux: ~/.local/share/wescode/logs/wescode.log

2. 检查引擎版本

正常启动日志应包含引擎版本：

boot: engine version  sdk_version=v1.0.x

如果没有这行，说明引擎未成功初始化。

3. 检查 DB 迁移

wescode-app.db 迁移失败时的降级策略（INV-RESIL-01）：

迁移失败 → 关闭 DB → 归档旧文件为 .migration-failed
  → 重新打开全新 DB → 再次迁移 → 第二次失败才返回 fatal error

归档文件位于数据目录中：

ls ~/Library/Application\ Support/wescode/cells/ws-*/wescode-app.db*
# 查看是否有 .migration-failed 后缀的归档文件

解决方案

• 删除 wescode-app.db，重启 wescode（开发阶段 DEV-1：清库重建）
• 检查磁盘空间
• 确认 Go 后端二进制存在且可执行

CKG 索引不更新

症状

调用图为空、代码搜索无结果、项目概览面板无数据。

诊断步骤

1. 检查索引进度

状态栏的索引进度条（indexProgressBar.ts）应显示进度。如果不显示：

• 确认已打开工作区（无工作区 = 无 Cell = 无索引）
• 检查 Go 后端是否正常运行

2. 检查 code.db 版本

CKG 索引使用 PRAGMA user_version 管理 schema 版本：

code.db 版本不匹配
  → 自动 wipe-rebuild（删除旧 DB + 重建）
  → 索引重新开始

3. 强制重建索引

状态栏 → 索引进度条 → 右键 → 重建索引

或者手动删除索引文件：

rm -rf ~/Library/Application\ Support/wescode/cells/ws-*/index/code.db
# 重启 wescode

Chat 发送后无响应

症状

点击发送按钮后无反应，或显示「该工作区已有生成任务进行中」。

原因

chatInFlight 锁未正确释放（INV-WS-11）。

诊断步骤

1. 检查是否有未完成的 Run

如果之前的 Run 未正确结束（没有发出 done/error/interrupted 终端事件），锁会一直持有。

2. 锁释放机制

chatInFlight 锁的生命周期 = 用户可见生成轮次
  → done 事件到达 → 释放锁（_dispatchNotification, requestId 匹配）
  → error 事件到达 → 释放锁
  → interrupted 事件到达 → 释放锁

解决方案

• 开新对话（开新 session 不受旧锁影响）
• 重启 wescode 窗口
• 检查 Go 后端日志是否有 missing_terminal_event 错误

多窗口冲突

症状

同一 workspace 打开多个窗口后出现异常行为。

工作原理（INV-WS-08）

窗口 A 打开 /project → 启动 Go 进程 #1
窗口 B 打开 /project → 复用 Go 进程 #1（引用计数 +1）
窗口 A 关闭         → 引用计数 -1（进程仍在）
窗口 B 关闭         → 引用计数 → 0 → shutdown Go 进程

注意事项

• 同一 workspace 最多一个 Chat Run（chatInFlight 锁）
• Go→TS 通知不跨窗口广播（INV-WS-06）
• chat/stream 按 JSON-RPC request id 路由到发起窗口

Buffer Overlay 不生效

症状

AI 的 read 工具读到的是磁盘文件而非编辑器中的最新内容。

原因

macOS 下 /var → /private/var 符号链接导致路径不匹配。

修复（已内置）

// normalizePath 使用 filepath.EvalSymlinks 解析真实路径
func (bs *BufferStore) normalizePath(p string) string {
    resolved, err := filepath.EvalSymlinks(p)
    if err == nil {
        p = resolved
    }
    return filepath.Abs(p)
}

如果仍然不生效：

• 检查文件是否超过 1MB（大文件不同步）
• 确认 WescodeBufferSync 扩展已启用
• 检查 editor/didSave 事件是否正常触发

AI 编辑后 tab 显示未保存 dot

症状

AI 修改文件后，tab 标题显示未保存的圆点 (●)。

原因

Buffer 内容与磁盘不一致（INV-EDIT-01 revert 同步失败）。

正确行为

edit.applied 后：
  → textFileService.revert(uri)
  → 原子完成：读磁盘 + 更新 buffer + 清 dirty flag
  → tab 无 dot ✅

解决方案

• 确认 InlineDiffController.confirmDiff() 正常执行
• Cmd+S 手动保存
• 检查文件权限（磁盘不可写会导致 revert 失败）

Provider 连接失败

症状

Chat 发送后报错「模型服务不可用」或「连接失败」。

诊断步骤

1. 连通性测试

POST /cells/{cellID}/providers/test
{
  "provider": "my-openai",
  "model": "gpt-4o",
  "mode": "chat"
}

测试模式：chat（基础）/ embedding（向量化）/ vision（图像理解）。

2. 检查 catalog.yaml

模型市场数据来自 weisyn.ProviderCatalog()。如果模型不在 catalog 中，引擎不猜测上下文窗口，可能触发 context_length_exceeded。

3. 检查 SecretRef

确认 API Key 正确存储：

• inline：检查 spec.key 文件是否存在
• env：检查环境变量是否设置
• live（WES/Org）：检查 JWT 是否过期

4. WES 模型特殊检查

WES 模型需要登录 weisyn 平台：

• 确认已登录且 JWT 未过期
• 检查账户余额（欠费 → WES 路径失效）

Go→TS 通知丢失

症状

功能「悄悄什么都不做」——Go 后端发了通知但前端没反应。

原因（INV-WS-12）

Go 能发的通知方法名是封闭集合，TS 侧的 _dispatchNotification 是 switch + assertNever。如果两者不一致：

Go 新增 Method → tsgen.go 生成 TS 联合类型
  → TS switch 未新增 case → tsc 编译报错

诊断步骤

# 检查生成的通知类型是否最新
cd backend && go test ./internal/notify
# TestGeneratedTypeScriptIsCurrent 断言生成物与 method.go 逐字相等

WES 欠费状态下的行为

行为规则（INV-CHAT-02/04）

状态栏指示

aiStatusBar.ts 在欠费时显示黄色「WES 欠费」标记：

_wesStatus === 'debt' → $(warning) WES 欠费

保留 60s timer + provider/visibility/引擎恢复时重探。

日志路径速查

Linux 替换为 ~/.local/share/wescode/。环境变量 WESCODE_DATA_DIR 可覆盖。