sanguo/sanguo_moziplus_v3
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: v0.1 PRD 和设计文档

Browse Source 
- docs/01-PRD-v0.1.md: 产品需求文档
  - 项目定位：多 AI 桥接协作系统
  - 用户场景：研发提效、通用编排、特定场景
  - 核心功能：桥接通信、角色分工、三层架构、成本追踪

- design/01-design-v0.1.md: 系统设计文档
  - 架构设计：规则层、能力层、通信层分离
  - 核心组件：桥接器、任务编排器、成本追踪器
  - 协作模式：串行审查、对抗辩论、三方共识
  - 数据库设计：tasks、costs、collaborations 表

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Dev
2026-06-29 07:11:42 +08:00
parent 342c4ee24c
commit 37ba76f92e
2 changed files with 1131 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
design/01-design-v0.1.md
+750
View File
@@ -0,0 +1,750 @@
# sanguo_moziplus_v3 设计文档 v0.1
**项目名称**: sanguo_moziplus_v3
**版本**: v0.1
**创建日期**: 2026-06-29
**状态**: Draft
---
## 1. 架构概述
### 1.1 系统架构图
```
┌─────────────────────────────────────────────────────────────────┐
│ Claude Code CLI │
│ (用户交互层) │
└─────────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────────▼───────────────────────────────────┐
│ CLAUDE.md (规则层) │
│ - 协作规范 │
│ - 角色分工 │
│ - Git 规范 │
└─────────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────────▼───────────────────────────────────┐
│ Superpowers (能力层) │
│ - Planning Skill │
│ - Review Skill │
│ - Debug Skill │
└─────────────────────────────┬───────────────────────────────────┘
│
┌─────────────────────────────▼───────────────────────────────────┐
│ CCB (通信层) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │Bridge │ │Bridge │ │Bridge │ │Bridge │ │
│ │Codex │ │Gemini │ │GPT │ │Custom │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
└───────┼────────────┼────────────┼────────────┼───────────────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐
│Codex │ │Gemini │ │GPT │ │Custom │
│API │ │API │ │API │ │API │
└───────┘ └───────┘ └───────┘ └───────┘
┌─────────────────────────────────────────────────────────────────┐
│ 任务存储层 (SQLite) │
│ - tasks (任务表) │
│ - collaborations (协作记录表) │
│ - costs (成本表) │
└─────────────────────────────────────────────────────────────────┘
```
### 1.2 核心设计原则
1. **分层解耦**: 规则层、能力层、通信层清晰分离
2. **可扩展**: 桥接器插件化，支持新增 AI 模型
3. **可配置**: 通过配置文件定义角色和协作模式
4. **成本优先**: Claude 只做决策，体力活交给便宜 AI
---
## 2. 核心组件设计
### 2.1 CCB 桥接器 (Bridge)
#### 2.1.1 桥接器接口
```python
class BridgeAgent(ABC):
"""桥接器抽象基类"""
@abstractmethod
async def ask(self, prompt: str, context: dict) -> BridgeResponse:
"""向 AI 发送请求"""
pass
@abstractmethod
def get_cost(self) -> TokenCost:
"""获取成本统计"""
pass
@abstractmethod
def get_capabilities(self) -> List[str]:
"""获取能力列表"""
pass
```
#### 2.1.2 具体实现
**Codex Bridge**:
```python
class CodexBridge(BridgeAgent):
def __init__(self, api_key: str, endpoint: str):
self.api_key = api_key
self.endpoint = endpoint
async def ask(self, prompt: str, context: dict) -> BridgeResponse:
# 调用 Codex API
response = await self._call_codex(prompt, context)
return BridgeResponse(
content=response.content,
tokens_used=response.tokens,
cost=response.tokens * CODEX_PRICE
)
```
**Gemini Bridge**:
```python
class GeminiBridge(BridgeAgent):
def __init__(self, api_key: str, model: str = "gemini-pro"):
self.api_key = api_key
self.model = model
async def ask(self, prompt: str, context: dict) -> BridgeResponse:
# 调用 Gemini API
response = await self._call_gemini(prompt, context)
return BridgeResponse(
content=response.content,
tokens_used=response.tokens,
cost=response.tokens * GEMINI_PRICE
)
```
### 2.2 任务编排器 (Orchestrator)
#### 2.2.1 任务模型
```python
from enum import Enum
from datetime import datetime
from typing import Optional, List, Dict, Any
class TaskType(Enum):
PLAN = "plan" # 规划任务
CODE_BACKEND = "code_backend" # 后端编码
CODE_FRONTEND = "code_frontend" # 前端编码
REVIEW = "review" # 代码审查
VERIFY = "verify" # 验收测试
class TaskStatus(Enum):
PENDING = "pending"
IN_PROGRESS = "in_progress"
COMPLETED = "completed"
FAILED = "failed"
BLOCKED = "blocked"
class AgentRole(Enum):
CLAUDE = "claude" # PM / 架构师
CODEX = "codex" # 后端开发
GEMINI = "gemini" # 前端开发
GPT = "gpt" # 通用助手
@dataclass
class TokenCost:
model: str
input_tokens: int
output_tokens: int
total_cost: float
@property
def total_tokens(self) -> int:
return self.input_tokens + self.output_tokens
@dataclass
class Task:
id: str
type: TaskType
title: str
description: str
assigned_to: AgentRole
status: TaskStatus = TaskStatus.PENDING
dependencies: List[str] = field(default_factory=list)
input: Dict[str, Any] = field(default_factory=dict)
output: Dict[str, Any] = field(default_factory=dict)
cost: Optional[TokenCost] = None
created_at: datetime = field(default_factory=datetime.now)
completed_at: Optional[datetime] = None
error_message: Optional[str] = None
def can_execute(self, completed_tasks: set) -> bool:
"""检查任务是否可以执行（依赖已完成）"""
return all(dep in completed_tasks for dep in self.dependencies)
```
#### 2.2.2 编排器实现
```python
class TaskOrchestrator:
"""任务编排器"""
def __init__(self, db_path: str):
self.db = sqlite3.connect(db_path)
self.bridges: Dict[AgentRole, BridgeAgent] = {}
self._init_bridges()
def _init_bridges(self):
"""初始化桥接器"""
config = self._load_config()
if config.get("codex", {}).get("enabled"):
self.bridges[AgentRole.CODEX] = CodexBridge(...)
if config.get("gemini", {}).get("enabled"):
self.bridges[AgentRole.GEMINI] = GeminiBridge(...)
async def create_task(self, task: Task) -> str:
"""创建任务"""
await self.db.execute(
"INSERT INTO tasks ...",
task.to_dict()
)
return task.id
async def execute_task(self, task_id: str) -> Task:
"""执行任务"""
task = await self._get_task(task_id)
# 检查依赖
if not task.can_execute(await self._get_completed_tasks()):
raise TaskBlockedError("Dependencies not met")
# 获取桥接器
bridge = self.bridges.get(task.assigned_to)
if not bridge:
raise BridgeNotFoundError(f"No bridge for {task.assigned_to}")
# 执行任务
task.status = TaskStatus.IN_PROGRESS
await self._update_task(task)
try:
response = await bridge.ask(
prompt=task.description,
context=task.input
)
task.output = response.content
task.cost = response.cost
task.status = TaskStatus.COMPLETED
task.completed_at = datetime.now()
except Exception as e:
task.status = TaskStatus.FAILED
task.error_message = str(e)
await self._update_task(task)
return task
```
### 2.3 成本追踪器 (CostTracker)
```python
class CostTracker:
"""成本追踪器"""
async def record_cost(self, task_id: str, cost: TokenCost):
"""记录成本"""
await self.db.execute(
"INSERT INTO costs (task_id, model, input_tokens, output_tokens, total_cost) VALUES (?, ?, ?, ?, ?)",
(task_id, cost.model, cost.input_tokens, cost.output_tokens, cost.total_cost)
)
async def get_cost_report(self, project_id: str) -> CostReport:
"""获取成本报告"""
rows = await self.db.execute(
"SELECT model, SUM(input_tokens), SUM(output_tokens), SUM(total_cost) FROM costs WHERE project_id = ? GROUP BY model",
(project_id,)
)
return CostReport(
by_model=[{r[0]: {"tokens": r[1]+r[2], "cost": r[3]}} for r in rows],
total=sum(r[3] for r in rows)
)
```
---
## 3. 数据库设计
### 3.1 表结构
#### tasks 表
```sql
CREATE TABLE tasks (
id TEXT PRIMARY KEY,
type TEXT NOT NULL,
title TEXT NOT NULL,
description TEXT NOT NULL,
assigned_to TEXT NOT NULL,
status TEXT NOT NULL,
dependencies TEXT, -- JSON array
input TEXT, -- JSON object
output TEXT, -- JSON object
cost_model TEXT,
cost_input_tokens INTEGER,
cost_output_tokens INTEGER,
cost_total REAL,
created_at TEXT NOT NULL,
completed_at TEXT,
error_message TEXT
);
CREATE INDEX idx_tasks_status ON tasks(status);
CREATE INDEX idx_tasks_assigned ON tasks(assigned_to);
```
#### costs 表
```sql
CREATE TABLE costs (
id INTEGER PRIMARY KEY AUTOINCREMENT,
task_id TEXT NOT NULL,
model TEXT NOT NULL,
input_tokens INTEGER NOT NULL,
output_tokens INTEGER NOT NULL,
total_cost REAL NOT NULL,
recorded_at TEXT NOT NULL,
FOREIGN KEY (task_id) REFERENCES tasks(id)
);
CREATE INDEX idx_costs_model ON costs(model);
CREATE INDEX idx_costs_task ON costs(task_id);
```
#### collaborations 表
```sql
CREATE TABLE collaborations (
id INTEGER PRIMARY KEY AUTOINCREMENT,
project_id TEXT NOT NULL,
task_id TEXT NOT NULL,
from_agent TEXT NOT NULL,
to_agent TEXT NOT NULL,
message TEXT NOT NULL,
created_at TEXT NOT NULL,
FOREIGN KEY (task_id) REFERENCES tasks(id)
);
```
---
## 4. 协作模式设计
### 4.1 串行审查模式 (Superpowers)
```
┌─────────────┐
│ Implementer │
│ (Codex) │
└──────┬──────┘
│ task_completed
▼
┌─────────────┐
│Spec Reviewer│
│ (Gemini) │
└──────┬──────┘
│ spec_passed
▼
┌──────────────────┐
│ Code Quality │
│ Reviewer │
│ (Gemini) │
└──────┬───────────┘
│ quality_passed
▼
┌─────────────┐
│ Next Task │
└─────────────┘
```
**实现要点**:
- Implementer 完成任务后报告状态
- Spec Reviewer 先检查实现与需求一致性
- 通过后再进行 Code Quality Review
- 任一环节失败则返回 Implementer
### 4.2 对抗辩论模式 (TradingAgents)
```
┌──────────────────┐
│ 4 Analysts (并行) │
└────┬────────┬────┘
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ Bull │ │ Bear │
└────┬────┘ └────┬────┘
│ │
└─────┬─────┘
▼
┌─────────┐
│Research │
│ Manager │
└────┬────┘
▼
┌─────────┐
│ Trader │
└─────────┘
```
**实现要点**:
- 多个 Analyst 并行分析
- Bull 和 Bear 交替辩论（最多 N 轮）
- Research Manager 裁决并综合
- 最终由 Trader 做决策
### 4.3 三方共识模式 (oh-my-claudecode)
```
┌─────────┐
│ Planner │
└────┬────┘
│ plan_ready
▼
┌───────────┐
│ Architect │
└────┬──────┘
│ architecture_approved
▼
┌─────────┐
│ Critic │
└────┬────┘
│ consensus_reached
▼
┌─────────────┐
│ Execute │
└─────────────┘
```
**实现要点**:
- Planner 先做规划
- Architect 审查架构
- Critic 提出批判
- 三方达成共识后才执行
---
## 5. 配置设计
### 5.1 CLAUDE.md 模板
```markdown
# {项目名称}
## 工作模式
Superpowers + AI 协作
## 角色分工
### Claude (我) — 架构师 / 项目经理
- 需求分析、架构设计、任务拆分
- 使用 Superpowers 进行规划、审查、调试
- 代码审核、最终验收、Git 提交管理
- **绝对不亲自编写代码**
### Codex — 后端开发
- 服务端代码、API、数据库、Migration
- 单元测试、集成测试
- 通过 `ask codex "..."` 调用
### Gemini — 前端开发
- 前端组件、页面、样式、交互逻辑
- 代码审查、安全审计
- 通过 `ask gemini "..."` 调用
## 协作规范
1. Claude 不写代码，所有编码任务委派给 Codex/Gemini
2. 后端任务 → Codex，前端任务 → Gemini
3. 代码审查 → Gemini
4. 验收测试 → Claude
## Git 规范
- 分支命名: `feature/<task-name>`
- 提交格式: `<type>: <description>`
- 合并策略: Squash merge
```
### 5.2 配置文件 (config.yaml)
```yaml
# 项目配置
project:
name: "sanguo_moziplus_v3"
description: "多 AI 桥接协作系统"
# 桥接器配置
bridges:
codex:
enabled: true
endpoint: "http://localhost:8080"
api_key_env: "CODEX_API_KEY"
model: "codex-4"
max_tokens: 4000
gemini:
enabled: true
endpoint: "http://localhost:8081"
api_key_env: "GEMINI_API_KEY"
model: "gemini-pro"
max_tokens: 4000
gpt:
enabled: false
endpoint: "https://api.openai.com/v1"
api_key_env: "OPENAI_API_KEY"
model: "gpt-4"
max_tokens: 4000
# 协作模式配置
collaboration:
default_mode: "sequential" # sequential, debate, consensus
max_retries: 3
timeout_seconds: 300
# 成本配置
cost:
tracking_enabled: true
alert_threshold: 10.0 # 美元
models:
claude:
input_price: 0.003 # per 1k tokens
output_price: 0.015
codex:
input_price: 0.0001
output_price: 0.0002
gemini:
input_price: 0.0001
output_price: 0.0001
gpt:
input_price: 0.03
output_price: 0.06
# 数据库配置
database:
path: "~/.moziplus-v3/tasks.db"
backup_enabled: true
backup_interval_hours: 24
```
---
## 6. API 设计
### 6.1 Claude Code 集成 API
```python
class CCBClient:
"""CCB 客户端，供 Claude Code 调用"""
async def ask(self, agent: str, task: str, context: dict = None) -> dict:
"""
委派任务给指定 AI
Args:
agent: AI 名称 (codex, gemini, gpt)
task: 任务描述
context: 上下文信息
Returns:
{
"task_id": "...",
"status": "pending",
"estimated_cost": 0.01
}
"""
pass
async def status(self, task_id: str) -> dict:
"""查询任务状态"""
pass
async def cost(self, project_id: str = None) -> dict:
"""获取成本统计"""
pass
async def config(self, key: str = None, value: Any = None) -> dict:
"""配置管理"""
pass
```
### 6.2 命令行接口
```bash
# 委派任务
moziplus ask codex "实现用户认证 API"
# 查询状态
moziplus status <task_id>
# 成本报告
moziplus cost
# 配置管理
moziplus config set collaboration.default_mode debate
```
---
## 7. 实现计划
### 7.1 Phase 1: 桥接器实现 (Week 1)
- [ ] 实现 BridgeAgent 抽象类
- [ ] 实现 CodexBridge
- [ ] 实现 GeminiBridge
- [ ] 实现 GPTBridge
- [ ] 单元测试
### 7.2 Phase 2: 任务编排器 (Week 1-2)
- [ ] 实现任务模型
- [ ] 实现数据库层
- [ ] 实现任务编排器
- [ ] 实现成本追踪器
- [ ] 集成测试
### 7.3 Phase 3: Claude Code 集成 (Week 2)
- [ ] 实现 CCBClient
- [ ] 实现命令行接口
- [ ] 实现 CLAUDE.md 加载
- [ ] 端到端测试
### 7.4 Phase 4: 协作模式 (Week 3)
- [ ] 实现串行审查模式
- [ ] 实现对抗辩论模式
- [ ] 实现三方共识模式
- [ ] 模式测试
---
## 8. 技术栈
| 组件 | 技术 | 说明 |
|------|------|------|
| **语言** | Python 3.11+ | 主要开发语言 |
| **数据库** | SQLite | 任务存储 |
| **异步** | asyncio | 异步任务处理 |
| **配置** | PyYAML | 配置文件解析 |
| **CLI** | Click / Typer | 命令行接口 |
| **测试** | pytest | 单元测试和集成测试 |
| **API 调用** | httpx | HTTP 客户端 |
---
## 9. 部署架构
```
┌─────────────────────────────────────────────────┐
│ 开发环境 │
│ ~/.openclaw/sanguo_projects/sanguo_moziplus_v3 │
└─────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐
│ 安装环境 │
│ ~/.sanguo_projects/sanguo_moziplus_v3 │
└─────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐
│ 数据目录 │
│ ~/.moziplus-v3/ │
│ - tasks.db │
│ - config.yaml │
│ - logs/ │
└─────────────────────────────────────────────────┘
```
---
## 10. 与 v2 的集成
### 10.1 兼容性设计
- v3 可独立运行
- 可选择性集成 v2 的黑板架构
- 共享数据库 schema（部分表）
### 10.2 迁移路径
```
v2 用户 → v3 迁移步骤：
1. 安装 v3
2. 配置桥接器
3. 更新 CLAUDE.md
4. 运行迁移脚本
5. 验证功能
```
---
## 11. 测试策略
### 11.1 单元测试
- 桥接器测试（Mock API）
- 任务模型测试
- 成本计算测试
### 11.2 集成测试
- 端到端任务流程
- 多 AI 协作场景
- 成本追踪验证
### 11.3 压力测试
- 并发任务处理
- 大量任务调度
- 长时间运行稳定性
---
## 12. 监控和日志
### 12.1 日志策略
```python
import logging
logger = logging.getLogger("moziplus-v3")
# 任务日志
logger.info(f"Task {task_id} assigned to {agent}")
# 成本日志
logger.info(f"Cost: {model} {tokens} tokens = ${cost}")
# 错误日志
logger.error(f"Task {task_id} failed: {error}")
```
### 12.2 监控指标
- 任务成功率
- 平均任务耗时
- 成本趋势
- 桥接器可用性
---
**文档版本**: v0.1
**最后更新**: 2026-06-29
**作者**: Claude Dev
**审核状态**: 待审核
docs/01-PRD-v0.1.md
+381
View File
@@ -0,0 +1,381 @@
# 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
**审核状态**: 待审核