sanguo_moziplus_v3/docs/design/04-design-v0.4.md

# sanguo_moziplus_v3 设计文档 v0.4

**项目名称**: sanguo_moziplus_v3
**版本**: v0.4
**创建日期**: 2026-06-30
**状态**: Draft
**基于**: v0.3 + 三实例方案

---

## 1. 版本变更

| 版本 | 变更说明 | 日期 |
|------|---------|------|
| v0.1 | 初始设计 | 2026-06-29 |
| v0.2 | 基于 videotext 调研更新，集成 GLM-5.2、Web 访问 | 2026-06-29 |
| v0.3 | 移除 CCB，采用 Claude Code 内置多 Agent 能力 | 2026-06-30 |
| **v0.4** | **三实例方案：所有 Agent 共享 Superpowers skills** | **2026-06-30** |

### v0.4 核心变化

| 变更项 | v0.3 | v0.4 | 原因 |
|--------|------|------|------|
| **Agent 数量** | 1 个主 Agent | **3 个独立实例** | 清晰的角色隔离 |
| **实例类型** | Claude Code 主实例 | **3 个 Claude Code 实例** | 统一的技术栈 |
| **Skills 访问** | 主实例访问 | **所有实例共享 Superpowers** | 统一的能力库 |
| **角色定义** | 通过 Agent 类型 | **通过 CLAUDE.md** | 更清晰的角色隔离 |
| **协作方式** | Agent 工具调用 | **SendMessage 跨实例** | 更灵活的协作 |

---

## 2. 架构概述

### 2.1 系统架构图

```
┌─────────────────────────────────────────────────────────────────────┐
│                        tmux sanguo_dev 会话                         │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │  tmux pane #0: Claude (架构师/项目经理)                        │ │
│  │  项目: ~/.claude/projects/sanguo-main                         │ │
│  │  配置: sanguo-main/.claude/CLAUDE.md                          │ │
│  │  职责: 需求分析、架构设计、任务拆分、审查、验收               │ │
│  │  限制: 绝对不亲自编写代码                                     │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │  tmux pane #1: Codex (后端开发)                               │ │
│  │  项目: ~/.claude/projects/sanguo-backend                      │ │
│  │  配置: sanguo-backend/.claude/CLAUDE.md                        │ │
│  │  职责: 服务端代码、API、数据库、Migration、测试                │ │
│  │  限制: 只处理后端任务                                         │ │
│  └───────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │  tmux pane #2: Gemini (前端开发)                              │ │
│  │  项目: ~/.claude/projects/sanguo-frontend                     │ │
│  │  配置: sanguo-frontend/.claude/CLAUDE.md                       │ │
│  │  职责: 前端组件、页面、样式、交互逻辑、审查                    │ │
│  │  限制: 只处理前端任务                                         │ │
│  └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                  Superpowers Skills (共享)                         │
│  路径: ~/.claude/skills/                                           │
│  所有三个实例都可以访问                                           │
│                                                                     │
│  ┌───────────────────────────────────────────────────────────────┐ │
│  │ • CODE-REVIEW (代码审查专业知识)                               │ │
│  │ • test-engineer (测试专业知识)                                │ │
│  │ • copywriting-base (营销文案等47个技能)                        │ │
│  │ • debugger (调试技能)                                          │ │
│  │ • ... (100+ 专业技能)                                          │ │
│  └───────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                      GLM-5.2 (统一后端)                             │
│  端点: https://api.z.ai/api/anthropic                             │
│  所有三个实例通过同一模型执行                                      │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                    Web 访问层 (ttyd)                                │
│  端口: 8088                                                         │
│  访问: http://YOUR_LAN_IP:8088                                      │
│  共享 tmux sanguo_dev 会话                                          │
└─────────────────────────────────────────────────────────────────────┘
```

### 2.2 完整链路

