sanguo_moziplus_v3/docs/design/02-videotext-investigation-report.md

# videotext 方案调查报告

**来源**: /Volumes/KnowledgeBase/videotext/
**图片数量**: 23张
**提取时间**: 2026-06-29
**文档状态**: 原始回溯，无加工

---

## 一、方案概述

这是一个 **Claude Code + Superpowers + CCB (Claude Code Bridge)** 多 AI 协作开发方案。

### 核心理念

**让 Claude 只做决策（高价值），把体力活交给便宜的 AI**

---

## 二、三层架构

### 2.1 架构图

```
CLAUDE.md (规则层)
  ↓ Claude 启动时自动读取，里面定义了协作规范和角色分工

Superpowers (能力层)
  ↓ 作为 Skills 安装在 .claude/skills/ 目录下，提供标准化的规划、审查、调试流程

CCB (通信层)
  ↓ 桥接器，让 Claude 能通过 /ask、/pend、/ping 指挥 Codex 和 Gemini
```

### 2.2 完整链路

```
CLAUDE.md 定好规则 → Superpowers 提供标准流程 → CCB 打通多模型通信
```

---

## 三、角色分工

### Claude (架构师 / 项目经理)

**职责**:
- 需求分析、架构设计、任务拆分
- 使用 Superpowers 进行规划、审查、调试
- 代码审核、最终验收、Git 提交管理
- **绝对不亲自编写代码**

**成本**: 最贵，但用量极少（仅规划、任务拆分、验收）

### Codex (后端开发)

**职责**:
- 服务端代码、API、数据库、Migration
- 单元测试、集成测试

**调用方式**: `/ask codex "..."`

**成本**: 几乎免费（代码、数据库、测试）

### Gemini (前端开发)

**职责**:
- 前端组件、页面、样式、交互逻辑
- 代码审查、安全审计

**调用方式**: `/ask gemini "..."`

**成本**: 几乎免费（前端页面、代码审查、安全审计）

---

## 四、成本结构

| AI | 角色 | 成本特点 |
|---|------|---------|
| Claude | 规划、任务拆分、验收 | 最贵，但用量极少 |
| Codex | 代码、数据库、测试 | 几乎免费 |
| Gemini | 前端、代码审查、安全审计 | 几乎免费 |

---

## 五、前置准备

### 5.1 环境检查

需要安装三样工具：

1. **Claude Code**
2. **Codex CLI** (OpenAI 的命令行工具)
   ```bash
   npm install -g @openai/codex
   export OPENAI_API_KEY="你的 OpenAI Key"
   ```

3. **Gemini CLI** (Google 的命令行工具)
   ```bash
   npm install -g @google/gemini-cli
   export GEMINI_API_KEY="你的 Gemini Key"
   ```

### 5.2 版本验证

```bash
claude --version   # 2.1.39
codex --version    # codex-cli 0.98.0
gemini --version    # 有版本号输出
```

### 5.3 tmux 安装

**Mac**:
```bash
brew install tmux
tmux -V
```

**Linux (Ubuntu/Debian)**:
```bash
sudo apt-get install tmux
tmux -V
```

**Windows**:
```bash
choco install tmux
# 或
scoop install tmux
tmux -V
```

### 5.4 tmux 配置 (~/.tmux.conf)

```bash
# 启用鼠标支持
set -g mouse on

# 设置前缀键为 Ctrl+a
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# 设置窗口和面板的索引从 1 开始
set -g base-index 1
setw -g pane-base-index 1

# 状态栏配置
set -g status-left-length 32
set -g status-right-length 150
set -g status-interval 5
set -g status-bg colour234
set -g status-fg white
```

### 5.5 tmux 基本操作

- 创建新会话: `tmux new -s session_name`
- 分离会话: `Ctrl+a d`
- 重新连接: `tmux attach -t session_name`
- 切换窗口: `Ctrl+a 数字`
- 切换面板: `Ctrl+a 方向键`
- 垂直分割: `Ctrl+a %`
- 水平分割: `Ctrl+a "`
- 关闭面板: `Ctrl+a x`

---

## 六、CCB (Claude Code Bridge) 安装

### 6.1 系统要求

- Python 3.10 以上版本

```bash
python3 --version  # 需要 3.10+
```

### 6.2 安装步骤

```bash
git clone https://github.com/bfly123/claude_code_bridge.git
```

**注意**: CCB 是社区项目，作者 bfly123 开源，不是官方内置功能。

### 6.3 CCB 安装后自动配置

安装后，CCB 会自动：
- 往 CLAUDE.md 追加配置
- 注册 `/ask`、`/pend`、`ping` 命令
- 更新 Codex skills 目录
- 更新 AI 协作规则
- 安装辅助脚本 (ccb-status.sh, ccb-border.sh, ccb-nit.sh)

### 6.4 可用命令

```bash
# Codex 通信
cask / cping / cpend

# Gemini 通信
gask / gping / gpend
```

---

## 七、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. **这个方案真的能解决问题吗？** → 拒绝自嗨

---

## 九、实战演示架构

### 启动顺序

```
askd started at 127.0.0.1:32779
  ↓
Starting Gemini backend (tmux)
Gemini started! (tmux pane: #1)
  ↓
Starting Codex backend (tmux)
Codex started! (tmux pane: #2)
  ↓
Waiting for codex...
Codex connection OK (Session healthy)
  ↓
Starting Claude...
Session ID: 1770888307-6072
Runtime dir: /tmp/claude-ai-dev-ai-1770888307-6072
Active backends: codex, gemini, claude
```

