基于YAML的Gemini CLI工作流编排：从单次问答到自动化流程

1. 项目概述：一个命令行里的“缝合怪”

如果你经常在终端里和 Gemini API 打交道，大概率会遇到一个痛点：每次想调用不同的功能，比如分析图片、总结PDF、或者处理一段长文本，都得写一堆重复的脚本，或者在不同的工具之间来回切换。stitch这个项目，就是来解决这个问题的。它不是一个独立的 CLI 工具，而是gemini-cli-extensions这个大家族里的一个“缝合”模块。顾名思义，它的核心能力就是把多个独立的、简单的操作，像缝衣服一样“缝合”成一个连贯、复杂的自动化流程。

想象一下，你手头有一堆零散的布料（各种小脚本或命令），stitch就是那根针和线，让你能按照自己的设计，把它们组合成一件完整的衣服（一个功能强大的自动化任务）。它本质上是一个流程编排器，让你能在命令行里，用类似写剧本的方式，定义一系列对 Gemini 模型的调用，并让数据在这些调用之间自动流转。这不仅仅是省去了手动复制粘贴的麻烦，更重要的是，它把一次性的、临时的“玩一玩” API，变成了可重复、可分享、甚至可产品化的稳定工作流。

这个工具非常适合那些需要将 AI 能力深度集成到日常开发、运维、内容处理或数据分析流程中的朋友。无论是想批量处理文档、构建一个智能化的代码审查助手，还是创建一个多步骤的创意生成管道，stitch都能提供一个轻量级但极其灵活的解决方案。它降低了构建复杂 AI 工作流的门槛，让你无需搭建一个完整的 Web 服务，就能在终端里享受到自动化带来的效率提升。

2. 核心设计思路：从“单次问答”到“流程编排”

传统的 CLI 工具，比如curl调用 API，或者基础的gemini-cli，其模式是“一问一答”。你发出一个请求，获得一个响应，流程就结束了。stitch的设计哲学是颠覆这种线性思维，转向“有状态的、多步骤的对话流”。

2.1 流程即代码：YAML 作为编排语言

stitch选择使用 YAML 文件来定义工作流，这是一个非常明智的设计。相比于用 Python 或 Bash 脚本硬编码，YAML 提供了更清晰、更声明式的结构，专注于描述“做什么”，而不是“怎么做”。这使得工作流定义文件本身就像一份可读的文档，易于理解、修改和分享。

一个典型的stitch工作流文件（比如my_workflow.yaml）会包含以下几个核心部分：

1. 全局配置：定义整个工作流使用的模型版本（如gemini-1.5-pro）、API 密钥的引用方式、默认参数（温度、top_p 等）。
2. 输入定义：声明工作流需要哪些外部输入。这可以是命令行参数、环境变量，甚至是上一个工作流的输出。这明确了工作流的“接口”。
3. 步骤序列：这是核心。每个步骤都是一个独立的“任务单元”，可以是：
   • 调用 Gemini 模型：进行文本生成、分析、总结等。
   • 执行 Shell 命令：调用外部工具处理文件、下载数据等。
   • 条件判断：根据上一步的结果决定下一步的走向。
   • 循环迭代：对列表中的每一项重复执行某些步骤。
4. 输出定义：指定工作流的最终产出是什么，可能是某个步骤的输出，也可能是经过组合或格式化的数据。

通过这种结构，一个复杂任务被分解为一系列可管理、可测试的小步骤，逻辑一目了然。

2.2 上下文传递与变量系统

多步骤工作流的关键在于数据如何在步骤间流动。stitch设计了一套简洁而强大的变量系统。每个步骤的执行结果（通常是文本，也可能是结构化数据）都会被赋予一个名字，存储在“上下文”中。后续的步骤可以像模板一样引用这些变量。

