远程开发

wescode 支持远程开发场景，允许在远程服务器、容器或云端环境中使用完整的 AI 编程能力。远程开发时，AI 引擎和 CKG 索引运行在远程环境中，确保代码分析和工具执行的准确性。

SSH 连接

基本连接

wescode 支持通过 SSH 连接到远程服务器进行开发：

安装 Remote-SSH 扩展（预装）
打开命令面板：Ctrl+Shift+P → Remote-SSH: Connect to Host
输入 SSH 连接信息：user@hostname
等待远程环境初始化

SSH 配置

推荐在 ~/.ssh/config 中预配置连接信息：

# ~/.ssh/config
Host dev-server
    HostName 192.168.1.100
    User developer
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    ForwardAgent yes

Host gpu-workstation
    HostName gpu.mycompany.com
    User ml-engineer
    Port 2222
    IdentityFile ~/.ssh/id_rsa
    ServerAliveInterval 60
    ServerAliveCountMax 3

连接后即可从 wescode 中直接选择主机名连接。

远程环境要求

远程服务器需要满足以下条件：

要求	说明
操作系统	Linux (x64/arm64) 或 macOS
Node.js	22+
Go	1.22+（用于 wescode Go 后端）
存储空间	至少 2GB 可用空间
网络	SSH 访问，可选 HTTP 出站（用于 AI Provider）

首次连接初始化

首次连接远程服务器时，wescode 会自动：

安装远程服务组件
安装 wescode Go 后端
配置 AI Provider（使用本地配置的 API Key）
创建工作区 Cell

# 手动初始化远程环境
wescode remote init dev-server

# 检查远程环境状态
wescode remote status dev-server

容器开发

Dev Containers

wescode 支持 Dev Containers 规范，在容器中进行开发：

// .devcontainer/devcontainer.json
{
  "name": "My Go Project",
  "image": "mcr.microsoft.com/devcontainers/go:1.22",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "22"
    }
  },
  "customizations": {
    "vscode": {
      "settings": {
        "wescode.remote.dataDir": "/workspace/.wescode-data"
      },
      "extensions": [
        "golang.go"
      ]
    }
  },
  "postCreateCommand": "wescode init --non-interactive",
  "remoteUser": "vscode",
  "mounts": [
    "source=${localWorkspaceFolder}/.wescode-data,target=/workspace/.wescode-data,type=bind,consistency=cached"
  ]
}

Docker 容器开发

也可以直接连接到运行中的 Docker 容器：

# 启动开发容器
docker run -d \
  --name dev-env \
  -v $(pwd):/workspace \
  -p 2222:22 \
  my-dev-image

# 在 wescode 中连接
# Ctrl+Shift+P → Remote-Containers: Attach to Running Container

容器环境配置

# .wescode/remote.yaml
container:
  # wescode 数据目录
  data-dir: "/workspace/.wescode-data"

  # CKG 索引持久化
  persist-index: true

  # 工具路径
  tools:
    go: "/usr/local/go/bin/go"
    node: "/usr/local/bin/node"

  # 环境变量
  env:
    GOPATH: "/workspace/go"
    PATH: "/usr/local/go/bin:${PATH}"

Kubernetes 开发环境

对于 Kubernetes 环境，支持连接到 Pod 进行开发：

# 使用 kubectl 端口转发
kubectl port-forward pod/dev-pod 2222:22

# 然后在 wescode 中通过 SSH 连接
# Host: localhost:2222

远程工作区

工作区映射

远程开发时，wescode 的工作区和 Cell 映射遵循以下规则：

场景	Cell ID 来源	数据位置
SSH 远程	远程服务器上的路径	远程服务器
Dev Container	容器内路径	容器内（可挂载持久化）
WSL	WSL 内路径	WSL 文件系统

数据位置

远程开发时，所有数据默认存储在远程环境中：

远程服务器 ~/.local/share/wescode/
├── hypervisor.db
├── cells/
│   └── ws-{hash}/          # 远程工作区的 Cell
│       ├── sessions.db     # 会话和记忆
│       ├── index/          # CKG 索引
│       └── ...
└── logs/

配置同步

本地配置（如 API Key）不会自动同步到远程。需要手动配置或使用环境变量：

# 方式 1：在远程环境中配置
ssh dev-server "wescode config set provider.api-key YOUR_KEY"

