# v0.4 → Main + Sub Agent 迁移计划

## 概述

将三实例方案 (v0.4) 迁移到 Main + Sub Agent 架构。

## 架构对比

### v0.4 (三实例)

```
┌─────────────────────────────────────────┐
│         tmux sanguo_dev                 │
│  ┌─────────────┐ ┌─────────┐ ┌───────┐ │
│  │ Claude      │ │ Codex   │ │Gemini │ │
│  │ (架构师)    │ │(后端)   │ │(前端) │ │
│  └─────────────┘ └─────────┘ └───────┘ │
└─────────────────────────────────────────┘

通信: SendMessage 跨实例
项目: 3 个独立目录
```

### Main + Sub Agent

```
┌─────────────────────────────────────────┐
│    sanguo_moziplus_v3 项目              │
│  ┌───────────────────────────────────┐  │
│  │     Main Agent (架构师)          │  │
│  │  - 分析需求                       │  │
│  │  - Agent() 指派 Sub Agent        │  │
│  │  - 整合结果                       │  │
│  └───────────────────────────────────┘  │
│           │              │              │
│           ▼              ▼              │
│  ┌──────────────┐ ┌──────────────┐     │
│  │ Sub Agent 1  │ │ Sub Agent 2  │     │
│  │ (Executor)  │ │ (Reviewer)  │     │
│  └──────────────┘ └──────────────┘     │
└─────────────────────────────────────────┘

通信: Agent 工具
项目: 1 个目录
```

## 迁移映射

| 组件 | v0.4 | 目标 | 操作 |
|------|------|------|------|
| **Claude Code 实例** | 3 个 | 1 个 | 移除多余实例 |
| **项目目录** | 3 个 | 1 个 | 保留 sanguo_moziplus_v3 |
| **CLAUDE.md** | 3 个文件 | 1 个文件 | 合并到主项目 |
| **SendMessage** | 跨实例 | Agent 工具 | 替换通信方式 |
| **tmux 配置** | ~/.tmux-sanguo.conf | 不需要 | 删除 |
| **启动脚本** | start-sanguo-env.sh | 不需要 | 删除 |
| **消息队列** | message.sh | 不需要 | 删除 |
| **ttyd Web** | 8088 端口 | 可选 | 保留用于远程 |
| **角色 Skills** | 3 个 | 3 个 | ✅ 保留 |
| **Superpowers** | 共享 | 共享 | ✅ 保留 |
| **GLM-5.2** | 统一后端 | 统一后端 | ✅ 保留 |

## 迁移步骤

### 步骤 1: 保留部分

#### 1.1 保留 Superpowers Skills

**无需操作** - 已安装在 `~/.claude/skills/`

#### 1.2 保留角色 Skills

**无需操作** - 已创建:
- `~/.claude/skills/architect-role/`
- `~/.claude/skills/backend-dev/`
- `~/.claude/skills/frontend-dev/`

#### 1.3 保留 GLM-5.2 配置

**无需操作** - 已在 `~/.claude/settings.json`

### 步骤 2: 创建 Main Agent 配置

#### 2.1 创建主项目 CLAUDE.md

在 `sanguo_moziplus_v3/.claude/CLAUDE.md`:

```markdown
# sanguo_moziplus_v3 - Main Agent

## 角色

你是架构师/项目经理，负责协调 Sub Agent 完成开发任务。

## 核心职责

- 接收用户需求
- 分析并拆分任务
- 指派 Sub Agent 执行
- 收集并整合结果
- 最终审查和验收

## 严格限制

**绝对不亲自编写代码**。所有编码任务通过 Agent 工具指派给 Sub Agent。

## 工作流程

1. 接收用户需求
2. 加载 architect-role skill
3. 分析需求，拆分任务
4. 使用 Agent 工具指派 Sub Agent:
   ```javascript
   Agent({
     subagent_type: "claude",
     prompt: "作为后端开发专家，实现: ..."
   })
   ```
5. 收集 Sub Agent 返回结果
6. 加载 CODE-REVIEW skill 审查
7. 整合结果并提交 Git

## Sub Agent 类型

- **Executor**: 执行编码任务 (加载 backend-dev/frontend-dev)
- **Reviewer**: 代码审查 (加载 CODE-REVIEW)

## 决策框架 (Linus 三问)

1. 这是现实问题还是想象问题？
2. 这个问题真的需要解决吗？
3. 这个方案真的能解决问题吗？
```

