工作区管理

wescode 采用 1 workspace = 1 Cell 的物理隔离架构。每个 VS Code 工作区对应一个独立的 wesgine Cell，CKG 索引、记忆、技能、知识库等数据完全隔离。本文档介绍工作区管理的各项功能。

多工作区

架构模型

wescode 进程模型：
├── VS Code 窗口 1 (项目 A)
│   └── Go 后端进程 → Cell "ws-a1b2c3d4"
│       ├── CKG 索引
│       ├── 记忆数据
│       ├── 技能集
│       └── 会话历史
│
├── VS Code 窗口 2 (项目 B)
│   └── Go 后端进程 → Cell "ws-e5f6g7h8"
│       ├── CKG 索引
│       ├── 记忆数据
│       ├── 技能集
│       └── 会话历史
│
└── 无工作区窗口
    └── Config Mode（仅支持设置操作）

Cell ID 映射

Cell ID 由工作区路径确定性派生：

workspace 路径 → SHA256 → 前 4 字节 → "ws-" 前缀
例如：/Users/dev/myproject → ws-a1b2c3d4

这意味着：

同一路径的工作区始终映射到同一个 Cell
不同路径的工作区完全隔离
重新打开同一项目自动恢复所有上下文

多窗口同工作区

当多个 VS Code 窗口打开同一个工作区时：

共享同一个 Go 后端进程和 Cell
同一时刻最多一个 Chat 对话在运行
如果已有对话运行，新窗口的发送会被拒绝
Cancel 仅作用于发起窗口

无工作区状态

未打开文件夹时进入 Config Mode：

不创建任何 Cell
仅支持认证、Provider 配置、设置等操作
Chat 面板显示引导信息，提示打开文件夹
CKG、记忆、技能等功能不可用

配置隔离

数据目录结构

每个工作区的数据独立存储：

~/Library/Application Support/wescode/     # macOS
├── hypervisor.db                          # Cell 注册表（全局）
├── db/wescode_auth.db                     # 登录凭证（跨工作区共享）
├── cells/
│   ├── ws-a1b2c3d4/                       # 项目 A 的 Cell
│   │   ├── meta.db                        # Cell 元数据
│   │   ├── sessions.db                    # 会话和记忆
│   │   ├── state.db                       # 运行时状态
│   │   ├── index/                         # CKG 索引
│   │   ├── knowledge/                     # 知识库
│   │   ├── skills/                        # 技能包
│   │   └── wescode-app.db                # 应用数据
│   │
│   └── ws-e5f6g7h8/                       # 项目 B 的 Cell
│       └── (同上结构)
│
├── logs/wescode.log                       # Go 后端日志
└── crashes/                               # 崩溃日志

配置层级

wescode 的配置分为三个层级：

层级	存储位置	作用范围
全局配置	`~/.config/wescode/config.yaml`	所有工作区
工作区配置	`.wescode/` 项目目录	当前工作区
会话配置	Cell 数据库	当前对话

优先级：会话配置 > 工作区配置 > 全局配置

工作区配置示例

# .wescode/config.yaml（项目级配置）
provider:
  default: "anthropic"
  model: "claude-sonnet-4-20250514"

ckg:
  exclude:
    - "vendor/"
    - "node_modules/"
    - ".git/"

review:
  rules-file: ".wescode/review.yaml"

test:
  framework: "testify"
  coverage-target: 80

数据迁移

跨机器迁移

将工作区数据迁移到新机器：

# 导出工作区数据
wescode export-workspace --cell ws-a1b2c3d4 --output backup.tar.gz

# 在新机器上导入
wescode import-workspace --input backup.tar.gz

导出内容包括：

会话历史和记忆
CKG 索引（可选，也可在新机器重建）
知识库文件
已安装的技能
工作区配置

版本升级迁移

wescode 升级时自动处理数据迁移：

检测版本：启动时检查数据目录版本
自动迁移：执行必要的数据库 Schema 迁移
降级保护：迁移失败时归档旧数据，创建全新数据库

# 手动触发迁移检查
wescode migrate --check

# 执行迁移
wescode migrate --execute

# 查看迁移历史
wescode migrate --history

数据备份

# 备份所有工作区数据
wescode backup --all --output ~/wescode-backup/

# 备份指定工作区
wescode backup --cell ws-a1b2c3d4 --output ~/wescode-backup/

# 从备份恢复
wescode restore --input ~/wescode-backup/ws-a1b2c3d4.tar.gz

索引管理

CKG 索引状态

在状态栏查看当前工作区的索引状态：