例如，第一步analyze的输出被存入变量{{ analysis_result }}。在第二步summarize的提示词（prompt）中，你就可以直接写：“基于以下分析：{{ analysis_result }}，请生成一份摘要...”。stitch会在执行第二步前，自动将{{ analysis_result }}替换为第一步的实际输出内容。

这种设计极大地增强了灵活性。你可以轻松地：

• 将前序模型的输出作为后续模型的输入，实现链式思考。
• 将外部命令的结果（如ls,cat,curl）注入到提示词中，让 AI 处理真实世界的数据。
• 根据中间结果动态调整后续流程，实现简单的决策逻辑。

2.3 与gemini-cli生态的集成

stitch并非重新造轮子，它紧密构建在gemini-cli的基础之上。这意味着它天然继承了gemini-cli的所有特性：统一的认证管理（通过gcloud auth或 API 密钥文件）、丰富的模型支持、流式响应、以及稳定的 API 客户端。stitch在其上添加了“编排”这一层抽象，使得用户无需关心底层的 API 调用细节，只需关注业务逻辑的串联。

这种设计也带来了良好的可扩展性。未来，stitch可以很容易地集成gemini-cli-extensions中的其他模块，比如专门处理图像的vision模块或处理音频的模块，将它们也作为可编排的“步骤”纳入工作流中。

3. 实战演练：构建一个多步骤内容处理流水线

理论说得再多，不如亲手实践。让我们来设计并实现一个真实场景下的工作流：“智能博客创意生成器”。这个工作流的目标是：给定一个核心关键词（如“微服务”），自动完成从头脑风暴到大纲拟定的全过程。

3.1 工作流设计拆解

我们的流水线将包含四个核心步骤：

1. 创意发散：让 Gemini 基于关键词，生成 5 个不同角度的博客文章创意。
2. 创意评选：让 Gemini 从 5 个创意中，选出最具潜力的 1 个，并简述理由。
3. 受众分析：针对选定的创意，分析其目标读者群体及他们的核心痛点。
4. 大纲生成：结合创意和受众分析，生成一篇详细的博客文章大纲。

此外，我们还需要处理输入（关键词）和输出（最终的大纲）。

3.2 编写blog_pipeline.yaml工作流定义文件

下面是一个完整的工作流定义示例。请将其保存为blog_pipeline.yaml。

# blog_pipeline.yaml name: blog_idea_to_outline description: 从关键词生成博客创意并输出完整大纲。 version: '1.0' # 1. 全局配置 config: model: gemini-1.5-pro-latest # 指定使用的模型 # API密钥通常通过环境变量 GOOGLE_API_KEY 或 gcloud 自动管理，此处无需硬编码。 # 2. 输入定义：声明工作流需要一个名为 `topic` 的输入 inputs: topic: description: "博客的核心主题关键词" required: true # 运行时将通过命令行参数 `--topic` 提供，例如：stitch run blog_pipeline.yaml --topic "容器化" # 3. 步骤序列 steps: # 步骤 1: 创意发散 - name: brainstorm_ideas type: llm # 类型为调用大语言模型 config: prompt: | 你是一位资深技术博客作者。请针对主题“{{ inputs.topic }}”，构思 5 个与众不同的博客文章创意。 每个创意需要包含： 1. 一个吸引人的标题。 2. 一句话的核心观点。 3. 预期的读者群体（如：初学者、架构师、运维工程师）。 请以清晰的编号列表形式输出。 output: brainstorm_result # 此步骤的结果将存入变量 `brainstorm_result` # 步骤 2: 创意评选 - name: select_best_idea type: llm config: prompt: | 以下是关于“{{ inputs.topic }}”的 5 个博客创意： {{ steps.brainstorm_ideas.output }} 请你扮演主编，从中评选出最具传播潜力和实践价值的一个创意。 请输出以下内容： - **最佳创意**：[复制选中的完整创意标题和核心观点] - **选择理由**：从新颖性、受众需求、内容深度三个方面，简要说明选择它的原因（不超过150字）。 output: selection_result # 步骤 3: 受众分析 - name: analyze_audience type: llm config: prompt: | 针对以下选定的博客创意： {{ steps.select_best_idea.output }} 请深入分析这篇博客的目标读者。 请输出： 1. **读者画像**：描述典型读者的角色、技术背景、工作职责。 2. **核心痛点**：他们在“{{ inputs.topic }}”领域可能遇到的具体挑战或困惑是什么？ 3. **阅读目标**：他们希望从这篇文章中获得什么？（如：解决方案、最佳实践、趋势解读） output: audience_analysis # 步骤 4: 大纲生成 - name: generate_outline type: llm config: prompt: | 综合以下信息，生成一篇结构完整、层次清晰的博客文章大纲。 - **核心创意**：{{ steps.select_best_idea.output }} - **受众分析**：{{ steps.analyze_audience.output }} 大纲要求： - 包含引言、正文（至少3个主要章节，每章下含2-3个小节）、结论。 - 在每个章节和小节标题后，用括号简要说明该部分要解决的核心问题或阐述的核心观点。 - 风格偏向实用主义，避免纯理论堆砌。 output: final_outline # 4. 输出定义：指定工作流的最终输出是什么 outputs: final_outline: description: "生成的博客文章详细大纲" value: "{{ steps.generate_outline.output }}" # 引用最后一步的输出 selected_idea: description: "被选中的最佳创意" value: "{{ steps.select_best_idea.output }}"