```
用户输入需求
     ↓
Claude (架构师) 接收
     ↓
加载 planning skill 进行规划
     ↓
SendMessage 指派任务:
  → backend: "实现后端 API"
  → frontend: "实现前端页面"
     ↓
Codex (后端) 加载 backend-dev skill
Gemini (前端) 加载 frontend-dev skill
     ↓
各自执行任务 (通过 GLM-5.2)
     ↓
SendMessage 返回结果给架构师
     ↓
Claude (架构师) 加载 CODE-REVIEW skill 审查
     ↓
Git 提交
```

---

## 3. 三实例角色定义

### 3.1 Claude — 架构师/项目经理

**项目配置**:
- 项目路径: `~/.claude/projects/sanguo-main`
- CLAUDE.md: `sanguo-main/.claude/CLAUDE.md`

**角色定义**:
```markdown
# sanguo-main/.claude/CLAUDE.md

## 角色定义

你是架构师/项目经理，负责项目的整体规划和协调。

### 核心职责

- 需求分析和理解
- 架构设计和技术选型
- 任务拆分和优先级排序
- 代码审核和质量把关
- 最终验收和 Git 提交管理

### 严格限制

**绝对不亲自编写代码**。所有编码任务必须通过 SendMessage 指派给 backend 或 frontend agent。

### 工作流程

1. 接收用户需求
2. 加载 planning skill 进行规划
3. 拆分任务为后端和前端两部分
4. 通过 SendMessage 指派任务:
   - SendMessage({ to: "backend", message: "..." })
   - SendMessage({ to: "frontend", message: "..." })
5. 等待 agents 返回结果
6. 加载 CODE-REVIEW skill 审查代码
7. 整合结果并提交 Git

### 协作规范

- 使用 Superpowers skills 进行:
  - 规划: planning skill
  - 审查: CODE-REVIEW skill
  - 调试: debugger skill
  - 验收: test-engineer skill

- 向 backend/frontend 指派任务时，提供:
  - 清晰的任务描述
  - 技术要求和约束
  - 预期输出格式
  - 验收标准

### 决策框架 (Linus 三问)

1. 这是现实问题还是想象问题？ → 拒绝过度设计
2. 这个问题真的需要解决吗？ → 拒绝伪需求
3. 这个方案真的能解决问题吗？ → 拒绝自嗨
```

**Superpowers 使用**:
- `planning` — 技术方案规划
- `CODE-REVIEW` — 代码审查
- `debugger` — 问题调试
- `test-engineer` — 测试策略

---

### 3.2 Codex — 后端开发

**项目配置**:
- 项目路径: `~/.claude/projects/sanguo-backend`
- CLAUDE.md: `sanguo-backend/.claude/CLAUDE.md`

**角色定义**:
```markdown
# sanguo-backend/.claude/CLAUDE.md

## 角色定义

你是后端开发专家，专注于服务器端代码实现。

### 核心职责

- 服务端代码实现 (Node.js/Python/Go 等)
- API 设计和实现 (REST/GraphQL/gRPC)
- 数据库设计和 Migration
- 单元测试和集成测试
- 性能优化和错误处理

### 严格限制

- 只处理后端任务
- 拒绝前端相关任务 (组件、页面、样式)
- 如果收到前端任务，明确拒绝并告知转给 frontend agent

### 工作流程

1. 从架构师接收任务 (通过 SendMessage)
2. 加载 backend-dev skill 进行分析
3. 设计实现方案
4. 编写代码
5. 编写测试
6. 自测验证
7. 返回结果给架构师 (通过 SendMessage)

### 技术标准

- 代码规范: 遵循项目约定的代码风格
- API 设计: RESTful 原则，清晰的错误码
- 数据库: 规范化设计，适当的索引
- 测试: 单元测试覆盖率 > 80%
- 文档: API 文档 (OpenAPI/Swagger)

### Superpowers 使用

- `CODE-REVIEW` — 自我审查代码
- `debugger` — 调试后端问题
- `test-engineer` — 编写测试

### 输出格式

完成任务后，通过 SendMessage 返回:
- 实现的文件列表
- API 端点说明
- 数据库变更 (如有)
- 测试结果
- 已知问题或限制
```

