# codespace 可运行后端骨架设计

日期：2026-07-02

## 目标

在当前目录 `/Users/taochen/llm/codespace` 生成一个 Go 后端项目骨架。第一版目标是可运行、可测试、边界清晰的 Workspace Service，而不是完整 Web IDE。

核心能力：

- 每个 workspace 对应本地文件系统中的一个目录。
- 文件读写统一通过 `FileSystem` 接口，第一版实现 `LocalFS`。
- OpenCode 以本机进程方式启动，工作目录 `cwd` 指向 workspace root。
- HTTP handler 不直接操作文件系统或进程，必须经过 service 层。
- 预留 watcher、Git、LSP、AI Agent 的后续扩展点。
- 不依赖 Docker。

## 非目标

第一版不实现：

- 用户认证和权限系统。
- Docker / 容器隔离。
- Git 集成。
- LSP。
- AI Agent 编排。
- Web 前端。
- 完整 watcher / WebSocket 文件事件推送。

这些能力以后接入，但不能污染第一版的核心边界。

## 目录结构

```text
.
├── cmd/
│   └── server/
│       └── main.go
├── configs/
│   └── config.yaml
├── internal/
│   ├── api/
│   │   ├── router.go
│   │   ├── workspace_handler.go
│   │   ├── file_handler.go
│   │   └── process_handler.go
│   ├── workspace/
│   │   ├── manager.go
│   │   ├── workspace.go
│   │   └── path.go
│   ├── fs/
│   │   ├── filesystem.go
│   │   ├── localfs.go
│   │   └── fileinfo.go
│   ├── process/
│   │   ├── manager.go
│   │   ├── session.go
│   │   └── opencode.go
│   ├── watcher/
│   │   └── watcher.go
│   ├── service/
│   │   ├── workspace_service.go
│   │   ├── file_service.go
│   │   └── process_service.go
│   ├── model/
│   │   ├── workspace.go
│   │   ├── file.go
│   │   └── process.go
│   └── util/
│       ├── path.go
│       └── errors.go
├── pkg/
│   ├── config/
│   ├── logger/
│   └── response/
├── web/
├── docs/
├── Makefile
├── go.mod
└── README.md
```

## 架构

```text
HTTP request
  ↓
internal/api handler
  ↓
internal/service
  ↓
workspace.Manager / fs.FileSystem / process.Manager
  ↓
local workspace directory + opencode process
```

边界规则：

1. `api` 只负责 HTTP 编解码、路由参数、状态码。
2. `service` 负责业务编排和校验。
3. `workspace` 负责 workspace 元数据和 root 目录管理。
4. `fs` 负责 workspace 内文件操作。
5. `process` 负责进程生命周期。
6. `watcher` 第一版只保留接口/占位，不接入运行链路。

## 核心数据结构

### Workspace

```go
type Workspace struct {
    ID   string `json:"id"`
    Root string `json:"root"`
}
```

含义：

- `ID` 是外部 API 使用的 workspace 标识。
- `Root` 是服务端本地绝对路径。
- 第一版不引入数据库，workspace 是否存在由目录和 manager 判断。

### FileInfo

```go
type FileInfo struct {
    Name    string    `json:"name"`
    Path    string    `json:"path"`
    IsDir   bool      `json:"isDir"`
    Size    int64     `json:"size"`
    ModTime time.Time `json:"modTime"`
}
```

`Path` 始终是 workspace 内相对路径，不向 API 暴露宿主机绝对路径。

### ProcessStatus

```go
type ProcessStatus struct {
    WorkspaceID string `json:"workspaceId"`
    Running     bool   `json:"running"`
    PID         int    `json:"pid,omitempty"`
}
```

## Workspace Manager

职责：

- 创建 workspace 目录。
- 查询 workspace。
- 删除 workspace 目录。
- 生成 workspace root 路径。

接口：

```go
type Manager interface {
    Create(id string) (*Workspace, error)
    Get(id string) (*Workspace, error)
    Delete(id string) error
}
```

路径策略：

- 配置项 `workspaceRoot` 默认使用 `./workspaces`。
- workspace root 为 `<workspaceRoot>/<workspaceID>`。
- workspace ID 第一版限制为安全路径片段，只允许字母、数字、`-`、`_`、`.`。

## FileSystem

所有文件操作必须走接口：

```go
type FileSystem interface {
    List(path string) ([]FileInfo, error)
    Read(path string) ([]byte, error)
    Write(path string, data []byte) error
    Mkdir(path string) error
    Remove(path string) error
    Rename(oldPath, newPath string) error
    Stat(path string) (*FileInfo, error)
}
```

第一版实现 `LocalFS`：

- `LocalFS` 绑定一个 workspace root。
- 所有传入路径都是 workspace 内相对路径。
- 解析路径时必须阻止 `../` 逃逸。
- API 不返回宿主机绝对路径。

