# Pipeline DSL 系统

> **版本**: v0.10.0
> **更新日期**: 2026-04-01
> **状态**: ✅ 完整实现 (90% 完整度)
> **架构**: Rust 后端 (zclaw-pipeline crate) + React 前端
> **Crate 完整度**: **90%**

---

## 一、概述

Pipeline DSL 是 ZCLAW 的自动化工作流编排系统，允许用户通过声明式 YAML 配置定义多步骤任务。

### 1.1 核心特性

- **声明式配置**: 使用 YAML 定义工作流步骤
- **状态管理**: ExecutionContext 管理步骤间数据传递
- **表达式解析**: 支持 `${inputs.topic}`、`${steps.step1.output}` 等表达式
- **并行执行**: 支持 `parallel` 动作并行处理多个项目
- **LLM 集成**: 内置 `llm_generate` 动作调用大语言模型
- **文件导出**: 支持 PPTX/HTML/PDF/Markdown 等格式导出
- **Agent 集成**: 在对话中智能推荐相关 Pipeline

### 1.2 设计原则

- **用户只看到 Pipeline**: Hands/Skills 作为内部实现被隐藏
- **行业扩展**: 支持垂直扩展（不同学科）和水平扩展（跨行业）
- **智能推荐**: Agent 主动识别用户意图，推荐合适的 Pipeline

---

## 二、架构设计

### 2.1 分层架构

```
┌─────────────────────────────────────────────────────────┐
│                    User Interface                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │ Pipeline List│  │ Pipeline Run│  │ Result Preview  │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   Pipeline Engine                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │ DSL Parser  │  │ Executor    │  │ State Manager   │  │
│  │ YAML/TOML   │  │ DAG Runner  │  │ Context Store   │  │
│  └─────────────┘  └─────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│ Skills (隐藏)    │ │ Hands (隐藏)│ │ Exporters       │
│ prompt templates│ │ executors   │ │ pptx/html/pdf   │
└─────────────────┘ └─────────────┘ └─────────────────┘
```

### 2.2 核心组件

| 组件 | 职责 | 位置 | 实现状态 |
|------|------|------|---------|
| PipelineParser | YAML 解析 | `crates/zclaw-pipeline/src/parser.rs` | ✅ 100% |
| PipelineExecutor | 执行引擎 | `crates/zclaw-pipeline/src/executor.rs` | ✅ 100% |
| ExecutionContext | 状态管理 | `crates/zclaw-pipeline/src/state.rs` | ✅ 100% |
| ActionRegistry | 动作注册 | `crates/zclaw-pipeline/src/actions/mod.rs` | ✅ 100% |
| PipelineClient | 前端客户端 | `desktop/src/lib/pipeline-client.ts` | ✅ 95% |
| PipelinesPanel | UI 组件 | `desktop/src/components/PipelinesPanel.tsx` | ✅ 90% |
| PipelineRecommender | 智能推荐 | `desktop/src/lib/pipeline-recommender.ts` | ✅ 85% |
| ClassroomPreviewer | 课堂预览 | `desktop/src/components/ClassroomPreviewer.tsx` | ✅ 90% |

### 2.3 Action 实现状态

| Action | 状态 | 说明 |
|--------|------|------|
| `llm_generate` | ✅ | LLM 生成 |
| `parallel` | ✅ | 并行执行 |
| `sequential` | ✅ | 顺序执行 |
| `condition` | ✅ | 条件判断 |
| `skill` | ✅ | 技能调用 |
| `hand` | ✅ | Hand 调用 |
| `classroom` | ✅ | 课堂生成 |
| `export` | ✅ | 文件导出 |
| `http` | ✅ | HTTP 请求 |

---

## 三、Pipeline 配置格式

### 3.1 基本结构

