sanguo_moziplus_v3/docs/design/03-design-v0.3.md

# sanguo_moziplus_v3 设计文档 v0.3

**项目名称**: sanguo_moziplus_v3
**版本**: v0.3
**创建日期**: 2026-06-30
**状态**: Draft
**基于**: v0.2 + Claude Code 内置多 Agent 能力

---

## 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.3 核心变化

| 变更项 | v0.2 | v0.3 | 原因 |
|--------|------|------|------|
| **CCB 层** | Codex + Gemini 桥接 | ❌ 移除 | Codex CLI 不兼容 GLM-5.2 |
| **编排方式** | Workflow 脚本 | Skills 内置编排 | Skills 可调用 Agent 工具 |
| **Agent 调用** | 外部 CLI | 内置 Agent 工具 | Explore、Plan、通用 agents |
| **架构层数** | 5 层 | 3 层 | 简化架构 |

---

## 2. 架构概述

### 2.1 系统架构图

```
┌─────────────────────────────────────────────────────────────────┐
│                        Claude Code CLI                          │
│                     (用户交互层 + 主协调)                         │
│                                                                 │
│  内置能力:                                                       │
│  • Agent 工具 — 启动专门 agents                                  │
│  • Skills — 封装可复用能力                                        │
│  • SendMessage — Agent 间通信                                   │
│  • worktree 隔离 — 独立工作环境                                   │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                   Superpowers (Skills 层)                        │
│                                                                 │
│  每个 Skill 内部编排多个 Agents:                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Planning Skill                                            │   │
│  │  1. Agent(Explore) → 搜索相关文件                         │   │
│  │  2. Agent(Plan) → 设计架构方案                            │   │
│  │  3. 返回整合规划                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Review Skill                                              │   │
│  │  1. Agent(code-reviewer) → 审查代码                      │   │
│  │  2. 返回审查报告                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Debug Skill                                               │   │
│  │  1. Agent(Explore) → 定位问题                            │   │
│  │  2. Agent(general-purpose) → 修复问题                     │   │
│  │  3. Agent(test-automation) → 验证修复                    │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                    CLAUDE.md (规范层)                            │
│  - 协作规范                                                      │
│  - Git 规范                                                      │
│  - 决策框架 (Linus 三问)                                         │
└─────────────────────────────┬───────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────┐
│                      GLM-5.2 (统一后端)                          │
│  • Anthropic 兼容端点: https://api.z.ai/api/anthropic           │
│  • 1M 上下文支持                                                 │
│  • 所有 Agent 通过同一模型执行                                   │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                    Web 访问层 (ttyd)                              │
│  端口: 8088                                                      │
│  访问: http://YOUR_LAN_IP:8088                                   │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 完整链路

```
用户输入需求
     ↓
Claude Code (主 Agent)
     ↓
调用 Skill (如 /plan)
     ↓
Skill 内部编排多个 Agents
     ├─ Agent(Explore) → 搜索文件
     ├─ Agent(Plan) → 设计方案
     └─ 返回整合结果
     ↓
GLM-5.2 (统一后端)
     ↓
