# 使用 jcad 进行多 feature 并行开发

## 概述

`jcad`（Jarvis Code Agent Dispatcher）是专门为并行开发设计的工具，自动启用非交互模式、worktree 隔离和任务派发，适合快速启动多个独立的代码任务。

**重要提示**：jcad 需要配合 tmux 使用才能实现任务派发功能。如果系统未安装 tmux，jcad 将无法正常工作。

## 核心特性

- **自动 worktree 隔离**：每个任务自动创建独立的 Git worktree
- **自动任务派发**：使用 tmux 将任务派发到独立 panel，支持并行执行
- **自动清理**：任务完成后自动清理 worktree 和临时分支
- **快速启动**：简化参数，快速启动代码任务

## 使用方法

### 基本用法

```bash
# 单行任务
jcad "实现用户注册和登录功能"

# 多行任务（自动创建临时文件）
jcad "
实现用户认证模块：
1. 用户注册
2. 用户登录
3. 密码重置
"

# 使用任务文件
jcad feature_task.txt
```

### 并行启动多个任务

在多个终端中同时启动不同的任务，每个任务会在独立的 tmux panel 中运行：

```bash
# 终端 1
jcad "实现用户模块"

# 终端 2
jcad "实现订单模块"

# 终端 3
jcad "实现支付模块"
```

## Worktree 隔离机制

### 什么是 Worktree

Git worktree 允许你在同一个仓库中同时检出多个分支到不同的目录。jcad 利用这个特性为每个任务创建独立的开发环境，实现完全隔离的并行开发。

### Worktree 工作流程

1. **创建阶段**：
   - 自动检测主仓库是否有未提交的更改，如有则自动提交
   - 如果仓库没有初始提交，自动创建初始提交
   - 生成唯一的分支名：`jarvis-{项目名}-{时间戳}-{随机后缀}`
   - 在仓库父目录创建独立的 worktree 目录
   - 设置 `.jarvis` 目录的分层软链接结构

2. **开发阶段**：
   - 在独立的 worktree 目录中执行代码修改
   - 所有变更都在独立分支上进行，不影响主分支
   - `.jarvis/rule` 和 `.jarvis/rules/` 独立复制，避免分支间冲突
   - `.jarvis/memory/` 等运行时数据通过软链接共享

3. **合并阶段**：
   - 使用 rebase 策略将 worktree 分支变基到主分支
   - 通过 fast-forward 合并保持线性 Git 历史
   - 如果出现冲突，提示手动解决

4. **清理阶段**：
   - 删除 worktree 目录
   - 删除临时分支

### Worktree 的优势

- **完全隔离**：每个任务在独立分支和目录中开发，互不干扰
- **安全可靠**：主分支始终保持稳定，不会受到并行任务的影响
- **自动管理**：无需手动创建和删除 worktree，系统自动处理
- **配置共享**：运行时数据通过软链接共享，避免重复和混乱
- **配置独立**：规则文件独立复制，避免分支间修改冲突

### .jarvis 目录处理

jcad 采用分层软链接策略处理 `.jarvis` 目录：

- **独立复制**：`.jarvis/rule` 和 `.jarvis/rules/` 在每个 worktree 中独立复制
- **软链接共享**：`.jarvis/memory/` 等运行时数据通过软链接共享主仓库的数据

这样设计的原因：

- 规则文件需要独立，避免不同分支间的修改冲突
- 运行时数据需要共享，避免重复和混乱

## 任务管理

### 查看任务状态

使用 tmux 命令查看所有运行中的任务：

```bash
tmux ls                    # 列出所有 session
tmux attach -t <session>  # 附加到特定 session
```

### 任务完成处理

任务完成后，jcad 会自动：

1. 将 worktree 的变更合并回主分支（使用 rebase 策略）
2. 删除 worktree 目录
3. 删除临时分支

如果合并有冲突，jcad 会提示你手动解决。

## 最佳实践

### 任务划分

- **独立任务**：确保任务之间没有文件依赖，可以并行执行
- **依赖任务**：有依赖关系的任务应串行执行，或在任务描述中明确依赖关系

### 命名规范

为任务使用清晰的描述，便于后续识别和管理。

### 避免冲突

1. **任务独立性**：确保任务之间没有文件依赖
2. **及时合并**：完成一个任务后尽快合并，减少冲突概率
3. **小步提交**：将大任务拆分为多个小任务，降低冲突风险

## Tmux 配置

jcad 依赖 tmux 来实现任务派发功能。建议使用以下配置以获得最佳体验：

```bash
git clone https://github.com/skyfireitdiy/dotfile
cd dotfile
./install.sh tmux
```

**注意**：此配置为非强制要求，但强烈推荐使用，可以优化 tmux 的使用体验。

## 注意事项

- **tmux 依赖**：jcad 需要 tmux 才能正常工作，请确保系统已安装 tmux
- jcad 自动启用非交互模式（`-n`）、worktree（`-w`）和 dispatch（`--dispatch`）
- 非交互模式下会自动进行代码审查（review）
- 任务文件判断：如果文件存在则作为任务文件处理，否则作为任务内容处理
- 多行任务会自动创建临时文件处理
- 推荐同时运行 3-5 个任务，避免超过 10 个任务导致合并冲突

## 与 jca 的区别

| 特性 | jcad | jca |
|------|------|-----|
| **并行开发** | ✅ 自动支持 | ⚠️ 需手动管理 |
| **Worktree 隔离** | ✅ 自动启用 | ⚠️ 需手动指定 `-w` |
| **任务派发** | ✅ 自动派发到 tmux | ⚠️ 需手动指定 `--dispatch` |
| **交互模式** | ❌ 非交互模式 | ✅ 完整交互 |
| **适用场景** | 快速任务派发、并行开发 | 交互式开发、学习探索 |

**选择建议**：

- **使用 jcad**：需要并行开发多个独立功能、快速任务派发
- **使用 jca**：需要交互式开发、逐步完善代码、学习探索

---

**文档版本**：v1.0  
**最后更新**：2025-01-12  
**维护者**：Jarvis Team