**backend-dev Skill**:
```markdown
## ~/.claude/skills/backend-dev/SKILL.md

你现在是后端开发专家。专注于服务器端代码实现。

### 核心原则

1. **API First**: 先设计 API，再实现逻辑
2. **测试驱动**: 先写测试，再写代码
3. **安全优先**: 输入验证、输出编码、权限检查
4. **性能意识**: 避免N+1查询、适当缓存、异步处理

### 实现流程

1. **理解需求**: 确认功能、约束、验收标准
2. **设计 API**: 端点、方法、参数、响应
3. **设计数据库**: 表结构、索引、关系
4. **实现逻辑**: 按照最佳实践编写代码
5. **编写测试**: 单元测试、集成测试
6. **自测验证**: 确保功能正常

### 拒绝任务

如果任务涉及:
- 前端组件
- 页面样式
- UI 交互
- 浏览器兼容性

明确拒绝并告知转给 frontend agent。
```

---

### 3.3 Gemini — 前端开发

**项目配置**:
- 项目路径: `~/.claude/projects/sanguo-frontend`
- CLAUDE.md: `sanguo-frontend/.claude/CLAUDE.md`

**角色定义**:
```markdown
# sanguo-frontend/.claude/CLAUDE.md

## 角色定义

你是前端开发专家，专注于用户界面实现。

### 核心职责

- 前端组件开发 (React/Vue/等)
- 页面布局和样式实现
- 用户交互逻辑
- 前端性能优化
- 浏览器兼容性处理
- 代码审查和安全审计

### 严格限制

- 只处理前端任务
- 拒绝后端相关任务 (API、数据库、服务器逻辑)
- 如果收到后端任务，明确拒绝并告知转给 backend agent

### 工作流程

1. 从架构师接收任务 (通过 SendMessage)
2. 加载 frontend-dev skill 进行分析
3. 设计组件结构
4. 实现页面和样式
5. 实现交互逻辑
6. 浏览器测试
7. 返回结果给架构师 (通过 SendMessage)

### 技术标准

- 组件化: 可复用的组件设计
- 响应式: 适配不同设备和屏幕
- 性能: 懒加载、代码分割、缓存优化
- 可访问性: ARIA 标准、键盘导航
- 兼容性: 支持主流浏览器

### Superpowers 使用

- `CODE-REVIEW` — 审查前端代码
- `ui-ux-pro-max` — UI/UX 设计指导
- `debugger` — 调试前端问题

### 输出格式

完成任务后，通过 SendMessage 返回:
- 实现的组件列表
- 页面预览或截图
- 交互说明
- 性能优化措施
- 兼容性问题 (如有)
```

**frontend-dev Skill**:
```markdown
## ~/.claude/skills/frontend-dev/SKILL.md

你现在是前端开发专家。专注于用户界面实现。

### 核心原则

1. **组件优先**: 可复用的组件设计
2. **移动优先**: 响应式设计，移动设备优先
3. **渐进增强**: 基础功能优先，逐步增强
4. **性能第一**: 懒加载、代码分割、资源优化

### 实现流程

1. **理解需求**: 确认功能、UI设计、交互要求
2. **组件设计**: 拆分为可复用的组件
3. **样式实现**: 响应式布局、动画效果
4. **交互实现**: 事件处理、状态管理
5. **测试验证**: 浏览器测试、性能测试
6. **优化改进**: 性能优化、兼容性处理

### 拒绝任务

如果任务涉及:
- API 端点实现
- 数据库设计
- 服务器逻辑
- 后端性能优化

明确拒绝并告知转给 backend agent。
```

---

## 4. Superpowers Skills 共享

### 4.1 共享机制

**所有三个实例共享同一套 Superpowers skills**:

```
~/.claude/skills/
├── CODE-REVIEW/              ← 三实例共享
├── test-engineer/            ← 三实例共享
├── copywriting-base/         ← 三实例共享
│   ├── skills/
│   │   ├── copywriting/      ← 三实例共享
│   │   ├── seo-audit/        ← 三实例共享
│   │   └── ... (47 skills)
├── debugger/                 ← 三实例共享
├── ui-ux-pro-max/            ← 三实例共享
└── ... (100+ skills)
```