### 三个终端界面

1. **Claude 端** — 规划与指挥
2. **Gemini 端** — 前端开发
3. **Codex 端** — 后端开发

---

## 十、Superpowers Marketplace 安装

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

---

## 附录：技术栈和版本

| 组件 | 版本 |
|------|------|
| Claude Code | v2.1.39 |
| CCB | v5.2.3 |
| Codex CLI | 0.98.0 |
| Python | 3.10+ |
| tmux | 系统包管理器安装 |

---

## 十一、GLM-5.2 配置方案（补充调研）

### 11.1 智谱 AI GLM-5.2 概述

**模型信息**:
- 模型名称: `glm-5.2`
- 上下文长度: 1M token（100万）
- 发布时间: 2026-06-13
- 特色: 长程 Coding Agent 场景优化

**OpenAI 兼容端点**:
```bash
base_url: https://api.zhipuai.cn/v1
```

### 11.2 Codex CLI 配置 GLM-5.2

**方案一：通过 config.toml 配置**

编辑 `~/.codex/config.toml`:
```toml
[profile.default]
openai_base_url = "https://api.zhipuai.cn/v1"
model = "glm-5.2"
```

设置 API Key:
```bash
export OPENAI_API_KEY="你的智谱API_Key"
```

**方案二：通过环境变量（更简单）**
```bash
export OPENAI_API_BASE="https://api.zhipuai.cn/v1"
export OPENAI_API_KEY="你的智谱API_Key"
```

**验证配置**:
```bash
codex --version
codex "测试"
```

### 11.3 Gemini CLI 配置 GLM-5.2

**根据智谱 AI 官方文档，需要使用定制版 Gemini CLI**

#### 获取定制版本

```bash
git clone https://github.com/heartyguy/gemini-cli
cd gemini-cli
git checkout feature/openrouter-support
```

#### 环境配置

**配置 API 基础 URL**:
```bash
export OPENROUTER_BASE_URL="https://open.bigmodel.cn/api/coding/paas/v4"
```

**配置 API Key**:
```bash
export OPENROUTER_API_KEY="你的智谱API_Key"
```

#### 系统要求

- Node.js 版本 >= 18

#### 完整配置示例

```bash
# 1. 克隆定制版本
git clone https://github.com/heartyguy/gemini-cli
cd gemini-cli
git checkout feature/openrouter-support

# 2. 安装依赖
npm install

# 3. 设置环境变量
export OPENROUTER_BASE_URL="https://open.bigmodel.cn/api/coding/paas/v4"
export OPENROUTER_API_KEY="你的智谱API_Key"

# 4. 启动
npm start
```

---

## 十二、配置总结

### 12.1 两个 CLI 都可以配置 GLM-5.2

| CLI | 配置方式 | Base URL |
|-----|---------|----------|
| **Codex CLI** | config.toml 或环境变量 | `https://api.zhipuai.cn/v1` |
| **Gemini CLI** | 定制版本 + 环境变量 | `https://open.bigmodel.cn/api/coding/paas/v4` |

### 12.2 API Key 格式

智谱 AI 的 API Key 格式：
```
xxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxx
```

### 12.3 模型名称

```
glm-5.2
```

---

## 十三、tmux Web 访问方案（补充调研）

### 13.1 可行方案

**推荐工具：gotty** - 将 tmux 会话共享为 web 应用

### 13.2 方案一：gotty（推荐）

#### 安装

**Mac (Homebrew)**:
```bash
brew install yudai/gotty/gotty
```

**Go 环境**:
```bash
go get github.com/yudai/gotty
```

#### 基本使用

**1. 启动 tmux 会话**
```bash
tmux new -s mysession
```

**2. 用 gotty 共享 tmux 会话**
```bash
gotty tmux attach -t mysession
```

**3. 访问**
- 本地访问: `http://localhost:8080`
- 局域网访问: `http://YOUR_LAN_IP:8080`

#### 局域网配置

**命令行参数**:
```bash
gotty -a 0.0.0.0 -p 8080 tmux attach -t mysession
```

**配置文件 (~/.gotty)**:
```
address = "0.0.0.0"
port = "8080"
permit_write = true
enable_basic_auth = false
```

**查看本机 IP**:
```bash
ifconfig | grep inet
# 或
ip addr show
```

### 13.3 方案二：webtmux（专为 tmux 设计）

**GitHub**: https://github.com/chrismccord/webtmux

**特点**:
- 基于 gotty，专门为 tmux 优化
- 可视化面板布局
- 触摸友好控制
- 更好的移动端支持

**基本使用**:
```bash
# 克隆项目
git clone https://github.com/chrismccord/webtmux
cd webtmux
make

# 运行
./webtmux --address 0.0.0.0 --port 8080
```

### 13.4 局域网访问要点

| 配置项 | 说明 |
|--------|------|
| **bind 0.0.0.0** | 监听所有网络接口（允许局域网访问） |
| **防火墙** | 确保端口 8080 未被阻止 |
| **获取 IP** | `ifconfig` 或 `ip addr` 查看局域网 IP |

**访问地址示例**:
```
http://192.168.1.100:8080
http://192.168.2.154:8080
```

---

**报告结束**