YAML模板语法参考 📝

掌握编钟的声明式配置语法,创建强大的自动化工作流

概述

什么是编钟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}}"

元数据配置

必需字段

字段类型描述示例
namestring工作流的名称"微信文章保存"
descriptionstring工作流的描述"将微信文章保存到本地"
versionstring版本号"1.0.0"

可选字段

字段类型描述示例
authorstring作者信息"张三"
tagsarray标签列表["content", "automation"]
categorystring分类"content-management"
timeoutnumber超时时间(秒)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"

编写优质模板的最佳实践

结构设计

  • • 使用清晰的命名约定
  • • 合理分解复杂任务
  • • 设置适当的超时时间
  • • 添加详细的注释说明

错误处理

  • • 为关键步骤设置重试机制
  • • 提供有意义的错误消息
  • • 实现优雅的失败回滚
  • • 记录详细的执行日志

性能优化

  • • 使用并行执行独立任务
  • • 避免不必要的数据传输
  • • 合理设置并发数量
  • • 缓存重复计算结果

维护性

  • • 使用版本控制管理模板
  • • 编写详细的使用文档
  • • 定期测试和更新
  • • 收集用户反馈改进