### 4.2 使用差异

**虽然共享同一套 skills，但使用方式因角色而异**:

| Skill | Claude (架构师) | Codex (后端) | Gemini (前端) |
|-------|----------------|-------------|---------------|
| **planning** | ✅ 主要使用 | ⚠️ 仅规划自己的实现 | ⚠️ 仅规划自己的实现 |
| **CODE-REVIEW** | ✅ 审查所有代码 | ✅ 自我审查 | ✅ 自我审查 + 审查前端 |
| **debugger** | ✅ 调试整体问题 | ✅ 调试后端问题 | ✅ 调试前端问题 |
| **test-engineer** | ✅ 设计测试策略 | ✅ 编写后端测试 | ✅ 编写前端测试 |
| **ui-ux-pro-max** | ❌ 不使用 | ❌ 不使用 | ✅ 主要使用 |
| **copywriting** | ❌ 不使用 | ❌ 不使用 | ⚠️ 仅文案相关 |

### 4.3 角色 Skills

**新增三个角色专属 skills**:

```
~/.claude/skills/
├── architect-role/           ← 架构师专属
├── backend-dev/              ← 后端开发专属
└── frontend-dev/             ← 前端开发专属
```

---

## 5. 协作流程

### 5.1 SendMessage 机制

**跨实例通信**:

```
Claude (架构师)                 Codex (后端)
     │                              │
     │─── SendMessage ──────────────>│
     │   to: "backend"              │
     │   message: "实现用户 API"     │
     │                              │
     │                              │
     │<──── SendMessage ─────────────│
     │   to: "main"                 │
     │   message: "后端完成，返回..." │
     │                              │
```

**验证需求**: 需要验证 Claude Code 的 SendMessage 是否支持跨实例通信。

### 5.2 典型工作流

**场景：实现用户认证系统**

```
1. 用户: "实现用户认证系统"
      ↓
2. Claude (架构师) 接收
   - 加载 planning skill
   - 规划任务: JWT认证 + 登录页面
      ↓
3. Claude 指派任务
   - SendMessage({ to: "backend", message: "实现JWT认证API" })
   - SendMessage({ to: "frontend", message: "实现登录注册页面" })
      ↓
4. Codex (后端) 执行
   - 加载 backend-dev skill
   - 设计API: /auth/login, /auth/register
   - 实现JWT逻辑
   - 编写测试
   - SendMessage({ to: "main", message: "后端完成" })
      ↓
5. Gemini (前端) 执行
   - 加载 frontend-dev skill
   - 设计登录页面组件
   - 实现表单验证
   - 调用后端API
   - SendMessage({ to: "main", message: "前端完成" })
      ↓
6. Claude (架构师) 整合
   - 加载 CODE-REVIEW skill
   - 审查后端代码
   - 审查前端代码
   - 集成测试
   - Git 提交
```

### 5.3 错误处理

**任务拒绝流程**:

```
Codex (后端) 收到前端任务
     ↓
加载 backend-dev skill
     ↓
识别为前端任务
     ↓
SendMessage({ to: "main", message: "这不是后端任务，请转给 frontend" })
     ↓
Claude (架构师) 重新指派
     ↓
SendMessage({ to: "frontend", message: "原任务..." })
```

---

## 6. 实施步骤

### Phase 1: 环境准备

#### 1.1 配置 GLM-5.2

**创建 `~/.claude/settings.json`**:
```json
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_API_KEY": "6903e83faf454106aa7529c9e18e2ea5.gYMSjWwk1XDN0U5h",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
  }
}
```

#### 1.2 安装 ttyd

```bash
brew install ttyd
```

**配置 `~/.ttyd`**:
```
address = "0.0.0.0"
port = "8088"
permit-write = true
enable-basic-auth = false
```

---

### Phase 2: 创建项目结构

#### 2.1 创建三个项目目录

```bash
# 创建项目目录
mkdir -p ~/.claude/projects/sanguo-main/.claude
mkdir -p ~/.claude/projects/sanguo-backend/.claude
mkdir -p ~/.claude/projects/sanguo-frontend/.claude
```

