# Worktree 通用能力设计

## 问题陈述

qwen-code 目前仅有面向 Arena 多模型对比场景的内部 worktree 实现（`GitWorktreeService`），用户无法在普通会话中使用 worktree 隔离工作，AgentTool 也不支持为 subagent 创建隔离的 worktree 环境。

目标是将 worktree 做成通用能力，支持用户会话级隔离和 Agent 级隔离，同时保证现有 Arena 功能体验完全不变。

## 现状对比

| 功能                              | qwen-code       | claude-code |
| --------------------------------- | --------------- | ----------- |
| `EnterWorktree` 工具              | ❌              | ✅          |
| `ExitWorktree` 工具               | ❌              | ✅          |
| AgentTool `isolation: 'worktree'` | ❌              | ✅          |
| worktree 会话状态持久化与恢复     | ❌              | ✅          |
| 过期 worktree 自动清理            | ❌              | ✅          |
| Post-creation setup（hooks 配置） | ❌              | ✅          |
| StatusLine worktree 状态展示      | ❌              | ✅          |
| WorktreeExitDialog（退出提示）    | ❌              | ✅          |
| 符号链接目录（node_modules 等）   | ❌              | ✅          |
| sparse checkout                   | ❌              | ✅          |
| `--worktree` CLI 启动标志         | ❌              | ✅          |
| tmux 集成                         | ❌              | ✅          |
| Arena 多模型 worktree 隔离        | ✅（qwen 独有） | ❌          |
| 脏状态覆盖（stash + copy）        | ✅              | ✅          |
| Baseline commit 追踪              | ✅（qwen 独有） | ❌          |

## 设计原则

**worktree 是通用能力，Arena 是其上层应用。**

- 通用 worktree 层：`EnterWorktree`/`ExitWorktree` 工具、AgentTool `isolation` 参数、会话状态管理、自动清理
- Arena 层：多模型并行调度、`worktreeBaseDir` 自定义路径、批量创建与 diff 对比，继续使用 `GitWorktreeService.setupWorktrees()` 的现有逻辑，不受通用层改动影响

AgentTool 的 `isolation: 'worktree'` 只走通用路径，Arena 内部不经过这个参数创建 worktree，两者路径独立。

## 路径与配置

### 通用 worktree 路径

由 `EnterWorktree` 工具或 AgentTool `isolation: 'worktree'` 创建的 worktree 固定存放在：

```
{git 仓库根}/.qwen/worktrees/{slug}
```

路径不可配置。slug 命名规则：

- 用户会话 worktree：用户指定名称，或自动生成（格式：`{形容词}-{名词}-{4位随机}`）
- Agent worktree：`agent-{7位随机 hex}`

### Arena worktree 路径（已有，保持不变）

Arena 的 worktree 路径由 `agents.arena.worktreeBaseDir` 控制，默认 `~/.qwen/arena`（`ArenaManager.ts:125`），与通用路径完全独立，不做任何改动。

### 扩展配置（暂缓至 Phase C/D）

| 配置项                        | 类型       | 用途                                                           | 阶段    |
| ----------------------------- | ---------- | -------------------------------------------------------------- | ------- |
| `worktree.symlinkDirectories` | `string[]` | 符号链接指定目录（如 `node_modules`）到 worktree，避免磁盘浪费 | Phase C |
| `worktree.sparsePaths`        | `string[]` | git sparse-checkout cone 模式，大型 monorepo 只写入指定路径    | Phase D |

Phase A / B 不新增任何配置项。

## 工具设计

### EnterWorktree

**触发条件：** 用户明确说 "start a worktree"、"use a worktree"、"create a worktree" 等词语。不应在用户说"修复 bug"、"开发功能"时自动触发。

**输入 schema：**

```
name?: string  // 可选，slug 格式：字母/数字/点/下划线/破折号，最大 64 字符
```

**行为：**

1. 验证当前未在 worktree 中（防止嵌套）
2. 解析到 git 仓库根（处理已在子目录的情况）
3. 调用 `GitWorktreeService` 创建 worktree，路径为 `.qwen/worktrees/{slug}`
4. 将 worktree 会话写入 `SessionService`
5. 切换工作目录到 worktree 路径
6. 清除文件缓存

**输出：** `worktreePath`、`worktreeBranch`、`message`

### ExitWorktree

**触发条件：** 用户说 "exit the worktree"、"leave the worktree"、"go back" 等。

**输入 schema：**

```
action: 'keep' | 'remove'
discard_changes?: boolean  // 仅 action='remove' 时有效
```

**安全守卫：**

- 仅操作本会话通过 `EnterWorktree` 创建的 worktree
- `action='remove'` 且存在未提交变更时，拒绝执行（除非 `discard_changes: true`）

**行为：**

- `keep`：清空会话中的 worktree 状态，保留 worktree 目录和分支，恢复原始工作目录
- `remove`：删除 worktree 目录，删除对应 git 分支，清空会话状态，恢复原始工作目录

**输出：** `action`、`originalCwd`、`worktreePath`、`worktreeBranch`

## 用户触发方式

| 方式           | 示例                                                     | 实现阶段 |
| -------------- | -------------------------------------------------------- | -------- |
| 会话中明确请求 | 用户说 "在 worktree 中开始工作" → 模型调用 EnterWorktree | Phase A  |
| Agent 隔离     | 模型为 subagent 设置 `isolation: 'worktree'`             | Phase B  |
| CLI 启动标志   | `qwen --worktree my-feature`                             | Phase D  |

