diff --git a/docs/design/02-design-v0.2.md b/docs/design/02-design-v0.2.md new file mode 100644 index 0000000..289c9ea --- /dev/null +++ b/docs/design/02-design-v0.2.md @@ -0,0 +1,489 @@ +# sanguo_moziplus_v3 设计文档 v0.2 + +**项目名称**: sanguo_moziplus_v3 +**版本**: v0.2 +**创建日期**: 2026-06-29 +**状态**: Draft +**基于**: videotext 方案调查报告 + +--- + +## 1. 版本变更 + +| 版本 | 变更说明 | 日期 | +|------|---------|------| +| v0.1 | 初始设计 | 2026-06-29 | +| v0.2 | 基于 videotext 调研更新，集成 GLM-5.2、Web 访问 | 2026-06-29 | + +--- + +## 2. 架构概述 + +### 2.1 系统架构图 + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Claude Code CLI │ +│ (用户交互层) │ +└─────────────────────────────┬───────────────────────────────────┘ + │ +┌─────────────────────────────▼───────────────────────────────────┐ +│ CLAUDE.md (规则层) │ +│ - 协作规范 │ +│ - 角色分工 │ +│ - Git 规范 │ +└─────────────────────────────┬───────────────────────────────────┘ + │ +┌─────────────────────────────▼───────────────────────────────────┐ +│ Superpowers (能力层) │ +│ - Planning Skill │ +│ - Review Skill │ +│ - Debug Skill │ +└─────────────────────────────┬───────────────────────────────────┘ + │ +┌─────────────────────────────▼───────────────────────────────────┐ +│ CCB (通信层) │ +│ ┌─────────┐ ┌─────────┐ │ +│ │Codex │ │Gemini │ │ +│ │(后端) │ │(前端) │ │ +│ └────┬────┘ └────┬────┘ │ +└───────┼────────────┼───────────────────────────────────────────┘ + │ │ + ▼ ▼ + 智谱 GLM-5.2 智谱 GLM-5.2 + +┌─────────────────────────────────────────────────────────────────┐ +│ Web 访问层 (gotty) │ +│ 端口: 8088 │ +│ 访问: http://YOUR_LAN_IP:8088 │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### 2.2 完整链路 + +``` +CLAUDE.md 定好规则 → Superpowers 提供标准流程 → CCB 打通多模型通信 + ↓ + 智谱 GLM-5.2 (Codex + Gemini) + ↓ + gotty Web 访问 (8088 端口) +``` + +--- + +## 3. 核心组件配置 + +### 3.1 角色分工 + +| AI | 角色 | 职责 | 模型 | +|---|------|------|------| +| **Claude** | PM/架构师 | 规划、拆分任务、验收 | Claude API | +| **Codex** | 后端开发 | 代码、数据库、测试 | GLM-5.2 | +| **Gemini** | 前端开发 | 页面、组件、审查 | GLM-5.2 | + +### 3.2 模型端点配置 + +| 组件 | Base URL | 环境变量 | +|------|----------|---------| +| **Codex CLI** | `https://api.zhipuai.cn/v1` | `OPENAI_API_BASE` | +| **Gemini CLI** | `https://open.bigmodel.cn/api/coding/paas/v4` | `OPENROUTER_BASE_URL` | + +### 3.3 API Key 配置 + +智谱 AI API Key 格式：`xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxx` + +**环境变量**: +```bash +# Codex +export OPENAI_API_KEY="6903e83faf454106aa7529c9e18e2ea5.gYMSjWwk1XDN0U5h" + +# Gemini +export OPENROUTER_API_KEY="4ae9f90df9514aa8ba61a5ee885d0dab.NIr7DfGQ8rdMN0Cd" +``` + +--- + +## 4. 端口规划 + +| 服务 | 端口 | 说明 | +|------|------|------| +| **gotty Web** | 8088 | tmux Web 访问（避开常见端口） | +| **Claude Code** | 默认 | 由 Claude Code 管理 | +| **CCB askd** | 32779 | CCB 通信端口（默认） | + +**已占用端口（避开）**: 3001, 6379, 18789, 19999 + +--- + +## 5. 实施步骤 + +### Phase 1: 环境准备 + +#### 1.1 基础工具安装 + +```bash +# 检查 Claude Code +claude --version + +# 安装 tmux +brew install tmux +tmux -V + +# 检查 Python +python3 --version # 需要 3.10+ +``` + +#### 1.2 安装 Codex CLI + +```bash +npm install -g @openai/codex +codex --version +``` + +**配置 GLM-5.2**: + +创建 `~/.codex/config.toml`: +```toml +[profile.default] +openai_base_url = "https://api.zhipuai.cn/v1" +model = "glm-5.2" +``` + +设置环境变量: +```bash +export OPENAI_API_BASE="https://api.zhipuai.cn/v1" +export OPENAI_API_KEY="6903e83faf454106aa7529c9e18e2ea5.gYMSjWwk1XDN0U5h" +``` + +验证: +```bash +codex "测试" +``` + +#### 1.3 安装 Gemini CLI（定制版） + +```bash +# 克隆定制版本 +git clone https://github.com/heartyguy/gemini-cli +cd gemini-cli + +# 切换到兼容分支 +git checkout feature/openrouter-support + +# 安装依赖 +npm install +``` + +**配置 GLM-5.2**: +```bash +export OPENROUTER_BASE_URL="https://open.bigmodel.cn/api/coding/paas/v4" +export OPENROUTER_API_KEY="4ae9f90df9514aa8ba61a5ee885d0dab.NIr7DfGQ8rdMN0Cd" + +# 启动 +npm start +``` + +#### 1.4 安装 gotty + +```bash +brew install yudai/gotty/gotty +``` + +**配置 gotty**: + +创建 `~/.gotty`: +``` +address = "0.0.0.0" +port = "8088" +permit_write = true +enable_basic_auth = false +``` + +--- + +### Phase 2: CCB 桥接器安装 + +```bash +# 克隆 CCB（注意使用正确的仓库） +git clone https://github.com/SeemSeam/claude_codex_bridge.git +cd claude_codex_bridge + +# 安装 +python install.py + +# 或 Windows PowerShell +powershell -ExecutionPolicy Bypass -File .\install.ps1 install +``` + +**安装后自动配置**: +- CLAUDE.md 追加协作规则 +- 注册 `/ask`、`/pend`、`ping` 命令 +- 更新 Codex skills 目录 +- 安装辅助脚本 + +--- + +### Phase 3: Superpowers 安装 + +在 Claude Code 中执行: +```bash +/plugin marketplace add https://github.com/obra/superpowers-marketplace +``` + +--- + +### Phase 4: CLAUDE.md 规范配置 + +**项目 CLAUDE.md 模板**: +```markdown +# {项目名称} + +## 工作模式 + +Superpowers + AI 协作 + +## 角色分工 + +### Claude (我) — 架构师 / 项目经理 + +- 需求分析、架构设计、任务拆分 +- 使用 Superpowers 进行规划、审查、调试 +- 代码审核、最终验收、Git 提交管理 +- **绝对不亲自编写代码**，所有编码任务必须委派给 Codex 或 Gemini + +### Codex — 后端开发 + +- 服务端代码、API、数据库、Migration +- 单元测试、集成测试 +- 通过 `/ask codex "..."` 调用 + +### Gemini — 前端开发 + +- 前端组件、页面、样式、交互逻辑 +- 代码审查、安全审计 +- 通过 `/ask gemini "..."` 调用 + +## 协作方式 + +**使用 Superpowers skills 进行**: +- 规划: `superpowers:writing-plans` +- 执行: `superpowers:executing-plans` +- 审查: `superpowers:requesting-code-review` +- 调试: `superpowers:systematic-debugging` +- 完成: `superpowers:finishing-a-development-branch` + +**调用 AI 提供者执行代码任务**: +```bash +# 指派 Codex 实现后端 +/ask codex "实现 XXX 后端功能，涉及文件：..." + +# 指派 Gemini 实现前端 +/ask gemini "实现 XXX 前端功能，涉及文件：..." + +# 查看执行结果 +/pend codex +/pend gemini +``` + +## Linus 三问 (决策前必问) + +1. 这是现实问题还是想象问题？ → 拒绝过度设计 +2. 这个问题真的需要解决吗？ → 拒绝伪需求 +3. 这个方案真的能解决问题吗？ → 拒绝自嗨 +``` + +--- + +## 6. 使用流程 + +### 6.1 启动流程 + +```bash +# 1. 启动 tmux 会话 +tmux new -s sanguo_dev + +# 2. 在 tmux 中启动 Claude Code +claude + +# 3. CCB 自动启动后端 +# - Gemini 启动在 pane #1 +# - Codex 启动在 pane #2 + +# 4. 启动 gotty Web 访问（在另一个终端） +gotty -a 0.0.0.0 -p 8088 tmux attach -t sanguo_dev +``` + +### 6.2 Web 访问 + +**局域网访问**: +``` +http://YOUR_LAN_IP:8088 +``` + +**查看本机 IP**: +```bash +ifconfig | grep inet +# 或 +ip addr show +``` + +### 6.3 典型工作流 + +``` +用户: "实现用户注册功能" + ↓ +Claude: 分析需求、拆分任务 + ↓ +Claude: /ask codex "实现后端认证 API" +Claude: /ask gemini "实现登录注册页面" + ↓ +Codex(GLM-5.2): 返回后端代码 +Gemini(GLM-5.2): 返回前端代码 + ↓ +Claude: 审核验收 + ↓ +Claude: Git 提交 +``` + +--- + +## 7. 配置文件汇总 + +### 7.1 配置文件位置 + +| 文件 | 路径 | 用途 | +|------|------|------| +| **CLAUDE.md** | `项目根目录/.claude/CLAUDE.md` | 协作规范 | +| **Codex 配置** | `~/.codex/config.toml` | GLM-5.2 端点 | +| **Gemini 配置** | 环境变量 | GLM-5.2 端点 | +| **gotty 配置** | `~/.gotty` | Web 访问配置 | +| **tmux 配置** | `~/.tmux.conf` | 终端复用配置 | + +### 7.2 环境变量汇总 + +```bash +# Codex (GLM-5.2) +export OPENAI_API_BASE="https://api.zhipuai.cn/v1" +export OPENAI_API_KEY="你的智谱API_Key" + +# Gemini (GLM-5.2) +export OPENROUTER_BASE_URL="https://open.bigmodel.cn/api/coding/paas/v4" +export OPENROUTER_API_KEY="你的智谱API_Key" +``` + +**建议**: 将环境变量添加到 `~/.zshrc` 或 `~/.bashrc` + +--- + +## 8. 技术栈 + +| 组件 | 技术/版本 | 说明 | +|------|----------|------| +| **Claude Code** | v2.1.39+ | 主控 CLI | +| **CCB** | SeemSeam/claude_codex_bridge | 多 AI 桥接器 | +| **Codex CLI** | @openai/codex | 后端开发 CLI | +| **Gemini CLI** | heartyguy/gemini-cli (定制版) | 前端开发 CLI | +| **Superpowers** | Marketplace | 工作流框架 | +| **GLM-5.2** | 智谱 AI | 代码生成模型 | +| **gotty** | yudai/gotty | Web 终端 | +| **tmux** | 系统包管理器 | 终端复用 | +| **Python** | 3.10+ | CCB 依赖 | + +--- + +## 9. 成本估算 + +| 组件 | 用量 | 单价 | 预估成本占比 | +|------|------|------|-------------| +| **Claude** | 规划+验收（低） | 高 | ~5% | +| **Codex (GLM-5.2)** | 代码实现（高） | 低 | ~70% | +| **Gemini (GLM-5.2)** | 前端+审查（中） | 低 | ~25% | + +**预期目标**: Claude Token 消耗降低 > 50% + +--- + +## 10. 检查清单 + +### 环境检查 + +- [ ] Claude Code 已安装 +- [ ] Python 3.10+ +- [ ] tmux 已安装 +- [ ] Node.js 18+ (Gemini CLI 需要) +- [ ] Homebrew (gotty 需要) + +### 组件安装 + +- [ ] Codex CLI 已安装 +- [ ] Gemini CLI（定制版）已安装 +- [ ] gotty 已安装 +- [ ] CCB 已安装 +- [ ] Superpowers 已安装 + +### 配置验证 + +- [ ] Codex 配置 GLM-5.2 端点 +- [ ] Gemini 配置 GLM-5.2 端点 +- [ ] 智谱 API Key 已设置 +- [ ] gotty 配置 8088 端口 +- [ ] CLAUDE.md 已创建 + +### 功能验证 + +- [ ] `codex "测试"` 有响应 +- [ ] `gemini` 启动正常 +- [ ] `/ask codex "测试"` 有响应 +- [ ] `/ask gemini "测试"` 有响应 +- [ ] tmux 会话正常 +- [ ] gotty web 访问 `http://YOUR_IP:8088` 正常 + +--- + +## 11. 故障排查 + +### 11.1 端口冲突 + +**问题**: 8088 端口被占用 + +**解决**: +```bash +# 查找占用进程 +lsof -i :8088 + +# 或更换端口 +gotty -a 0.0.0.0 -p 8089 tmux attach -t sanguo_dev +``` + +### 11.2 CCB 连接失败 + +**问题**: Codex/Gemini 连接不上 + +**检查**: +1. 确认 API Key 正确 +2. 确认端点 URL 正确 +3. 检查网络连接 + +### 11.3 gotty Web 无法访问 + +**检查**: +1. 确认绑定 0.0.0.0（非 127.0.0.1） +2. 检查防火墙设置 +3. 确认 IP 地址正确 + +--- + +## 12. 参考资料 + +- [videotext 方案调查报告](./02-videotext-investigation-report.md) +- [GLM-5.2 - 智谱AI开放文档](https://docs.bigmodel.cn/cn/guide/models/text/glm-5.2) +- [GoTTY GitHub](https://github.com/yudai/gotty) +- [webtmux GitHub](https://github.com/chrismccord/webtmux) +- [CCB GitHub](https://github.com/SeemSeam/claude_codex_bridge) + +--- + +**文档版本**: v0.2 +**最后更新**: 2026-06-29 +**作者**: Claude Dev +**审核状态**: 待审核