#### 2.2 创建 CLAUDE.md 文件

**sanguo-main/.claude/CLAUDE.md**:
```markdown
# sanguo-main — 架构师/项目经理

[使用第 3.1 节的完整内容]
```

**sanguo-backend/.claude/CLAUDE.md**:
```markdown
# sanguo-backend — 后端开发

[使用第 3.2 节的完整内容]
```

**sanguo-frontend/.claude/CLAUDE.md**:
```markdown
# sanguo-frontend — 前端开发

[使用第 3.3 节的完整内容]
```

---

### Phase 3: 创建角色 Skills

#### 3.1 创建 architect-role skill

```bash
mkdir -p ~/.claude/skills/architect-role
```

**`~/.claude/skills/architect-role/SKILL.md`**:
```markdown
---
name: architect-role
description: 当你作为架构师/项目经理角色时使用。负责需求分析、架构设计、任务拆分、代码审查、最终验收。绝对不亲自编写代码。
---

# Architect Role

你现在是架构师/项目经理角色。

## 核心职责

- 需求分析和理解
- 架构设计和技术选型
- 任务拆分和优先级排序
- 代码审核和质量把关
- 最终验收和 Git 提交管理

## 严格限制

**绝对不亲自编写代码**。

## 工作流程

1. 接收用户需求
2. 进行需求分析
3. 规划技术方案
4. 拆分任务
5. 指派给合适的 agent (backend/frontend)
6. 等待并整合结果
7. 审查和验收
8. 提交 Git
```

#### 3.2 创建 backend-dev skill

```bash
mkdir -p ~/.claude/skills/backend-dev
```

**`~/.claude/skills/backend-dev/SKILL.md`**:
```markdown
---
name: backend-dev
description: 后端开发专家。专注于服务器端代码、API、数据库、测试。只处理后端任务，拒绝前端任务。
---

# Backend Developer

你现在是后端开发专家。

## 核心职责

- 服务端代码实现
- API 设计和实现
- 数据库设计和 Migration
- 单元测试和集成测试

## 严格限制

- 只处理后端任务
- 拒绝前端相关任务

## 实现流程

1. 理解需求
2. 设计 API
3. 设计数据库
4. 实现代码
5. 编写测试
6. 自测验证
```

#### 3.3 创建 frontend-dev skill

```bash
mkdir -p ~/.claude/skills/frontend-dev
```

**`~/.claude/skills/frontend-dev/SKILL.md`**:
```markdown
---
name: frontend-dev
description: 前端开发专家。专注于组件、页面、样式、交互。只处理前端任务，拒绝后端任务。
---

# Frontend Developer

你现在是前端开发专家。

## 核心职责

- 前端组件开发
- 页面布局和样式
- 用户交互逻辑
- 浏览器兼容性

## 严格限制

- 只处理前端任务
- 拒绝后端相关任务

## 实现流程

1. 理解需求
2. 组件设计
3. 样式实现
4. 交互实现
5. 浏览器测试
```

---

### Phase 4: tmux 会话配置

#### 4.1 创建 tmux 配置

**创建 `~/.tmux-sanguo.conf`**:
```bash
# sanguo tmux 配置
new-session -d -s sanguo_dev -n "main"

# pane 0: main (架构师)
selectp -t 0
split-window -h -p 50

# pane 1: backend (后端开发)
selectp -t 1
split-window -v -p 50

# pane 2: frontend (前端开发)
selectp -t 2

# 回到 main pane
selectp -t 0

# 设置 pane 标题
select-pane -t 0 -T "Claude (架构师)"
select-pane -t 1 -T "Codex (后端)"
select-pane -t 2 -T "Gemini (前端)"
```

#### 4.2 启动 tmux 会话

```bash
# 加载配置启动 tmux
tmux new -f ~/.tmux-sanguo.conf

# 或手动创建
tmux new -s sanguo_dev
tmux split-window -h
tmux split-window -v
```

#### 4.3 在各 pane 中启动 Claude Code