索引中 ⏳：正在构建索引，显示进度百分比
就绪 ✅：索引完成，所有功能可用
部分就绪 ⚠️：部分文件索引失败
无索引 ❌：未开始或无工作区

索引操作

# 查看索引状态
/ckg status

# 输出示例：
CKG 索引状态：
  工作区：/Users/dev/myproject
  Cell ID：ws-a1b2c3d4
  状态：就绪 ✅
  索引文件：2,847
  符号数量：15,230
  调用边：42,156
  索引大小：128 MB
  最后更新：2 分钟前

# 重建索引
/ckg rebuild

# 重建指定目录的索引
/ckg rebuild internal/service/

# 清除并重建全部索引
/ckg rebuild --full

索引配置

# .wescode/ckg.yaml
ckg:
  # 排除目录
  exclude:
    - "vendor/"
    - "node_modules/"
    - "dist/"
    - "*.generated.go"
    - "testdata/"

  # 最大索引文件数
  max-files: 50000

  # 最大单文件大小
  max-file-size: "1MB"

  # 增量更新间隔
  incremental-interval: "2s"

  # 索引并行度
  workers: 4

索引诊断

# 运行索引诊断
/ckg diagnose

# 输出示例：
索引诊断报告：
├── 解析器状态
│   ├── Go: ✅ tree-sitter-go v0.21
│   ├── TypeScript: ✅ tree-sitter-typescript v0.20
│   └── Python: ✅ tree-sitter-python v0.20
│
├── 索引健康
│   ├── 损坏的条目: 0
│   ├── 孤立的引用: 3 (可自动修复)
│   └── 过时的条目: 12
│
└── 建议
    └── 运行 /ckg rebuild --incremental 修复过时条目

清理工具

磁盘空间管理

# 查看数据目录使用情况
/workspace disk-usage

# 输出示例：
wescode 数据目录使用情况：
  总计: 2.3 GB
  ├── ws-a1b2c3d4 (myproject): 890 MB
  │   ├── CKG 索引: 512 MB
  │   ├── 会话数据: 234 MB
  │   ├── 知识库: 89 MB
  │   └── 其他: 55 MB
  │
  ├── ws-e5f6g7h8 (webapp): 1.1 GB
  │   ├── CKG 索引: 780 MB
  │   └── ...
  │
  └── 全局数据: 310 MB
      ├── 日志: 180 MB
      ├── 崩溃报告: 30 MB
      └── 认证数据: 100 MB

清理操作

# 清理过期会话数据
/workspace cleanup sessions --older-than 30d

# 清理未使用的工作区 Cell
/workspace cleanup orphans

# 清理日志和崩溃报告
/workspace cleanup logs --older-than 7d

# 压缩数据库
/workspace cleanup compact

# 一键清理所有可清理项
/workspace cleanup --all

孤立 Cell 清理

当删除项目目录但未在 wescode 中关闭时，会留下孤立的 Cell：

# 检测孤立 Cell
/workspace cleanup orphans --check

# 输出示例：
检测到 2 个孤立 Cell：
  ws-x1y2z3w4 → /Users/dev/old-project (目录不存在)
      大小: 450 MB, 最后活跃: 3 个月前
  ws-m5n6o7p8 → /Users/dev/temp-demo (目录不存在)
      大小: 120 MB, 最后活跃: 6 个月前

删除这些 Cell？[Y/n/选择]

自动清理策略

# ~/.config/wescode/config.yaml
cleanup:
  # 自动清理过期会话
  sessions:
    enabled: true
    max-age: "90d"

  # 自动压缩数据库
  compact:
    enabled: true
    interval: "7d"

  # 日志保留
  logs:
    max-age: "30d"
    max-size: "500MB"

  # 崩溃报告保留
  crashes:
    max-age: "30d"

常见问题

Q: 切换工作区后数据怎么办？

A: 每个工作区的数据是独立的。切换工作区 = 切换 Cell，所有数据面（CKG/记忆/技能/会话）一起切换。这是隔离设计，不是数据丢失。

Q: 如何在多个工作区之间共享记忆？

A: 记忆天然按工作区隔离。如果需要跨项目的通用记忆，可以在全局配置中设置共享的记忆内容。

Q: 磁盘空间不足？

A: 运行 /workspace cleanup --all 进行一键清理，或参考清理工具章节进行针对性清理。CKG 索引通常是最大的空间消耗者，可以对不活跃的工作区运行 /ckg rebuild --compact。

Q: 重新打开项目后索引需要重建？

A: 不需要。索引持久化在 Cell 目录中，重新打开同一项目会自动加载已有索引。只有文件变更部分会增量更新。