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 配置:

{
  "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 工作流:

## Planning Skill

当用户需要规划时：

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

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

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

用户调用:

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

4.3 Skill 创建规范

<!-- ~/.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 基础工具安装

# 检查 Claude Code
claude --version

# 安装 tmux
brew install tmux
tmux -V

1.2 配置 GLM-5.2

创建/编辑 ~/.claude/settings.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]"
  }
}

验证:

claude "测试 GLM-5.2 连接"

1.3 安装 ttyd

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

mkdir -p ~/.claude/skills/planning

~/.claude/skills/planning/SKILL.md:

# Planning Skill

技术方案规划专家。

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

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

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

2.2 创建 Review Skill

mkdir -p ~/.claude/skills/review

~/.claude/skills/review/SKILL.md:

# Review Skill

代码审查专家。

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

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

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

2.3 创建 Debug Skill

mkdir -p ~/.claude/skills/debug

~/.claude/skills/debug/SKILL.md:

# Debug Skill

问题诊断和修复专家。

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

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

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

---

Phase 3: CLAUDE.md 规范配置

项目 CLAUDE.md 模板:

# {项目名称}

## 工作模式

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 会话

tmux new -s sanguo_dev

4.2 启动 ttyd Web 访问

ttyd -p 8088 tmux attach -t sanguo_dev

4.3 验证多 Agent 能力

# 测试 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 环境变量汇总

# 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开放文档
• ttyd GitHub
• Claude Code 文档

---

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 实施状态: 待实施