概述
什么是编钟YAML模板?
编钟YAML模板是一种声明式配置文件,用于定义自动化工作流。通过简洁的YAML语法, 你可以描述复杂的多工具协作流程,编钟会自动协调各个MCP Server的执行。
优势
- • 声明式语法,易于理解和维护
- • 自动处理工具依赖和执行顺序
- • 内置错误处理和重试机制
- • 支持并行执行和条件分支
注意事项
- • YAML语法对缩进敏感
- • 字符串值建议使用引号包围
- • 大型工作流建议拆分为多个模板
- • 定期测试和版本管理
基础语法
模板结构
一个完整的编钟YAML模板包含以下基本结构:
# 编钟工作流模板
name: "示例工作流"
description: "这是一个示例工作流模板"
version: "1.0.0"
author: "编钟开发者"
# 变量定义
variables:
input_url: ""
output_path: "~/Documents"
# 执行步骤
steps:
- name: "获取内容"
tool: "fetch-mcp"
params:
url: "{{variables.input_url}}"
- name: "保存文件"
tool: "file-mcp"
params:
path: "{{variables.output_path}}/content.md"
content: "{{steps.获取内容.result}}"
元数据配置
必需字段
字段 | 类型 | 描述 | 示例 |
---|---|---|---|
name | string | 工作流的名称 | "微信文章保存" |
description | string | 工作流的描述 | "将微信文章保存到本地" |
version | string | 版本号 | "1.0.0" |
可选字段
字段 | 类型 | 描述 | 示例 |
---|---|---|---|
author | string | 作者信息 | "张三" |
tags | array | 标签列表 | ["content", "automation"] |
category | string | 分类 | "content-management" |
timeout | number | 超时时间(秒) | 300 |
变量定义
变量允许你在模板中定义可重用的值,支持默认值、类型约束和验证规则。
基本变量
variables:
# 字符串变量
website_url: "https://example.com"
# 数字变量
retry_count: 3
# 布尔变量
enable_debug: false
# 数组变量
file_extensions: [".md", ".txt", ".pdf"]
# 对象变量
api_config:
endpoint: "https://api.example.com"
timeout: 30
headers:
Authorization: "Bearer {{env.API_TOKEN}}"
高级变量配置
variables:
# 带描述和类型的变量
input_file:
type: "string"
description: "输入文件路径"
default: ""
required: true
# 带验证规则的变量
email_address:
type: "string"
description: "邮箱地址"
pattern: "^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$"
required: true
# 环境变量引用
database_url:
type: "string"
description: "数据库连接地址"
default: "{{env.DATABASE_URL}}"
# 计算变量
output_filename:
type: "string"
description: "输出文件名"
default: "{{variables.input_file | basename}}.processed"
工作流配置
工作流配置是编钟模板的核心部分,定义了具体的执行逻辑和步骤编排。
执行步骤
基本步骤结构
steps:
- name: "下载网页内容"
tool: "fetch-mcp"
params:
url: "{{variables.target_url}}"
timeout: 30
output_var: "webpage_content"
- name: "解析文章内容"
tool: "html-parser-mcp"
params:
html: "{{steps.下载网页内容.result}}"
selector: "article"
output_var: "article_content"
- name: "保存到文件"
tool: "file-mcp"
params:
path: "{{variables.output_path}}/{{variables.filename}}"
content: "{{steps.解析文章内容.result}}"
output_var: "save_result"
步骤字段说明
字段 | 必需 | 描述 | 示例 |
---|---|---|---|
name | ✓ | 步骤的唯一名称 | "下载网页内容" |
tool | ✓ | 要使用的MCP Server名称 | "fetch-mcp" |
params | - | 传递给工具的参数 | url: "https://..." |
output_var | - | 存储结果的变量名 | "webpage_content" |
timeout | - | 步骤超时时间(秒) | 30 |
条件判断
使用条件判断可以根据执行结果或变量值来控制工作流的执行分支。
steps:
- name: "检查文件类型"
tool: "file-inspector-mcp"
params:
path: "{{variables.input_file}}"
output_var: "file_info"
- name: "处理图片文件"
tool: "image-processor-mcp"
params:
input: "{{variables.input_file}}"
output: "{{variables.output_path}}/processed.jpg"
condition:
if: "{{steps.检查文件类型.result.type}} == 'image'"
- name: "处理文档文件"
tool: "document-processor-mcp"
params:
input: "{{variables.input_file}}"
output: "{{variables.output_path}}/processed.pdf"
condition:
if: "{{steps.检查文件类型.result.type}} == 'document'"
- name: "处理失败通知"
tool: "notification-mcp"
params:
message: "不支持的文件类型: {{steps.检查文件类型.result.type}}"
condition:
if: "{{steps.检查文件类型.result.type}} not in ['image', 'document']"
支持的条件运算符
- •
==
等于 - •
!=
不等于 - •
>
,<
大于、小于 - •
in
,not in
包含、不包含 - •
and
,or
逻辑与、或
错误处理
编钟提供了多种错误处理机制,确保工作流的稳定性和可恢复性。
steps:
- name: "下载文件"
tool: "fetch-mcp"
params:
url: "{{variables.download_url}}"
retry:
max_attempts: 3
delay: 5
backoff_factor: 2
on_error:
action: "continue" # 或 "stop", "retry"
fallback_step: "使用本地缓存"
- name: "使用本地缓存"
tool: "file-mcp"
params:
path: "{{variables.cache_path}}"
condition:
if: "{{steps.下载文件.status}} == 'failed'"
- name: "处理数据"
tool: "data-processor-mcp"
params:
input: "{{steps.下载文件.result or steps.使用本地缓存.result}}"
validation:
required_fields: ["title", "content"]
max_size_mb: 10
- name: "清理临时文件"
tool: "file-mcp"
params:
action: "delete"
path: "{{variables.temp_dir}}"
run_on: "always" # 总是执行,即使前面步骤失败
高级特性
编钟提供了多种高级特性,帮助你构建更加复杂和高效的自动化工作流。
并行执行
使用并行执行可以同时运行多个独立的任务,大大提升工作流的执行效率。
steps:
# 串行步骤
- name: "初始化环境"
tool: "setup-mcp"
params:
workspace: "{{variables.workspace_path}}"
# 并行执行多个任务
- name: "并行处理组"
type: "parallel"
max_concurrency: 3 # 最大并发数
steps:
- name: "下载图片1"
tool: "fetch-mcp"
params:
url: "{{variables.image_urls[0]}}"
output: "{{variables.output_path}}/image1.jpg"
- name: "下载图片2"
tool: "fetch-mcp"
params:
url: "{{variables.image_urls[1]}}"
output: "{{variables.output_path}}/image2.jpg"
- name: "生成缩略图"
tool: "image-processor-mcp"
params:
input: "{{variables.template_image}}"
output: "{{variables.output_path}}/thumbnail.jpg"
# 等待所有并行任务完成后继续
- name: "合并结果"
tool: "image-combiner-mcp"
params:
inputs:
- "{{steps.并行处理组.下载图片1.result}}"
- "{{steps.并行处理组.下载图片2.result}}"
- "{{steps.并行处理组.生成缩略图.result}}"
output: "{{variables.output_path}}/combined.jpg"
并行执行注意事项
- • 并行任务之间不能有依赖关系
- • 合理设置max_concurrency避免资源耗尽
- • 错误处理策略会影响整个并行组
- • 使用steps.组名.步骤名来引用并行步骤的结果
动态配置
动态配置允许在运行时根据条件或数据动态生成步骤和参数。
variables:
file_list: [] # 运行时动态填充
steps:
- name: "扫描文件夹"
tool: "file-scanner-mcp"
params:
path: "{{variables.input_folder}}"
pattern: "*.txt"
output_var: "scanned_files"
# 动态生成处理步骤
- name: "批量处理文件"
type: "dynamic"
template:
name: "处理文件 {{item.name}}"
tool: "text-processor-mcp"
params:
input: "{{item.path}}"
output: "{{variables.output_folder}}/processed_{{item.name}}"
config:
encoding: "utf-8"
remove_duplicates: true
iterate_over: "{{steps.扫描文件夹.result.files}}"
# 条件性动态配置
- name: "发送通知"
tool: "notification-mcp"
params:
message: "{{#if steps.批量处理文件.success_count > 0}}成功处理了 {{steps.批量处理文件.success_count}} 个文件{{else}}没有文件被处理{{/if}}"
channels:
- type: "email"
enabled: "{{variables.enable_email_notification}}"
recipients: "{{variables.notification_emails}}"
- type: "slack"
enabled: "{{variables.enable_slack_notification}}"
webhook: "{{env.SLACK_WEBHOOK_URL}}"
模板继承
通过模板继承可以重用公共配置,减少重复代码,提高维护性。
基础模板 (base-content-processor.yml)
# 基础内容处理模板
name: "基础内容处理器"
description: "提供通用的内容处理功能"
version: "1.0.0"
variables:
input_url: ""
output_path: "~/Downloads"
enable_validation: true
# 公共步骤定义
common_steps:
download_content: &download_step
name: "下载内容"
tool: "fetch-mcp"
params:
url: "{{variables.input_url}}"
timeout: 30
retry:
max_attempts: 3
delay: 5
validate_content: &validate_step
name: "验证内容"
tool: "validator-mcp"
params:
input: "{{steps.下载内容.result}}"
rules:
- "required_length > 100"
- "no_malicious_content"
condition:
if: "{{variables.enable_validation}}"
steps:
- <<: *download_step
- <<: *validate_step
继承模板 (wechat-article-processor.yml)
# 继承基础模板
extends: "base-content-processor.yml"
name: "微信文章处理器"
description: "专门处理微信公众号文章的工作流"
version: "1.1.0"
# 扩展变量
variables:
output_format: "markdown"
extract_images: true
obsidian_vault: "~/Documents/Obsidian/Articles"
# 添加特定步骤
steps:
# 继承的基础步骤会自动包含
# 添加微信文章特定处理
- name: "解析微信文章"
tool: "wechat-parser-mcp"
params:
content: "{{steps.下载内容.result}}"
extract_images: "{{variables.extract_images}}"
format: "{{variables.output_format}}"
- name: "保存到Obsidian"
tool: "obsidian-mcp"
params:
vault: "{{variables.obsidian_vault}}"
content: "{{steps.解析微信文章.result.content}}"
filename: "{{steps.解析微信文章.result.title}}.md"
tags: ["微信文章", "{{steps.解析微信文章.result.author}}"]
# 覆盖基础模板的步骤
- name: "验证内容"
tool: "validator-mcp"
params:
input: "{{steps.解析微信文章.result}}"
rules:
- "has_title"
- "has_content"
- "valid_markdown_format"
模板继承优势
- • 减少重复配置,提高开发效率
- • 统一管理公共逻辑,便于维护
- • 支持多层继承和选择性覆盖
- • 促进模板生态的标准化发展
完整示例
以下是几个实际应用场景的完整YAML模板示例,展示编钟的强大功能。
微信文章保存到Obsidian工作流
自动抓取微信公众号文章,解析内容和图片,保存到Obsidian笔记系统。
name: "微信文章保存到Obsidian"
description: "自动抓取微信文章并保存到Obsidian笔记系统"
version: "1.2.0"
author: "编钟社区"
category: "content-management"
tags: ["微信", "obsidian", "内容管理"]
variables:
# 输入参数
article_url: ""
obsidian_vault: "~/Documents/Obsidian"
folder_name: "Articles/微信文章"
# 处理选项
download_images: true
extract_audio: false
add_metadata: true
# 输出格式
filename_template: "{{date}}-{{title}}"
content_format: "markdown"
steps:
# 第一步:抓取文章内容
- name: "抓取微信文章"
tool: "crawl-mcp"
params:
url: "{{variables.article_url}}"
strategy: "conservative"
timeout: 30000
save_images: "{{variables.download_images}}"
output_var: "article_data"
retry:
max_attempts: 3
delay: 5
backoff_factor: 2
# 第二步:验证内容质量
- name: "验证文章内容"
tool: "content-validator-mcp"
params:
content: "{{steps.抓取微信文章.result.content}}"
min_length: 500
required_elements: ["title", "content"]
condition:
if: "{{variables.add_metadata}}"
# 第三步:处理图片资源
- name: "下载图片资源"
type: "parallel"
max_concurrency: 5
condition:
if: "{{variables.download_images}} and {{steps.抓取微信文章.result.images | length}} > 0"
steps:
# 动态生成图片下载任务
- name: "下载图片{{item.index}}"
tool: "image-downloader-mcp"
params:
url: "{{item.url}}"
output_path: "{{variables.obsidian_vault}}/attachments/{{item.filename}}"
max_size_mb: 10
iterate_over: "{{steps.抓取微信文章.result.images}}"
# 第四步:生成Markdown内容
- name: "生成Markdown文档"
tool: "markdown-generator-mcp"
params:
title: "{{steps.抓取微信文章.result.title}}"
content: "{{steps.抓取微信文章.result.content}}"
author: "{{steps.抓取微信文章.result.author}}"
publish_date: "{{steps.抓取微信文章.result.publish_date}}"
source_url: "{{variables.article_url}}"
images: "{{steps.下载图片资源.results}}"
template: |
---
title: "{{title}}"
author: "{{author}}"
source: "{{source_url}}"
created: "{{now}}"
tags: ["微信文章", "{{author}}"]
---
# {{title}}
> 作者:{{author}}
> 来源:[微信公众号]({{source_url}})
> 保存时间:{{now}}
{{content}}
---
*本文通过编钟自动保存*
output_var: "markdown_content"
# 第五步:保存到Obsidian
- name: "保存到Obsidian"
tool: "obsidian-mcp"
params:
vault_path: "{{variables.obsidian_vault}}"
folder: "{{variables.folder_name}}"
filename: "{{variables.filename_template | replace('{date}', steps.抓取微信文章.result.publish_date | date('YYYY-MM-DD')) | replace('{title}', steps.抓取微信文章.result.title | slugify)}}.md"
content: "{{steps.生成Markdown文档.result}}"
overwrite: false
output_var: "save_result"
# 第六步:发送完成通知
- name: "发送完成通知"
tool: "notification-mcp"
params:
message: |
✅ 微信文章保存成功!
📄 文章:{{steps.抓取微信文章.result.title}}
👤 作者:{{steps.抓取微信文章.result.author}}
📁 位置:{{steps.保存到Obsidian.result.file_path}}
🖼️ 图片:{{steps.下载图片资源.success_count || 0}} 张
🔗 原文链接:{{variables.article_url}}
channels:
- type: "system"
level: "info"
run_on: "success"
# 错误处理:清理临时文件
- name: "清理临时文件"
tool: "file-cleaner-mcp"
params:
paths:
- "{{temp_dir}}"
- "{{cache_dir}}"
run_on: "always"
# 错误处理配置
on_error:
strategy: "rollback"
notification:
message: "❌ 微信文章保存失败:{{error.message}}"
channels: ["system"]
批量文件处理工作流
扫描指定目录,批量处理文件,支持格式转换、压缩和分类整理。
name: "批量文件处理器"
description: "扫描、处理和整理文件的自动化工作流"
version: "2.1.0"
category: "file-management"
variables:
input_directory: ""
output_directory: ""
file_patterns: ["*.jpg", "*.png", "*.pdf", "*.docx"]
max_file_size_mb: 50
enable_compression: true
organize_by_type: true
steps:
- name: "扫描输入目录"
tool: "file-scanner-mcp"
params:
directory: "{{variables.input_directory}}"
patterns: "{{variables.file_patterns}}"
recursive: true
max_size: "{{variables.max_file_size_mb}}MB"
output_var: "file_list"
- name: "文件分类处理"
type: "dynamic"
template:
name: "处理{{item.type}}文件:{{item.name}}"
tool: "{{#switch item.type}}{{#case 'image'}}image-processor-mcp{{/case}}{{#case 'document'}}document-processor-mcp{{/case}}{{#default}}file-mcp{{/default}}{{/switch}}"
params:
input: "{{item.path}}"
output: "{{variables.output_directory}}/{{#if variables.organize_by_type}}{{item.type}}/{{/if}}{{item.name}}"
compression: "{{variables.enable_compression}}"
quality: 85
iterate_over: "{{steps.扫描输入目录.result.files}}"
max_concurrency: 4
- name: "生成处理报告"
tool: "report-generator-mcp"
params:
title: "文件处理报告"
data: "{{steps.文件分类处理.results}}"
output: "{{variables.output_directory}}/processing_report.html"
template: "batch_processing"
编写优质模板的最佳实践
结构设计
- • 使用清晰的命名约定
- • 合理分解复杂任务
- • 设置适当的超时时间
- • 添加详细的注释说明
错误处理
- • 为关键步骤设置重试机制
- • 提供有意义的错误消息
- • 实现优雅的失败回滚
- • 记录详细的执行日志
性能优化
- • 使用并行执行独立任务
- • 避免不必要的数据传输
- • 合理设置并发数量
- • 缓存重复计算结果
维护性
- • 使用版本控制管理模板
- • 编写详细的使用文档
- • 定期测试和更新
- • 收集用户反馈改进