```yaml
apiVersion: zclaw/v1
kind: Pipeline
metadata:
  name: my-pipeline
  displayName: 我的 Pipeline
  category: productivity
  description: 这是一个示例 Pipeline
  tags:
    - 示例
    - 测试
  icon: 🚀
  author: ZCLAW
  version: 1.0.0

spec:
  inputs:
    - name: topic
      type: string
      required: true
      label: 主题
      placeholder: 请输入主题

  steps:
    - id: step1
      description: 第一步
      action:
        type: llm_generate
        template: |
          处理以下主题: {{topic}}
        json_mode: true
        temperature: 0.7
        max_tokens: 1000

  outputs:
    result: ${steps.step1.output}

  on_error: stop
  timeout_secs: 300
```

### 3.2 输入类型

| 类型 | 说明 | 默认值 |
|------|------|--------|
| `string` | 单行文本 | `""` |
| `text` | 多行文本 | `""` |
| `number` | 数字 | `0` |
| `boolean` | 布尔值 | `false` |
| `select` | 单选 | `null` |
| `multi-select` | 多选 | `[]` |
| `file` | 文件 | `null` |

### 3.3 动作类型

| 动作 | 说明 | 示例 |
|------|------|------|
| `llm_generate` | LLM 生成 | 文本生成、数据分析 |
| `parallel` | 并行执行 | 批量处理 |
| `sequential` | 顺序执行 | 条件分支 |
| `condition` | 条件判断 | 流程控制 |
| `skill` | 调用技能 | 使用预定义技能 |
| `hand` | 调用 Hand | 浏览器操作、文件处理 |
| `file_export` | 文件导出 | PPTX/HTML/PDF |
| `http_request` | HTTP 请求 | API 调用 |
| `set_var` | 设置变量 | 数据转换 |
| `delay` | 延迟 | 等待操作 |

### 3.4 表达式语法

```yaml
# 输入参数
${inputs.topic}

# 步骤输出
${steps.step1.output}
${steps.step1.output.items}

# 循环变量 (在 parallel 中)
${item}
${index}

# 变量引用
${vars.my_variable}

# 函数调用
${chrono::Utc::now().to_rfc3339()}
```

---

## 四、已实现的 Pipeline 模板

### 4.1 教育类 (education)

| Pipeline | 说明 | 文件 |
|----------|------|------|
| 互动课堂生成器 | 输入课题，自动生成完整课件 | `pipelines/education/classroom.yaml` |

### 4.2 营销类 (marketing)

| Pipeline | 说明 | 文件 |
|----------|------|------|
| 营销方案生成器 | 输入产品信息，生成完整营销策略 | `pipelines/marketing/campaign.yaml` |

### 4.3 法律类 (legal)

| Pipeline | 说明 | 文件 |
|----------|------|------|
| 合同智能审查 | 上传合同，识别风险条款并生成建议 | `pipelines/legal/contract-review.yaml` |

### 4.4 研究类 (research)

| Pipeline | 说明 | 文件 |
|----------|------|------|
| 文献综述生成器 | 输入研究主题，生成文献综述报告 | `pipelines/research/literature-review.yaml` |

### 4.5 生产力类 (productivity)

| Pipeline | 说明 | 文件 |
|----------|------|------|
| 智能会议纪要 | 输入会议内容，生成结构化纪要 | `pipelines/productivity/meeting-summary.yaml` |

---

## 五、前端组件

### 5.1 PipelinesPanel

Pipeline 列表和运行界面。

```tsx
import { PipelinesPanel } from './components/PipelinesPanel';

// 在路由中使用
<Route path="/pipelines" element={<PipelinesPanel />} />
```

**功能**:
- 分类过滤
- 关键词搜索
- Pipeline 卡片展示
- 运行对话框（输入参数配置）
- 进度显示

### 5.2 PipelineResultPreview

Pipeline 执行结果预览组件。

```tsx
import { PipelineResultPreview } from './components/PipelineResultPreview';

<PipelineResultPreview
  result={runResult}
  pipelineId="classroom-generator"
  onClose={() => setShowResult(false)}
/>
```

