From 1c8a4ff95cd0ccd3f41a83041e2a42de6e7c3898 Mon Sep 17 00:00:00 2001 From: claude_dev Date: Tue, 30 Jun 2026 20:03:07 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20v0.3=20=E8=AE=BE?= =?UTF-8?q?=E8=AE=A1=E6=96=87=E6=A1=A3=20-=20=E9=87=87=E7=94=A8=20Claude?= =?UTF-8?q?=20Code=20=E5=86=85=E7=BD=AE=E5=A4=9A=20Agent=20=E8=83=BD?= =?UTF-8?q?=E5=8A=9B=EF=BC=8C=E7=A7=BB=E9=99=A4=20CCB=20=E5=B1=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 移除 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 兼容端点 --- docs/design/03-design-v0.3.md | 632 ++++++++++++++++++++++++++++++++++ 1 file changed, 632 insertions(+) create mode 100644 docs/design/03-design-v0.3.md diff --git a/docs/design/03-design-v0.3.md b/docs/design/03-design-v0.3.md new file mode 100644 index 0000000..a08775d --- /dev/null +++ b/docs/design/03-design-v0.3.md @@ -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 + + +## 技能名称 + +简要描述 + +### 触发条件 +- 用户说 "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 +**实施状态**: 待实施