**pane 0 (架构师)**:
```bash
cd ~/.claude/projects/sanguo-main
claude
# 设置为架构师角色
```

**pane 1 (后端)**:
```bash
cd ~/.claude/projects/sanguo-backend
claude
# 设置为后端开发角色
```

**pane 2 (前端)**:
```bash
cd ~/.claude/projects/sanguo-frontend
claude
# 设置为前端开发角色
```

---

### Phase 5: SendMessage 机制验证

#### 5.1 验证结果 (2026-06-30)

| 项目 | 结果 | 说明 |
|------|------|------|
| **跨会话能力** | ✅ 支持 | Claude Code v2.1.166+ 支持跨会话 SendMessage |
| **当前版本** | ✅ 2.1.187 | 已包含跨会话功能 |
| **安全限制** | ⚠️ 存在 | 有权限相关限制 |

**关键限制** (来源: changelog v2.1.166):
1. **权限限制**: 跨会话消息不携带用户权限
2. **工具调用**: 接收方拒绝中继的权限请求
3. **Auto 模块**: 自动模式会阻止跨会话消息

#### 5.2 对 v0.4 方案的影响

| 功能 | 原设计 | 实际情况 | 调整方案 |
|------|--------|----------|----------|
| **传递任务** | SendMessage 传递任务 | ✅ 可用 | 无需调整 |
| **执行工具** | 跨实例工具调用 | ❌ 受限 | 各实例自主执行 |
| **自动模式** | 自动指派/接收 | ❌ 受限 | 需手动确认 |

#### 5.3 实施建议

1. **保持设计**: SendMessage 可用于传递任务描述和结果
2. **自主执行**: 每个实例独立执行工具，不依赖跨实例调用
3. **文件辅助**: 大量代码传递使用共享文件系统

#### 5.4 工作流程调整

**原设计流程**:
```
架构师 SendMessage(任务) → 后端 执行工具 → 架构师
```

**实际可行流程**:
```
架构师 SendMessage(任务描述) → 后端 接收消息 → 后端 自主执行 → 后端 SendMessage(结果)
```

#### 5.5 备选方案 (保留)

如果遇到 SendMessage 问题，可以使用文件系统作为消息队列:

```bash
# 创建消息目录
mkdir -p ~/.claude/messages/sanguo

# 架构师发送任务
echo '{"to": "backend", "task": "...", "files": [...]}' > ~/.claude/messages/sanguo/backend_$(date +%s).json

# 后端监听并处理
fswatch ~/.claude/messages/sanguo/backend_*.json | xargs -I {} sh -c 'process_task {}'
```

---

### Phase 6: 启动 Web 访问

```bash
# 启动 ttyd 共享 tmux 会话
ttyd -p 8088 tmux attach -t sanguo_dev

# 访问: http://YOUR_LAN_IP:8088
```

---

## 7. 端口规划

| 服务 | 端口 | 说明 |
|------|------|------|
| **ttyd Web** | 8088 | tmux Web 访问 |
| **Claude Code** | 默认 | 由 Claude Code 管理 (每个实例) |

**已占用端口（避开）**: 3001, 6379, 18789, 19999

---

## 8. 配置文件汇总

### 8.1 配置文件位置

| 文件 | 路径 | 用途 |
|------|------|------|
| **settings.json** | `~/.claude/settings.json` | GLM-5.2 端点配置 |
| **ttyd 配置** | `~/.ttyd` | Web 访问配置 |
| **tmux 配置** | `~/.tmux-sanguo.conf` | tmux 会话配置 |
| **main CLAUDE.md** | `sanguo-main/.claude/CLAUDE.md` | 架构师角色定义 |
| **backend CLAUDE.md** | `sanguo-backend/.claude/CLAUDE.md` | 后端角色定义 |
| **frontend CLAUDE.md** | `sanguo-frontend/.claude/CLAUDE.md` | 前端角色定义 |
| **角色 Skills** | `~/.claude/skills/{architect-role,backend-dev,frontend-dev}/` | 角色专属技能 |

### 8.2 环境变量汇总

```bash
# GLM-5.2 (Anthropic 兼容)
export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_API_KEY="你的智谱API_Key"
```

