zclaw_openfang/plans/enumerated-hopping-tome.md

# Pipeline 2.0 重构计划

> **目标**: 学习 OpenMAIC 输入→产出→展示流程，重构 ZCLAW Pipeline 系统
> **日期**: 2026-03-26

---

## 一、背景与问题

### 1.1 当前痛点

| 痛点 | 描述 |
|------|------|
| **输入体验差** | YAML 配置繁琐，不够自然语言化 |
| **输出展示单一** | 结果只是文本/文件，缺少丰富的交互式展示 |

### 1.2 学习目标

OpenMAIC 的核心流程：
```
输入 (自然语言/文档) → 生成 (多阶段 Pipeline) → 展示 (幻灯片/白板/测验/图表)
```

### 1.3 设计决策

| 决策点 | 用户选择 |
|--------|---------|
| **输入模式** | 混合式 - 简单任务对话，复杂任务表单 |
| **展示优先级** | P0: 图表+测验 → P1: 幻灯片+白板 |
| **展示决策** | LLM 推荐 + 用户可切换 |

---

## 二、整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         用户界面层                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │  💬 对话入口  │  │  📋 快捷入口  │  │  ⚙️ 高级入口  │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      🧠 智能入口层 (Intent Router)              │
│                                                                 │
│  职责：                                                         │
│  • 意图识别 - 理解用户想做什么                                   │
│  • Pipeline 匹配 - 找到合适的 Pipeline                          │
│  • 模式决策 - conversation / form / hybrid                     │
│  • 参数收集 - 对话收集或表单填充                                 │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      ⚡ 执行引擎层 (Engine v2)                  │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │ StageRunner │  │ ParallelMap │  │ Conditional │            │
│  │ (顺序阶段)   │  │ (并行映射)   │  │ (条件分支)   │            │
│  └─────────────┘  └─────────────┘  └─────────────┘            │
│                                                                 │
│  能力调用：LLM / Skill / Hand / Tool                           │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      🎨 智能展示层 (Presentation)               │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │
│  │ 展示分析器   │  │ 渲染器注册表 │  │ 切换控制器  │            │
│  │ (LLM 推荐)  │  │ (多类型)    │  │ (用户干预)  │            │
│  └─────────────┘  └─────────────┘  └─────────────┘            │
│                                                                 │
│  渲染器：Slideshow / Quiz / Chart / Whiteboard / Document      │
└─────────────────────────────┬───────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                         数据持久层                              │
│                                                                 │
│  • 执行历史 • 生成结果 • 用户偏好 • 模板缓存                    │
└─────────────────────────────────────────────────────────────────┘
```

---

## 三、Pipeline 2.0 格式设计

### 3.1 新格式示例

```yaml
# pipelines/education/course-generator.yaml
apiVersion: zclaw/v2
kind: Pipeline

metadata:
  name: course-generator
  displayName: 课程生成器
  description: 根据主题生成完整的互动课程
  category: education
  icon: 🎓

# 触发条件 - 支持自然语言匹配
trigger:
  patterns:
    - "帮我做*课程"
    - "生成*教程"
    - "我想学习{topic}"
  keywords: [课程, 教程, 学习, 培训]

# 输入模式决策
input:
  mode: auto  # conversation | form | auto
  # auto 模式：简单任务用对话，复杂任务用表单
  complexity_threshold: 3  # 参数超过3个用表单

# 参数定义
params:
  - name: topic
    type: string
    required: true
    label: 课程主题
    description: 你想学习什么内容？
    placeholder: 例如：机器学习基础、Python 入门

  - name: level
    type: select
    label: 难度级别
    options: [入门, 中级, 高级]
    default: 入门

  - name: duration
    type: number
    label: 预计时长（分钟）
    default: 30

