# sanguo_moziplus_v3 产品需求文档 v0.1

**项目名称**: sanguo_moziplus_v3
**版本**: v0.1
**创建日期**: 2026-06-29
**状态**: Draft

---

## 1. 项目概述

### 1.1 产品定位

sanguo_moziplus_v3 是一个**多 AI 桥接协作系统**，以 Claude Code 为核心调度者，通过桥接器（CCB）实现与多个 AI 模型（Codex、Gemini 等）的协作，最大化开发效率，最小化成本。

**核心定位**：
- **以多 AI 桥接系统为主**：实现跨 AI 通信和任务调度
- **结合全新架构**：整合黑板架构和对抗式协作模式
- **支持三大场景**：研发提效、通用编排、特定场景

### 1.2 核心价值

| 价值维度 | 描述 |
|---------|------|
| **成本优化** | Claude 只做决策（高价值），代码实现交给便宜的 AI |
| **效率提升** | 多 AI 并行工作，各司其职，专业分工 |
| **质量保证** | 内置代码审查和安全审计机制 |
| **架构灵活** | 支持多种协作模式（串行审查、对抗辩论、三方共识） |

### 1.3 与 v2 的区别

| 特性 | moziplus v2 | moziplus v3 |
|------|------------|------------|
| **核心架构** | 黑板架构 + Daemon 调度 | 多 AI 桥接 + 通信层 |
| **AI 模型** | 单一 Claude | Claude + Codex + Gemini + ... |
| **协作模式** | Agent 认领任务 | 桥接器调度，角色分工 |
| **成本策略** | 无优化 | Claude 只做决策，体力活交给便宜 AI |
| **应用场景** | DevOps 自动化 | 研发提效、通用编排、特定场景 |

---

## 2. 用户场景

### 2.1 主要用户场景

#### 场景 1: 研发提效（核心场景）

**用户**: 软件开发团队
**痛点**: Claude 成本高，但代码质量好；便宜的 AI 代码能力弱
**解决方案**: Claude 做架构和验收，Codex/Gemini 写代码

**典型工作流**:
1. 开发者提出需求："实现用户认证功能"
2. Claude 分析需求、拆分任务、设计接口
3. Claude 通过 CCB 委派任务：
   - `ask codex "实现后端认证 API"`
   - `ask gemini "实现登录注册页面"`
4. Codex/Gemini 返回代码
5. Claude 审核代码并验收
6. 提交到 Git

#### 场景 2: 通用编排

**用户**: AI 应用开发者
**痛点**: 需要协调多个 AI 完成复杂任务
**解决方案**: 提供通用的多 AI 编排框架

**典型工作流**:
1. 定义任务流程（规划 → 执行 → 审查 → 验收）
2. 配置每个环节使用的 AI 模型
3. 系统自动调度和协作
4. 收集结果并汇总

#### 场景 3: 特定场景协作

**用户**: 特定业务领域用户
**痛点**: 需要针对特定场景优化的协作模式
**解决方案**: 提供可配置的协作模板

**示例场景**:
- 投资决策：多空辩论模式
- 代码审查：两阶段串行审查
- 架构设计：三方共识模式

### 2.2 用户画像

| 用户类型 | 角色 | 需求 | 使用频率 |
|---------|------|------|---------|
| **核心用户** | 软件工程师 | 日常开发提效 | 每日 |
| **次要用户** | AI 开发者 | 构建多 AI 应用 | 每周 |
| **探索用户** | 技术管理者 | 了解架构和成本 | 偶尔 |

---

## 3. 功能需求

### 3.1 核心功能（P0 - MVP）

#### F1: 多 AI 桥接通信

**描述**: 实现跨 AI 通信能力，让 Claude 能够指挥其他 AI

**子功能**:
- F1.1: 支持与 Codex 通信
- F1.2: 支持与 Gemini 通信
- F1.3: 支持与 OpenAI GPT 通信
- F1.4: 可扩展的桥接器架构

**验收标准**:
- Claude 可以通过简单指令（如 `/ask codex "..."`）调用其他 AI
- 支持异步调用和结果收集
- 通信延迟 < 2 秒

#### F2: 角色分工定义

**描述**: 定义不同 AI 的角色和能力边界

**角色定义**:
| 角色 | 职责 | 工具限制 |
|------|------|---------|
| Claude (PM) | 需求分析、任务拆分、验收 | 无限制 |
| Codex (后端) | 服务端代码、数据库、测试 | 禁用前端工具 |
| Gemini (前端) | 前端组件、页面、样式 | 禁用后端工具 |

**验收标准**:
- 角色定义清晰可配置
- 工具限制硬编码生效
- 支持 CLAUDE.md 规范注入

#### F3: 三层架构支持

**描述**: 实现规则层、能力层、通信层的分离

**层级定义**:
1. **CLAUDE.md (规则层)**: 协作规范、角色分工、Git 规范
2. **Superpowers (能力层)**: 规划、审查、调试等标准化流程
3. **CCB (通信层)**: 跨 AI 桥接通信

**验收标准**:
- 层级清晰分离
- Claude 启动时自动加载 CLAUDE.md
- Superpowers 作为 Skills 可安装
- CCB 作为独立模块可配置

#### F4: 成本追踪

**描述**: 追踪各 AI 的 Token 消耗和成本

**子功能**:
- F4.1: 记录每个 AI 的 Token 使用量
- F4.2: 计算各 AI 的成本占比
- F4.3: 生成成本报告