### 步骤 3: 创建工作流

已在 `.claude/workflows/feature-development.js`

### 步骤 4: 清理 v0.4 组件

#### 4.1 可以删除的文件

```bash
# tmux 配置 (可选删除，如果不用三实例)
rm ~/.tmux-sanguo.conf

# 旧项目目录 (可选删除，如果不再使用)
rm -rf ~/.claude/projects/sanguo-main
rm -rf ~/.claude/projects/sanguo-backend
rm -rf ~/.claude/projects/sanguo-frontend

# 启动脚本 (可选删除)
rm ~/.claude/messages/sanguo/start-sanguo-env.sh
rm ~/.claude/messages/sanguo/message.sh
```

#### 4.2 保留的文件

```bash
# 角色 Skills - 保留
~/.claude/skills/architect-role/
~/.claude/skills/backend-dev/
~/.claude/skills/frontend-dev/

# GLM-5.2 配置 - 保留
~/.claude/settings.json

# 可选: ttyd 配置 (如果需要 Web 访问)
~/.ttyd
```

### 步骤 5: 更新文档

#### 5.1 创建新设计文档

`docs/design/06-design-v0.5-sub-agent.md`

#### 5.2 更新快速参考

`docs/06-quick-reference-v0.5.md`

### 步骤 6: 验证测试

#### 6.1 测试 Agent 工具

```javascript
// 在 Main Agent 中测试
Agent({
  subagent_type: "claude",
  prompt: "作为后端开发专家，编写一个简单的 Hello World API"
})
```

#### 6.2 测试工作流

```javascript
Agent({
  scriptPath: ".claude/workflows/feature-development.js",
  args: "实现用户登录功能"
})
```

## 对比表

| 方面 | v0.4 三实例 | Main + Sub Agent |
|------|-------------|------------------|
| **复杂度** | 🟡 中等 | 🟢 简单 |
| **启动** | 需要启动脚本 | 直接使用 |
| **通信** | SendMessage (有限制) | Agent 工具 |
| **隔离** | 实例级别 | 会话级别 |
| **并行** | ⚠️ 复杂 | ✅ 支持 |
| **学习成本** | 🟡 中等 | 🟢 低 |
| **维护成本** | 🟡 中等 | 🟢 低 |
| **Web 访问** | ✅ ttyd + tmux | ⚠️ 需要 Claude Code |

## 优势

Main + Sub Agent 方案优势:

1. **更简单**: 不需要 tmux、启动脚本
2. **更灵活**: Sub Agent 自动隔离、并行执行
3. **更可靠**: Agent 工具是内置功能，无跨实例限制
4. **更易维护**: 单一项目目录

## 迁移检查清单

### 保留
- [x] Superpowers skills
- [x] 角色 Skills (architect-role, backend-dev, frontend-dev)
- [x] GLM-5.2 配置
- [ ] ttyd (可选)

### 创建
- [ ] .claude/CLAUDE.md
- [ ] .claude/workflows/feature-development.js
- [ ] docs/design/06-design-v0.5-sub-agent.md
- [ ] docs/06-quick-reference-v0.5.md

### 删除
- [ ] ~/.tmux-sanguo.conf
- [ ] ~/.claude/projects/sanguo-*
- [ ] ~/.claude/messages/sanguo/*.sh

### 测试
- [ ] Agent 工具测试
- [ ] 工作流测试
- [ ] Skills 加载测试

## 回滚方案

如果需要回滚到 v0.4:

```bash
# 恢复项目目录
# 从 Git 恢复或重新创建

# 重新运行 v0.4 设置
~/.claude/messages/sanguo/test-sanguo-env.sh
~/.claude/messages/sanguo/start-sanguo-env.sh
```

## 相关文档

- [v0.4 设计文档](./04-design-v0.4.md)
- [Sub Agent 方案](../sub-agent-orchestration.md)
- [Agent 工具文档](https://docs.anthropic.com/claude-code/agent)