Worktree 通用能力设计

问题陈述

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

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

现状对比

设计原则

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 A / B / C 不新增任何配置项。

工具设计

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 的触发依赖用户明确提及，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：为每个工具编写使用说明，明确何时调用、何时不调用

影响文件：

不在 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 代码路径。

影响文件：

Phase C：会话完整性（SessionService 持久化 + UI 安全网）

目标： worktree 状态在会话中断后可恢复，用户在界面上始终知道自己在哪个 worktree 里，退出会话时有安全提示。

要实现的功能：

SessionService worktree 状态持久化 + --resume 恢复：

• SessionService 扩展 WorktreeSession 字段，记录 { slug, worktreePath, worktreeBranch, originalCwd, originalBranch }
• EnterWorktreeTool 调用 sessionService.setWorktreeSession() 写入状态
• ExitWorktreeTool 调用 sessionService.clearWorktreeSession() 清除状态
• --resume 启动路径读取该字段，恢复 targetDir 并向模型注入上下文提示

Post-creation setup：

• 创建 worktree 后自动执行 git config core.hooksPath <mainRepo>/.git/hooks，确保 worktree 内的提交与主仓库 hooks 行为一致

StatusLine worktree 展示：

• UIStateContext 新增 activeWorktree 字段（从 session 状态读取），在会话进入 / 退出 worktree 时更新
• StatusLineCommandInput payload 新增 worktree?: { slug: string; branch: string } 字段，供用户 statusline 脚本使用
• Footer 在 activeWorktree 非空时内置展示一行 ⎇ <branch> (<slug>)，无需用户配置 statusline 脚本即可获得基本可见性

WorktreeExitDialog：

• 新增 WorktreeExitDialog.tsx 组件，参考现有 Dialog 写法
• 修改退出键（Ctrl+C / Ctrl+D）处理逻辑：检测到 activeWorktree 非空时，拦截第二次确认，展示 Dialog 提示用户选择 keep 或 remove
• keep / remove 操作复用 ExitWorktreeTool 的现有路径

影响文件：

Phase D：启动时配置（--worktree CLI 标志 + 目录符号链接）

目标： 支持在启动时直接进入 worktree，并通过目录符号链接减少大型项目的磁盘开销。

要实现的功能：

--worktree [name] CLI 启动标志：

• packages/cli/src/args.ts 新增 --worktree [name] 参数
• 启动流程在进入主循环前调用 createUserWorktree()，将 targetDir 设为 worktree 路径，并写入 SessionService 状态
• 整个会话从启动即在 worktree 环境中运行，退出时触发 WorktreeExitDialog

worktree.symlinkDirectories 配置项：

• settings schema 新增 worktree.symlinkDirectories: string[]
• createUserWorktree() 后遍历配置，调用 fs.symlink() 将主仓库目录链接进 worktree
• 跳过目标不存在的项；目标已存在时跳过（不覆盖）

影响文件：

Future：高级功能（按需实现）

以下功能面向更特定的使用场景，当前阶段不纳入排期，待用户需求明确后再评估实现。