## Process Manager

职责：按 workspace 管理 OpenCode 进程。

接口：

```go
type Manager interface {
    Start(workspaceID string, workspaceRoot string) error
    Stop(workspaceID string) error
    Restart(workspaceID string, workspaceRoot string) error
    Status(workspaceID string) Status
}
```

第一版行为：

- 命令默认是 `opencode`，通过配置项 `opencodeCommand` 可改。
- `cmd.Dir = workspace.Root`。
- `HOME` 默认设置为 workspace root，避免不同 workspace 共享 CLI 状态。
- 同一个 workspace 已有运行进程时，再次 start 返回已运行错误，不重复启动。
- stop 使用进程 kill；优雅退出可以后续补。

## Service 层

### WorkspaceService

- `CreateWorkspace(id string)`
- `GetWorkspace(id string)`
- `DeleteWorkspace(id string)`

删除 workspace 前，先停止对应进程，避免目录被运行进程占用。

### FileService

- `List(workspaceID, path string)`
- `Read(workspaceID, path string)`
- `Write(workspaceID, path string, data []byte)`
- `Mkdir(workspaceID, path string)`
- `Remove(workspaceID, path string)`
- `Rename(workspaceID, oldPath, newPath string)`
- `Stat(workspaceID, path string)`

每次通过 workspace manager 取 workspace，再构造绑定该 root 的 `LocalFS`。

### ProcessService

- `Start(workspaceID string)`
- `Stop(workspaceID string)`
- `Restart(workspaceID string)`
- `Status(workspaceID string)`

ProcessService 不自己拼路径，只通过 workspace manager 取 root。

## HTTP API

基础路径：`/api`

### 健康检查

```text
GET /healthz
```

返回：

```json
{"status":"ok"}
```

### Workspace

```text
POST /api/workspaces
GET /api/workspaces/{id}
DELETE /api/workspaces/{id}
```

创建请求：

```json
{"id":"user1"}
```

### Files

```text
GET /api/workspaces/{id}/files?path=.
GET /api/workspaces/{id}/files/read?path=main.go
PUT /api/workspaces/{id}/files/write
POST /api/workspaces/{id}/files/mkdir
DELETE /api/workspaces/{id}/files?path=main.go
POST /api/workspaces/{id}/files/rename
```

写文件请求：

```json
{"path":"main.go","content":"package main\n"}
```

重命名请求：

```json
{"oldPath":"old.go","newPath":"new.go"}
```

### Process

```text
POST /api/workspaces/{id}/process/start
POST /api/workspaces/{id}/process/stop
POST /api/workspaces/{id}/process/restart
GET /api/workspaces/{id}/process/status
```

## 配置

`configs/config.yaml`：

```yaml
server:
  addr: ":8080"
workspace:
  root: "./workspaces"
process:
  opencodeCommand: "opencode"
```

配置加载规则：

1. 先加载默认值。
2. 如果配置文件存在，覆盖默认值。
3. 环境变量可覆盖：
   - `CODESPACE_ADDR`
   - `CODESPACE_WORKSPACE_ROOT`
   - `CODESPACE_OPENCODE_COMMAND`

## 错误处理

统一 JSON 响应：

```json
{
  "error": {
    "code": "bad_request",
    "message": "invalid workspace id"
  }
}
```

常见映射：

- 参数错误：400
- workspace 不存在：404
- 文件不存在：404
- 进程已运行：409
- 内部错误：500

第一版只做简单错误类型，不引入复杂错误框架。

## 测试策略

最小测试：

- workspace ID 校验和路径生成。
- LocalFS 路径逃逸防护。
- LocalFS 基础读写/列表。
- Process manager 状态逻辑使用可配置命令测试，不依赖真实 OpenCode。
- HTTP handler 可做轻量测试，至少覆盖 health 和 workspace 创建。

验收命令：

```sh
go test ./...
go run ./cmd/server
```

## 兼容性与风险

- 当前目录是项目根目录，不再额外创建 `codespace/` 子目录。
- 初始化会创建标准 Go 项目文件；如果目标文件已存在，实施阶段必须先检查，避免覆盖用户已有内容。
- 不改变公共 API，因为这是初始版本。
- 最大安全风险是路径逃逸，必须在 `LocalFS` 和 workspace ID 校验中处理。
- 最大复杂度风险是过早引入 watcher/Git/LSP/Agent；第一版明确不实现。

## 骨架完成标准

完成后应满足：

- 当前目录包含完整 Go module。
- `go test ./...` 通过。
- `go run ./cmd/server` 能启动 HTTP 服务。
- 可以创建 workspace、读写 workspace 内文件、查询/启动/停止进程。
- Handler 不直接调用 `os.*` 或 `exec.*`。
- 文件路径不能逃逸 workspace root。