---

## 9. 技术栈

| 组件 | 技术/版本 | 说明 |
|------|----------|------|
| **Claude Code** | v2.1.39+ | 主控 CLI (三个实例) |
| **Superpowers** | Marketplace | 共享技能库 |
| **GLM-5.2** | 智谱 AI | 统一后端 |
| **ttyd** | v1.7.7 | Web 终端 |
| **tmux** | 系统包管理器 | 终端复用 (三 pane) |

---

## 10. 成本估算

| 组件 | 用量 | 单价 | 预估成本占比 |
|------|------|------|-------------|
| **Claude (架构师)** | 规划+审查+验收（中） | 低 | ~30% |
| **Codex (后端)** | 代码实现（高） | 低 | ~50% |
| **Gemini (前端)** | 页面实现（中） | 低 | ~20% |

**v0.4 成本优势**:
- 统一使用 GLM-5.2，成本最低
- 三个实例按需消耗 token
- 1M 上下文减少频繁请求

---

## 11. 检查清单

### 环境检查

- [ ] Claude Code 已安装
- [ ] tmux 已安装
- [ ] ttyd 已安装

### 配置验证

- [ ] `~/.claude/settings.json` 已配置 GLM-5.2 端点
- [ ] 智谱 API Key 已设置
- [ ] ttyd 配置 8088 端口
- [ ] tmux 配置文件已创建

### 项目创建

- [ ] sanguo-main 项目目录已创建
- [ ] sanguo-backend 项目目录已创建
- [ ] sanguo-frontend 项目目录已创建
- [ ] 三个 CLAUDE.md 文件已创建

### Skills 创建

- [ ] architect-role skill 已创建
- [ ] backend-dev skill 已创建
- [ ] frontend-dev skill 已创建

### 功能验证

- [ ] tmux 三 pane 会话正常启动
- [ ] 三个 Claude Code 实例正常启动
- [ ] SendMessage 跨实例通信正常
- [ ] 各实例能正确加载角色定义
- [ ] 各实例能访问 Superpowers skills
- [ ] ttyd web 访问正常

---

## 12. 故障排查

### 12.1 SendMessage 不工作

**问题**: 跨实例 SendMessage 无法传递消息

**解决**:
1. 验证 Claude Code SendMessage 能力
2. 使用文件系统作为备选消息队列
3. 实现简单的轮询机制

### 12.2 角色隔离不生效

**问题**: 实例没有按照 CLAUDE.md 定义的角色执行

**解决**:
1. 确认 CLAUDE.md 文件位置正确
2. 确认 Claude Code 加载了正确的 CLAUDE.md
3. 在启动 Claude Code 时明确指定角色

### 12.3 Skills 访问问题

**问题**: 某个实例无法访问 Superpowers skills

**解决**:
1. 确认 `~/.claude/skills/` 目录存在
2. 确认技能文件权限正确
3. 重新安装 Superpowers

---

## 13. 参考资料