# 方式 2：通过环境变量
ssh dev-server "export ANTHROPIC_API_KEY=YOUR_KEY"

# 方式 3：使用 SSH Agent Forwarding（推荐）
# 在 ~/.ssh/config 中配置 ForwardAgent yes
# API Key 通过本地 Agent 代理

同步策略

文件同步

wescode 使用 VSCode 的远程文件系统，文件编辑直接在远程进行：

编辑器缓冲区：本地缓存，保存时同步到远程
Buffer Overlay：在远程 Go 后端维护，实时同步
CKG 索引：在远程构建和维护

配置同步策略

# .wescode/sync.yaml
sync:
  # 全局设置同步
  settings: true

  # 扩展同步
  extensions: true

  # 技能同步
  skills: false  # 默认不同步，避免环境差异

  # CKG 索引
  index:
    strategy: "remote"  # remote: 远程构建 | local: 本地构建后上传

离线模式

网络不稳定时，wescode 提供离线降级支持：

代码编辑：完全可用（文件在远程）
AI 功能：取决于 Provider 网络可达性
CKG 分析：完全可用（索引在远程）
Git 操作：取决于远程服务器的网络状态

性能优化

延迟优化

远程开发时的延迟优化建议：

选择地理位置近的服务器：减少网络往返时间
使用 SSH 连接复用：

# ~/.ssh/config
Host *
    ControlMaster auto
    ControlPath ~/.ssh/sockets/%r@%h-%p
    ControlPersist 600

启用压缩：

Host dev-server
    Compression yes

CKG 索引优化

远程环境中的索引优化：

# .wescode/ckg.yaml
ckg:
  # 减少索引范围
  exclude:
    - "vendor/"
    - "node_modules/"
    - "*.pb.go"
    - "testdata/"

  # 调整并行度（根据远程 CPU 核心数）
  workers: 2

  # 限制内存使用
  max-memory: "1GB"

  # 增量更新间隔（降低 I/O 压力）
  incremental-interval: "5s"

带宽优化

减少本地和远程之间的数据传输：

禁用不必要的文件监听：

{
  "files.watcherExclude": {
    "**/vendor/**": true,
    "**/node_modules/**": true,
    "**/.git/objects/**": true
  }
}

使用远程终端：在远程终端中执行命令，避免输出回传
大文件处理：使用远程工具处理大文件，不要打开超大文件

资源监控

# 查看远程环境资源使用
/workspace remote-status

# 输出示例：
远程环境状态：
  主机: dev-server (192.168.1.100)
  CPU: 4 核 (使用率 35%)
  内存: 8GB (使用 4.2GB)
  磁盘: 50GB (wescode 使用 1.8GB)
  Go 后端: 运行中 (PID 12345, 280MB)
  CKG 索引: 就绪 (2847 文件)
  网络延迟: 15ms

平台特定说明

WSL (Windows Subsystem for Linux)

在 Windows 上使用 WSL 开发时：

wescode 推荐使用 WSL 模式而非 Windows 原生模式
项目文件应存放在 WSL 文件系统中（/home/user/），而非 /mnt/c/
环境配置和路径遵循 Linux 规范

macOS 远程到 Linux

确保 SSH 密钥和 Agent 正确配置
ForwardAgent yes 允许远程服务器使用本地的 SSH 密钥
文件权限差异（macOS 大小写不敏感 vs Linux 大小写敏感）需注意

云开发环境

支持连接到以下云开发环境：

GitHub Codespaces
Gitpod
AWS Cloud9
Google Cloud Shell

常见问题

Q: 远程开发时 AI 功能延迟大？

A: AI 请求从远程服务器直接发送到 Provider，不经过本地。确保远程服务器能正常访问 AI Provider API。如果远程网络受限，考虑配置代理。

Q: 远程服务器磁盘空间不足？

A: 运行 /workspace cleanup --all 清理不必要的数据。CKG 索引是最大消耗者，可以通过缩小索引范围或使用 --compact 选项减小体积。

Q: 容器重建后数据丢失？

A: 在 devcontainer.json 中配置持久化挂载（见容器开发章节），将 .wescode-data 目录挂载到宿主机。

Q: 多个开发者共享同一台远程服务器？

A: 每个用户在各自的 home 目录下有独立的 wescode 数据目录，Cell 按工作区路径隔离，互不影响。