sanguo/sanguo_moziplus_v3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0829b34b9248f3cd0620997bd33bbd72ba54665a
sanguo_moziplus_v3/docs/design/02-design-v0.2.md
T
claude_dev a1972c7ff9 docs: 更新 v0.2 设计文档中所有旧端点为 GLM Coding Plan 端点 
- 统一使用 https://api.z.ai/api/coding/paas/v4
- 移除所有旧的 api.zhipuai.cn 和 open.bigmodel.cn 引用
2026-06-30 08:18:42 +08:00

16 KiB
Raw Blame History

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

环境变量:

# 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 基础工具安装

# 检查 Claude Code
claude --version

# 安装 tmux
brew install tmux
tmux -V

# 检查 Python
python3 --version  # 需要 3.10+

1.2 安装 Codex CLI

npm install -g @openai/codex
codex --version

配置 GLM-5.2:

创建 ~/.codex/config.toml:

[profile.default]
openai_base_url = "https://api.z.ai/api/coding/paas/v4"
model = "glm-5.2"

设置环境变量:

export OPENAI_API_BASE="https://api.z.ai/api/coding/paas/v4"
export OPENAI_API_KEY="6903e83faf454106aa7529c9e18e2ea5.gYMSjWwk1XDN0U5h"

验证:

codex "测试"

1.3 安装 Gemini CLI（定制版）

# 克隆定制版本
git clone https://github.com/heartyguy/gemini-cli
cd gemini-cli

# 切换到兼容分支
git checkout feature/openrouter-support

# 安装依赖
npm install

配置 GLM-5.2:

export OPENROUTER_BASE_URL="https://api.z.ai/api/coding/paas/v4"
export OPENROUTER_API_KEY="4ae9f90df9514aa8ba61a5ee885d0dab.NIr7DfGQ8rdMN0Cd"

# 启动
npm start

1.4 安装 ttyd (gotty 替代方案)

brew install ttyd

配置 ttyd:

创建 ~/.ttyd:

address = "0.0.0.0"
port = "8088"
permit-write = true
enable-basic-auth = false

使用方式:

# 共享 tmux 会话
ttyd -p 8088 tmux attach -t sanguo_dev

# 或共享新 shell
ttyd -p 8088 bash

Phase 2: CCB 桥接器安装

# 克隆 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 中执行:

/plugin marketplace add https://github.com/obra/superpowers-marketplace

Phase 4: CLAUDE.md 规范配置

项目 CLAUDE.md 模板:

# {项目名称}

## 工作模式

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:

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 环境变量汇总

# 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 端口被占用

解决:

# 查找占用进程
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. 参考资料

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 正确端点:

# 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 使用方式:

# 共享 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 桥接）：

// ~/.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 连接待排查

Reference in New Issue View Git Blame Copy Permalink