zclaw_openfang/docs/features/07-pipeline-dsl/00-pipeline-overview.md

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 基本结构

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 表达式语法

# 输入参数
${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 列表和运行界面。

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

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

功能:

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

5.2 PipelineResultPreview

Pipeline 执行结果预览组件。

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

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

预览模式:

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

5.3 ClassroomPreviewer

课堂内容专用预览器。

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

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

功能:

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

---

六、Agent 对话集成

6.1 智能推荐

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

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 使用示例

// 列出所有 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 使用示例

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 检测算法

// 检测逻辑示例
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 模板