claude_dev
a1972c7ff9
- 统一使用 https://api.z.ai/api/coding/paas/v4 - 移除所有旧的 api.zhipuai.cn 和 open.bigmodel.cn 引用
588 lines
16 KiB
Markdown
588 lines
16 KiB
Markdown
# 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.z.ai/api/coding/paas/v4` | `OPENAI_API_BASE` |
|
||
| **Gemini CLI** | `https://api.z.ai/api/coding/paas/v4` | `OPENROUTER_BASE_URL` |
|
||
|
||
### 3.3 API Key 配置
|
||
|
||
智谱 AI API Key 格式：`xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxx`
|
||
|
||
**环境变量**:
|
||
```bash
|
||
# Codex (GLM Coding Plan)
|
||
export OPENAI_API_BASE="https://api.z.ai/api/coding/paas/v4"
|
||
export OPENAI_API_KEY="你的智谱API_Key"
|
||
|
||
# Gemini (GLM Coding Plan)
|
||
export OPENROUTER_BASE_URL="https://api.z.ai/api/coding/paas/v4"
|
||
export OPENROUTER_API_KEY="你的智谱API_Key"
|
||
```
|
||
|
||
---
|
||
|
||
## 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.z.ai/api/coding/paas/v4"
|
||
model = "glm-5.2"
|
||
```
|
||
|
||
设置环境变量:
|
||
```bash
|
||
export OPENAI_API_BASE="https://api.z.ai/api/coding/paas/v4"
|
||
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://api.z.ai/api/coding/paas/v4"
|
||
export OPENROUTER_API_KEY="4ae9f90df9514aa8ba61a5ee885d0dab.NIr7DfGQ8rdMN0Cd"
|
||
|
||
# 启动
|
||
npm start
|
||
```
|
||
|
||
#### 1.4 安装 ttyd (gotty 替代方案)
|
||
|
||
```bash
|
||
brew install ttyd
|
||
```
|
||
|
||
**配置 ttyd**:
|
||
|
||
创建 `~/.ttyd`:
|
||
```
|
||
address = "0.0.0.0"
|
||
port = "8088"
|
||
permit-write = true
|
||
enable-basic-auth = false
|
||
```
|
||
|
||
**使用方式**:
|
||
```bash
|
||
# 共享 tmux 会话
|
||
ttyd -p 8088 tmux attach -t sanguo_dev
|
||
|
||
# 或共享新 shell
|
||
ttyd -p 8088 bash
|
||
```
|
||
|
||
---
|
||
|
||
### 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.z.ai/api/coding/paas/v4"
|
||
export OPENAI_API_KEY="你的智谱API_Key"
|
||
|
||
# Gemini (GLM-5.2)
|
||
export OPENROUTER_BASE_URL="https://api.z.ai/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)
|
||
- [ttyd GitHub](https://github.com/tsl0922/ttyd)
|
||
- [CCB GitHub](https://github.com/SeemSeam/claude_codex_bridge)
|
||
|
||
---
|
||
|
||
## 13. 实施状态
|
||
|
||
### 已完成
|
||
|
||
| 组件 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| **Go** | ✅ 已安装 | v1.26.4 darwin/arm64 |
|
||
| **CCB** | ✅ 已安装 | v8.0.4, via npm @seemseam/ccb |
|
||
| **Codex CLI** | ✅ 已安装 | v0.142.4, via npm @openai/codex |
|
||
| **Gemini CLI** | ✅ 已安装 | 定制版 (feature/openrouter-support分支) |
|
||
| **tmux** | ✅ 已安装 | 系统包管理器 |
|
||
| **ttyd** | ✅ 已安装 | v1.7.7, via brew (gotty 替代方案) |
|
||
|
||
### 已验证
|
||
|
||
| 项目 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| **GLM Coding Plan 端点** | ✅ 正确且可用 | `https://api.z.ai/api/coding/paas/v4/chat/completions` |
|
||
| **API Key 有效性** | ✅ 有效 | Coding Plan Key 可正常调用 |
|
||
|
||
### 配置更新
|
||
|
||
**GLM Coding Plan 正确端点**:
|
||
```bash
|
||
# Codex CLI (OpenAI 兼容)
|
||
export OPENAI_API_BASE="https://api.z.ai/api/coding/paas/v4"
|
||
|
||
# Gemini CLI (OpenAI 兼容)
|
||
export OPENROUTER_BASE_URL="https://api.z.ai/api/coding/paas/v4"
|
||
|
||
# Claude Code (Anthropic 兼容)
|
||
export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
|
||
```
|
||
|
||
**ttyd 使用方式**:
|
||
```bash
|
||
# 共享 tmux 会话
|
||
ttyd -p 8088 tmux attach -t sanguo_dev
|
||
|
||
# 访问: http://YOUR_LAN_IP:8088
|
||
```
|
||
|
||
---
|
||
|
||
**文档版本**: v0.2
|
||
**最后更新**: 2026-06-30
|
||
**作者**: Claude Dev
|
||
**审核状态**: 待审核
|
||
**实施状态**: 环境准备完成 ⚠️ - GLM Coding Plan 端点验证成功，但 Codex/Gemini CLI 不兼容
|
||
|
||
## 14. GLM Coding Plan 兼容性说明
|
||
|
||
### 验证结果
|
||
|
||
| 组件 | 端点 | 状态 | 说明 |
|
||
|------|------|------|------|
|
||
| **curl 直接调用** | `https://api.z.ai/api/coding/paas/v4/chat/completions` | ✅ 成功 | 返回完整响应 |
|
||
| **Codex CLI** | 同上 | ❌ 失败 | 需要 `/responses` WebSocket 端点 |
|
||
| **Gemini CLI** | 同上 | ❌ 失败 | 使用 OpenRouter 格式，不兼容 |
|
||
|
||
### 推荐方案
|
||
|
||
**直接使用 Claude Code + GLM-5.2**（无需 CCB 桥接）：
|
||
|
||
```json
|
||
// ~/.claude/settings.json
|
||
{
|
||
"env": {
|
||
"CLAUDE_CODE_AUTO_COMPACT_WINDOW": "1000000",
|
||
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7",
|
||
"ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-5.2[1m]",
|
||
"ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5.2[1m]"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Claude Code GLM-5.2 端点**：
|
||
- Anthropic 兼容：`https://api.z.ai/api/anthropic`
|
||
- 使用 1M 上下文：模型名称加 `[1m]` 后缀
|
||
|
||
### CCB 替代方案
|
||
|
||
如果仍需多 AI 协作，可考虑：
|
||
1. 使用支持 OpenAI 标准格式的其他 CLI 工具
|
||
2. 直接通过 HTTP API 调用 GLM-5.2
|
||
3. 等待 Codex/Gemini CLI 支持更多端点格式
|
||
|
||
**文档版本**: v0.2
|
||
**最后更新**: 2026-06-29
|
||
**作者**: Claude Dev
|
||
**审核状态**: 待审核
|
||
**实施状态**: 进行中 - 环境准备完成，API 连接待排查
|