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 新格式示例

# 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 触发器定义格式

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

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

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

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

4.2 意图路由流程

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 类型体系

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 执行上下文

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 表达式系统

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

5.4 执行流程示例

# 课程生成 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 进度回调

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 结构检测规则

// 快速路径 - 基于数据结构自动判断
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 渲染器接口

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 单元测试

# 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 集成测试

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

10.3 手动验证清单

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