ttyd Web 访问
```

---

## 3. 核心组件配置

### 3.1 Claude Code 内置 Agent 能力

| 能力 | 用途 | 调用方式 |
|------|------|---------|
| **Agent 工具** | 启动专门 agents | `Agent({subagent_type: "Explore", prompt: "..."})` |
| **Workflow** | JS 脚本编排 (被 Skills 替代) | ❌ 不推荐使用 |
| **SendMessage** | Agent 间通信 | `SendMessage({to: "agent-name", message: "..."})` |
| **worktree** | 独立工作环境 | `Agent({isolation: "worktree", ...})` |
| **Fleet** | 并发配置 | settings.json 中配置 |

### 3.2 可用 Agent 类型

| Agent 类型 | 用途 | 典型场景 |
|-----------|------|---------|
| **Explore** | 文件搜索和定位 | "搜索所有 API 文件"、"找到数据库配置" |
| **Plan** | 架构设计和技术方案 | "设计用户认证系统"、"规划数据库架构" |
| **claude** | 通用任务执行 | "实现用户注册功能" |
| **general-purpose** | 复杂多步骤任务 | "重构整个模块" |
| **code-reviewer** | 代码审查 | "审查这个 PR 的安全性" |
| **test-automation*** | 测试相关 | "编写 E2E 测试" |

### 3.3 GLM-5.2 端点配置

| 端点类型 | URL | 用途 |
|---------|-----|------|
| **Anthropic 兼容** | `https://api.z.ai/api/anthropic` | Claude Code 主接口 |
| **Coding Plan** | `https://api.z.ai/api/coding/paas/v4` | ❌ Codex 不兼容，不使用 |

**settings.json 配置**:
```json
{
  "env": {
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_API_KEY": "你的智谱API_Key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
  }
}
```

---

## 4. Superpowers Skills 设计

### 4.1 核心 Skills

| Skill | 触发方式 | 内部 Agent 编排 | 输出 |
|-------|---------|----------------|------|
| **Planning** | `/plan` 或自然语言 | Explore → Plan → 返回方案 | 技术方案文档 |
| **Review** | `/review` 或自然语言 | code-reviewer → 返回报告 | 审查报告 |
| **Debug** | `/debug` 或自然语言 | Explore → general-purpose → test | 问题定位和修复 |

### 4.2 Skill 内部编排示例

**Planning Skill 工作流**:
```markdown
## Planning Skill

当用户需要规划时：

1. 启动 Explore Agent 搜索相关文件
   - 搜索项目中已有的相关代码
   - 查找配置文件和文档
   - 返回相关文件列表

2. 启动 Plan Agent 设计方案
   - 基于搜索结果设计架构
   - 拆分实施步骤
   - 列出需要修改的文件

3. 返回整合后的规划文档
```

**用户调用**:
```
我：/plan "实现用户认证功能"
    ↓
Planning Skill 内部执行
    ├─ Agent(Explore, "搜索现有认证代码")
    ├─ Agent(Plan, "设计 JWT 认证方案")
    └─ 返回规划文档
```

### 4.3 Skill 创建规范

```markdown
<!-- ~/.claude/skills/my-skill/SKILL.md -->

## 技能名称

简要描述

### 触发条件
- 用户说 "XXX"
- 或调用 `/my-skill`

### 工作流程
1. Agent(Explore) → ...
2. Agent(Plan) → ...
3. 返回结果

### 输出格式
- 文档路径
- 或代码片段
```

---

## 5. 端口规划

| 服务 | 端口 | 说明 |
|------|------|------|
| **ttyd Web** | 8088 | tmux Web 访问 |
| **Claude Code** | 默认 | 由 Claude Code 管理 |

**已移除端口**：
- ~~CCB askd (32779)~~ — 不再需要

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

---

## 6. 实施步骤

### Phase 1: 环境准备

#### 1.1 基础工具安装

```bash
# 检查 Claude Code
claude --version

# 安装 tmux
brew install tmux
tmux -V
```

#### 1.2 配置 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]"
  }
}
```

**验证**:
```bash
claude "测试 GLM-5.2 连接"
```

#### 1.3 安装 ttyd

```bash
brew install ttyd
```

**配置 ttyd**:

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

---

### Phase 2: Superpowers Skills 创建

#### 2.1 创建 Planning Skill

```bash
mkdir -p ~/.claude/skills/planning
```

**`~/.claude/skills/planning/SKILL.md`**:
```markdown
# Planning Skill

技术方案规划专家。

## 触发条件
- 用户说 "规划"、"设计方案"、"技术方案"
- 或直接调用 `/plan`

## 工作流程
1. 启动 Explore Agent 搜索相关文件和代码
2. 启动 Plan Agent 设计技术方案
3. 返回包含架构、步骤、文件清单的规划文档