3.3 运行工作流与解析结果

首先，确保你已安装gemini-cli及其扩展。通常可以通过 pip 安装：

pip install google-gemini-cli # 假设 stitch 作为扩展包含在内，或单独安装扩展包

运行工作流非常简单，使用stitch run命令：

stitch run blog_pipeline.yaml --topic "微服务架构"

执行这个命令后，stitch会：

1. 解析 YAML 文件，加载工作流定义。
2. 将--topic参数值“微服务架构”绑定到inputs.topic。
3. 按顺序执行四个步骤。每一步都会：
   • 渲染提示词模板（将{{ ... }}替换为实际变量值）。
   • 调用配置的 Gemini 模型。
   • 将模型响应存储到指定的输出变量中。
4. 所有步骤执行完毕后，将outputs部分定义的内容打印到终端。

你会在终端看到类似这样的输出：

Run completed successfully for workflow 'blog_idea_to_outline'. Outputs: - final_outline: # 从零到一：构建可观测的微服务架构 ## 引言 （为什么微服务监控比单体应用复杂数倍？） - 现状与挑战：从“黑盒”到“灰盒”的困境。 - 本文目标：提供一套立即可实施的观测性建设路径。 ## 正文 ### 第一章：度量（Metrics）——定义系统的脉搏 - 黄金信号：延迟、流量、错误、饱和度在微服务下的具体含义。 - 业务指标：如何将用户行为转化为可衡量的数据点？ ... ## 结论 （观测性建设是一个持续迭代的过程） - selected_idea: **最佳创意**：2. 《从零到一：构建可观测的微服务架构》 核心观点：抛开复杂理论，一步步讲解如何为初创微服务项目搭建切实可用的监控、日志、追踪体系。 预期读者：正在实践微服务的中小型团队开发者和架构师。 **选择理由**：该创意直击“微服务架构运维复杂度高”的核心痛点，内容定位极其务实。“从零到一”的视角对目标读者（中小团队）有强烈吸引力，避免了与大型互联网公司现有方案的直接比较，更具普适性和指导价值。

实操心得：在编写提示词（prompt）时，务必明确输出格式。例如，要求“以编号列表形式输出”或“包含加粗关键词”，能显著提升模型输出结果的规整度和可复用性，方便后续步骤或人工阅读。模糊的指令会导致输出格式不一，增加解析难度。

4. 高级技巧与模式探索

掌握了基础流程后，我们可以探索stitch更强大的能力，以实现更复杂的自动化逻辑。

4.1 条件执行与动态流程