**预览模式**:
- JSON 数据预览
- Markdown 渲染
- 文件下载列表
- 自动模式检测

### 5.3 ClassroomPreviewer

课堂内容专用预览器。

```tsx
import { ClassroomPreviewer } from './components/ClassroomPreviewer';

<ClassroomPreviewer
  data={classroomData}
  onExport={(format) => handleExport(format)}
/>
```

**功能**:
- 幻灯片导航
- 大纲视图
- 自动播放
- 全屏模式
- 讲解文本显示
- 导出功能

---

## 六、Agent 对话集成

### 6.1 智能推荐

PipelineRecommender 分析用户消息，推荐相关 Pipeline：

```tsx
import { pipelineRecommender } from './lib/pipeline-recommender';

// 分析用户消息
const recommendations = await pipelineRecommender.recommend(userMessage);

if (recommendations.length > 0) {
  const topRec = recommendations[0];
  // 向用户展示推荐
  const message = pipelineRecommender.formatRecommendationForAgent(topRec);
}
```

### 6.2 意图识别模式

| 类别 | 关键词模式 | 推荐 Pipeline |
|------|------------|---------------|
| 教育 | 课件、教案、备课 | classroom-generator |
| 营销 | 营销、推广、宣传 | marketing-campaign |
| 法律 | 合同审查、风险条款 | contract-review |
| 研究 | 文献综述、学术研究 | literature-review |
| 生产力 | 会议纪要、待办事项 | meeting-summary |

### 6.3 推荐阈值

- **置信度 >= 0.8**: 直接推荐
- **置信度 0.6-0.8**: 询问用户
- **置信度 < 0.6**: 不推荐

---

## 七、Tauri 命令

### 7.1 命令列表

| 命令 | 说明 | 参数 |
|------|------|------|
| `pipeline_list` | 列出所有 Pipeline | `category?` |
| `pipeline_get` | 获取 Pipeline 详情 | `pipelineId` |
| `pipeline_run` | 运行 Pipeline | `request` |
| `pipeline_progress` | 获取运行进度 | `runId` |
| `pipeline_result` | 获取运行结果 | `runId` |
| `pipeline_cancel` | 取消运行 | `runId` |
| `pipeline_runs` | 列出所有运行 | - |
| `pipeline_refresh` | 刷新 Pipeline 列表 | - |

### 7.2 使用示例

```typescript
// 列出所有 Pipeline
const pipelines = await invoke('pipeline_list', { category: null });

// 运行 Pipeline
const { runId } = await invoke('pipeline_run', {
  request: {
    pipelineId: 'classroom-generator',
    inputs: { topic: '牛顿第二定律', difficulty: '中级' }
  }
});

// 获取进度
const progress = await invoke('pipeline_progress', { runId });
```

---

## 八、文件结构

```
crates/zclaw-pipeline/
├── Cargo.toml
├── src/
│   ├── lib.rs
│   ├── parser.rs        # YAML 解析
│   ├── executor.rs      # 执行引擎
│   ├── state.rs         # 状态管理
│   ├── types.rs         # 类型定义
│   └── actions/         # 内置动作
│       ├── mod.rs
│       ├── llm.rs
│       ├── parallel.rs
│       └── export.rs

pipelines/
├── education/
│   └── classroom.yaml
├── marketing/
│   └── campaign.yaml
├── legal/
│   └── contract-review.yaml
├── research/
│   └── literature-review.yaml
└── productivity/
    └── meeting-summary.yaml

desktop/src/
├── lib/
│   ├── pipeline-client.ts      # 前端客户端
│   └── pipeline-recommender.ts # 智能推荐
└── components/
    ├── PipelinesPanel.tsx      # Pipeline 列表
    ├── PipelineResultPreview.tsx # 结果预览
    └── ClassroomPreviewer.tsx  # 课堂预览器
```

