refactor: 重新组织文档结构

- docs/PRD.md - 产品需求文档（移到根目录） - docs/design/01-design-v0.1.md - 系统设计文档（移到子目录） Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-29 08:25:00 +08:00
parent d811a5e212
commit 37579ebdcd
2 changed files with 0 additions and 0 deletions
@@ -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
+**审核状态**: 待审核