bf6d81f9c6
Some checks failed
CI / Rust Check (push) Has been cancelled
CI / Lint & TypeCheck (push) Has been cancelled
CI / Unit Tests (push) Has been cancelled
CI / Build Frontend (push) Has been cancelled
CI / Security Scan (push) Has been cancelled
CI / E2E Tests (push) Has been cancelled
style: 统一代码格式和注释风格 docs: 更新多个功能文档的完整度和状态 feat(runtime): 添加路径验证工具支持 fix(pipeline): 改进条件判断和变量解析逻辑 test(types): 为ID类型添加全面测试用例 chore: 更新依赖项和Cargo.lock文件 perf(mcp): 优化MCP协议传输和错误处理
421 lines
12 KiB
Markdown
421 lines
12 KiB
Markdown
# Pipeline DSL 系统
|
||
|
||
> **版本**: v0.4.0
|
||
> **更新日期**: 2026-03-25
|
||
> **状态**: ✅ 完整实现 (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 # 课堂预览器
|
||
```
|
||
|
||
---
|
||
|
||
## 九、扩展指南
|
||
|
||
### 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.4.0 | 代码现状验证：90% 完整度，新增 Action 实现状态表 |
|
||
| 2026-03-25 | v0.3.0 | Pipeline DSL 系统实现，包含 5 类 Pipeline 模板 |
|