## 输出格式
- 技术方案文档 (docs/方案名称.md)
- 实施步骤清单
- 需要修改/创建的文件列表
```

#### 2.2 创建 Review Skill

```bash
mkdir -p ~/.claude/skills/review
```

**`~/.claude/skills/review/SKILL.md`**:
```markdown
# Review Skill

代码审查专家。

## 触发条件
- 用户说 "审查"、"review"、"代码检查"
- 或直接调用 `/review`

## 工作流程
1. 启动 code-reviewer Agent 审查代码
2. 检查安全性、性能、可维护性
3. 返回包含问题和建议的审查报告

## 输出格式
- 审查报告 (docs/review-日期.md)
- 问题清单（按严重程度排序）
- 改进建议
```

#### 2.3 创建 Debug Skill

```bash
mkdir -p ~/.claude/skills/debug
```

**`~/.claude/skills/debug/SKILL.md`**:
```markdown
# Debug Skill

问题诊断和修复专家。

## 触发条件
- 用户说 "调试"、"debug"、"修复问题"
- 或直接调用 `/debug`

## 工作流程
1. 启动 Explore Agent 定位问题
2. 启动 general-purpose Agent 修复问题
3. 启动 test-automation Agent 验证修复
4. 返回问题分析和修复方案

## 输出格式
- 问题分析报告
- 修复代码
- 测试验证结果
```

---

### Phase 3: CLAUDE.md 规范配置

**项目 `CLAUDE.md` 模板**:
```markdown
# {项目名称}

## 工作模式

Claude Code + GLM-5.2 + Superpowers Skills

## 核心能力

### 内置 Agent 工具
- **Agent(Explore)**: 搜索和定位文件
- **Agent(Plan)**: 设计技术方案
- **Agent(general-purpose)**: 执行复杂任务
- **Agent(code-reviewer)**: 代码审查

### Superpowers Skills
- **/plan**: 规划技术方案
- **/review**: 审查代码质量
- **/debug**: 调试和修复问题

## 典型工作流

### 方案规划
```
用户: "规划用户认证系统"
    ↓
调用 /plan Skill
    ↓
Skill 内部:
  - Agent(Explore) 搜索现有认证代码
  - Agent(Plan) 设计 JWT 方案
    ↓
返回规划文档
```

### 代码开发
```
用户: "实现用户注册 API"
    ↓
Agent(general-purpose) 实现代码
    ↓
调用 /review Skill 审查
    ↓
Git 提交
```

### 问题调试
```
用户: "登录接口报错"
    ↓
调用 /debug Skill
    ↓
Skill 内部:
  - Agent(Explore) 定位问题
  - Agent(general-purpose) 修复代码
  - Agent(test-automation) 验证修复
    ↓
返回修复报告
```

## Linus 三问 (决策前必问)

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

## Git 规范

- 提交前使用 `/review` 审查代码
- 提交信息格式: `类型: 简短描述`
- 类型: feat/fix/refactor/docs/test/chore
```

---

### Phase 4: 启动和验证

#### 4.1 启动 tmux 会话

```bash
tmux new -s sanguo_dev
```

#### 4.2 启动 ttyd Web 访问

```bash
ttyd -p 8088 tmux attach -t sanguo_dev
```

#### 4.3 验证多 Agent 能力

```bash
# 测试 Agent 工具
claude "Agent(Explore, '搜索所有 API 文件')"