并非所有工作流都是线性的。stitch支持基于步骤结果的条件判断，实现分支逻辑。例如，在代码审查工作流中，如果 AI 发现严重安全漏洞，则立即通知负责人；如果是风格问题，则仅生成修改建议。

这通常在步骤定义中使用when条件来实现（具体语法需参考stitch最新文档）。其核心思想是，通过一个步骤（通常是llm类型）输出一个结构化判断（如{“has_critical_issue”: true}），后续步骤根据这个判断决定是否执行。

# 概念性示例，非精确语法 - name: check_code_security type: llm config: prompt: “检查这段代码的安全漏洞...” output: security_report - name: alert_team_lead type: command # 假设可以执行发送消息的命令 config: command: “send-slack-message --channel alerts ‘发现关键漏洞！’” when: “{{ steps.check_code_security.output.has_critical_issue }}” # 条件执行

4.2 循环迭代：批量处理任务

当需要对一个列表中的每一项执行相同操作时，循环就派上用场了。比如，你有一个包含多个文件路径的列表，需要对每个文件进行内容总结。

# 概念性示例：批量总结多个文件 inputs: file_list: type: array default: [“./doc1.txt“, “./doc2.md“] steps: - name: process_each_file type: llm for_each: “{{ inputs.file_list }}“ # 对列表进行迭代 config: prompt: | 请总结文件 `{{ item }}` 的核心内容。 （这里 `{{ item }}` 在每次循环中代表列表中的一个文件路径） output: “{{ ‘summary_’ + loop.index }}“ # 动态生成输出变量名，如 summary_1, summary_2

4.3 集成外部工具与命令

stitch的command步骤类型是其强大扩展性的体现。你可以执行任何 Shell 命令，并将其输出作为变量供后续步骤使用。这使得工作流可以轻松融入现有的工具链。

场景：自动抓取最新 Hacker News 头条并让 AI 点评。

steps: - name: fetch_hn_top type: command config: command: “curl -s ‘https://hn.algolia.com/api/v1/search?tags=front_page&hitsPerPage=5‘ | jq -r ‘.hits[].title’“ # 使用 curl 获取，jq 解析 JSON output: hn_titles - name: comment_on_news type: llm config: prompt: | 以下是当前 Hacker News 的几条热门标题： {{ steps.fetch_hn_top.output }} 请以技术投资人的视角，简要评论这些趋势背后的技术动因或市场信号。

注意事项：使用command步骤时，务必注意命令执行的环境和安全性。避免执行不可信来源的命令。对于复杂的命令，建议先在单独终端中测试通过。此外，命令输出的清理和格式化很重要，杂乱的输出可能会干扰后续 LLM 步骤的解析。

4.4 错误处理与重试机制

在生产环境中，网络波动或 API 限流可能导致步骤失败。一个健壮的工作流应该具备一定的容错能力。stitch可能支持（或未来会支持）在步骤级别配置重试策略。

# 概念性示例：配置重试 - name: call_llm_api type: llm config: prompt: “...“ retry: max_attempts: 3 delay: 2s # 每次重试前等待2秒 output: api_response

即使没有内置重试，你也可以通过设计工作流逻辑来实现简单的容错，例如，将一个可能失败的操作放在独立的子流程中，主流程根据其成功与否状态决定下一步。

5. 常见问题与调试指南

在实际使用stitch构建工作流时，你可能会遇到一些典型问题。以下是一些排查思路和解决方案。

5.1 变量引用错误

这是最常见的问题之一。错误提示可能类似于“Template variable ‘steps.analyze.output’ not found”。

排查步骤：

1. 检查步骤名称：确保在{{ steps.[step_name].output }}中，[step_name]与前面步骤定义的name字段完全一致，包括大小写。
2. 检查执行顺序：确保你引用的步骤确实在当前步骤之前已经执行。YAML 文件中的步骤顺序就是执行顺序。
3. 检查输出变量名：如果步骤指定了output字段（如output: my_result），则引用方式为{{ steps.[step_name].output }}。如果步骤有多个输出或使用默认输出，引用方式可能不同，需查阅具体文档。