---

## 九、智能展示层 (Smart Presentation Layer)

### 9.1 概述

智能展示层是 Pipeline 输出的渲染系统，能够自动分析数据结构并推荐最佳展示格式。

### 9.2 支持的展示类型

| 类型 | 说明 | 检测规则 |
|------|------|---------|
| `document` | Markdown 文档 | 包含 content 或 text 字段 |
| `chart` | 数据可视化 | 包含 datasets、series 或 chartType |
| `quiz` | 互动测验 | 包含 questions 数组 |
| `slideshow` | 幻灯片 | 包含 slides 数组 |
| `whiteboard` | 交互式白板 | 包含 elements 数组 |

### 9.3 Rust 后端组件

| 组件 | 职责 | 位置 |
|------|------|------|
| PresentationType | 类型枚举 | `crates/zclaw-pipeline/src/presentation/types.rs` |
| PresentationAnalyzer | 数据分析器 | `crates/zclaw-pipeline/src/presentation/analyzer.rs` |
| PresentationRegistry | 渲染器注册表 | `crates/zclaw-pipeline/src/presentation/registry.rs` |

### 9.4 React 前端组件

| 组件 | 职责 | 位置 |
|------|------|------|
| PresentationContainer | 主容器组件 | `desktop/src/components/presentation/PresentationContainer.tsx` |
| TypeSwitcher | 类型切换器 | `desktop/src/components/presentation/TypeSwitcher.tsx` |
| ChartRenderer | 图表渲染 | `desktop/src/components/presentation/renderers/ChartRenderer.tsx` |
| QuizRenderer | 测验渲染 | `desktop/src/components/presentation/renderers/QuizRenderer.tsx` |
| SlideshowRenderer | 幻灯片渲染 | `desktop/src/components/presentation/renderers/SlideshowRenderer.tsx` |
| DocumentRenderer | 文档渲染 | `desktop/src/components/presentation/renderers/DocumentRenderer.tsx` |

### 9.5 使用示例

```tsx
import { PresentationContainer } from '@/components/presentation';

// 在 Pipeline 结果展示中使用
<PresentationContainer
  data={pipelineOutput}
  pipelineId="classroom-generator"
  supportedTypes={['document', 'chart', 'quiz', 'slideshow']}
/>
```

### 9.6 Tauri 命令

| 命令 | 说明 | 参数 |
|------|------|------|
| `analyze_presentation` | 分析数据推荐展示类型 | `data: Value` |

### 9.7 检测算法

```rust
// 检测逻辑示例
fn detect_quiz(data: &Value) -> f64 {
    if let Some(obj) = data.as_object() {
        if obj.contains_key("questions") && obj["questions"].is_array() {
            return 0.95;
        }
    }
    0.0
}
```

---

## 十、扩展指南

### 9.1 添加新 Pipeline

1. 在 `pipelines/` 目录下创建 YAML 文件
2. 定义 `metadata`（名称、类别、描述等）
3. 定义 `inputs`（输入参数）
4. 定义 `steps`（执行步骤）
5. 定义 `outputs`（输出映射）

### 9.2 添加新 Action

1. 在 `crates/zclaw-pipeline/src/actions/` 创建新模块
2. 实现 `ActionExecutor` trait
3. 在 `ActionRegistry` 中注册
4. 更新 Parser 支持新动作类型

---

## 十一、变更历史

| 日期 | 版本 | 变更内容 |
|------|------|---------|
| 2026-03-26 | v0.5.0 | 新增智能展示层 (Smart Presentation Layer)，支持自动类型检测和多种渲染器 |
| 2026-03-25 | v0.4.0 | 代码现状验证：90% 完整度，新增 Action 实现状态表 |
| 2026-03-25 | v0.3.0 | Pipeline DSL 系统实现，包含 5 类 Pipeline 模板 |