sanguo/sanguo_moziplus_v3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加 v0.3 设计文档 - 采用 Claude Code 内置多 Agent 能力，移除 CCB 层

Browse Source 
- 移除 CCB 桥接层（Codex/Gemini CLI 不兼容 GLM-5.2）
- 采用 Claude Code 内置 Agent 工具（Explore、Plan、通用 agents）
- Skills 替代 Workflow 编排
- 简化为三层架构：Claude Code → Skills → GLM-5.2
- 统一使用 GLM-5.2 Anthropic 兼容端点
This commit is contained in:
Claude Dev
2026-06-30 20:03:07 +08:00
parent a1972c7ff9
commit 1c8a4ff95c
1 changed files with 632 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/03-design-v0.3.md
+632
View File
@@ -0,0 +1,632 @@
# 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
**实施状态**: 待实施