无斜杠命令。会话中 worktree 的触发依赖用户明确提及，`isolation: 'worktree'` 才是模型自主决策的场景。

## 分阶段实现计划

### Phase A：核心工具（用户会话级 worktree）

**目标：** 用户能在会话中进入 / 退出 worktree。

**要实现的功能：**

- `EnterWorktree` 工具：创建 worktree，切换工作目录，记录会话状态
- `ExitWorktree` 工具：keep / remove 两种退出方式，安全守卫
- `GitWorktreeService` 扩展：新增面向单用户会话的 `createUserWorktree()` / `removeUserWorktree()` 方法，复用现有 git 操作逻辑，不改动 Arena 使用的批量接口
- `SessionService` 扩展：新增 `WorktreeSession` 字段，记录 `{ slug, worktreePath, worktreeBranch, originalCwd, originalBranch }`；`--resume` 时恢复 worktree 工作目录
- 工具 prompt：为每个工具编写使用说明，明确何时调用、何时不调用

**影响文件：**

| 文件                                               | 变更类型                                      |
| -------------------------------------------------- | --------------------------------------------- |
| `packages/core/src/tools/tool-names.ts`            | 新增 `ENTER_WORKTREE`、`EXIT_WORKTREE` 常量   |
| `packages/core/src/tools/EnterWorktreeTool/`       | 新建目录：`EnterWorktreeTool.ts`、`prompt.ts` |
| `packages/core/src/tools/ExitWorktreeTool/`        | 新建目录：`ExitWorktreeTool.ts`、`prompt.ts`  |
| `packages/core/src/services/gitWorktreeService.ts` | 新增用户会话级接口（不改动 Arena 接口）       |
| `packages/core/src/services/sessionService.ts`     | 新增 `WorktreeSession` 字段及读写方法         |
| `packages/core/src/tools/` 注册入口                | 注册新工具                                    |

**不在 Phase A 范围内：**

- Agent 隔离（Phase B）
- hooks 配置等 post-creation setup（Phase C）
- UI 状态展示（Phase C）

---

### Phase B：Agent 隔离（AgentTool `isolation: 'worktree'`）+ 描述更新

**目标：** 模型可为 subagent 创建临时隔离 worktree，agent 结束后自动清理；同步更新受影响的工具描述和提示词。

**要实现的功能：**

_Agent 隔离核心：_

- `AgentTool` 新增 `isolation?: 'worktree'` 参数
- Agent 启动时创建临时 worktree（slug：`agent-{7hex}`，路径：`.qwen/worktrees/agent-{7hex}`）
- Agent 结束后：无变更则自动删除；有变更则保留，将路径和分支返回在结果中
- 过期 worktree 自动清理：扫描 `.qwen/worktrees/`，匹配 `agent-{7hex}` 模式，超过 30 天且无未推送提交则删除，fail-closed 策略

_描述与提示词更新：_

- `AgentTool` description 补充 `isolation: 'worktree'` 参数说明（参考 claude-code `AgentTool/prompt.ts:272`）
- 新增 `buildWorktreeNotice()`：当 fork subagent 在 worktree 中运行时，向其注入上下文提示，说明其处于隔离 worktree、路径继承自父 agent、编辑前需重新读取文件（参考 claude-code `forkSubagent.ts:buildWorktreeNotice`）

_无需改动：_

- review skill（`SKILL.md`）：review 使用独立机制（路径 `.qwen/tmp/review-pr-<n>`，通过 `qwen review fetch-pr` 命令创建），与通用 worktree 路径和机制完全不同，不存在混淆

**Arena 兼容保证：** Arena 内部不经过 `isolation` 参数创建 worktree，此改动不触碰 Arena 代码路径。

**影响文件：**

| 文件                                               | 变更类型                                               |
| -------------------------------------------------- | ------------------------------------------------------ |
| `packages/core/src/tools/agent/agent.ts`           | 新增 `isolation` 参数及 worktree 创建/清理逻辑         |
| `packages/core/src/tools/agent/fork-subagent.ts`   | 新增 `buildWorktreeNotice()` 并在 worktree 模式下注入  |
| `packages/core/src/services/gitWorktreeService.ts` | 新增 `createAgentWorktree()` / `removeAgentWorktree()` |
| `packages/core/src/services/worktreeCleanup.ts`    | 新建：过期 worktree 自动清理逻辑                       |

---

### Phase C：体验优化（Post-creation setup + UI）

**目标：** worktree 创建后自动初始化环境，状态在界面上可见。

**要实现的功能：**

- Post-creation setup：配置 `core.hooksPath` 指向主仓库（qwen-code 无 `settings.local.json` 概念，不需要复制）
- StatusLine 展示当前 worktree 名称 / 分支
- WorktreeExitDialog：会话退出时（检测到 worktree 仍活跃）提示用户选择 keep 或 remove
- 新增 `worktree.symlinkDirectories` 配置项，实现目录符号链接

---

### Phase D：高级功能

**目标：** 对齐 claude-code 的完整特性集。

**要实现的功能：**

- `--worktree [name]` CLI 启动标志：启动时直接创建 worktree，整个会话在隔离环境中运行
- sparse checkout 支持：新增 `worktree.sparsePaths` 配置项
- `.worktreeinclude` 文件：支持将 gitignore 的文件复制到 worktree
- tmux 集成：`--worktree --tmux` 在 tmux 会话中启动
- PR 引用解析：`--worktree=#123` 自动 fetch 并基于 PR 创建 worktree