# 生成流程
stages:
  - id: outline
    type: llm
    description: 生成课程大纲
    prompt: |
      为"{params.topic}"创建一个{params.level}级别的课程大纲。
      预计学习时长：{params.duration}分钟。

      输出 JSON 格式：
      {
        "title": "课程标题",
        "sections": [
          {"id": "s1", "title": "章节标题", "duration": 10}
        ]
      }
    output_schema: outline_schema

  - id: content
    type: parallel
    description: 并行生成各章节内容
    each: "${stages.outline.sections}"
    stage:
      type: llm
      prompt: |
        为章节"${item.title}"生成详细内容。
        包含：讲解内容、示例、互动问题。
      output_schema: section_schema

  - id: assemble
    type: compose
    description: 组装完整课程
    template: |
      {
        "title": "${stages.outline.title}",
        "sections": ${stages.content},
        "metadata": {
          "level": "${params.level}",
          "duration": ${params.duration}
        }
      }

# 输出定义
output:
  type: dynamic  # LLM 决定展示方式
  allow_switch: true  # 用户可切换
  supported_types:
    - slideshow  # 幻灯片
    - quiz       # 测验
    - document   # 文档
    - whiteboard # 白板
  default_type: slideshow
```

### 3.2 格式对比

| 特性 | Pipeline v1 | Pipeline v2 |
|------|-------------|-------------|
| **触发方式** | 手动选择 | 自然语言匹配 |
| **输入模式** | 固定表单 | 对话/表单/自动 |
| **执行流程** | steps 数组 | stages + 类型 |
| **输出类型** | 文本/文件 | 动态展示组件 |
| **并行支持** | parallel action | parallel stage |
| **条件分支** | condition action | conditional stage |

---

## 四、智能入口层设计

### 4.1 触发器定义格式

```yaml
# Pipeline 中的 trigger 定义
trigger:
  # 快速匹配 - 关键词
  keywords: [课程, 教程, 学习, 培训]

  # 快速匹配 - 正则模式
  patterns:
    - "帮我做*课程"
    - "生成*教程"
    - "我想学习{topic}"

  # 语义匹配提示（用于 LLM 理解）
  description: "根据用户主题生成完整的互动课程内容"

  # 示例（帮助 LLM 匹配）
  examples:
    - "帮我做一个 Python 入门课程"
    - "生成机器学习基础教程"
```

### 4.2 意图路由流程

```rust
pub async fn route(user_input: &str) -> RouteResult {
    // Step 1: 快速匹配 (本地，< 10ms)
    if let Some(pipeline) = quick_match(user_input) {
        return prepare(pipeline, extracted_params);
    }

    // Step 2: 语义匹配 (LLM, ~200ms)
    let intent = llm.analyze_intent(user_input).await;
    let matched = semantic_match(&intent);

    // Step 3: 模式决策
    let mode = decide_mode(&matched);

    RouteResult {
        pipeline_id: matched.id,
        mode,  // conversation | form
        params: intent.extracted_params,
        confidence: intent.confidence,
    }
}
```

### 4.3 参数收集模式

**对话模式** (简单任务，参数 ≤ 3):
```
用户: 帮我做一个 Python 入门课程
系统: 好的！课程预计多长时间学习？(默认 30 分钟)
用户: 1 小时吧
系统: 明白了，开始生成...
```

**表单模式** (复杂任务，参数 > 3):
```
系统检测到 Pipeline 有 5 个参数，自动显示表单：

┌─────────────────────────────────┐
│  📚 课程生成器                   │
├─────────────────────────────────┤
│  课程主题: [Python 入门________] │
│  难度级别: [▼ 入门]              │
│  预计时长: [60] 分钟             │
│  目标受众: [________________]   │
│  特殊要求: [________________]   │
│                                 │
│         [开始生成]               │
└─────────────────────────────────┘
```

---

## 五、执行引擎层设计

### 5.1 Stage 类型体系

```rust
pub enum StageType {
    /// LLM 生成阶段
    Llm {
        prompt: String,           // 支持变量插值 {params.topic}
        model: Option<String>,    // 可选模型覆盖
        temperature: Option<f32>,
        output_schema: Option<JsonSchema>,  // 结构化输出
    },

    /// 并行执行 - 遍历数组，每个元素执行子阶段
    Parallel {
        each: Expression,          // 如 "${stages.outline.sections}"
        stage: Box<StageType>,     // 子阶段模板
        max_workers: usize,        // 并发数限制 (默认 3)
    },

