# 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 连接待排查