- [GLM-5.2 - 智谱AI开放文档](https://docs.bigmodel.cn/cn/guide/models/text/glm-5.2)
- [ttyd GitHub](https://github.com/tsl0922/ttyd)
- [tmux 官方文档](https://github.com/tmux/tmux/wiki)

---

## 14. 实施状态

### 已完成 (2026-06-30 更新)

| 组件 | 状态 | 说明 |
|------|------|------|
| **ttyd** | ✅ 已安装 | v1.7.7 |
| **Claude Code** | ✅ v2.1.187 | 支持跨会话 SendMessage |
| **项目目录** | ✅ 已创建 | sanguo-main, sanguo-backend, sanguo-frontend |
| **CLAUDE.md 文件** | ✅ 已创建 | 三个角色定义文件 |
| **角色 Skills** | ✅ 已创建 | architect-role, backend-dev, frontend-dev |
| **SendMessage 验证** | ✅ 已验证 | 支持跨会话但有限制 |
| **tmux 配置** | ✅ 已创建 | ~/.tmux-sanguo.conf |
| **消息队列** | ✅ 已创建 | ~/.claude/messages/sanguo/message.sh |
| **启动脚本** | ✅ 已创建 | start-sanguo-env.sh |
| **快速参考** | ✅ 已创建 | docs/04-quick-reference.md |

### 待启动

| 组件 | 状态 | 说明 |
|------|------|------|
| **tmux 会话** | ⚠️ 待启动 | 运行 start-sanguo-env.sh |
| **Claude Code 实例** | ⚠️ 待启动 | 在各 pane 中启动 claude |
| **ttyd Web** | ⚠️ 待启动 | ttyd -p 8088 tmux attach |

### 验证结果

- [x] SendMessage 跨实例通信 — ✅ 支持 (有限制)
- [x] CLAUDE.md 角色隔离 — ✅ 已定义
- [x] Superpowers skills 共享 — ✅ 已确认可用
- [ ] 三实例协作流程 — ⚠️ 待实际测试

### 关键发现

**SendMessage 限制**:
- 跨会话消息不携带用户权限
- 接收方拒绝中继的权限请求
- Auto 模式会阻止跨会话消息

**应对方案**:
- 使用 SendMessage 传递任务描述和结果
- 每个实例独立执行工具
- 文件消息队列作为备选方案

### 创建的文件

```
~/.tmux-sanguo.conf                              # tmux 配置
~/.claude/messages/sanguo/message.sh            # 消息队列脚本
~/.claude/messages/sanguo/start-sanguo-env.sh   # 启动脚本
~/.claude/projects/sanguo-main/.claude/CLAUDE.md        # 架构师角色
~/.claude/projects/sanguo-backend/.claude/CLAUDE.md     # 后端角色
~/.claude/projects/sanguo-frontend/.claude/CLAUDE.md    # 前端角色
~/.claude/skills/architect-role/SKILL.md        # 架构师 skill
~/.claude/skills/backend-dev/SKILL.md           # 后端 skill
~/.claude/skills/frontend-dev/SKILL.md          # 前端 skill
docs/04-quick-reference.md                       # 快速参考
```

---

**文档版本**: v0.4
**最后更新**: 2026-06-30
**作者**: Claude Dev
**审核状态**: Draft
**实施状态**: ✅ 设计和基础设施完成 - 待启动测试

### 完成清单

#### 文档
- [x] 完整设计文档 (04-design-v0.4.md)
- [x] 快速参考 (04-quick-reference.md)
- [x] 示例工作流 (05-example-workflows.md)

#### 项目结构
- [x] sanguo-main 项目目录 + CLAUDE.md
- [x] sanguo-backend 项目目录 + CLAUDE.md
- [x] sanguo-frontend 项目目录 + CLAUDE.md

#### 角色 Skills
- [x] architect-role/SKILL.md
- [x] backend-dev/SKILL.md
- [x] frontend-dev/SKILL.md

#### 配置和脚本
- [x] ~/.tmux-sanguo.conf
- [x] start-sanguo-env.sh
- [x] message.sh
- [x] test-sanguo-env.sh

#### 验证
- [x] 环境测试: 18/18 通过
- [x] SendMessage 跨实例通信验证

### 启动步骤

```bash
# 1. 测试环境
~/.claude/messages/sanguo/test-sanguo-env.sh

# 2. 启动 tmux 环境
~/.claude/messages/sanguo/start-sanguo-env.sh

# 3. 在各 pane 中启动 Claude Code
# pane 0 (architect): cd ~/.claude/projects/sanguo-main && claude
# pane 1 (backend): cd ~/.claude/projects/sanguo-backend && claude
# pane 2 (frontend): cd ~/.claude/projects/sanguo-frontend && claude

# 4. (可选) 启动 Web 访问
ttyd -p 8088 tmux attach -t sanguo_dev
```

### Git 提交历史

```
5d85c08 docs: 添加示例工作流文档
0187809 docs: 完成 v0.4 基础设施实施
0829b34 docs: 更新 v0.4 设计 - SendMessage 验证结果和实施状态
eda9930 docs: 添加 v0.4 设计文档 - 三实例方案
```