    /// 顺序子阶段
    Sequential {
        stages: Vec<StageType>,
    },

    /// 条件分支
    Conditional {
        condition: Expression,     // 如 "${params.level} == '高级'"
        branches: HashMap<String, StageType>,
        default: Option<Box<StageType>>,
    },

    /// 组合结果 - 模板拼接
    Compose {
        template: String,          // JSON 模板
    },

    /// 调用 Skill
    Skill {
        skill_id: String,
        input: HashMap<String, Expression>,
    },

    /// 调用 Hand
    Hand {
        hand_id: String,
        action: String,
        params: HashMap<String, Expression>,
    },
}
```

### 5.2 执行上下文

```rust
pub struct ExecutionContext {
    // 输入参数 (来自用户)
    params: HashMap<String, Value>,

    // 阶段输出 (累积)
    stages: HashMap<String, Value>,

    // 循环上下文 (Parallel 内部)
    loop_context: Option<LoopContext>,

    // 变量 (中间计算)
    vars: HashMap<String, Value>,

    // 执行状态
    status: ExecutionStatus,
    current_stage: Option<String>,
    progress: f32,
}

pub struct LoopContext {
    item: Value,      // 当前元素
    index: usize,     // 索引
    array: Vec<Value>,// 原数组
}
```

### 5.3 表达式系统

```yaml
# 支持的表达式语法
"${params.topic}"           # 参数引用
"${stages.outline.sections}" # 阶段输出引用
"${item.title}"              # 循环元素
"${index}"                   # 循环索引
"${vars.customVar}"          # 变量引用
```

### 5.4 执行流程示例

```yaml
# 课程生成 Pipeline 执行流程

# Stage 1: outline (Llm)
输入: { params: { topic: "Python", level: "入门" } }
输出: { stages.outline: { title: "...", sections: [...] } }

# Stage 2: content (Parallel)
遍历: stages.outline.sections (假设 5 个章节)
并发: 3 个 worker
每个执行: Llm 生成章节内容
输出: { stages.content: [{...}, {...}, ...] }

# Stage 3: assemble (Compose)
模板: 组装完整课程 JSON
输出: 最终结果
```

### 5.5 进度回调

```rust
pub enum ExecutionEvent {
    StageStart { stage_id: String },
    StageProgress { stage_id: String, progress: f32 },
    StageComplete { stage_id: String, output: Value },
    ParallelProgress { completed: usize, total: usize },
    Error { stage_id: String, message: String },
}
```

---

## 六、智能展示层设计

### 6.1 核心架构

```
Pipeline 执行结果
       ↓
┌─────────────────────────────────────┐
│      Presentation Analyzer          │
│                                     │
│  1. 结构检测 (快速路径, < 5ms)       │
│  2. LLM 分析 (语义理解, ~300ms)      │
│  3. 推荐排序 (置信度排序)            │
└─────────────────────────────────────┘
       ↓
┌─────────────────────────────────────┐
│      Renderer Registry              │
│                                     │
│  • Slideshow (幻灯片)               │
│  • Quiz (测验)                      │
│  • Chart (图表)                     │
│  • Document (文档)                  │
│  • Whiteboard (白板)                │
└─────────────────────────────────────┘
       ↓
┌─────────────────────────────────────┐
│      Type Switcher                  │
│                                     │
│  当前: [📊 图表] [📝 文档] [🎓 测验] │
│  点击可切换展示方式                  │
└─────────────────────────────────────┘
```

### 6.2 结构检测规则

```typescript
// 快速路径 - 基于数据结构自动判断
const detectionRules = [
  // 幻灯片: 有 slides 数组
  {
    type: 'slideshow',
    test: (data) => Array.isArray(data.slides) ||
                   (Array.isArray(data.sections) && data.sections.every(s => s.title && s.content))
  },

  // 测验: 有 quiz.questions 或 questions 数组
  {
    type: 'quiz',
    test: (data) => data.quiz?.questions ||
                   (Array.isArray(data.questions) && data.questions[0]?.options)
  },

  // 图表: 有 chart/data 数组且元素是数值型
  {
    type: 'chart',
    test: (data) => data.chart ||
                   (Array.isArray(data.data) && typeof data.data[0] === 'number') ||
                   data.xAxis || data.yAxis
  },

  // 白板: 有 canvas/elements/strokes
  {
    type: 'whiteboard',
    test: (data) => data.canvas || data.strokes || data.elements
  },

  // 文档: 默认兜底
  { type: 'document', test: () => true }
];
```

### 6.3 LLM 分析提示词

```
分析以下 Pipeline 输出数据，推荐最佳展示方式。