# 测试 Skills
claude "/plan '设计数据库架构'"
claude "/review '审查 src/api/'"
```

---

## 7. 配置文件汇总

### 7.1 配置文件位置

| 文件 | 路径 | 用途 |
|------|------|------|
| **settings.json** | `~/.claude/settings.json` | GLM-5.2 端点配置 |
| **CLAUDE.md** | `项目根目录/.claude/CLAUDE.md` | 协作规范 |
| **Skills** | `~/.claude/skills/*/SKILL.md` | 能力封装 |
| **ttyd 配置** | `~/.ttyd` | Web 访问配置 |
| **tmux 配置** | `~/.tmux.conf` | 终端复用配置 |

### 7.2 环境变量汇总

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

---

## 8. 技术栈

| 组件 | 技术/版本 | 说明 |
|------|----------|------|
| **Claude Code** | v2.1.39+ | 主控 CLI + 内置 Agent 能力 |
| **Superpowers** | Skills | 能力封装 + 内部 Agent 编排 |
| **Agent 工具** | 内置 | Explore、Plan、通用 agents |
| **GLM-5.2** | 智谱 AI | 统一后端，1M 上下文 |
| **ttyd** | v1.7.7 | Web 终端 |
| **tmux** | 系统包管理器 | 终端复用 |

### 已移除组件

| 组件 | 原因 |
|------|------|
| ~~CCB~~ | Codex CLI 不兼容 GLM-5.2 |
| ~~Codex CLI~~ | 需要 `/responses` WebSocket 端点 |
| ~~Gemini CLI~~ | OpenRouter 格式不兼容 |
| ~~Workflow 脚本~~ | 被 Skills 替代 |

---

## 9. 成本估算

| 组件 | 用量 | 单价 | 预估成本占比 |
|------|------|------|-------------|
| **Claude (GLM-5.2)** | 全流程（规划+开发+审查） | 低 | 100% |

**v0.3 成本优势**:
- ✅ 统一使用 GLM-5.2，成本最低
- ✅ 1M 上下文减少频繁请求
- ✅ 内置 Agent 能力，无额外工具成本

---

## 10. 检查清单

### 环境检查

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

### 配置验证

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

### 功能验证

- [ ] `claude "测试"` 有响应
- [ ] `Agent(Explore, "测试")` 正常工作
- [ ] `/plan` Skill 正常工作
- [ ] `/review` Skill 正常工作
- [ ] `/debug` Skill 正常工作
- [ ] tmux 会话正常
- [ ] ttyd web 访问 `http://YOUR_IP:8088` 正常

---

## 11. 故障排查

### 11.1 GLM-5.2 连接失败

**检查**:
1. 确认 API Key 正确
2. 确认端点 URL: `https://api.z.ai/api/anthropic`
3. 检查网络连接

### 11.2 Agent 工具无响应

**检查**:
1. 确认 Agent 类型正确
2. 检查 prompt 格式
3. 查看 Claude Code 日志

### 11.3 Skills 不工作

**检查**:
1. 确认 Skill 目录结构正确
2. 检查 SKILL.md 格式
3. 尝试重启 Claude Code

### 11.4 ttyd Web 无法访问

**检查**:
1. 确认绑定 0.0.0.0（非 127.0.0.1）
2. 检查防火墙设置
3. 确认 IP 地址正确

---

## 12. 参考资料

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

---

## 13. 实施状态

### 待实施

| 组件 | 状态 | 说明 |
|------|------|------|
| **Claude Code** | ✅ 已安装 | 主控 CLI |
| **GLM-5.2 配置** | ⚠️ 待配置 | settings.json |
| **ttyd** | ✅ 已安装 | v1.7.7 |
| **Skills 创建** | ❌ 未开始 | Planning/Review/Debug |
| **CLAUDE.md** | ❌ 未开始 | 项目规范 |

### 已移除组件

| 组件 | 状态 | 说明 |
|------|------|------|
| **CCB** | ❌ 已移除 | 不再需要 |
| **Codex CLI** | ❌ 已移除 | 不兼容 GLM-5.2 |
| **Gemini CLI** | ❌ 已移除 | 不兼容 GLM-5.2 |

---

**文档版本**: v0.3
**最后更新**: 2026-06-30
**作者**: Claude Dev
**审核状态**: Draft
**实施状态**: 待实施