@zeyue0329/xiaoma-cli 1.11.0 → 1.13.0

package/docs/roadshow/03-/346/231/272/350/203/275/344/275/223/344/272/244/344/272/222/346/265/201/347/250/213/345/233/276.md

@@ -0,0 +1,334 @@
+# 智能体交互流程图
+
+> XiaoMa-CLI 的核心价值在于**智能体协作编排** -- 多个 AI 智能体按照预定义的工作流自动切换角色、传递上下文、完成端到端的软件开发流程。本文档通过 Mermaid 流程图全面展示这一协作机制。
+
+---
+
+## 1. 全局智能体协作关系图
+
+XiaoMa-CLI 共有 **9 个专业智能体**，覆盖从需求分析到交付的完整软件开发生命周期。每个智能体拥有独立的 persona、menu 命令和专业能力，同时通过**共享命令**实现跨智能体协作。
+
+```mermaid
+graph LR
+    subgraph "分析阶段"
+        AN["📊 业务分析师\nxiaofen"]
+    end
+
+    subgraph "规划阶段"
+        PM["📋 产品经理\nxiaochan"]
+        UX["🎨 UX设计师\nxiaoshe"]
+    end
+
+    subgraph "架构阶段"
+        AR["🏗️ 架构师\nxiaojia"]
+    end
+
+    subgraph "实施阶段"
+        SM["🏃 Scrum Master\nxiaomin"]
+        DEV["💻 开发工程师\nxiaokai"]
+        QA["🧪 QA工程师\nxiaoce"]
+        QF["🚀 快速流开发者\nxiaoquan"]
+    end
+
+    subgraph "文档支持"
+        TW["📚 技术写作\nxiaowen"]
+    end
+
+    AN -->|需求分析| PM
+    AN -->|架构输入| AR
+    PM -->|PRD 与史诗| AR
+    PM -->|UX 需求| UX
+    AR -->|架构设计| SM
+    PM -->|故事定义| SM
+    SM -->|Sprint 规划| DEV
+    SM -->|Sprint 规划| QF
+    DEV -->|代码评审| DEV
+    QF -->|代码评审| QF
+    DEV -->|提交测试| QA
+    SM -->|回顾| PM
+
+    PM -.->|IR 实施就绪| AR
+    PM -.->|CC 航向修正| SM
+    DEV -.->|CR 代码评审| QF
+    AN -.->|DP 项目文档| TW
+```
+
+**图例说明：**
+
+- **实线箭头** -- 主要数据流和工作交接关系
+- **虚线箭头** -- 共享命令触发的跨智能体协作
+- 每个智能体节点标注了其**图标、角色名称和系统标识符**
+
+---
+
+## 2. 三大自动化流水线
+
+XiaoMa-CLI 提供三条核心自动化流水线，实现从需求到交付的端到端自动化。这是框架最核心的能力。
+
+### 2.1 自动需求流水线 (Auto Requirements Pipeline - AR)
+
+自动需求流水线将一份原始需求文档转化为完整的、可实施的技术方案。流水线自动在**分析师、架构师、产品经理**三个角色之间切换，每个步骤都有质量门控和重试机制。
+
+**角色切换路径：** 分析师 -> 架构师 -> 产品经理 -> 架构师
+
+```mermaid
+flowchart TD
+    START(["开始"]) --> S1["Step 1: 初始化\n验证需求文档"]
+    S1 --> S2["Step 2: 需求分析\n📊 分析师角色"]
+    S2 --> S3["Step 3: 当前架构分析\n🏗️ 架构师角色"]
+    S3 --> S4["Step 4: PRD 创建\n📋 产品经理角色"]
+    S4 --> S5["Step 5: PRD 验证\n📋 产品经理角色"]
+    S5 -->|"验证失败（最多3次）"| S4
+    S5 -->|验证通过| S6["Step 6: 创建史诗与故事\n📋 产品经理角色"]
+    S6 --> S7["Step 7: 架构设计\n🏗️ 架构师角色"]
+    S7 --> S8["Step 8: 最终交付"]
+
+    S2 -->|"分析不足（最多2次重试）"| S2
+    S7 -->|"架构不完整（最多2次重试）"| S7
+
+    S8 --> OUT1[/"requirements-analysis.md"/]
+    S8 --> OUT2[/"current-architecture-analysis.md"/]
+    S8 --> OUT3[/"prd.md"/]
+    S8 --> OUT4[/"epics.md"/]
+    S8 --> OUT5[/"architecture.md"/]
+```
+
+**关键特性：**
+
+- **质量门控：** PRD 验证步骤最多重试 3 次，确保产出质量
+- **自动重试：** 需求分析和架构设计步骤各有 2 次重试机会
+- **多角色协作：** 单次流水线运行涉及 3 个不同智能体角色的自动切换
+- **五大交付物：** 需求分析、架构分析、PRD、史诗故事、架构设计文档
+
+---
+
+### 2.2 自动故事流水线 (Auto Story Pipeline - ASP)
+
+自动故事流水线将已规划的故事从发现到测试通过全流程自动化。支持**单故事模式**和**批处理模式**两种运行方式。
+
+```mermaid
+flowchart TD
+    START(["开始"]) --> S1["Step 1: 初始化验证"]
+    S1 --> S2["Step 2: 自动发现故事\n🏃 SM 角色"]
+    S2 --> S3["Step 3: 故事验证\n📋 PM 角色"]
+    S3 --> S4["Step 4: 开发实现\n💻 DEV 角色"]
+    S4 --> S5["Step 5: 代码评审\n评审者角色"]
+    S5 --> S6["Step 6: QA 测试\n🧪 QA 角色"]
+    S6 -->|发现 Bug| S7["Step 7: Bug 修复\n💻 DEV 角色"]
+    S7 -->|"修复后重测（最多5次）"| S6
+    S6 -->|测试通过| S8["Step 8: 最终验证"]
+    S8 --> S9{"Step 9: 循环检查"}
+    S9 -->|"批处理模式\n还有更多故事"| S2
+    S9 -->|全部完成| END(["完成"])
+```
+
+**两种运行模式：**
+
+| 模式 | 说明 | 适用场景 |
+|------|------|----------|
+| **单故事模式** | 只处理一个指定的故事 | 紧急修复、单独功能开发 |
+| **批处理模式** | 自动循环处理所有待办故事 | Sprint 批量开发、自动化交付 |
+
+**关键特性：**
+
+- **Bug 修复循环：** QA 发现问题后自动回到开发修复，最多 5 次循环
+- **四角色协作：** SM -> PM -> DEV -> QA 的完整开发链路
+- **批处理能力：** 可一次性处理整个 Sprint 的所有故事
+
+---
+
+### 2.3 自动全流程流水线 (Auto Full Pipeline - AFP)
+
+自动全流程流水线是 XiaoMa-CLI 的**旗舰能力** -- 将需求流水线和故事流水线串联，实现从原始需求到代码交付的**完全自动化**。
+
+```mermaid
+flowchart TD
+    START(["开始"]) --> P1
+
+    subgraph P1["阶段一：需求分析"]
+        R1["初始化需求"] --> R2["📊 需求分析"]
+        R2 --> R3["🏗️ 架构分析"]
+        R3 --> R4["📋 PRD 创建"]
+        R4 --> R5["📋 PRD 验证"]
+        R5 --> R6["📋 史诗与故事创建"]
+        R6 --> R7["🏗️ 架构设计"]
+        R7 --> R8["交付"]
+    end
+
+    P1 --> P2
+
+    subgraph P2["阶段二：Sprint 规划桥接"]
+        SP["🏃 Sprint 规划\n生成 sprint-status.yaml"]
+    end
+
+    P2 --> P3
+
+    subgraph P3["阶段三：故事开发（批处理循环）"]
+        D1["发现故事"] --> D2["创建故事上下文"]
+        D2 --> D3["💻 开发实现"]
+        D3 --> D4["代码评审"]
+        D4 --> D5["🧪 QA 测试"]
+        D5 --> D6{"还有更多故事?"}
+        D6 -->|是| D1
+        D6 -->|否| DONE
+    end
+
+    DONE(["全部完成"])
+```
+
+**三阶段角色编排：**
+
+| 阶段 | 角色切换路径 | 产出 |
+|------|-------------|------|
+| **阶段一：需求分析** | 分析师 -> 架构师 -> 产品经理 -> 架构师 | PRD、架构文档、史诗与故事 |
+| **阶段二：Sprint 规划** | Scrum Master | sprint-status.yaml |
+| **阶段三：故事开发** | SM -> PM -> DEV -> 评审者 -> QA（循环） | 已测试通过的代码 |
+
+这意味着：**一条命令，从需求到代码交付，全部自动完成。**
+
+---
+
+## 3. 共享命令交叉点
+
+共享命令是 XiaoMa-CLI 智能体协作的关键机制。当一个命令在多个智能体的 menu 中同时出现时，表示这些智能体需要在该节点进行**跨角色协作**。
+
+| 命令 | 命令全称 | 共享智能体 | 用途 |
+|------|----------|------------|------|
+| **IR** | Implementation Readiness | 架构师 + 产品经理 | 实施前对齐验证，确保 PRD 和架构设计一致 |
+| **CC** | Correct Course | 产品经理 + Scrum Master | 中途航向修正，应对需求变更 |
+| **CR** | Code Review | 开发工程师 + 快速流开发者 | 代码评审，两种开发角色共享相同评审标准 |
+| **DP** | Document Project | 分析师 + 技术写作 | 项目文档化，整合分析与写作能力 |
+
+**共享命令的设计理念：**
+
+- 共享命令体现了敏捷开发中的**跨职能协作**原则
+- 同一命令在不同智能体中可能有不同的执行视角，但产出相互补充
+- 流水线自动化时，共享命令是角色切换的**交接点**
+
+---
+
+## 4. 故事状态机
+
+每个用户故事在 XiaoMa-CLI 中遵循严格的状态流转机制。状态存储在 `sprint-status.yaml` 中，由各智能体在工作流执行过程中自动更新。
+
+```mermaid
+stateDiagram-v2
+    [*] --> backlog: 创建
+    backlog --> ready_for_dev: 创建故事上下文 CS
+    ready_for_dev --> in_progress: 开发故事 DS
+    in_progress --> review: 开发完成
+    review --> done: 评审通过
+    review --> in_progress: 评审发现问题
+
+    state "Epic 状态" as epic {
+        [*] --> epic_backlog
+        epic_backlog --> epic_in_progress: 首个故事开始
+        epic_in_progress --> epic_done: 所有故事完成
+    }
+```
+
+**状态说明：**
+
+| 状态 | 含义 | 触发动作 |
+|------|------|----------|
+| `backlog` | 待办 | 故事创建后的初始状态 |
+| `ready_for_dev` | 准备开发 | 执行 CS（创建故事上下文）命令后 |
+| `in_progress` | 开发中 | 执行 DS（开发故事）命令后 |
+| `review` | 评审中 | 开发完成提交评审后 |
+| `done` | 已完成 | 代码评审和 QA 测试均通过后 |
+
+**Epic 与 Story 的联动：**
+
+- Epic 状态由其包含的 Story 状态自动推导
+- 当第一个 Story 进入 `in_progress`，Epic 自动变为 `epic_in_progress`
+- 当所有 Story 达到 `done`，Epic 自动变为 `epic_done`
+
+---
+
+## 5. 单故事开发完整生命周期
+
+下图展示了一个故事从 Sprint 规划到最终完成的完整生命周期，标注了每个阶段负责的智能体角色。
+
+```mermaid
+flowchart LR
+    A["Sprint 规划\n🏃 SM"] --> B["创建故事\n🏃 SM"]
+    B --> C["开发故事\n💻 DEV"]
+    C --> D["代码评审\n👨‍💻 评审者"]
+    D --> E["QA 测试\n🧪 QA"]
+    E --> F["完成"]
+    D -->|发现问题| C
+    E -->|发现 Bug| C
+```
+
+**各阶段详细说明：**
+
+1. **Sprint 规划（SM）** -- Scrum Master 从 Epic 中选取故事，安排 Sprint 计划
+2. **创建故事（SM）** -- 为故事生成开发上下文，包括技术方案、验收标准、相关文件清单
+3. **开发故事（DEV）** -- 开发工程师根据故事上下文进行编码实现
+4. **代码评审（评审者）** -- 专门的评审者角色检查代码质量、架构一致性、最佳实践
+5. **QA 测试（QA）** -- QA 工程师执行测试验证，包括功能测试和回归测试
+6. **完成** -- 故事状态更新为 `done`，Sprint 状态文件同步更新
+
+**回退机制：** 代码评审和 QA 测试阶段发现问题时，故事自动回退到开发阶段进行修复，形成闭环。
+
+---
+
+## 6. 数据流向图
+
+下图展示了 XiaoMa-CLI 工作流中各类文档和数据的流转关系，从原始需求到最终交付的完整数据链路。
+
+```mermaid
+flowchart TD
+    REQ["需求文档"] --> ANA["📊 需求分析"]
+    ANA --> PRD["prd.md"]
+    ANA --> ARCH["architecture.md"]
+    ANA --> EPIC["epics.md"]
+
+    PRD --> IR{"实施就绪检查"}
+    ARCH --> IR
+    EPIC --> IR
+
+    IR -->|通过| SPRINT["sprint-status.yaml"]
+    SPRINT --> STORY["story-file.md"]
+
+    PRD --> STORY
+    ARCH --> STORY
+    EPIC --> STORY
+
+    STORY --> DEV["开发实现"]
+    DEV --> REVIEW["代码评审"]
+    REVIEW --> TEST["QA 测试"]
+    TEST --> DONE["完成交付"]
+
+    DONE --> RETRO["史诗回顾"]
+    RETRO --> NEXT["下一个史诗"]
+```
+
+**数据流关键节点解析：**
+
+| 节点 | 数据格式 | 说明 |
+|------|----------|------|
+| **需求文档** | Markdown | 用户提供的原始需求描述 |
+| **prd.md** | Markdown | 产品需求文档，包含功能规格 |
+| **architecture.md** | Markdown | 架构设计文档，包含技术方案 |
+| **epics.md** | Markdown | 史诗与故事列表，包含验收标准 |
+| **sprint-status.yaml** | YAML | Sprint 状态追踪文件，记录所有故事状态 |
+| **story-file.md** | Markdown | 单个故事的开发上下文文件 |
+
+**实施就绪检查（IR）** 是数据流中的关键质量门控：
+
+- 验证 PRD、架构文档、史诗故事三者之间的**一致性**
+- 确保技术方案覆盖所有产品需求
+- 只有通过 IR 检查，才能进入 Sprint 规划和开发阶段
+
+---
+
+## 总结
+
+XiaoMa-CLI 的智能体交互体系体现了三个核心设计原则：
+
+1. **角色专业化** -- 每个智能体专注于一个领域，拥有独立的 persona 和能力边界
+2. **流水线自动化** -- 通过预定义的工作流编排，实现多角色无缝切换和自动重试
+3. **质量内建** -- 每个关键节点都有验证门控和回退机制，确保产出质量
+
+这套体系让 AI 辅助开发从"单点对话"升级为"全流程自动化协作"。