数据结构: {json_structure}
数据摘要: {data_summary}

可选展示类型:
- slideshow: 分页展示，适合课程、汇报
- quiz: 互动测验，适合教育场景
- chart: 数据可视化，适合分析结果
- document: 文档阅读，适合长文本
- whiteboard: 实时标注，适合讲解

返回 JSON:
{
  "primary": "推荐类型",
  "confidence": 0.85,
  "reason": "推荐原因",
  "alternatives": ["其他适合的类型"]
}
```

### 6.4 渲染器接口

```typescript
export interface PresentationRenderer {
  type: PresentationType;
  name: string;
  icon: string;

  // 检查是否能渲染 (用于快速路径)
  canRender(data: unknown): boolean;

  // 渲染 React 组件
  render(data: unknown): React.ReactNode;

  // 导出格式支持
  exportFormats?: ExportFormat[];
}

export type PresentationType =
  | 'slideshow'  // 幻灯片
  | 'quiz'       // 测验
  | 'chart'      // 图表
  | 'document'   // 文档
  | 'whiteboard';// 白板
```

### 6.5 渲染器实现优先级

| 优先级 | 渲染器 | 技术方案 | 工作量 |
|--------|--------|---------|--------|
| **P0** | 📊 Chart | ECharts / Chart.js | 3 天 |
| **P0** | ✅ Quiz | 自定义表单组件 | 3 天 |
| **P1** | 📄 Document | Markdown 渲染 | 2 天 |
| **P1** | 🎨 Slideshow | reveal.js / Swiper | 5 天 |
| **P1** | 📝 Whiteboard | SVG Canvas | 7 天 |

### 6.6 用户切换流程

```
1. Pipeline 执行完成
2. Analyzer 推荐展示类型 (如 slideshow)
3. 渲染 slideshow
4. 显示切换器: [📊 幻灯片✓] [📝 文档] [🎓 测验]
5. 用户点击 "文档"
6. 立即切换到 DocumentRenderer
7. 记录用户偏好 (可选)
```

---

## 七、前端组件设计

### 7.1 新增组件

```
desktop/src/
├── components/
│   ├── pipeline/
│   │   ├── IntentInput.tsx        # 智能输入组件
│   │   ├── ConversationCollector.tsx  # 对话式参数收集
│   │   ├── PipelineSelector.tsx   # Pipeline 选择器
│   │   └── ExecutionProgress.tsx  # 执行进度
│   │
│   └── presentation/
│       ├── PresentationContainer.tsx  # 展示容器
│       ├── TypeSwitcher.tsx       # 类型切换器
│       ├── renderers/
│       │   ├── SlideshowRenderer.tsx
│       │   ├── QuizRenderer.tsx
│       │   ├── ChartRenderer.tsx
│       │   ├── WhiteboardRenderer.tsx
│       │   └── DocumentRenderer.tsx
│       └── analyzer/
│           └── PresentationAnalyzer.ts
│
├── store/
│   ├── pipelineStore.ts           # Pipeline 状态
│   └── presentationStore.ts       # 展示状态
│
└── lib/
    ├── intent-router.ts           # 前端意图路由
    └── presentation/
        └── renderer-registry.ts   # 渲染器注册表
```

### 7.2 UI 流程

```
用户输入 → IntentInput
    ↓
意图分析 (显示推荐 Pipeline)
    ↓
参数收集 (对话 or 表单)
    ↓
执行 → ExecutionProgress
    ↓
结果 → PresentationContainer
    ↓
展示分析 → 推荐渲染器
    ↓
