docs/plan/2026-07-03-cloud-workspace-git-init.md
Rama main · réplica de lectura del repositorio original.
# 云端模式 Git 初始化工作区方案
## 一、背景
当前云端模式创建会话时，用户只能输入一个项目名称（`cloudProjectKey`），后端创建一个空目录作为工作区。用户希望在云端模式下也能通过 Git 地址（`git clone`）来初始化工作区，从而快速从已有仓库开始工作。
---
## 二、现有架构分析
### 2.1 当前 CLOUD 模式创建流程
```
用户 → ChatInput/NewTaskDialog → createSession API
→ SessionService.createSession()
├─ 有 cloudProjectKey → 创建 /workspace-root/{userId}/projects/{slug}
└─ 无 cloudProjectKey → 创建 /workspace-root/{userId}/{sessionId}
→ environmentInfoProvider.detect() 检测环境信息
```
### 2.2 关键现有字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `cloudProjectKey` | String | 用户输入的项目名（slug），对应 `projects/{slug}` 目录 |
| `isGit` | Boolean | 标记工作区是否处于 Git 仓库中 |
| `projectKey` | String | 存储到 session 表的项目标识 |
---
## 三、方案总览
在创建工作区时，**不增加并行输入框**，而是采用**先选择模式、再输入对应内容**的交互方式：
```
用户选择工作区来源：
┌───────────────────────────────────────┐
│ ○ 选择已有工作区 （已有工作区时默认） │
│ ○ 创建新工作区 （无已有工作区时默认） │
│ ○ 初始化 Git 工作区 │
└───────────────────────────────────────┘
↓ 根据选择，展示不同输入
┌───────────────────────────────────────┐
│ 选择已有工作区 → 下拉列表选择项目名 │
│ 创建新工作区 → 输入项目名（可选） │
│ 初始化 Git → 输入 Git 地址 + 分支名 │
└───────────────────────────────────────┘
```
**关键原则**：
- 三个选项互斥，同一时间只展示一个输入区域
- 如果当前已存在工作区，默认选中"选择已有工作区"
- 如果当前不存在工作区，默认选中"创建新工作区"
---
## 四、后端改动
### 4.1 SessionController — 新增请求参数
**文件**: `backend/src/main/java/cn/etarch/mao/session/controller/SessionController.java`
`CreateSessionRequest` DTO 新增字段：
```java
@Data
public static class CreateSessionRequest {
// ... 现有字段 ...
private String cloudProjectKey; // 已有：项目名（slug）
private String workspaceMode; // 新增：existing | new | git
private String gitCloneUrl; // 新增：Git 仓库地址（支持 https 和 ssh）
private String gitBranch; // 新增：指定分支（可选，默认使用默认分支）
}
```
### 4.2 SessionService — 核心逻辑
**文件**: `backend/src/main/java/cn/etarch/mao/session/service/SessionService.java`
修改 `createSession()` 中 CLOUD 模式分支：
```java
if ("CLOUD".equals(session.getExecutionMode())) {
if ("git".equals(workspaceMode) && gitCloneUrl != null && !gitCloneUrl.isBlank()) {
// === Git 初始化工作区 ===
String slug = GitUrlParser.extractSlug(gitCloneUrl);
String projectPath = CloudWorkspaceResolver.resolveProjectWorkspace(
pathSandbox, userId, slug);
ensureWorkspaceDirectory(projectPath);
// 执行 git clone（同步，带超时）
GitCloneResult result = gitClone(gitCloneUrl, gitBranch, projectPath);
if (!result.success) {
// 清理已创建目录
deleteWorkspaceDirectory(projectPath);
throw new BusinessException(ErrorCode.GIT_CLONE_FAILED, result.error);
}
session.setWorkspace(projectPath);
session.setProjectKey(slug);
session.setIsGit(true);
} else if ("existing".equals(workspaceMode) && cloudProjectKey != null) {
// === 选择已有工作区 ===
String slug = CloudWorkspaceResolver.normalizeAndValidate(cloudProjectKey);
String projectPath = CloudWorkspaceResolver.resolveProjectWorkspace(
pathSandbox, userId, slug);
if (!Files.exists(Paths.get(projectPath))) {
throw new BusinessException(ErrorCode.PARAM_INVALID, "工作区不存在");
}
session.setWorkspace(projectPath);
session.setProjectKey(slug);
} else {
// === 新建工作区（现有逻辑） ===
if (cloudProjectKey != null && !cloudProjectKey.isBlank()) {
String slug = CloudWorkspaceResolver.normalizeAndValidate(cloudProjectKey);
String projectPath = CloudWorkspaceResolver.resolveProjectWorkspace(
pathSandbox, userId, slug);
ensureWorkspaceDirectory(projectPath);
session.setWorkspace(projectPath);
session.setProjectKey(slug);
} else {
// 临时工作区（无项目名）
String autoPath = pathSandbox.getWorkspaceRoot()
.resolve(String.valueOf(userId))
.resolve(String.valueOf(session.getId()))
.toString();
ensureWorkspaceDirectory(autoPath);
session.setWorkspace(autoPath);
session.setProjectKey(deriveProjectKey(autoPath));
}
}
sessionMapper.updateById(session);
}
```
### 4.3 Git Clone 实现
**新增文件**: `backend/src/main/java/cn/etarch/mao/session/service/GitOperationService.java`
```java
@Service
@Slf4j
public class GitOperationService {
private static final long CLONE_TIMEOUT_SECONDS = 120;
/**
* Execute git clone synchronously.
* Supports both HTTPS and SSH protocols.
* SSH keys are assumed to be pre-configured on the server.
*/
public GitCloneResult clone(String url, String branch, Path targetDir) {
List<String> command = new ArrayList<>();
command.add("git");
command.add("clone");
if (branch != null && !branch.isBlank()) {
command.add("--branch");
command.add(branch);
}
command.add(url);
command.add(targetDir.toString());
try {
ProcessBuilder pb = new ProcessBuilder(command);
pb.redirectErrorStream(true);
Process process = pb.start();
StringBuilder output = new StringBuilder();
try (BufferedReader reader = new BufferedReader(
new InputStreamReader(process.getInputStream()))) {
String line;
while ((line = reader.readLine()) != null) {
output.append(line).append("\n");
log.debug("git clone [{}]: {}", url, line);
}
}
boolean finished = process.waitFor(CLONE_TIMEOUT_SECONDS, TimeUnit.SECONDS);
if (!finished) {
process.destroyForcibly();
return GitCloneResult.fail("Git clone timeout (>" +
CLONE_TIMEOUT_SECONDS + "s)");
}
int exitCode = process.exitValue();
if (exitCode == 0) {
log.info("git clone success: {} → {}", url, targetDir);
return GitCloneResult.success();
} else {
log.warn("git clone failed: exit={}, output={}", exitCode, output);
return GitCloneResult.fail("Git clone failed: " + output.toString());
}
} catch (IOException e) {
log.error("git clone IO error for {}: {}", url, e.getMessage());
return GitCloneResult.fail("Git clone error: " + e.getMessage());
} catch (InterruptedException e) {
Thread.currentThread().interrupt();
process.destroyForcibly();
return GitCloneResult.fail("Git clone interrupted");
}
}
public record GitCloneResult(boolean success, String error) {
public static GitCloneResult success() {
return new GitCloneResult(true, null);
}
public static GitCloneResult fail(String error) {
return new GitCloneResult(false, error);
}
}
}
```
### 4.4 Git URL 解析与校验
**新增文件**: `backend/src/main/java/cn/etarch/mao/session/util/GitUrlParser.java`
```java
public final class GitUrlParser {
// HTTPS: https://github.com/user/repo.git or https://github.com/user/repo
private static final Pattern HTTPS_PATTERN =
Pattern.compile("^https://[\\w.-]+(/[\\w.-]+)*\\.git$",
Pattern.CASE_INSENSITIVE);
// SSH: git@github.com:user/repo.git
private static final Pattern SSH_PATTERN =
Pattern.compile("^git@[\\w.-]+:[\\w.-]+(/[\\w.-]+)*\\.git$");
/**
* Extract repository name from Git URL.
* https://github.com/user/my-repo.git → my-repo
* git@github.com:user/my-repo.git → my-repo
*/
public static String extractSlug(String url) {
if (url == null || url.isBlank()) {
throw new BusinessException(ErrorCode.PARAM_INVALID, "Git URL 不能为空");
}
String path;
if (url.startsWith("https://") || url.startsWith("http://")) {
if (!url.startsWith("https://")) {
throw new BusinessException(ErrorCode.PARAM_INVALID,
"仅支持 HTTPS 协议的 Git 地址");
}
// Extract path part after host
try {
URI uri = new URI(url);
path = uri.getPath();
} catch (URISyntaxException e) {
throw new BusinessException(ErrorCode.PARAM_INVALID,
"Git URL 格式无效");
}
} else if (url.startsWith("git@")) {
// SSH format: git@host:path → extract path after ':'
int colonIdx = url.indexOf(':');
if (colonIdx < 0) {
throw new BusinessException(ErrorCode.PARAM_INVALID,
"SSH Git 地址格式无效");
}
path = url.substring(colonIdx + 1);
} else {
throw new BusinessException(ErrorCode.PARAM_INVALID,
"不支持的 Git 地址协议，请使用 HTTPS 或 SSH");
}
// Extract repo name: strip leading / and trailing .git
if (path.startsWith("/")) path = path.substring(1);
if (path.endsWith(".git")) path = path.substring(0, path.length() - 4);
// Take last segment as repo name
int lastSlash = path.lastIndexOf('/');
String name = lastSlash >= 0 ? path.substring(lastSlash + 1) : path;
if (name.isBlank()) {
throw new BusinessException(ErrorCode.PARAM_INVALID,
"无法从 Git URL 提取仓库名");
}
// Reuse existing slug validation
return CloudWorkspaceResolver.normalizeAndValidate(name);
}
/**
* Validate git URL format (HTTPS or SSH).
*/
public static void validate(String url) {
if (url == null || url.isBlank()) {
throw new BusinessException(ErrorCode.PARAM_INVALID, "Git URL 不能为空");
}
if (url.startsWith("https://")) {
// basic sanity: must contain a host and path
if (!url.matches("^https://[^\\s]+/[^\\s]+")) {
throw new BusinessException(ErrorCode.PARAM_INVALID,
"Git URL 格式无效，示例: https://github.com/user/repo.git");
}
} else if (url.startsWith("git@")) {
if (!url.matches("^git@[^\\s]+:[^\\s]+")) {
throw new BusinessException(ErrorCode.PARAM_INVALID,
"SSH Git 地址格式无效，示例: git@github.com:user/repo.git");
}
} else {
throw new BusinessException(ErrorCode.PARAM_INVALID,
"不支持的协议，仅支持 HTTPS 和 SSH");
}
}
}
```
### 4.5 获取已有工作区列表 API
**新增 API**: `GET /v1/sessions/cloud-projects`
**文件**: `SessionController.java`
```java
@GetMapping("/cloud-projects")
public Result<List<CloudProjectVO>> listCloudProjects(
@AuthenticationPrincipal Long userId) {
Path userRoot = pathSandbox.getWorkspaceRoot().resolve(String.valueOf(userId));
Path projectsDir = userRoot.resolve("projects");
List<CloudProjectVO> projects = new ArrayList<>();
if (Files.exists(projectsDir)) {
try (var stream = Files.list(projectsDir)) {
stream.filter(Files::isDirectory)
.map(dir -> {
CloudProjectVO vo = new CloudProjectVO();
vo.setName(dir.getFileName().toString());
vo.setPath(dir.toString());
// Check if contains .git
vo.setIsGit(Files.exists(dir.resolve(".git")));
return vo;
})
.sorted(Comparator.comparing(CloudProjectVO::getName))
.forEach(projects::add);
} catch (IOException e) {
log.warn("Failed to list cloud projects for user {}: {}", userId, e.getMessage());
}
}
return Result.ok(projects);
}
```
### 4.6 安全考量
| 约束 | 说明 |
|------|------|
| SSH Key | 由运维在服务器端预配置（`~/.ssh/config` 或 `ssh-agent`），不在代码中管理 |
| 协议白名单 | 仅允许 `https://` 和 `git@`（SSH）开头 |
| 路径隔离 | 目标路径始终在 `PathSandbox` 沙箱内，由 `assertUnderUserSandbox` 保证 |
| 超时控制 | 默认 120 秒超时，防止资源占用 |
| 错误清理 | Clone 失败时自动清理已创建的目录 |
| 命令注入防护 | 使用 `ProcessBuilder` + 参数列表（非 shell 拼接），Git URL 作为单独参数传入 |
---
## 五、前端改动
### 5.1 交互设计
核心思路：**先选择模式，再展示对应输入内容**——一个始终只有一个主输入区域的表单。
```
┌──────────────────────────────────────────────┐
│ 新建任务 ✕ │
├──────────────────────────────────────────────┤
│ │
│ ○ 云端模式 ○ 本地模式 │
│ │
│ ── 工作区来源 ───────────────────────────── │
│ │
│ ┌─ 选择已有工作区 ──────────────────────┐ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ my-project ▼ │ │ │
│ │ └──────────────────────────────────┘ │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌─ 创建新工作区 ────────────────────────┐ │
│ │ 输入项目名（可留空，留空=临时工作区） │ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ new-project │ │ │
│ │ └──────────────────────────────────┘ │ │
│ └──────────────────────────────────────┘ │
│ │
│ ┌─ 初始化 Git 工作区 ───────────────────┐ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ https://github.com/user/repo.git │ │ │
│ │ └──────────────────────────────────┘ │ │
│ │ 分支（可选，默认使用默认分支） │ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ main │ │ │
│ │ └──────────────────────────────────┘ │ │
│ └──────────────────────────────────────┘ │
│ │
│ [取消] [开始（克隆中...）] │
└──────────────────────────────────────────────┘
```
**交互规则**：
| 规则 | 说明 |
|------|------|
| 默认选中 | 有已有工作区 → 选中"选择已有工作区"；无已有工作区 → 选中"创建新工作区" |
| 互斥展开 | 三个选项是 radio 行为，选中一个时自动折叠另外两个 |
| 单个输入区 | 同一时间只有一个输入区域可见 |
| Loading 状态 | 点击"开始"后，按钮变为 loading 态，显示"正在克隆仓库..."或"正在初始化..." |
| Git URL 格式化 | 用户输入时实时校验格式，自动 trim、补全 `.git` 后缀 |
### 5.2 NewTaskDialog 改动
**文件**: `desktop/src/components/task/NewTaskDialog.vue`
新增状态：
```typescript
// 工作区来源模式
type WorkspaceMode = 'existing' | 'new' | 'git'
const workspaceMode = ref<WorkspaceMode>('new')
// 已有工作区列表
interface CloudProject {
name: string
path: string
isGit: boolean
}
const cloudProjects = ref<CloudProject[]>([])
// Git 相关
const gitCloneUrl = ref('')
const gitBranch = ref('')
// Loading 状态
const isCreating = ref(false)
const createLoadingText = ref('')
```
关键逻辑：
```typescript
async function onOpen() {
// ... 现有初始化逻辑 ...
// 加载已有云端工作区列表
cloudProjects.value = await sessionStore.fetchCloudProjects()
// 默认选中逻辑
workspaceMode.value = cloudProjects.value.length > 0 ? 'existing' : 'new'
}
async function confirm() {
isCreating.value = true
if (workspaceMode.value === 'git') {
createLoadingText.value = '正在克隆仓库...'
} else {
createLoadingText.value = '正在初始化工作区...'
}
try {
const session = await sessionStore.createSession(
selectedAgent.value!.id,
selectedMode.value,
/* workspace */ undefined,
/* environmentInfo */ undefined,
/* modelId */ undefined,
/* permissionLevel */ undefined,
/* cloudProjectKey */ getCloudProjectKey(),
/* gitCloneUrl */ workspaceMode.value === 'git' ? gitCloneUrl.value : undefined,
/* gitBranch */ workspaceMode.value === 'git' ? gitBranch.value || undefined : undefined,
/* workspaceMode */ workspaceMode.value,
)
if (session) emit('created', session)
} finally {
isCreating.value = false
createLoadingText.value = ''
}
}
function getCloudProjectKey(): string | undefined {
if (workspaceMode.value === 'existing') {
return selectedCloudProject.value
}
if (workspaceMode.value === 'new') {
return newProjectName.value || undefined
}
return undefined // git mode — 后端从 URL 提取
}
```
### 5.3 sessionStore 改动
**文件**: `desktop/src/stores/session.ts`
```typescript
async function createSession(
agentId: string,
executionMode: string,
workspace?: string,
environmentInfo?: SessionEnvironmentInfo,
modelId?: number,
permissionLevel?: string,
cloudProjectKey?: string,
gitCloneUrl?: string, // 新增
gitBranch?: string, // 新增
workspaceMode?: string, // 新增: 'existing' | 'new' | 'git'
) {
const payload: Record<string, unknown> = {
agentId,
executionMode,
modelId: modelId || undefined,
permissionLevel: permissionLevel || undefined,
// ...
}
if (executionMode === 'CLOUD') {
payload.workspaceMode = workspaceMode || 'new'
if (workspaceMode === 'git' && gitCloneUrl) {
payload.gitCloneUrl = gitCloneUrl
if (gitBranch) payload.gitBranch = gitBranch
} else if (cloudProjectKey) {
payload.cloudProjectKey = cloudProjectKey
}
}
// ...
}
async function fetchCloudProjects(): Promise<CloudProject[]> {
const { data } = await api.get('/sessions/cloud-projects')
return data || []
}
```
### 5.4 useChat 改动
**文件**: `desktop/src/composables/useChat.ts`
新增状态：
```typescript
const workspaceMode = ref<'existing' | 'new' | 'git'>('new')
const gitCloneUrl = ref('')
const gitBranch = ref('')
```
创建 session 时传递：
```typescript
const sessionData = await sessionStore.createSession(
agentId.value,
executionMode.value,
executionMode.value === 'LOCAL' ? workspace.value || undefined : undefined,
environmentInfo,
selectedModelId?.value,
permissionLevel?.value,
executionMode.value === 'CLOUD' ? cloudProjectKey.value || undefined : undefined,
executionMode.value === 'CLOUD' ? gitCloneUrl.value || undefined : undefined,
executionMode.value === 'CLOUD' ? gitBranch.value || undefined : undefined,
executionMode.value === 'CLOUD' ? workspaceMode.value : undefined,
)
```
### 5.5 ChatInput 改动
**文件**: `desktop/src/components/chat/ChatInput.vue`
当前 ChatInput 中已有 `el-autocomplete` 用于输入项目名。改造为与 NewTaskDialog 一致的三选一交互。
新增 props:
```typescript
const props = defineProps<{
// ... 现有 props ...
workspaceMode?: 'existing' | 'new' | 'git'
gitCloneUrl?: string
gitBranch?: string
cloudProjects?: CloudProject[]
}>()
const emit = defineEmits<{
// ... 现有 emits ...
'update:workspaceMode': [mode: string]
'update:gitCloneUrl': [url: string]
'update:gitBranch': [branch: string]
}>()
```
### 5.6 Loading 提示
在整个创建流程中（从点击"开始"到获得 session 响应），前端需要显示 loading 状态：
```
场景 A：新建空工作区
→ 按钮显示 "正在初始化..."，约 1-2 秒
场景 B：Git Clone 工作区
→ 按钮显示 "正在克隆仓库...（可能需要 1-2 分钟）"
→ 后端同步 clone，前端等待 API 响应
→ 超时/失败时显示错误 toast："克隆失败：xxx"
```
实现方式：在 `NewTaskDialog.confirm()` 和 `ChatInput` 发送流程中，创建 session 前设置 `isCreating = true`，并在确认按钮上展示 loading spinner + 状态文字。
---
## 六、数据库改动
**无需新增表或字段**。现有 `session` 表已有足够字段支撑：
| 字段 | 用途 |
|------|------|
| `workspace` | 存储工作区路径（clone 目标路径） |
| `project_key` | 存储从 Git URL 提取的项目名 |
| `is_git` | Git Clone 成功后自动设为 `true` |
---
## 七、接口汇总
| 方法 | 路径 | 说明 | 新增/修改 |
|------|------|------|-----------|
| POST | `/v1/sessions` | 创建会话 | 修改：新增 `workspaceMode`、`gitCloneUrl`、`gitBranch` |
| GET | `/v1/sessions/cloud-projects` | 获取已有云端工作区列表 | **新增** |
---
## 八、实施步骤
| 步骤 | 内容 | 涉及文件 |
|------|------|----------|
| **1** | 新建 `GitUrlParser` 工具类 | `backend/.../session/util/GitUrlParser.java`（新增） |
| **2** | 新建 `GitOperationService` | `backend/.../session/service/GitOperationService.java`（新增） |
| **3** | `CreateSessionRequest` 新增字段 | `SessionController.java` |
| **4** | `SessionService.createSession()` 增加三模式分支 | `SessionService.java` |
| **5** | 新增 `GET /cloud-projects` 接口 | `SessionController.java` |
| **6** | `sessionStore.createSession()` 传递新参数 | `desktop/src/stores/session.ts` |
| **7** | `sessionStore.fetchCloudProjects()` | `desktop/src/stores/session.ts` |
| **8** | `NewTaskDialog` 增加三选一 + loading | `desktop/src/components/task/NewTaskDialog.vue` |
| **9** | `ChatInput` 改造为三选一交互 | `desktop/src/components/chat/ChatInput.vue` |
| **10** | `useChat` 传递新参数 | `desktop/src/composables/useChat.ts` |
---
## 九、边界情况与风险
| 场景 | 处理策略 |
|------|----------|
| 项目名与已有项目冲突 | `projects/{slug}` 目录已存在时，复用 `normalizeAndValidate` 报错，提示用户项目名已被占用 |
| Git URL 格式无效 | 前端实时校验 + 后端 `GitUrlParser.validate()`，返回明确错误信息 |
| Clone 超时（>120s） | 返回超时错误，清理已创建目录 |
| 私有仓库无权限（SSH Key 未配置） | Git 返回认证错误，透传给前端："Authentication failed. Please check SSH key configuration." |
| 克隆大仓库 | 120 秒超时适用于大多数仓库；超大仓库可后续改为异步模式 |
| 工作区目录安全 | 目标路径始终在 `PathSandbox` 沙箱内，由 `assertUnderUserSandbox` 保证 |
| 命令注入 | 使用 `ProcessBuilder` + 参数列表，Git URL 作为单独参数，不拼接 shell 命令 |
| 字符编码 | Git clone 输出使用 UTF-8 读取，兼容中英文仓库名 |
---
## 十、后续增强（可选 Phase 2）
### 10.1 异步 Clone
对于大型仓库，可将 clone 改为异步：
```
1. createSession 快速返回（workspace 目录已创建但为空）
2. 后台异步 clone，WebSocket 推送 workspace_init 事件
3. 前端显示 "正在克隆仓库..." 进度
4. clone 完成后，前端收到通知，刷新文件树
```
新增 WebSocket 事件：`workspace_init`
```json
{
"status": "CLONING" | "READY" | "FAILED",
"progress": "Cloning repository...",
"error": "Authentication failed"
}
```
### 10.2 Clone 进度输出
后端在执行 clone 时，通过 WebSocket 实时推送 git clone 的标准输出，让前端展示进度条或日志行。
### 10.3 支持直接打开已有工作区
在 ChatInput 中，当前"项目名输入"已支持 autocomplete 建议。可进一步增强：输入已有项目名时直接复用该工作区，无需重新创建 session，而是直接在该项目下新建一个会话。