**验收标准**:
- 实时追踪 Token 消耗
- 成本数据可视化
- 支持成本预警

### 3.2 重要功能（P1 - v0.2）

#### F5: 协作模式模板

**描述**: 提供预定义的协作模式模板

**模板类型**:
1. 串行审查模式（Superpowers 风格）
2. 对抗辩论模式（TradingAgents 风格）
3. 三方共识模式（oh-my-claudecode 风格）
4. 黑板协作模式（moziplus v2 风格）

#### F6: 任务编排引擎

**描述**: 支持复杂的多步骤任务编排

**子功能**:
- DAG 任务依赖管理
- 并行执行支持
- 失败重试机制
- 任务超时控制

#### F7: 代码质量门控

**描述**: 内置代码审查和质量检查

**子功能**:
- 自动代码审查（通过 Gemini）
- 安全审计（静态分析）
- 测试覆盖率检查
- 代码风格检查

### 3.3 可选功能（P2 - 未来版本）

#### F8: Web Dashboard

**描述**: 提供 Web 界面监控和配置

#### F9: 多项目管理

**描述**: 支持同时管理多个项目的协作

#### F10: AI 模型市场

**描述**: 支持接入更多 AI 模型和服务

---

## 4. 非功能需求

### 4.1 性能要求

| 指标 | 要求 |
|------|------|
| **桥接延迟** | < 2 秒 (P95) |
| **任务调度** | 支持 10+ 并发任务 |
| **内存占用** | < 500MB (空闲) |

### 4.2 可靠性要求

| 指标 | 要求 |
|------|------|
| **系统可用性** | > 99% (开发阶段) |
| **数据持久化** | 任务状态不丢失 |
| **错误恢复** | 支持断点续传 |

### 4.3 可扩展性要求

- 支持新增 AI 模型接入（通过插件机制）
- 支持自定义协作模式
- 支持 CLAUDE.md 热更新

### 4.4 安全性要求

- API Key 加密存储
- 通信内容脱敏
- 访问权限控制

---

## 5. 界面需求

### 5.1 Claude Code 集成

**主要交互界面**: Claude Code CLI

**关键交互**:
- `/ask <agent> "<task>"` - 委派任务给指定 AI
- `/status` - 查看任务状态
- `/cost` - 查看成本统计
- `/config` - 配置协作模式

### 5.2 配置文件

**CLAUDE.md 结构**:
```markdown
# 项目名称

## 工作模式
- Superpowers + AI 协作

## 角色分工
- Claude: 架构师/PM
- Codex: 后端开发
- Gemini: 前端开发

## 协作规范
- Claude 不写代码
- 所有编码任务委派给 Codex/Gemini
```

**配置文件 (config.yaml)**:
```yaml
bridge:
  codex:
    enabled: true
    endpoint: "http://localhost:8080"
  gemini:
    enabled: true
    endpoint: "http://localhost:8081"
```

---

## 6. 数据模型

### 6.1 任务模型

```python
class Task:
    id: str
    type: TaskType  # PLAN, CODE, REVIEW, VERIFY
    assigned_to: str  # claude, codex, gemini
    status: TaskStatus  # pending, in_progress, completed, failed
    input: dict
    output: dict
    cost: TokenCost
    created_at: datetime
    completed_at: datetime
```

### 6.2 成本模型

```python
class TokenCost:
    model: str  # claude, codex, gemini
    input_tokens: int
    output_tokens: int
    total_cost: float
```

---

## 7. 里程碑

| 阶段 | 目标 | 交付物 | 时间 |
|------|------|--------|------|
| **v0.1** | MVP 核心功能 | 桥接通信、角色分工、三层架构 | Week 1-2 |
| **v0.2** | 协作模式 | 串行审查、对抗辩论模板 | Week 3-4 |
| **v0.3** | 编排引擎 | DAG 调度、质量门控 | Week 5-6 |
| **v0.4** | 生产就绪 | Dashboard、监控告警 | Week 7-8 |

---

## 8. 风险与挑战

### 8.1 技术风险

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 桥接通信不稳定 | 高 | 实现重试机制和降级策略 |
| AI 能力差异 | 中 | 针对不同 AI 优化 Prompt |
| 成本控制失效 | 中 | 实时监控和预警 |

### 8.2 产品风险

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 用户学习成本高 | 中 | 提供详细文档和示例 |
| 协作效果不理想 | 高 | 持续优化 Prompt 和流程 |

---

## 9. 成功指标

### 9.1 核心指标

- **成本降低**: Claude Token 消耗降低 > 50%
- **效率提升**: 任务完成时间缩短 > 30%
- **质量保证**: 代码审查通过率 > 90%

### 9.2 用户指标

- **采用率**: 活跃项目数 > 10
- **满意度**: NPS > 8
- **留存率**: 月留存 > 80%

---

## 10. 附录

### 10.1 参考文档

- CCB + Superpowers 教程
- moziplus v2 架构文档
- Superpowers 框架文档
- TradingAgents 论文

### 10.2 术语表

| 术语 | 定义 |
|------|------|
| CCB | Claude Code Bridge，多 AI 桥接器 |
| Superpowers | Agentic Skills Framework |
| CLAUDE.md | 项目协作规范文件 |
| TokenCost | Token 成本追踪模型 |

---

**文档版本**: v0.1
**最后更新**: 2026-06-29
**作者**: Claude Dev
**审核状态**: 待审核