feat(pipeline): implement Pipeline DSL system for automated workflows

Add complete Pipeline DSL system including: - Rust backend (zclaw-pipeline crate) with parser, executor, and state management - Frontend components: PipelinesPanel, PipelineResultPreview, ClassroomPreviewer - Pipeline recommender for Agent conversation integration - 5 pipeline templates: education, marketing, legal, research, productivity - Documentation for Pipeline DSL architecture Pipeline DSL enables declarative workflow definitions with: - YAML-based configuration - Expression resolution (${inputs.topic}, ${steps.step1.output}) - LLM integration, parallel execution, file export - Agent smart recommendations in conversations Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-25 00:52:12 +08:00
parent 0179f947aa
commit 9c781f5f2a
30 changed files with 6944 additions and 24 deletions
--- a/docs/features/07-pipeline-dsl/00-pipeline-overview.md
+++ b/docs/features/07-pipeline-dsl/00-pipeline-overview.md
@@ -0,0 +1,403 @@
+# Pipeline DSL 系统
+
+> **版本**: v0.3.0
+> **更新日期**: 2026-03-25
+> **状态**: ✅ 已实现
+> **架构**: Rust 后端 (zclaw-pipeline crate) + React 前端
+
+---
+
+## 一、概述
+
+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` |
+| PipelineExecutor | 执行引擎 | `crates/zclaw-pipeline/src/executor.rs` |
+| ExecutionContext | 状态管理 | `crates/zclaw-pipeline/src/state.rs` |
+| ActionRegistry | 动作注册 | `crates/zclaw-pipeline/src/actions/mod.rs` |
+| PipelineClient | 前端客户端 | `desktop/src/lib/pipeline-client.ts` |
+| PipelinesPanel | UI 组件 | `desktop/src/components/PipelinesPanel.tsx` |
+| PipelineRecommender | 智能推荐 | `desktop/src/lib/pipeline-recommender.ts` |
+
+---
+
+## 三、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  # 课堂预览器
+```
+
+---
+
+## 九、扩展指南
+
+### 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-25 | v0.3.0 | Pipeline DSL 系统实现，包含 5 类 Pipeline 模板 |