Files

T

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

- 移除 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 兼容端点

2026-06-30 20:03:07 +08:00

18 KiB

Raw Blame History

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 连接失败

检查:

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

11.2 Agent 工具无响应

检查:

确认 Agent 类型正确
检查 prompt 格式
查看 Claude Code 日志

11.3 Skills 不工作

检查:

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

11.4 ttyd Web 无法访问

检查:

确认绑定 0.0.0.0（非 127.0.0.1）
检查防火墙设置
确认 IP 地址正确

12. 参考资料

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

18 KiB Raw Blame History Unescape Escape

sanguo_moziplus_v3 设计文档 v0.3

1. 版本变更

v0.3 核心变化

2. 架构概述

2.1 系统架构图

2.2 完整链路

3. 核心组件配置

3.1 Claude Code 内置 Agent 能力

3.2 可用 Agent 类型

3.3 GLM-5.2 端点配置

4. Superpowers Skills 设计

4.1 核心 Skills

4.2 Skill 内部编排示例

4.3 Skill 创建规范

5. 端口规划

6. 实施步骤

Phase 1: 环境准备

1.1 基础工具安装

1.2 配置 GLM-5.2

1.3 安装 ttyd

Phase 2: Superpowers Skills 创建

2.1 创建 Planning Skill

2.2 创建 Review Skill

2.3 创建 Debug Skill

Phase 3: CLAUDE.md 规范配置

Phase 4: 启动和验证

4.1 启动 tmux 会话

4.2 启动 ttyd Web 访问

4.3 验证多 Agent 能力

7. 配置文件汇总

7.1 配置文件位置

7.2 环境变量汇总

8. 技术栈

已移除组件

9. 成本估算

10. 检查清单

环境检查

配置验证

功能验证

11. 故障排查

11.1 GLM-5.2 连接失败

11.2 Agent 工具无响应

11.3 Skills 不工作

11.4 ttyd Web 无法访问

12. 参考资料

13. 实施状态

待实施

已移除组件

18 KiB

Raw Blame History