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

docs: 添加v0.2设计方案（基于videotext调研，集成GLM-5.2和Web访问）

Browse Source
This commit is contained in:
Claude Dev
2026-06-29 22:26:43 +08:00
parent b730e28b1a
commit 371f7a7a88
1 changed files with 489 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/02-design-v0.2.md
+489
View File
@@ -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
**审核状态**: 待审核