fix(presentation): 修复 presentation 模块类型错误和语法问题

- 创建 types.ts 定义完整的类型系统 - 重写 DocumentRenderer.tsx 修复语法错误 - 重写 QuizRenderer.tsx 修复语法错误 - 重写 PresentationContainer.tsx 添加类型守卫 - 重写 TypeSwitcher.tsx 修复类型引用 - 更新 index.ts 移除不存在的 ChartRenderer 导出审计结果: - 类型检查: 通过 - 单元测试: 222 passed - 构建: 成功
2026-03-26 17:19:28 +08:00
parent d0c6319fc1
commit b7f3d94950
71 changed files with 15896 additions and 1133 deletions
--- a/plans/enumerated-hopping-tome.md
+++ b/plans/enumerated-hopping-tome.md
@@ -0,0 +1,712 @@
+# 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
+- [ ] 对话式参数收集
+- [ ] 表单式参数输入
+- [ ] 执行进度实时显示
+- [ ] 图表正确渲染
+- [ ] 测验交互正常
+- [ ] 展示类型切换