> ## Documentation Index
> Fetch the complete documentation index at: https://gnero.genetind.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 并行会话

> 并行运行多个隔离的 AI 会话

## 两种方式

Trellis 支持两种方式运行多个 agent：

| 方式                | 说明                         | 隔离性       |
| ----------------- | -------------------------- | --------- |
| **Multi-Agent**   | 多个 agent 在同一目录             | 共享文件，可能冲突 |
| **Multi-Session** | 每个 agent 在独立的 Git worktree | 完全隔离，无冲突  |

本指南介绍 **Multi-Session** —— 基于 worktree 的方式。

## 为什么用 Multi-Session

有些任务是独立的。加登录页面不影响加设置页面。用独立的 worktree，agent 之间互不干扰。

```
主仓库
    │
    ├── worktree-1/  →  会话 1 (feature-a)
    ├── worktree-2/  →  会话 2 (feature-b)
    └── worktree-3/  →  会话 3 (feature-c)
```

每个 worktree 是独立的 checkout，在独立的分支上。开发过程中不会有合并冲突。

完成后，每个会话创建一个 PR。你审查然后合并。

## 配置

启动前，在项目根目录创建 `worktree.yaml`：

```yaml theme={null}
# worktree.yaml
base_branch: main
worktree_dir: ../.trellis-worktrees # worktree 创建位置
tasks:
  - id: feature-a
    branch: feature/login-page
    prd: |
      添加登录页面，包含邮箱/密码认证。
      包括表单验证和错误处理。
  - id: feature-b
    branch: feature/settings-page
    prd: |
      添加用户设置页面。
      允许修改显示名和密码。
```

每个任务定义：

* `id`：唯一标识符
* `branch`：Git 分支名
* `prd`：此任务的需求

## 启动并行会话

在 Claude Code 里用 `/trellis:parallel` 命令。它会引导你：

* 定义任务
* 创建 worktree
* 启动会话

这会创建：

* 每个任务一个 worktree
* 每个任务一个 Claude Code 会话
* 每个任务一个分支

每个会话独立运行。

## 监控进度

查看状态：

```bash theme={null}
python3 .trellis/scripts/multi_agent/status.py
```

输出会显示每个任务的当前阶段和分支。

## 会话流水线

每个会话经过这些阶段：

1. **Plan** - 理解需求，找出要改的文件
2. **Implement** - 写代码
3. **Check** - 按规范审查，自己修问题
4. **PR** - 创建 pull request

check 阶段有个 "Ralph Loop"——如果发现问题，它会回去修。这防止提交质量差的 PR。

## 什么时候用

适合：

* 独立的功能
* 并行修 bug
* 生成变体（同一问题的不同方案）

不适合：

* 互相依赖的功能
* 改同一个文件的工作
* 需要跟 AI 反复迭代时

## 清理

完成后清理 worktree：

```bash theme={null}
python3 .trellis/scripts/multi_agent/cleanup.py
```

这会删除 worktree 但保留分支。合并后的分支正常删就行。

## 平台支持

| 功能                      | Claude Code | Cursor  | iFlow  | OpenCode | Codex   |
| ----------------------- | ----------- | ------- | ------ | -------- | ------- |
| Multi-Agent（同目录）        | ✅ 完全支持      | ⚠️ 有限支持 | ✅ 完全支持 | ⚠️ 有限支持  | ⚠️ 有限支持 |
| Multi-Session（worktree） | ✅ 完全支持      | ❌ 不支持   | ✅ 完全支持 | ❌ 不支持    | ❌ 不支持   |

Multi-Session 需要 hooks 来自动注入上下文（目前 Claude Code 和 iFlow 支持）。

### Agent 流水线

每个 Multi-Session 任务使用 6-agent 流水线：

| Agent         | 职责           |
| ------------- | ------------ |
| **plan**      | 分析需求，规划要改的文件 |
| **dispatch**  | 编排整个流水线      |
| **implement** | 写代码          |
| **check**     | 按规范审查，自己修问题  |
| **debug**     | 修复特定问题       |
| **research**  | 搜索代码库，找模式    |

你也需要足够的 API 额度。三个会话意味着三倍的 token 消耗。