渲染 + 切换器
```

---

## 八、实现计划

### Phase 1: 智能入口层 (1 周)

**目标**: 实现自然语言触发 Pipeline

| 任务 | 文件 | 说明 |
|------|------|------|
| Intent Router | `crates/zclaw-pipeline/src/intent.rs` | 意图识别和路由 |
| Trigger Parser | `crates/zclaw-pipeline/src/trigger.rs` | 触发模式解析 |
| IntentInput 组件 | `desktop/src/components/pipeline/IntentInput.tsx` | 前端输入组件 |

### Phase 2: Pipeline v2 格式 (1 周)

**目标**: 支持新格式定义

| 任务 | 文件 | 说明 |
|------|------|------|
| v2 Parser | `crates/zclaw-pipeline/src/parser_v2.rs` | 新格式解析 |
| Stage Engine | `crates/zclaw-pipeline/src/engine/stage.rs` | 阶段执行器 |
| Context v2 | `crates/zclaw-pipeline/src/engine/context.rs` | 执行上下文 |

### Phase 3: 智能展示层 - P0 (1 周)

**目标**: 实现图表和测验渲染器

| 任务 | 文件 | 说明 |
|------|------|------|
| Presentation Analyzer | `crates/zclaw-pipeline/src/presentation/` | 展示分析 |
| Chart Renderer | `desktop/src/components/presentation/renderers/ChartRenderer.tsx` | 图表渲染 |
| Quiz Renderer | `desktop/src/components/presentation/renderers/QuizRenderer.tsx` | 测验渲染 |
| Type Switcher | `desktop/src/components/presentation/TypeSwitcher.tsx` | 类型切换 |

### Phase 4: 智能展示层 - P1 (2 周)

**目标**: 实现幻灯片和白板渲染器

| 任务 | 文件 | 说明 |
|------|------|------|
| Slideshow Renderer | `desktop/src/components/presentation/renderers/SlideshowRenderer.tsx` | 幻灯片 |
| Whiteboard Renderer | `desktop/src/components/presentation/renderers/WhiteboardRenderer.tsx` | 白板 |

---

## 九、关键文件清单

### 9.1 需要修改的文件

| 文件 | 修改内容 |
|------|---------|
| `crates/zclaw-pipeline/src/lib.rs` | 导出新模块 |
| `crates/zclaw-pipeline/src/types.rs` | 添加 v2 类型 |
| `crates/zclaw-pipeline/src/executor.rs` | 支持 Stage 执行 |
| `desktop/src-tauri/src/pipeline_commands.rs` | 添加新命令 |
| `desktop/src/components/PipelinesPanel.tsx` | 集成新组件 |

### 9.2 需要新增的文件

| 文件 | 说明 |
|------|------|
| `crates/zclaw-pipeline/src/intent.rs` | 意图路由 |
| `crates/zclaw-pipeline/src/trigger.rs` | 触发器解析 |
| `crates/zclaw-pipeline/src/engine/stage.rs` | 阶段执行 |
| `crates/zclaw-pipeline/src/presentation/` | 展示层 |
| `desktop/src/components/pipeline/IntentInput.tsx` | 智能输入 |
| `desktop/src/components/presentation/` | 展示组件 |

---

## 十、验证方案

### 10.1 单元测试

```bash
# Pipeline v2 格式解析
cargo test -p zclaw-pipeline parser_v2

# 意图路由
cargo test -p zclaw-pipeline intent_router

# 阶段执行
cargo test -p zclaw-pipeline stage_engine
```

### 10.2 集成测试

```bash
# 端到端流程
1. 用户输入 "帮我做一个 Python 入门课程"
2. 系统识别意图 → 匹配 course-generator
3. 对话收集参数 (主题: Python, 难度: 入门)
4. 执行 Pipeline
5. 输出展示为幻灯片
6. 用户切换到文档模式
```

### 10.3 手动验证清单

- [ ] 自然语言触发 Pipeline
- [ ] 对话式参数收集
- [ ] 表单式参数输入
- [ ] 执行进度实时显示
- [ ] 图表正确渲染
- [ ] 测验交互正常
- [ ] 展示类型切换