5.2 提示词（Prompt）渲染不符合预期

有时感觉 AI 的回答没有基于你提供的变量内容。

排查步骤：

1. 使用stitch dry-run或stitch render命令：很多 CLI 工作流工具提供“预演”功能。这个命令会解析工作流，渲染所有模板变量，但不会真正执行 API 调用。你可以检查渲染后的提示词是否正确插入了变量值。

   stitch dry-run blog_pipeline.yaml --topic “测试”

2. 检查变量内容格式：如果上一步输出的内容包含 YAML 或 Markdown 的特殊字符（如:，-，**），在嵌入到新提示词时可能会引起歧义。考虑让上一步的输出格式更纯净，或在提示词中使用分隔符明确指示变量内容的范围。

   错误示例（可能混淆）： 请分析：{{ steps.raw_output.output }} 更好示例： 请分析以下文本：

   {{ steps.raw_output.output }}

5.3 API 调用失败或超时

排查步骤：

1. 验证认证：确保gemini-cli的基础认证已正确设置。可以运行一个简单的gemini-cli命令测试，如gemini-cli generate “Hello”。
2. 检查模型可用性：确认config.model中指定的模型名称是正确的，且在你的区域/项目中可用。
3. 调整超时设置：如果处理长文本或复杂请求，默认超时可能不够。查看stitch文档，看是否支持在全局配置或步骤配置中设置timeout参数。
4. 查看详细日志：运行命令时添加--verbose或--debug标志，获取每一步的详细请求和响应信息，有助于定位问题。

5.4 工作流执行性能优化

当工作流步骤很多或每个步骤处理内容很长时，执行时间可能会变长。

优化建议：

1. 并行化可能：检查工作流中是否有步骤是彼此独立、不依赖对方输出的？如果stitch支持并行步骤（例如parallel或run类型），可以将它们并行执行以缩短总耗时。
2. 精简提示词与输出：在保证效果的前提下，让每个步骤的提示词更精准，并明确要求输出“简洁”或“只包含关键信息”，减少不必要的令牌消耗和传输时间。
3. 缓存中间结果：对于耗时长、输入不变且结果可复用的步骤（如从固定URL抓取并分析内容），可以考虑将其结果手动保存到文件，并修改工作流第一步为“从文件读取缓存”，跳过实际调用。

5.5 版本控制与团队协作

工作流 YAML 文件是纯文本，非常适合用 Git 等工具进行版本控制。

最佳实践：

1. 分离配置与密钥：绝对不要将 API 密钥等敏感信息硬编码在 YAML 文件中。始终通过环境变量（如GOOGLE_API_KEY）或gemini-cli的认证系统来管理。
2. 使用模板继承或包含：如果多个工作流共享相同的配置（如模型参数、认证方式），可以将其提取为“基础模板”或使用 YAML 的锚点（&）和别名（*）特性来复用，保持 DRY（Don‘t Repeat Yourself）。
3. 添加详尽注释：在 YAML 文件中使用#注释每个步骤的意图、关键输入输出的格式说明，这对未来的自己和团队成员至关重要。
4. 创建“工作流库”：在团队内部，可以建立一个共享的 Git 仓库，收集和分类各种有用的stitch工作流模板，如“代码审查”、“周报生成”、“故障排查助手”等，促进知识沉淀和工具复用。

stitch将 Gemini 模型从一次性的问答工具，转变为了一个可编程的、组件化的智能引擎。它代表了 AI 工程化应用的一个务实方向：通过简单的编排，将原子化的 AI 能力组合成解决复杂实际问题的自动化方案。随着你创建的工作流越来越多，你会逐渐积累一套属于自己的“智能脚本库”，很多重复性的脑力劳动将得以解放，让你更专注于那些真正需要创造力和深度思考的任务。