第一章：为什么需要工作流思维
- 传统AI使用的三大痛点
- 工作流系统核心价值（模块化、可复用、成本优化）
- 成功案例数据支撑
- 读者共鸣场景设计
第二章：完成环境准备，安装所有依赖
- 系统要求明确说明
- 三种安装方式：虚拟环境、Poetry、Docker
- API密钥获取详细步骤
- 验证安装成功的方法
第三章：深入理解工作流的工作原理
- 工作流 = 配置文件 + 提示词模板
- 多步骤串联机制
- 长文本分块处理
- 成本优化策略
第四章：运行第一个工作流，体验完整流程
- 三个经典工作流演示
- 命令行 + Web界面双轨教学
- 输出结果质量分析
- 调试技巧分享
第五章：学习进阶技巧，包括自定义工作流
- 工作流设计思路
- Pattern模板编写
- 多步骤工作流创建
- Memory功能使用
第六章：通过实战案例掌握常见应用场景
- 学术文献处理
- 视频字幕批量处理
- 技术博客生成
- 知识库构建
- 多轮对话写作
- 代码文档生成
- 整合实时搜索
第七章：解决可能遇到的各种问题
- 安装配置问题
- 运行时错误处理
- 输出质量优化
- 性能成本优化
第一章 从一个问题开始
你有没有遇到过这样的场景：拿到一篇英文文章想翻译成中文，却发现机翻的结果生硬别扭；或者写了一篇技术文档想让它更易读，却不知从何下手。这些都是真实的需求，也是我搭建这套智能工作流系统的初衷。
传统方式的困境
痛点一：碎片化工具，效率低下
根据2025年AI应用实践报告显示，93%的知识工作者在使用AI时面临工具切换频繁的问题：
- 工具孤岛：ChatGPT做对话，DeepL做翻译，Notion做整理，每个工具都有独立账号和使用逻辑
- 上下文丢失：在工具间切换时，前面的处理结果很难完整传递到下一步
- 重复劳动：同样的提示词要在不同场合反复输入调整
痛点二：质量不稳定，结果难预期
单次AI调用就像抛硬币，结果的好坏很大程度靠运气：
- 提示词敏感：同一个需求，措辞稍微不同，输出质量差异巨大
- 无法迭代：一次性处理，如果结果不满意只能重来
- 标准缺失：没有统一的质量评判和改进机制
痛点三：成本不透明，费用难控制
个人或小团队在使用AI时经常遇到：
- 按月付费压力：ChatGPT Plus每月$20，Claude Pro每月$20，多个订阅累计成本高
- 用量难预估：不知道处理特定任务需要消耗多少tokens
- 模型选择盲目：不确定什么任务该用什么级别的模型
工作流系统的价值
想象一下，如果有这样一个系统：
-
你只需准备好原始文本，执行一条命令，系统就会自动完成翻译、评估、优化三个步骤，最后给你一份高质量的译文。
-
或者你想把技术文档转换成通俗易懂的博客风格，只需选择对应的工作流，系统会自动帮你完成转换。
这就是 Workflows_with_Zen 要解决的问题。它从开源项目 Fabric 获得核心思想——Fabric 是一个专注于用 AI 处理文本的框架，我们在其基础上进行了改进：支持中文，优化了长文本分块处理，加入了 “Zen 风格” 转换，并提供了更灵活的配置方式。Fabric 的理念是将 AI 提示词模块化，通过**模式（Pattern）**组合完成复杂任务。
Fabric 项目通过模块化的提示词（Patterns）将复杂任务拆解为多个可复用步骤，如上图所示。本项目在 Fabric 基础上增加了中文支持和更多改进，让复杂文本处理变得自动化、可定制。
这套系统能做什么
让我们来看几个实际例子：
案例一：三轮优化翻译
假设你有一篇英文技术文章需要翻译成中文。传统做法是直接翻译，然后发现很多专业术语不准确、语序不地道。
使用我们的工作流 translation_to_cn，系统会自动执行三轮处理：
- 初步翻译 – 确保基本意思准确。
- 质量评估 – 自动评估译文质量，找出不足之处（例如术语翻译不当、某段话不够流畅）。
- 优化翻译 – 基于评估结果重新翻译，输出优化后的最终版本。
整个过程自动完成，无需任何手动干预。
案例二：提取智慧精华
有时候你读到一篇很有价值的文章，想提炼其中的核心观点。使用 extract_wisdom 工作流，系统会自动帮你提取出多层次的要点：
- 核心洞察（3–5 条）：文章中最重要、最深刻的见解。
- 关键观点（5–10 条）：除核心洞察外的重要观点。
- 金句摘录：文中最精彩的原句摘录。
- 实用建议：可付诸实践的建议。
- 思考问题：引发读者思考的开放性问题。
这些内容通过精心设计的提示词引导生成，确保提取的不只是表面信息，而是真正有价值的“智慧”。
案例三：Zen 风格转换
技术文档往往枯燥难懂，充斥专业术语。使用 convert_zen_style 工作流，可以将其转换成温暖有趣、类比生动的表述。例如原文：
原文： “机器学习模型的训练过程涉及大量参数调整和超参数优化。通过反向传播算法，模型能够逐步减小预测误差。”
转换后会变成：
转换后： “想象你在教一个孩子骑自行车。一开始他会摇摇晃晃，不断跌倒。但每次跌倒后，他都会调整姿势、力度，慢慢找到平衡感。机器学习的训练就是这样，通过不断尝试和纠正，让模型逐步学会如何降低错误率。”
这种转换不仅仅是换个说法，而是用日常类比让复杂概念变得易于理解、富有温度。
为什么选择这套系统
市面上处理文本的 AI 工具不少，为什么要用这一套？
- 开箱即用的专业工作流： 系统内置了 40+ 个专业工作流，覆盖翻译、总结、提取、写作、分析等场景。每个工作流都经过精心设计和测试，确保输出质量。你无需从零设计提示词，也不必反复调试参数。
- 真正的模块化设计： 每个工作流由两部分组成：YAML 配置文件定义流程，Markdown 文件定义提示词模板。这种设计让你可以轻松理解、修改、组合工作流。要创建新工作流，只需编写配置和提示词文件，无需改动代码。
- 智能分块处理长文本： 面对超长文本，系统会按 Markdown 结构自动分块处理，再合并结果。你不需要手动切分，也不用担心上下文不连贯。
- 成本优化的模型选择： 不同任务对 AI 能力要求不同。简单清洗文本用最便宜的模型即可，复杂分析才需要顶级模型。系统为每个工作流选用合适的模型，在保证质量的同时将成本降低 70% 以上。例如简单提取用 GPT-5 Nano（$0.05/$0.40 每百万 tokens），复杂推理用 Claude Sonnet 4.5（$3/$15 每百万 tokens）。
- 对话管理和上下文支持： 某些任务需要多轮对话。例如修改一篇文章，第一轮给出初步修改，第二轮根据反馈继续优化。系统内置了会话管理功能，可以保存对话历史，在后续交互中自动加载上下文，保持改进连贯。
适合谁用
这套系统特别适合：
- 写作者和内容创作者： 经常需要处理文本、撰写内容的人。无论翻译、润色、列提纲，还是风格转换，都有现成工作流助力，大幅提升效率。
- 研究人员和学生： 阅读文献时提取要点、整理笔记，写论文时润色语言、检查格式，都可以用工作流自动化完成。
- 技术文档作者： 技术文档既要准确又要易读。用 Zen 风格转换让文档更有温度；用术语解释工作流自动生成术语表。
- 想深入理解 AI 的开发者： 本项目本身就是很好的学习案例。代码结构清晰、注释详细，可帮助理解如何设计和实现完整的 AI 应用。
第二章 准备工作
搭建这套系统并不复杂，但需要按步骤来。下面我们逐步讲清每一步在做什么，以及为什么这么做。
系统要求
首先确认你的电脑满足基本要求：
- 操作系统： macOS、Linux 或 Windows 均可。本教程主要基于 macOS，但 Linux 下命令基本通用，Windows 用户可能需要稍作调整。
- Python 版本： 需要 Python 3.11 或更高。为什么是 3.11？因为我们用到的一些库（如 LiteLLM）需要较新的 Python 特性。
- 内存： 建议 4GB 以上。系统本身占用不大，但处理长文本时需要一定内存。
检查你的 Python 版本：
python3 --version
如果版本低于 3.11，建议通过 Python 官网下载最新版本并安装。
获取 API 密钥
这套系统的核心是调用多个 AI 模型，因此你需要准备相应的 API 密钥。
OpenRouter API Key（必需）： OpenRouter 是一个 AI 模型聚合平台，一个密钥即可访问多个模型，包括 GPT-5 系列、Claude Sonnet 4.5、Google Gemini 等。它为不同模型提供统一的接口，自动处理回退和最优路由。注册 OpenRouter 帐号后，在账户的 Keys 页面创建 API 密钥。新用户通常有一些免费额度（约 $5～$10）用于测试。
OpenRouter 平台的账户界面。在登录 OpenRouter 后，进入账户设置中的 *Keys* 页面（如上图所示），点击 “Create Key” 即可创建新的 API 密钥。创建后请立即复制保存，因为密钥只会显示一次。
为什么选择 OpenRouter 而不直接用 OpenAI 或 Anthropic 官方 API？一是使用方便，一个密钥搞定所有模型，不用分别注册多个平台；二是价格透明，按使用量付费且通常比官方更低；三是稳定性好，有多个备用节点。
EXA API Key（可选）： 如果需要用到联网搜索功能（例如获取最新资讯、查找相关文章），可以申请 EXA 的 API 密钥。EXA 提供基于网络的实时信息检索。这个密钥不是必需的，大部分工作流并不需要联网搜索。
安装项目
方式一：使用虚拟环境（推荐新手） – 虚拟环境可以将项目依赖与系统环境隔离，避免版本冲突。
# 1. 克隆项目仓库
git clone https://github.com/whotto/workflows_with_zen.git
cd workflows_with_zen
# 2. 创建虚拟环境
python3 -m venv .venv
# 3. 激活虚拟环境
source .venv/bin/activate # macOS/Linux
# Windows 用户使用: .venv\Scripts\activate
# 4. 安装依赖包
pip install -r requirements.txt
激活虚拟环境后，命令行提示符前会出现 (.venv) 标记，表示当前处于该虚拟环境中。以后每次使用本项目，都需要先激活虚拟环境。
方式二：使用 Poetry（推荐开发者） – Poetry 是现代化的 Python 包管理工具，集依赖管理、虚拟环境、版本锁定于一体。
# 1. 安装 Poetry（如果尚未安装）
curl -sSL https://install.python-poetry.org | python3 -
# 2. 克隆项目仓库
git clone https://github.com/your-username/workflows_with_zen.git
cd workflows_with_zen
# 3. 安装依赖（Poetry 会自动创建虚拟环境）
poetry install
# 4. 激活虚拟环境
poetry shell
Poetry 根据项目中的 pyproject.toml 文件自动安装所有依赖，并生成 poetry.lock 锁定版本，确保不同环境下安装的依赖版本一致。
配置 API 密钥
在项目根目录创建一个名为 .env 的文本文件，填入以下内容：
# OpenRouter API Key（必需）
OPENROUTER_API_KEY=你的_openrouter_api_key
# EXA API Key（可选，用于联网搜索）
EXA_API_KEY=你的_exa_api_key
# OpenAI API Key（可选，如果要直接调用 OpenAI 接口）
OPENAI_API_KEY=你的_openai_api_key
将 你的_openrouter_api_key 替换为实际的 OpenRouter 密钥。
验证安装
在一切安装配置完成后，可以进行简单的功能测试。
查看可用工作流列表：
python app.py --list-workflows
你会看到所有内置工作流的列表，包括 extract_wisdom、translation_to_cn、convert_zen_style 等。
查看特定工作流配置：
python app.py --show-workflow extract_wisdom
这会显示 extract_wisdom 工作流的完整配置，包括所用模型、提示词等内容。例如，你将看到类似的结构：
上图展示了 Fabric 项目中一个模式（Pattern）的配置结构。本项目的工作流配置与之类似，由 YAML 定义工作流步骤，Markdown 定义提示词模板，实现逻辑与内容分离。
如果以上命令都能正常运行，说明环境搭建成功。
（可选）启动 Web 界面：
streamlit run app_web.py
浏览器将自动打开 http://localhost:8501，你会看到一个简洁的 Web 界面。在这里可以：
- 粘贴文本或上传文本文件
- 选择工作流并执行
- 查看处理结果
- 管理历史会话
Web 界面基于 Streamlit 框架，代码位于 app_web.py。如果对界面样式不满意，可以自行修改。
理解项目结构
正式使用之前，建议先了解项目的文件结构，方便日后定制或排错：
workflows_with_zen/
├── app.py # 命令行入口
├── app_web.py # Web 界面入口
├── session_manager.py # 会话管理模块
├── context_manager.py # 上下文管理模块
├── .env # API 密钥配置（需手动创建）
├── requirements.txt # 依赖列表
│
├── config/ # 工作流配置目录（50+ 个 YAML 文件）
│ ├── extract_wisdom.yaml
│ ├── translation_to_cn.yaml
│ └── ... （每个工作流对应一个配置）
│
├── patterns/ # 提示词模板目录（50+ 个子目录）
│ ├── extract_wisdom/
│ │ └── system.md # 提示词模板文件
│ ├── convert_zen_style/
│ │ └── system.md
│ └── ...
│
├── contexts/ # 上下文模板（预设角色/风格）
│ ├── academic_writer.md
│ ├── casual_blogger.md
│ └── ...
│
├── memory/ # 可重用内容片段
│ └── vocab.md # 例如术语表等
│
└── logs/ # 运行日志（自动生成）
└── runs/ # 每次运行都会生成独立日志目录
重点关注三个目录：
- config/ – 工作流配置，每个 YAML 文件定义一个工作流的执行步骤、模型选择、参数设置等。
- patterns/ – 提示词模板，每个工作流一个子目录，里面的 system.md 定义该工作流的 System 提示 内容。
- contexts/ – 上下文模板，定义可重用的角色设定或写作风格（如“学术写作者”、“技术博主”等），可在多个工作流中引用。
第一次运行
现在让我们做一个简单测试，确保系统正常工作。
创建测试文件：新建文件 test.txt，内容可以是几句话，例如：
人工智能正在改变世界。从自动驾驶到医疗诊断，AI 的应用无处不在。
但同时，我们也需要思考 AI 带来的伦理问题和社会影响。
运行摘要工作流：在终端执行：
python3 app.py test.txt --workflow summarize
系统会读取 test.txt 内容，调用 GPT 模型生成总结。你将看到进度日志，处理完成后结果会保存到 summarize-output.md，并自动复制到剪贴板。
查看结果：打开生成的 summarize-output.md，你会看到一份简洁的总结。同时，在 logs/runs/ 目录下生成本次运行的详细日志，包括输入、输出、使用的提示词等，方便调试。
如果一切正常，恭喜你，环境搭建完成！若遇到错误，请检查：
- API 密钥是否正确配置（.env 文件内容和格式正确，无多余空格或引号）。
- 是否已激活虚拟环境（命令行前缀是否有 (.venv)）。
- 依赖是否完整安装（尝试重新运行 pip install -r requirements.txt）。
- 网络连接是否正常（必要时科学上网，保证能调用 OpenRouter API）。
成本预估
你可能关心使用这些模型的成本。根据 OpenRouter 公布的定价（2025 年 1 月数据）：
- GPT-5 Nano： $0.05/百万 输入 tokens，$0.40/百万 输出 tokens
- GPT-5 Mini： $0.25/百万 输入，$2/百万 输出
- GPT-5： $1.25/百万 输入，$10/百万 输出
- Claude Sonnet 4.5： $3/百万 输入，$15/百万 输出
举例来说，翻译一篇 5000 字（约 7500 tokens）的文章，用 GPT-5 Mini 处理成本大约 $0.02～$0.05；用 Claude Sonnet 4.5 做复杂分析成本大约 $0.1～$0.2。OpenRouter 新用户通常有 $5～$10 的免费额度，可足够处理几十篇文章。
小结
至此，你已经完成以下准备工作：
- 安装了所需的 Python 环境和项目依赖
- 获取并配置了 OpenRouter（及可选的 EXA）API 密钥
- 了解了项目的目录结构
- 运行了第一个简单工作流进行功能验证
接下来，我们将深入理解工作流的运行原理，这样你才能真正掌握这套系统，而不仅是会用几个现成命令。
第三章 理解工作流的本质
在着手创建或定制工作流之前，需要先理解它的工作原理。这部分可能略偏技术，但我会尽量用通俗方式解释。
什么是工作流？
工作流（Workflow） 本质上是一个自动化的处理流程。你给它输入，它按照预设的步骤逐步处理，最后输出结果。以翻译工作流 translation_to_cn 为例，它的流程是：
输入英文原文 → 初步翻译 → 翻译质量评估 → 优化翻译 → 输出中文译文
每个箭头代表一个步骤，每个步骤都由 AI 模型执行。系统自动将上一步的输出传递给下一步，如此串联直至完成全部流程。多步拆解的好处是每一步都专注于一个明确任务，最终结果往往比一次性完成更好。
工作流的两大组成
每个工作流由两个文件定义：
YAML配置文件（定义"做什么"）
YAML文件是工作流的"大脑"，它告诉系统按什么顺序、用什么模型、怎样处理数据。
- 配置文件（YAML 格式）： 位于 config/ 目录，定义工作流的执行逻辑。例如看看 extract_wisdom.yaml 的片段：
strategies:
- model: openrouter/openai/gpt-5-mini
prompt_name: extract_wisdom
params:
temperature: 0.3
input_format: "{{text}}"
output_name: wisdom_extracted
其中关键信息包括：
- model：指定使用的 AI 模型，这里是 GPT-5 Mini，通过 OpenRouter 调用。
- prompt_name：指定使用的提示词模板，这里是 extract_wisdom，对应 patterns/extract_wisdom/system.md 文件。
- params：模型参数设置，如 temperature: 0.3 表示输出倾向确定性（值越低越保守，越高越有创意）。
- input_format：定义输入格式。{{text}} 是占位符，表示用户输入的文本将插入这里。
- output_name：为此步输出起一个变量名，后续步骤可以引用它。
Markdown提示词模板（定义"怎么做"）
如果YAML是大脑，那么Markdown模板就是"灵魂"，它决定了AI的身份、目标和工作方式。
- 提示词模板（Markdown 格式）： 位于 patterns/ 目录，定义如何引导 AI 模型。打开 patterns/extract_wisdom/system.md，你会看到类似内容：
# IDENTITY and PURPOSE
你是一个智慧提取大师，能从任何文本中提炼出最有价值的洞察、观点和智慧。
# CORE PRINCIPLES
**深度优于广度**
- 不要泛泛而谈，要找到那些一针见血的观点
- 挖掘隐含的智慧，不只停留在表面意思
**实用性第一**
- 提取的智慧必须能指导实践
- 优先选择那些反直觉的见解
# OUTPUT SECTIONS
## 核心洞察 (3-5 条)
- 用一句话概括每条洞察
## 关键观点 (5-10 条)
- 用简洁语言列出重要观点
...
这个文件以 Markdown 写成，定义了 AI 的身份、原则、输出结构等。系统会将其作为系统消息发送给模型，即告诉模型“你是谁”、“你的任务是什么”、“输出格式要求如何”等等。
多步骤工作流的设计
有些任务需要多个步骤才能做好。以三轮翻译 translation_to_cn 为例，其配置文件结构如下：
strategies:
- model: openrouter/openai/gpt-5-mini
prompt_name: translate_cn
input_format: "{{text}}"
output_name: translation
- model: openrouter/openai/gpt-5-mini
prompt_name: comment_cn_trans
input_format: |
original text:
{{text}}
translation:
{{translation}}
output_name: reflection
- model: openrouter/openai/gpt-5-mini
prompt_name: improved_trans_cn
input_format: |
original text:
{{text}}
translation:
{{translation}}
comments:
{{reflection}}
output_name: improvement
注意这里有三个 strategy，分别对应三个步骤：
- 第一步： 初步翻译。输入原文 {{text}}，输出保存为 translation。
- 第二步： 评估翻译。输入原文和第一步译文（占位符 {{translation}} 会被替换为上一步输出），输出保存为 reflection。
- 第三步： 优化翻译。输入原文、初译和评估结果，输出最终译文 improvement。
每一步都可以通过 {{变量名}} 引用前面步骤的输出。系统会按顺序执行各步，自动完成数据传递。
占位符系统的威力
占位符不仅能插入变量文本，还支持智能的长文本处理：
- {{text}} – *自动分块处理长文本。*当输入文本很长，超过模型上下文限制时，系统会自动将其分块（通常按段落或句子）。每块分别处理后再合并结果。绝大多数工作流使用这种默认方式处理输入。
- <
> – *整体传递长文本。*如果你希望模型一次性处理整个输入（不进行分块），可以用双尖括号。如：
面对长文档，不同的占位符有不同的处理方式：
input_format: "<<text>>"
- 这会把完整文本作为一个整体发送给模型。适用于需要全局理解的任务，但要注意长度不要超出模型限制。
- ((text)) – *按 Markdown 层级智能分块。*这是更智能的分割方式，系统会识别 Markdown 标题层级来分块。例如文档：
# 第一章
内容A
## 1.1 小节
内容B
# 第二章
内容C
- 使用 ((text)) 会按一级标题分块得到两块：“第一章（含其小节）”和“第二章”。还可以指定层级深度，例如 ((text))2 表示按二级标题分块。这样保持了章节完整，不会把段落拆散。
- {{memory_XXX}} – *引用预置内容片段。*在 memory/ 目录下可以放置一些常用可复用内容，如术语表、写作指南等。在提示词模板中可用占位符引入它们。例如：
input_format: |
请参考以下术语表：
{{memory_vocab}}
然后翻译下列文本：
{{text}}
- 系统会读取 memory/vocab.md（因为占位符名称匹配文件名），将内容插入提示中。通过这种机制，可以为模型提供统一的背景知识或风格指南。
模型选择策略
选对模型是成本控制的关键。根据OpenRouter最新定价分析，不同模型的价格差异高达60倍。
不同任务对模型能力要求不同，选对模型能保证质量并优化成本：
- 简单任务用 GPT-5 Nano： 对于文本清理、格式规范、添加标点这类机械规则任务，使用最便宜的 GPT-5 Nano 足够。示例配置：
model: openrouter/openai/gpt-5-nano
params:
temperature: 0.1 # 输出倾向保守确定
- GPT-5 Nano 每百万 tokens 成本仅 $0.05/$0.40。
- 中等复杂度用 GPT-5 Mini： 翻译、总结、提取观点这类需要一定理解力的任务，GPT-5 Mini 性价比最高：
model: openrouter/openai/gpt-5-mini
params:
temperature: 0.3
- 它比 Nano 强大不少，但价格仍低廉 ($0.25/$2 每百万 tokens)。
- 创意写作用 GPT-5： 改写文章风格、头脑风暴这类需要创造力的任务，可用 GPT-5:
model: openrouter/openai/gpt-5
params:
temperature: 0.6 # 增加输出的多样性
- GPT-5 是旗舰模型，适合对语言质量要求极高的场景。
- 复杂推理用 Claude Sonnet 4.5： 代码解析、复杂推理、深度分析这类最具挑战的任务，可用 Anthropic 的 Claude Sonnet 4.5:
model: openrouter/anthropic/claude-sonnet-4.5
params:
temperature: 0.4
- 根据 OpenRouter 模型排名，Claude Sonnet 4.5 在推理能力上名列前茅。它擅长长上下文推理和工具调用，但成本也最高（$3/$15 每百万 tokens）。一般只有在 GPT-5 系列不胜任时才需要用它。
Temperature 参数的影响
Temperature 控制模型输出的随机性大小：
- 0.1～0.3： 输出非常保守、确定性强，适合翻译、信息提取、分析等需要准确复现的任务。
- 0.4～0.6： 平衡一定的创造力和准确性，适合撰写内容、改写措辞等任务。
- 0.7～1.0： 输出更具创造性、多样性，适合头脑风暴、故事创作等对一致性要求不高的任务。
一般而言，事实类任务用低温度保证可靠性，创意类任务用较高温度增加丰富性。
系统的处理流程
当你执行 python app.py test.txt –workflow extract_wisdom 时，系统会进行如下处理：
- 加载配置： 读取 config/extract_wisdom.yaml，了解需要执行的步骤和所用模型等。
- 加载提示词模板： 读取 patterns/extract_wisdom/system.md 作为系统提示。
- 读取输入文件： 将 test.txt 的内容读入，赋值给占位符 {{text}}。
- 预处理长文本： 根据 input_format 设置，决定是否分块。如使用 {{text}} 则按需自动分块处理长文本，每块分别调用模型。
- 构造 API 请求： 将 system 提示和用户文本组合，构造 OpenRouter API 调用的 JSON 请求。
- 调用 AI 模型： 通过 OpenRouter 用指定模型运行推理，获取输出。
- 处理并保存结果： 将模型输出保存为指定的 output_name 变量，如果有后续步骤则继续，否则将最终结果写入 *-output.md 文件。
- 记录日志： 将每一步的输入输出内容写入日志文件，路径在 logs/runs/日期时间/ 下。
整个过程中每一步都有详细日志记录。你可以在 logs/ 目录查看每一次运行的所有中间步骤输入输出，便于调试。
Fabric 的模式设计理念
本系统的提示词模板设计借鉴了 Fabric 项目。Fabric 的核心思想是将 AI 能力模块化，每个 Pattern 解决一个具体问题，通过组合不同 Pattern 实现复杂工作流。Fabric 的模式模板具有统一结构：
# IDENTITY and PURPOSE
# CORE PRINCIPLES (或 STEPS)
# OUTPUT SECTIONS
# OUTPUT INSTRUCTIONS
# INPUT
这种结构让提示词层次清晰、易于维护和复用。本项目完全遵循这种格式设计提示词，因此你可以直接使用 Fabric 社区分享的 Pattern（通常只需稍作修改）。
为什么要这样设计？
你可能会问，为什么要将配置和提示词分开？为什么不用代码硬编码流程和提示？
-
配置与代码分离： 这是软件工程的最佳实践。YAML 配置定义“做什么”，代码实现定义“怎么做”。当你想修改工作流流程时，只需编辑 YAML，毋须改动任何 Python 代码。
-
提示词易读易维护： 把提示词放在 Markdown 文件中而非代码字符串，有多重好处：
- 可以利用 Markdown 格式对提示词进行排版，增加可读性。
- 可在任何文本编辑器中方便地编辑和预览。
- 模板文件可单独进行版本管理和分享。
- 不同工作流可以引用相同的模板，实现一次编写，多处复用。
-
模块化与复用： 每个 Pattern 独立封装一种 AI 能力，可在不同工作流中组合使用。例如，同样的翻译提示词模式可以用于多个不同翻译工作流，只需在配置中引用它。这避免了重复劳动，也使优化某个模式时能同时提升所有使用它的工作流效果。
小结
这一章你了解到：
- 工作流由 YAML 配置（定义流程）和 Markdown 提示词（定义内容）组成
- 将复杂任务拆解成多步骤工作流通常能提升效果
- 占位符系统可以灵活处理长文本和注入额外上下文
- 根据任务难度和性质选择合适的模型可以兼顾质量和成本
- 整个系统采用模块化和配置驱动的设计，灵感来自 Fabric 项目
接下来,我们会实际运行几个工作流,看看它们的效果,并学习如何创建自己的工作流。
第四章 运行你的第一个工作流
理论讲解完毕，现在让我们实际操作，体验一下工作流的强大威力。本章将运行几个典型工作流，看看它们能做什么并分析效果。
示例一：提取文章精华
场景： 你读到一篇很好的文章，想快速提炼其中的精华要点。
使用工作流： extract_wisdom 提取智慧。
- 准备测试文本： 创建文件 article.txt，内容可以是任意你感兴趣的文章片段。这里举个例子：
为什么工作流思维很重要？
在现代工作中，我们面临的任务越来越复杂，单靠人力处理效率低下且容易出错。
工作流思维的核心是把复杂任务拆解成小步骤，每个步骤专注做好一件事，然后串联起来。
这种思维的价值在于：
1. **可复现性** – 相同输入总能得到稳定输出；
2. **可调试性** – 出问题可定位到具体步骤；
3. **可优化性** – 可以针对瓶颈环节重点改进。
AI 时代，工作流思维更加重要。因为 AI 擅长执行明确的任务，却不擅长处理模糊需求。把需求拆解成明确的步骤，才能发挥 AI 的最大价值。
- 运行工作流： 执行命令：
python3 app.py article.txt --workflow extract_wisdom
系统会开始处理，你将看到日志输出类似：
Processing strategy 1: extract_wisdom ... done
Results saved to: extract_wisdom-output.md
✅ 结果已保存到: extract_wisdom-output.md
📋 结果已复制到剪贴板
查看结果： 打开 extract_wisdom-output.md，你将看到结构化的输出，例如：
## 🎯 核心洞察 (4 条)
- AI 的价值取决于它如何被设计与治理——技术本身不是目标，服务人类才是。
- 数据驱动的学习能力既是力量，也是风险：越依赖数据，越可能放大偏见与侵犯隐私。
- 技术进步必须伴随制度建设与人力重塑，否则收益会被社会成本侵蚀。
- 在拥抱变革时保持警惕——可持续的创新来自并行推进能力建设、伦理约束与监督机制。
## 💡 关键观点 (8 条)
- AI 正在渗透日常生活，从消费级应用到关键基础设施，其影响具有系统性。
- 机器学习是实现智能行为的核心路径，但其效果高度依赖于数据的量与质。
- 深度学习通过多层网络处理复杂模式，但带来了可解释性和可控性的挑战。
- 隐私保护、算法偏见和就业影响不是技术问题的“副产品”，而是设计与部署中的核心考量。
- 技术和伦理需要并行：技术推进速度不能超过法规、伦理与社会适应能力。
- 医疗、教育和科研等领域既是最大受益者，也是对安全性与公平性要求最高的场景。
- 主动治理（标准、审计、问责）比事后补救更具成本效益和公信力。
- 人机协作优先于完全替代：把人放在决策链的关键位置能降低风险并提高信任。
## 📌 金句摘录 (4 条)
- “人工智能正在改变我们的世界。”（出处：输入文本）
- “通过大量数据的训练，机器可以学会识别模式、做出预测和决策。”（出处：输入文本）
- “隐私保护、算法偏见、就业影响等问题需要我们认真思考和应对。”（出处：输入文本）
- “我们应该积极拥抱这些变化，同时保持警惕，确保技术为人类服务。”（出处：输入文本）
可以看到，系统从原文中提炼出了核心洞察和关键观点等，信息比原文更精炼。如果你在做读书笔记或整理资料，这个工作流可以节省大量时间。
3.查看详细日志（可选）： 打开 logs/runs/XXXX…/（最新的以时间命名的运行日志目录），里面有：
- step_01_extract_wisdom_input.md – 发送给 AI 模型的完整提示（包含系统消息和用户文本）。
- step_01_extract_wisdom_output.md – 模型返回的原始响应。
- text_processor.log – 运行过程日志。
打开 step_01_extract_wisdom_input.md，可以看到 JSON 格式的对话：
[
{"role": "system", "content": "# IDENTITY and PURPOSE\n你是一个智慧提取大师…"},
{"role": "user", "content": "<task>\n<input_text>\n为什么工作流思维很重要…</input_text>\n</task>"}
]
这让你了解系统到底发送了什么给模型，便于检查提示词是否正确。如有需要，你可以根据输出调节提示词模板或参数。
示例二：三轮反思式翻译
场景： 有一段英语技术说明需要翻译成中文，希望措辞专业又自然。
使用工作流： translation_to_cn 三段式优化翻译。（参考吴恩达老师的反思式翻译）
- 准备英文文本： 新建文件 english.txt，内容示例：
The key to effective prompt engineering is understanding the model's capabilities and limitations.
A good prompt should be clear, specific, and provide enough context for the model to generate accurate responses.
Iterative refinement is often necessary to achieve optimal results.
- 运行工作流：
python3 app.py english.txt --workflow translation_to_cn
该工作流包含三个步骤，你会在日志中看到类似：
Executing strategy 1: translate_cn
Executing strategy 2: comment_cn_trans
Executing strategy 3: improved_trans_cn
Results saved to: translation_to_cn-output.md
- 查看最终译文： 打开 translation_to_cn-output.md，可以看到优化后的翻译结果。例如：
有效的 prompt engineering（提示工程）的关键在于了解模型的能力与局限性。
一个好的 prompt（提示）应该清晰、具体，为模型提供足够的上下文，以便生成准确的回答。
通常需要通过反复的 iterative refinement（迭代完善）才能达到最佳效果。
读起来是否比直接机翻自然流畅？
- 分析各步骤效果（查看日志）： 进入日志目录，打开：
- step_01_translate_cn_output.md 查看初步翻译：
有效提示工程的关键在于理解模型的能力和局限性。一个好的提示应该清晰、具体，并为模型提供足够的上下文以生成准确的响应。通常需要迭代改进以获得最佳结果。
- （初译基本直译，通顺但略显生硬）
- step_02_comment_cn_trans_output.md 查看翻译评估反馈：
翻译整体准确，但有以下改进建议：
1. "prompt engineering" 建议翻译为 "提示词设计"，更符合中文习惯；
2. "迭代改进" 可以换成 "反复打磨"，更口语化；
3. 部分句子结构略微直译，可调整使语言更自然。
- step_03_improved_trans_cn_output.md 查看最终优化译文：
有效的提示词设计关键在于理解模型的能力边界。好的提示词应清晰明确、信息充分，为模型提供足够的背景。要达到理想效果，往往需要反复打磨。
（采纳了反馈意见，措辞更本土、更流畅）
从初译到评估再到改进，可以明显看到译文质量的提升。这正是多步骤工作流的价值所在：每一步聚焦一个问题，最终叠加出远优于一次性完成的效果。
示例三：Zen 风格转换
场景： 技术说明过于晦涩，希望转换成生动易懂的表述。
使用工作流： convert_zen_style Zen 风格转换。
- 准备技术文本： 新建文件 tech.txt，内容示例：
卷积神经网络通过卷积层提取图像的局部特征，然后通过池化层降低维度。
多层卷积和池化的组合使得网络能够学习从简单边缘到复杂物体的逐层特征表示。
最后通过全连接层将特征映射到具体的分类结果上。
- 运行工作流：
python3 app.py tech.txt --workflow convert_zen_style
- 查看结果： 打开 convert_zen_style-output.md，你会看到完全不同风格的表达：
想象你在看一张模糊的照片。一开始，你可能只能分辨出一些简单的线条和色块；
再仔细看，你开始认出一些形状；最后，你发现照片里是一只猫。
卷积神经网络的工作方式跟这个过程很像。它不会一下子看懂整张图像，
而是分层次去观察：第一层看基本的线条和角落，第二层关注简单的形状，
第三层开始识别具体的物体。
每经过一层处理，图像的信息就变得更抽象一点——从像素到线条，再到形状，最后到物体。
就像看照片时，从“这里有条弧线”到“这可能是猫的尾巴”，再到“哦，这是一只猫”。
最后，网络会把这些层层累积的“理解”综合起来，给出它看到的东西：比如告诉你，这是一张猫的照片。
可以看到，原本生硬的技术描述被转换成了一个连续的类比故事，用教人看模糊照片来类比卷积神经网络提取特征的过程。这种表达更贴近读者，也更容易让人理解复杂原理。
分析： Zen 风格转换不仅替换了用词，更重要的是引入了场景类比、通俗解释。这对写科普文章、博客非常有用。你可以将专业论文或枯燥文档投喂进去，得到一篇有人情味的讲解。
使用 Web 界面
如果你觉得命令行不直观，可以尝试 Web 图形界面：
streamlit run app_web.py
浏览器将打开界面（默认 http://localhost:8501）。在 Web UI 上，你可以：
- 输入文本： 在左侧文本框粘贴文本，或上传一个 .txt 文件。
- 选择工作流： 从下拉菜单选择要执行的工作流。
- 查看处理结果： 点击 “开始处理”，右侧将显示处理进度和最终结果（支持 Markdown 格式预览）。
- 管理历史记录： UI 会保存最近的运行记录，你可以点击切换查看之前的结果。
- 上下文设置： 可以选择预设的角色/风格（academic_writer 等）来影响输出语气。
Web 界面对于新手来说更加友好直观。但命令行方式更适合批量处理和可编程调用——两种方式可根据需要灵活选择。
使用会话管理
有些任务需要多轮交互才能完成。会话管理允许你将多次调用串联成一段对话，有点类似 ChatGPT 的聊天上下文。
创建会话： 例如你有一篇文章多次修改，想和 AI 进行多轮讨论改进。第一次润色文章并创建会话：
python3 app.py draft1.txt --workflow improve_writing --session my_article
这会新建一个名为 “my_article” 的会话，并保存此次对话内容。
继续会话： 编辑文章或写下一轮修改要求保存为 draft2.txt，然后继续会话：
python3 app.py draft2.txt --workflow improve_writing --session my_article
系统会自动加载会话历史，把前一轮 AI 给你的修改建议当作上下文，这一轮 AI 会基于你新的反馈继续润色。如此可以反复迭代，直到满意为止。
查看会话内容：
python3 app.py --show-session my_article
这会打印整个 “my_article” 会话的消息历史，包括每一轮你给的内容和 AI 的回复。
删除会话：
python3 app.py --delete-session my_article
如果会话不再需要，可以将其删除（实际上是删除保存在 ~/.workflows_zen/sessions/ 下对应文件）。
会话管理使 AI 具备 “记忆”，非常适合需要持续讨论的任务，如反复完善一篇文章、长篇对话等。
使用上下文模板
上下文（Context） 功能可以为模型提供一个预设角色或说话风格，相当于隐含的背景设定。项目内置了一些常用上下文模板，在调用工作流时可以指定：
- 使用学术风格：
python3 app.py text.txt --workflow write_essay --context academic_writer
- 这会加载 contexts/academic_writer.md 模板，让 AI 以严谨学术的语气撰写文章（比如用词正式、逻辑清晰）。
- 使用博客风格：
python3 app.py text.txt --workflow write_essay --context casual_blogger
- 让 AI 以轻松口语化的风格输出，更贴近一般读者。
查看所有可用的 Context 列表：
python3 app.py --list-contexts
输出会显示已定义的上下文名称。你也可以很容易地创建自己的上下文：在 contexts/ 目录下新增 Markdown 文件，例如 my_style.md，定义你的风格偏好，然后运行时用 –context my_style 即可应用。
命令行高级用法
命令行模式还有一些高级技巧：
-
从剪贴板读取输入：
先复制好文本，然后运行：
python app.py --clipboard --workflow summarize
-
系统将直接读取剪贴板内容作为输入，生成总结。
-
通过管道传输输入：
可以将其他命令的输出通过管道传给工作流：
cat article.txt | python app.py --workflow extract_wisdom
-
这样无需创建临时文件，也能处理文本流。
-
指定输出文件路径：
默认输出会保存在当前目录下 workflow_name-output.md。你可以用 -o 参数自定义输出文件：
python3 app.py input.txt --workflow summarize -o ./output/summary.md
-
启用详细日志：
平时日志为了简洁默认只显示关键信息。若需调试，可以加 –verbose 或 –debug 开关：
python3 app.py input.txt --workflow extract_wisdom --verbose --debug
- 这会在控制台打印更多调试信息，例如各步骤的耗时、调用参数等。
小结
通过上述实践，你已经：
- 运行了不同类型的工作流，体验了单步骤和多步骤工作流的区别
- 学会查看工作流的输出结果和详细日志，了解内部处理过程
- 掌握了两种使用方式：命令行批处理和交互式 Web 界面
- 学习了会话管理和上下文模板的用法，能够进行多轮对话和风格定制
- 了解了一些命令行的高级技巧，如读取剪贴板、管道输入等
接下来,我们会学习如何创建自己的工作流,以及一些进阶技巧。
第五章 进阶技巧：创建自己的工作流
内置的 40+ 个工作流已经覆盖了很多场景，但你的需求可能更加特殊。本章将手把手教你从零创建自定义工作流。
设计工作流的思路
第一步：需求分析——明确要解决什么问题
在动手之前，先问自己几个关键问题：
- 要解决什么问题？ 先定义工作流的目标。例如，你需要把会议记录整理成任务清单。那么目标就是：输入会议记录，输出结构化的任务列表。
- 需要几步完成？ 简单任务一步够，复杂任务可能多步。对于会议记录示例，可以考虑两步：1）提取所有任务条目；2）为每个任务添加优先级和预估工时。
- 每步输入输出是什么？ 第一步输入会议记录文本，输出任务列表。第二步输入任务列表，输出带优先级和工时的清单。
- 选用什么模型？ 该任务主要是信息提取和简单推理，用 GPT-5 Mini 足矣，没必要上昂贵模型。
第二步：任务拆解——化繁为简
根据AI工作流设计最佳实践，优秀的工作流设计遵循"单一职责原则"：每个步骤只做一件事，并且做好。
拆解策略：
graph TD
A[复杂任务] --> B{可以拆解吗？}
B -->|是| C[拆解成子任务]
B -->|否| D[单步骤工作流]
C --> E[确定子任务顺序]
E --> F[定义数据传递]
F --> G[多步骤工作流]
实战：创建“会议任务提取”工作流
下面我们按上述思路一步步创建这个工作流。
需求分析
背景：你经常需要参加会议，手写的会议记录杂乱无章，希望AI帮你整理成标准格式的会议纪要。
输入：混乱的会议记录文本
输出：结构化的会议纪要，包含议题、决策、行动项、负责人等
复杂度：中等，需要2-3个步骤
任务拆解设计
经过分析，我们设计这样的处理流程：
- 信息提取：从杂乱记录中提取关键信息
- 结构化整理：按照标准格式组织内容
- 行动项优先级排序：为任务分配优先级和时间节点
第一步：创建 Pattern 模板 – 在 patterns/ 目录新建子目录和模板文件：
mkdir -p patterns/extract_meeting_tasks
touch patterns/extract_meeting_tasks/system.md
用编辑器打开 patterns/extract_meeting_tasks/system.md，编写提示词模板：
# IDENTITY and PURPOSE
你是一名经验丰富的项目管理助理，擅长从会议记录中提取可执行的任务项。
# CORE PRINCIPLES
**完整性**
- 不遗漏任何提到的任务（即使轻描淡写也要记录）
- 包含会议中提及的负责人或截止时间等信息
**可执行性**
- 任务描述要清晰具体，能直接据此行动
- 模糊表述要转换为明确的行动项
**结构化**
- 将任务按重要性或模块分类
- 列出任务必要的背景（如负责人、期限）
# OUTPUT SECTIONS
## 核心任务
最重要、最紧急的任务（优先级最高）。
格式：
- [任务描述] - [负责人] - [截止时间]
## 次要任务
重要但不那么紧急的任务。
## 待讨论事项
需要进一步确认或下次会议讨论的事项。
# OUTPUT INSTRUCTIONS
- 用中文输出结果。
- 使用 Markdown 列表格式列出任务，每个任务一行。
- 如果记录中未提及负责人或时间，标注为“待定”。
# INPUT
INPUT:
这里我们设置了 AI 的身份、原则和输出格式要求。输出部分定义了三个分类：核心任务、次要任务、待讨论事项，并规定了列表格式。
第二步：创建配置文件 – 在 config/ 目录创建 extract_meeting_tasks.yaml：
strategies:
- model: openrouter/openai/gpt-5-mini
prompt_name: extract_meeting_tasks
params:
temperature: 0.2 # 偏低，注重准确性
input_format: "{{text}}"
output_name: tasks_extracted
这个配置只有一个步骤（strategy），使用我们刚写的 extract_meeting_tasks 模板，用 GPT-5 Mini 模型，低温度输出，并将结果命名为 tasks_extracted。
第三步: 测试工作流 – 准备一份模拟的会议记录 meeting.txt：
产品评审会 2025-01-15
参会: 张三(产品), 李四(开发), 王五(设计)
讨论:
1. 新版本功能规划
- 用户反映搜索功能不好用，李四下周优化。
- 张三提议增加夜间模式，王五本周出设计稿。
- 数据统计页面加载慢，需要优化数据库查询（李四）。
2. Bug 修复
- iOS 端偶尔崩溃，李四承诺周五前修复。
- 注册页验证码不显示，**最高优先级**，李四明天解决。
3. 待确认
- 是否开发推送通知功能？意见不统一，下次会议再讨论。
运行我们新建的工作流：
python3 app.py meeting.txt --workflow extract_meeting_tasks
处理完成后，打开 extract_meeting_tasks-output.md，应看到结构化的任务清单，例如：
## 核心任务
- [修复注册页验证码不显示问题] - 李四 - 明天 (最高优先级)
## 次要任务
- [优化搜索功能体验] - 李四 - 下周
- [设计夜间模式界面] - 王五 - 本周
- [优化数据统计页面查询性能] - 李四 - 待定
## 待讨论事项
- [是否开发推送通知功能] - 待定 - 下次会议讨论
可以看到，AI 成功提取了会议中提到的任务项，并根据语境推断了优先级（注册页验证码作为核心任务）和负责人、期限等信息。“待讨论事项”也被单独列出。
第四步：添加到 Web 界面（可选）： 编辑 app_web.py，在 get_workflow_display_names() 函数的字典中加一行：
'extract_meeting_tasks': '会议任务提取',
保存并重新运行 Streamlit Web UI，在下拉列表中就能看到“会议任务提取”这个新工作流了。
创建多步骤工作流
现在，我们给刚才的工作流再加一个步骤：为每个任务评估优先级和预估工时。这需要一个新的 Pattern 以及修改配置：
新增第二个 Pattern：
mkdir -p patterns/prioritize_tasks
touch patterns/prioritize_tasks/system.md
编辑 patterns/prioritize_tasks/system.md：
# IDENTITY and PURPOSE
你是一名项目管理专家，负责为任务列表评估优先级和工作量。
# CORE PRINCIPLES
**优先级判断**
- 紧急且重要的任务标为 P0
- 重要不紧急 = P1；紧急不重要 = P2；其他 = P3
**工作量评估**
- 估计完成每个任务需要的工时（小时）
- 考虑任务复杂度和潜在困难
# OUTPUT INSTRUCTIONS
在每个任务描述前添加：
- 优先级标签 [P0/P1/P2/P3]
- 预估工时 (小时)
保持原有的任务分类结构和格式。
# INPUT
INPUT:
这个模板会给每个任务打上优先级（P0~P3）并估算工时。
修改配置文件： 编辑 config/extract_meeting_tasks.yaml，增加第二步 strategy：
strategies:
- model: openrouter/openai/gpt-5-mini
prompt_name: extract_meeting_tasks
params:
temperature: 0.2
input_format: "{{text}}"
output_name: tasks_list
- model: openrouter/openai/gpt-5-mini
prompt_name: prioritize_tasks
params:
temperature: 0.3
input_format: |
原始会议记录:
{{text}}
提取的任务清单:
{{tasks_list}}
output_name: tasks_prioritized
这样，第一步输出命名为 tasks_list，第二步可以引用它，同时我们也把原文 {{text}} 传入第二步供参考（以防 AI 需要上下文判断任务性质）。
再次运行工作流：
python3 app.py meeting.txt --workflow extract_meeting_tasks
现在输出将包含优先级和工时估算，例如：
## 核心任务
- [P0] [修复注册页验证码不显示问题] - 李四 - 明天 - **2小时**
*理由：影响用户注册流程，必须立即解决*
## 次要任务
- [P1] [优化搜索功能体验] - 李四 - 下周 - **8小时**
*理由：用户反馈集中，但不影响核心功能*
- [P1] [设计夜间模式界面] - 王五 - 本周 - **6小时**
*理由：提升用户体验，重要但时间不敏感*
- [P2] [优化数据统计页面查询性能] - 李四 - 待定 - **4小时**
*理由：有改进空间，但暂未严重影响使用*
## 待讨论事项
- [是否开发推送通知功能] - 待定 - 下次会议讨论 - **N/A**
*理由：需要进一步明确需求和优先级*
通过增加第二步，我们实现了一个两阶段工作流：第一步提取任务，第二步 enriched 任务信息。多步骤工作流设计就是如此灵活：可以将不同 AI 能力串联起来完成更复杂的目标。
利用 Memory 功能复用内容
如果某些信息在多个工作流中都会用到，可以放入 memory/ 目录实现共享。比如你的团队有固定的术语或规范：
创建文件 memory/team_terms.md：
# 团队术语表
- P0：最高优先级，必须立即处理
- P1：高优先级，本周内完成
- P2：中优先级，两周内完成
- P3：低优先级，排期处理
- 工时单位：以“人天”计算，1 人天 = 8 小时
然后在提示词模板或配置中引用它。例如在 prioritize_tasks 的模板中我们可以这样修改输入格式：
input_format: |
请参考以下优先级定义和工时单位说明：
{{memory_team_terms}}
对下列任务进行标注和评估：
{{tasks_list}}
系统会自动将 memory/team_terms.md 的内容插入提示中，相当于给模型提供了统一的参考规范。
Memory 功能可以用来存放长背景资料（如人物档案、术语解释）、格式规范等任何你希望在多个地方重复使用的文本片段。
处理长文本的技巧
在处理超长文本时，有几种不同策略，之前提到的占位符用法可以灵活控制分块方式：
- 自动分块 {{text}}： 这是默认方式，系统根据段落或句子长度自动切分。这适用于各部分可以独立处理然后再组合的情况，比如提取要点、摘要等。
- 按结构分块 ((text))： 适用于内容有层次结构且希望保持章节完整的情况。例如，处理一本电子书，可以按章（((text))）或节（((text))2）为单位分别总结，再合并。这样不会把一个章节内容拆散，输出更连贯。
- 整体不分块 <
>： 适用于需要全局理解才能完成的任务。例如让 AI 给整篇文章写评论或结论总结，就需要看完整篇才能下结论，此时用 <> 提供全文。但要注意模型的上下文长度限制（OpenRouter 上 GPT-5 Nano/Mini 支持最大 400k tokens 上下文）。 - 逐步处理长任务： 如果文本极长超出单次调用限制，另一种思路是分步摘要：先用模型对各章节分别总结，再把摘要汇总再总结。这相当于人工摘要长文的思路，只是由 AI 自动完成。
大多数情况下，智能分块 ((text)) 是效果和性能的最佳折中——它保持语义完整的同时避免模型上下文溢出。
调试工作流
创建工作流往往需要反复调试。这里提供一些排查问题的思路：
- 查看日志中的请求内容： 首先看 logs/runs/…/step_X_input.md，确认发送给模型的提示是否符合预期。占位符有没有正确替换？提示词格式有无错误？很多问题可通过检查这里发现。
- 检查模型输出原文： 打开 step_X_output.md 看 AI 原始输出。如果输出格式不对，可能是提示中的 OUTPUT INSTRUCTIONS 不够清晰。比如要求列表但AI写成段落，那就需要强化指令或给示例格式。
- 针对性测试单一步骤： 如果多步骤工作流结果不好，建议拆开每一步单独测试。你可以临时写一个只有单步的 YAML 来诊断是哪一步的问题。例如先单独用 extract_meeting_tasks 跑，看提取效果；再单独喂人工整理的任务列表给 prioritize_tasks 跑，看标注效果。确定问题环节后再改进模板或参数。
- 降低 Temperature 重试： 输出不稳定或偏离预期时，试试把温度调低接近 0，模型会更严格遵循提示指令，便于观察提示词设计是否有效。调试通过后再逐步提高温度以得到更丰富的输出。
- 利用 CLI 调试选项： 善用 –verbose 或 –debug 让运行时打印更多信息，比如每个 chunk 的内容长度、API 耗时等等，有助于发现性能瓶颈或错误发生的位置。
优化提示词的技巧
提示词质量直接决定了输出质量。以下是一些经验法则：
- 给示例而非笼统要求： 模型往往通过模仿来学习格式。比起说“输出要简洁明了”，不如给一个示例格式。“示例:” 可以帮助模型了解你想要的排版和语气。
- 分段说明而非一长段文字： 像 Fabric 模式那样用标题和要点列出规则，比把要求写成一段话更容易被模型正确解析。将不同侧重点分条陈述，模型更不会遗漏。
- 正面指令代替负面禁令： 与其说“不要输出废话”，不如明确说“只输出与任务相关的内容”。负面表述有时适得其反，不如直接告诉模型做什么。
- 强调重点和必须遵守点： 可以用 加粗 或「不允许…」「必须…」等字眼突出关键要求。例如“不允许在输出中添加任何解释性文字”这样的硬性要求务必在提示词中声明清楚。
- 逐步逼近：如果难以一下设计出完美提示词，可以先写一个大致的，然后实际运行看看输出哪里不理想，再针对性地在提示词中添加约束或示例。AI 可以成为调试提示词的“对照镜”，快速迭代改进。
组合已有 Pattern
你不需要每次都从零编写提示词。已经存在的 Pattern 完全可以复用和组合。例如，你想先翻译英文文章再提炼智慧精华，可以组合前面的 translate_cn 和 extract_wisdom 模式：
新建配置文件 trans_and_wisdom.yaml：
strategies:
- model: openrouter/openai/gpt-5-mini
prompt_name: translate_cn # 复用翻译模式
input_format: "{{text}}"
output_name: translated
- model: openrouter/openai/gpt-5-mini
prompt_name: extract_wisdom # 复用提炼智慧模式
input_format: "{{translated}}"
output_name: wisdom
就这样简单两步，第一步翻译，第二步对译文提炼智慧。同样，你可以用 convert_zen_style 的输出再接 improve_writing 来先转换风格再润色语言等等。模式复用让我们像搭积木一样构建新流程，充分体现了模块化的威力。
小结
这一章我们学习了如何设计和创建自己的工作流，以及提示词优化的进阶技巧。你已经掌握了：
-
从需求出发设计工作流的思路
-
创建新的 Pattern 模板和对应 YAML 配置的方法
-
如何将多个步骤串联形成复杂工作流
-
利用 Memory 实现提示词内容复用
-
控制长文本处理方式的多种技巧
-
调试和优化工作流的有效手段
-
提示词设计的经验法则
-
复用已有模式快速搭建新工作流
有了这些技能，你几乎可以按照自己的需求创造任意你能想象的工作流。
第六章 实战案例
纸上得来终觉浅，绝知此事要躬行。
现在让我们看看几个实际应用场景中如何利用这套工作流系统“炫技”。这些案例你可以直接“抄作业”，或作为灵感自定义属于你的工作流。
案例一：处理学术文献
场景： 研究人员需要阅读大量英文论文并做笔记。我们可以构建一个完整的“文献助手”工作流：先翻译，再提炼要点，最后生成结构化笔记。
需求分析：
- 翻译英文文献为中文，方便阅读。
- 提取论文中的核心论点和方法。
- 生成包含洞察、方法、结论等的读书笔记。
设计工作流： 创建 config/process_paper.yaml：
strategies:
# 第一步：翻译全文（按章节分块）
- model: openrouter/openai/gpt-5-mini
prompt_name: translation_to_cn
input_format: "((text))" # 按 Markdown 一级标题分块
params:
temperature: 0.3
split_by_markdown_level: 2 # 指定按二级标题分块
output_name: translated
# 第二步：提炼智慧要点
- model: openrouter/openai/gpt-5-mini
prompt_name: extract_wisdom
input_format: "{{translated}}"
output_name: wisdom
# 第三步：生成读书笔记
- model: openrouter/openai/gpt-5-mini
prompt_name: create_study_notes # 需要我们编写的 Pattern
input_format: |
论文原文（已翻译）：
{{translated}}
提取的核心内容：
{{wisdom}}
output_name: notes
这里假设我们还需要写一个 patterns/create_study_notes/system.md 模板，引导 AI 将翻译和要点结合，生成完整的笔记。你可以定义输出包含研究背景、主要方法、结论等部分。
使用方法： 准备论文的 Markdown 文档（可用工具将 PDF 转换为 Markdown），假设文件名 paper.md。运行：
python3 app.py paper.md --workflow process_paper
最终输出会是 process_paper-output.md，里面有这篇论文的中文翻译和结构化笔记。这样，你阅读文献时就多了一个强力助手，节省大量时间。
案例二：批量处理视频字幕
场景： 你有多个视频的自动转录字幕文件，想批量地润色断句，方便后续发布或分析。
需求分析：
- 修正语音识别错误和常见口语（“啊”、“嗯”）。
- 添加标点和段落，使字幕可读性提升。
- 由于文件很多，需要批量自动处理。
设计工作流： 我们可以利用已有的简单模式组合。比如系统里已有 correct_audio_transcription 模式（纠正文稿）和 add_punctuation_paragraphs 模式（加标点分段）。创建配置 config/polish_subtitle.yaml：
strategies:
- model: openrouter/openai/gpt-5-nano # 用最便宜的模型即可
prompt_name: correct_audio_transcription
params:
temperature: 0.2
input_format: "{{text}}"
output_name: cleaned
- model: openrouter/openai/gpt-5-nano
prompt_name: add_punctuation_paragraphs
params:
temperature: 0.1
input_format: "{{cleaned}}"
output_name: polished
批量处理脚本： 新建一个 Shell 脚本 batch_process_subtitles.sh：
#!/bin/bash
mkdir -p polished_subtitles
for file in subtitles/*.txt; do
echo "Processing $file..."
python app.py "$file" --workflow polish_subtitle -o "polished_subtitles/$(basename "$file" .txt)_polished.txt"
done
echo "All files processed."
给予执行权限并运行：
chmod +x batch_process_subtitles.sh
./batch_process_subtitles.sh
这样，subtitles 文件夹下所有 .txt 字幕文件都会自动依次处理，结果输出到 polished_subtitles 目录下，对应生成 “_polished.txt” 文件。你省去了手工一个个清理的麻烦。
案例三：技术博客生成流程
场景： 你有一些技术研究笔记，希望转换成面向大众的博客文章发布。
需求分析：
- 将专业、生硬的技术内容改写为通俗易懂、富有案例的表述（Zen 风格）。
- 插入类比或日常语言，让内容有趣。
- 确保逻辑通顺、读者友好。
解决方案： 结合前面学过的几个模式，可以设计这样一个多步流程：
strategies:
# 第一步：提取大纲（以确保逻辑结构清晰）
- model: openrouter/anthropic/claude-sonnet-4.5
prompt_name: get_outline_detail # 模式：生成详细大纲
input_format: "<<text>>" # 全文处理
output_name: outline
# 第二步：Zen 风格转换正文
- model: openrouter/openai/gpt-5
prompt_name: convert_zen_style
params:
temperature: 0.6 # 增加创意
input_format: "{{text}}"
output_name: zen_version
# 第三步：润色语气和连贯性
- model: openrouter/openai/gpt-4o # 假设 GPT-4o 对话模型
prompt_name: improve_writing
input_format: |
根据以下大纲检查文章结构：
{{outline}}
文章内容：
{{zen_version}}
output_name: final_article
在这个流程中，我们先用 Claude 4.5 根据原笔记生成一个细致的大纲（确保不会遗漏重要点），然后用 GPT-5 将全文转换成 Zen 风格，最后用一个对话模型 GPT-4o进行全文润色、调整段落衔接。
结合 Context 使用： 如果你有固定的写作风格偏好，可以通过 Context 来微调。如创建 contexts/my_blog_style.md：
# 我的博客风格偏好
**语言特点：**
- 用第一人称与读者交流，语气亲切
- 技术术语尽量用通俗类比解释
- 每段不宜过长（最好 3～5 句话），方便阅读
**结构要求：**
- 开篇从具体场景或问题引入
- 正文多举例，少长篇理论
- 结尾总结要点并提出引人思考的问题
**禁忌：**
- 不要使用生僻艰深的词汇
- 避免居高临下的说教语气
- 不用 “显而易见”“众所周知” 之类的词
运行时指定这个上下文：
python3 app.py notes.md --workflow tech_blog --context my_blog_style
这样，AI 会套用你定义的风格来输出最终文章。例如采用亲和的口吻、控制段落长短等，非常实用。
案例四：构建知识库
场景： 你在学习新领域，将零散的材料（文章、访谈、视频脚本等）整合成自己的知识库，提炼概念并建立关联。
需求分析：
- 从多个来源提取各自的关键知识点。
- 将所有知识点汇总，归类整理。
- 建立概念之间的关联，生成知识网络（甚至图谱）。
解决方案： 可以分两步：逐篇提取 + 汇总成图。
先对每个资料使用 extract_wisdom 工作流提取要点：
python3 app.py article1.txt --workflow extract_wisdom -o knowledge/article1_wisdom.md
python3 app.py article2.txt --workflow extract_wisdom -o knowledge/article2_wisdom.md
python3 app.py video1_transcript.txt --workflow extract_wisdom -o knowledge/video1_wisdom.md
...
假设我们将提取结果都存在 knowledge/ 目录。然后合并所有结果：
cat knowledge/*_wisdom.md > all_wisdom.md
接下来设计一个工作流 create_mindmap，用某种图表语言输出概念图（比如 Mermaid 或 mindmap DSL）。配置可能类似：
strategies:
- model: openrouter/openai/gpt-5
prompt_name: create_mindmap
input_format: "<<text>>"
output_name: mindmap
对应模式 patterns/create_mindmap/system.md 需要引导模型把输入的海量要点整理为知识树或思维导图。你可以要求输出 Mermaid 代码。例如：
# IDENTITY and PURPOSE
你是一位知识库构建助手，擅长将零散知识点组织成思维导图。
# OUTPUT INSTRUCTIONS
使用 Mermaid Markdown 语言绘制知识网络，节点代表概念，连线表示关联。
...
运行：
python3 app.py all_wisdom.md --workflow create_mindmap -o knowledge_graph.md
这样 knowledge_graph.md 将包含 Mermaid 图表定义。用支持 Mermaid 的 Markdown 工具打开，就能看到一张由AI整理的知识地图！
案例五：多轮对话式写作
场景： 长篇写作通常要经历初稿、修改、润色多个阶段。我们可以利用会话管理，让 AI 参与这个过程。
过程：
- 第一轮让 AI 生成文章初稿：
python3 app.py outline.txt --workflow write_essay --session my_essay
- （假设你提供了文章提纲或主题在 outline.txt 中）
- 第二轮人工阅读初稿后，写下反馈意见 feedback.txt，然后：
python3 app.py feedback.txt --workflow improve_writing --session my_essay
- AI 将结合你给的反馈，对之前的草稿进行修改提升（由于用了 –session my_essay，AI 能获取初稿内容作为上下文）。
- 第三轮如果还有问题，可以继续给新反馈然后调用 improve_writing。这个过程中，“my_essay” 会话一直记录上下文，AI 理解每次改动的来龙去脉。
- 查看全过程：
python3 app.py --show-session my_essay
- 可以看到从提纲到初稿，再到每次修改建议的全部对话记录。
这种人机多轮协作的写作方式，充分发挥人类创意和 AI 语言润色的优势，非常高效。如果对结果满意，记得用 –delete-session my_essay 清理会话数据。
案例六：代码文档生成
场景： 你编写了一些源代码，想自动生成用户友好的说明文档（也就是“代码解读”）。
设计思路：
- 让 AI 分析代码含义，生成注释性解释。
- 将解释转换成 Zen 风格的文字说明，便于非程序员理解。
工作流设计：
strategies:
# 第一步：解释代码（逐函数/类分块）
- model: openrouter/anthropic/claude-sonnet-4.5
prompt_name: explain_code
input_format: "((text))2" # 按二级标题（比如函数级）分块
output_name: code_explanation
# 第二步：转换为友好表述
- model: openrouter/openai/gpt-5
prompt_name: convert_zen_style
input_format: "{{code_explanation}}"
output_name: friendly_docs
Pattern explain_code 可以编写成一个指导 AI 逐段输出代码作用的模板。
使用方法： 将代码文件转成 Markdown 格式（每个函数用 python 代码块括起来）。比如 code.md 内容：
# my_module.py
```python
def process_workflow(config, text):
"""Process text through a workflow"""
processor = TextProcessor(config)
return processor.process_text(text)
运行：
```bash
python app.py code.md --workflow generate_docs
输出 generate_docs-output.md 会是一份解释文档。例如：
函数 `process_workflow(config, text)` 接收工作流配置和文本，然后调用 `TextProcessor` 对文本执行配置中定义的工作流处理，返回结果。它相当于整个工作流处理的封装入口函数。
再经过 Zen 风格转换，可以进一步润色，让说明听起来更易懂、有亲和力。你可以视需要决定是否要那一步。
案例七：整合搜索功能
场景： 生成一份行业分析报告，需要最新数据和趋势。这就要求 AI 先搜索信息再撰写。
设计思路：
- 用搜索引擎获取最新资料。
- AI 阅读资料并产出分析报告。
OpenRouter 支持类似工具调用的机制，这里假定我们有一个工具模式 exa_search 可以调用 EXA API 搜索。
工作流设计：
strategies:
# 第一步：搜索最新信息
- tool_name: exa_search
tool_params:
category: "news" # 搜索新闻类信息
num_results: 10
input_format: "<<text>>" # 输入为搜索关键词全文
output_name: search_results
# 第二步：分析搜索结果
- model: openrouter/anthropic/claude-sonnet-4.5
prompt_name: analyze_trends
input_format: |
搜索主题：
{{text}}
搜索结果摘要：
{{search_results}}
output_name: analysis
在这个配置里，第一个 strategy 用了 tool_name: exa_search 而不是 model，表示调用 EXA 搜索工具，参数里 category: "news" 可能会限定搜索范围为新闻。如果 EXA 返回的 search_results 包含网页摘要，第二步 Claude 4.5 就可以根据这些最新信息，产出一份分析报告。
使用方法： 写一个包含查询的文件 query.txt：
2025 年 AI 大模型领域的最新进展
运行：
python app.py query.txt --workflow analyze_trends
AI 会先检索互联网上与“大模型 2025 最新进展”相关的新闻、报告，然后综合分析它们，输出一份富有洞见的趋势分析报告。
实用技巧汇总
通过以上 7 个案例，我们可以总结一些实用技巧：
-
选对分块策略：
- 学术论文这类结构清晰的内容，用 ((text)) 按章节处理，确保逐章消化。
- 代码文档按函数分块（如 ((text))2），避免把整个文件一次丢给模型。
- 短文或连续内容直接用 {{text}} 自动分段即可。
- 需要整体把握时，一定用 <
> 全文输入，哪怕分多轮处理。
-
合理安排步骤顺序：
- 有些任务的先后顺序会影响效果。比如先翻译再提炼通常优于直接对英文提炼（因为提示词多为中文语境优化的）。
- 先粗后细：先让 AI 产出初稿，再让另一个 AI 或步骤来细化/检查，比一步到位更稳妥。
- 需要外部信息时，先搜索后分析。
-
善用内置工作流：
- 系统自带的模式库非常丰富，尽量组合使用现有模式，而不是重复造轮子。
- 可以通过 –list-workflows 和阅读 config/、patterns/ 了解已经有哪些模板，或从 Fabric 项目借鉴模式。
-
会话管理用于迭代：
- 写作、方案优化等需要多轮往复的场景，开启 –session 功能保持上下文，大大提升质量和连贯性。
- 善于将自己的反馈总结给 AI，比起自己逐字修改效率更高。
-
批量处理用脚本：
- 当你面对成百上千个文件要处理时，不妨写一个简单脚本（Shell、Python 均可）批量调用 app.py。批处理时注意加入适当延时（OpenRouter 有速率限制，每秒 5 次左右为宜）。
- 也可以考虑并行调用，但要小心 API 限制以及不要拖垮本地 CPU/IO。
这些技巧可以帮助你在各种实战中更高效地运用工作流系统，打造属于你自己的 AI 流程“生产力工具”。
第七章 常见问题和故障排除
即使按教程操作，你可能仍会遇到一些问题。本章汇总了常见问题及解决方案，方便对照排查。
安装和配置问题
问题： pip install 失败，提示权限错误或无法安装依赖。
可能原因： 没有使用虚拟环境，或虚拟环境未激活，导致权限不够或依赖版本冲突。
解决方案：
- 确认虚拟环境已激活（命令行前是否有 (.venv)）。若没有，执行 source .venv/bin/activate（Windows 下执行 .venv\Scripts\activate）后重试。
- 如果仍有错误，尝试升级 pip 后再安装依赖：
python3 -m pip install --upgrade pip
pip3 install -r requirements.txt
问题： 配置了 OpenRouter API Key，但仍提示鉴权错误或找不到模型。
检查要点：
- .env 文件格式是否正确：每行形式应为 KEY=value，等号左右不能有引号或空格。例如：
OPENROUTER_API_KEY=sk-or-... # 正确
OPENROUTER_API_KEY = sk-or-... # 错误，等号两边多余空格
OPENROUTER_API_KEY="sk-or-..." # 错误，不要加引号
- 确认 .env 文件和 app.py 在同一目录，且运行时当前路径也是项目根目录（否则 .env 可能未被加载）。
- 测试密钥有效性：在终端执行（将 $OPENROUTER_API_KEY 换成实际值）：
curl https://openrouter.ai/api/v1/models \
-H "Authorization: Bearer $OPENROUTER_API_KEY"
- 看是否返回模型列表。如果无响应，可能是网络问题或密钥无效。
问题： Python 版本过低（如默认是 3.8），无法运行项目。
解决方案：
- 安装并使用 Python 3.11+。可以直接从官网安装 Python 3.11，或使用 pyenv 管理多个版本。
- 安装后，确保命令行使用的是新版本。例如在 Unix 系统下用 python3.11 -m venv .venv 创建虚拟环境。
运行时错误
问题： FileNotFoundError: Config file not found
原因： 指定的工作流配置文件不存在。可能是工作流名称拼写错误。
解决：
- 运行 python3 app.py –list-workflows 查看有效工作流名称，确认你调用时拼写正确。
- 如果是自定义工作流，确认 config/ 目录下 YAML 文件名称与调用名称一致（不含“.yaml”）。例如调用 –workflow my_flow 就需要有 config/my_flow.yaml。
问题： API 请求超时（Timeout）或无响应。
可能原因： 网络问题或 OpenRouter 服务暂时不可用，导致调用未成功返回。
解决方案：
- 检查本地网络连接，可以的话切换网络或使用稳定的代理。
- 如果只是偶发超时，可稍等几秒后重试。同一密钥短时间大量调用可能被限流，等一会儿或减慢调用频率。
- 查看 OpenRouter 状态页 看是否有服务中断报告。
- 实在频繁超时，可以在 config 中对模型设置较长的 timeout 参数，例如：
params:
timeout: 60 # 等待 60 秒
- 但这只是提高耐心等待时间，根本解决还得靠网络通畅或服务正常。
问题： 输出内容被截断，AI 没写完就结束了。
原因分析：
- 模型达到最大输出长度上限，导致后面内容被截断。
- OpenRouter 对每次调用有 token 上限，例如 GPT-5 Mini 可能默认只输出一定长度。
- 也可能提示词不当，让模型误以为需要简短输出。
解决方案：
- 在 prompt_name 对应的模式中，明确要求输出完整。例如增加提示：“一定要完整覆盖所有部分，不要忽略”。
- 将长文本拆分处理，避免每次输出过长。或者尝试换更高级的模型（比如支持1M上下文的模型）。
- 如果使用 OpenRouter auto 路由，有时可能挑了一个不支持超长输出的模型。可尝试指定特定模型或提高 max_tokens 设置（OpenRouter 一般自动处理，无需手动设置 tokens）。
问题： rate_limit 限制错误（429 Too Many Requests）。
原因： 调用频率过高或并发调用过多。
解决方案：
- 在配置文件的 params 中添加 rate_limit_in_sec 参数限制速率。例如：
params:
rate_limit_in_sec: 0.5 # 每 0.5 秒最多一次调用，相当于每秒不超过 2 次
- 这样系统在调用模型时会自动节流。
- 或者在批量脚本中加入 sleep，如每处理一个文件后 sleep 1。
- 如果需要并行大量调用，可考虑申请更高的 OpenRouter 配额或者划分多个 API Key 轮流使用（但免费额度可能有限制）。
输出质量问题
问题： 输出格式不符合预期。
分析： 模型没有遵循提示的格式要求。通常是提示中的格式指令不够清晰或缺示例。
解决办法：
- 检查 Pattern 模板中的 OUTPUT INSTRUCTIONS 部分，确保格式描述清楚并有示例。如果之前只写了“输出结构化结果”，建议改为提供样例结构。例如：
输出格式：
## 部分1
- 点1
- 点2
## 部分2
...
示例：
## 核心观点
- AI 擅长执行明确任务...
- 可以在提示词中明确使用占位符或标签。例如要求模型输出以 ## 开头的标题，而不是含糊地说“列出几个部分”。
问题： 输出内容不完整或遗漏信息。
可能原因：
- 文本分块处理导致模型每次只看到一部分，未能整合全局信息。
- Temperature 过高，模型输出比较随意，可能跳过一些点。
- 提示词未明确要求必须涵盖所有要点。
解决方案：
- 对于需要整体考虑的任务，改用 <
> 提供全文给模型。如果文本太长，可以先让模型总结每块，再汇总总结，如前述多轮方案。 - 降低 temperature 到 0.2 左右，让模型更严谨地逐条输出，不发散。
- 在提示中强调“不要遗漏任何…，逐条涵盖…”之类的措辞。
问题： 每次运行结果不一致，输出风格或内容变化大。
原因： Temperature 设置较高或者模型本身有一定随机性。
解决方案：
- 将 temperature 调低接近 0。温度 0 会让模型成为确定性输出（相同输入总产出相同结果）。如需要稳定复现某些流程，可将温度设为 0 或 0.1。
- 如果需要一点变化但不想差异太大，温度设 0.3 左右比较稳妥。
问题： 翻译/润色结果有明显的 AI 腔调，缺乏人味。
分析： AI 生成内容有时会用一些套路化表达。
应对：
- 使用专门的text_polish或naturalize_text之类工作流，去除 AI 痕迹。比如项目可能有 improve_writing 的子模式能消除常见 AI用语。
- 在提示中加入反模式要求。例如：
# REQUIREMENTS
- 避免使用陈词滥调，如“随着……的发展”“众所周知”
- 尽量用口语化、有人情味的表达
- 可以加入适当的小故事或比喻，使语言更自然
- 明确告诉 AI 不要那些常见套话，多给些“人味”指导。
- 多轮优化：第一轮先让 AI 大致改，第二轮让它“口语化处理”“检查语气自然度”等。
性能和成本优化
问题： 处理速度太慢，等待时间长。
原因： 可能使用了复杂模型或处理超长文本分块太多。
优化：
- 检查是否模型性能过低：Claude 4.5 比 GPT-5 快或慢？其实 GPT-5速度通常快些。简单任务不要动用大模型。
- 避免不必要的步骤：流程能一步完成就不要拆两步。例如有的地方可能评估步骤可省略或者合并到其他步骤中。
- 如果处理批量文件，可以考虑一定的并行。例如 Python 脚本用 multiprocessing 同时处理几个文件。但注意不要超过 API rate limit。
- OpenRouter 提供一些免费模型（DeepSeek等）可用，虽然慢但不花钱。权衡速度和成本。
问题： 费用超出预期。
排查： 查看 logs/runs/…/text_processor.log，里面每步调用后通常有 tokens 计数。找出哪个步骤用了最多 tokens。针对性优化：
- 用更便宜的模型替代。如果某步用 Claude 4.5 只是提取信息，其实 GPT-5 Mini 也许够用，能省很多钱。
- 减少上下文。提示里是否附加了过多无关内容？{{memory_xxx}} 引入的内容是否必要？
- 优化提示词，让模型少“自说自话”。比如控制不要输出过长解释，只给所需结果。
- 将任务拆分。如一口气让模型输出 20 条创意，不如每次 5 条、循环4次，再合并结果。这样单次消耗降低，可利用OpenRouter对输入token缓存的优惠（如 cached input 费用更低）。
问题： 长文本处理时内存占用过高或程序卡住。
原因： 读入了超大文件或一次性拼装了巨量上下文。
解决：
- 利用 ((text)) 分块处理，避免一次把非常长文本全塞给模型。
- 在 YAML 的 params 可以设置 chunk_size（每块最大 token 数）。比如：
params:
chunk_size: 2000
- 将每块控制在 2000 tokens 左右，内存占用会小一些。
- 若仍有问题，可以考虑逐段读写，即流式处理文本：自己写 Python 脚本读文本一段调用一次 API。LiteLLM 等库支持 streaming 调用，可进一步优化内存和延迟。
调试技巧
如何查看发送给模型的完整请求？
在 logs/runs/… 目录下找到对应步骤的 _input.md 文件，其中包含system和user消息的完整内容。你也可以在终端用命令查看最新日志，例如：
cd logs/runs/$(ls -t logs/runs | head -1)
cat step_01_*_input.md
如何验证变量替换正确？
检查 input.md 文件里是否还残留 {{text}} 这类字样。如果有，说明变量没有传进去（可能 YAML 缩进错误或占位符拼写错误）。应当看到的是实际文本内容被插入其中。
如何测试单个步骤效果？
可以临时写一个简化的 YAML 只包含一个步骤，把想测试的内容作为输入。或者直接使用 app.py –show-workflow workflow_name 查看提示，然后手动用交互模式试一下该提示词和模型的配合。例如你可以复制 system 提示到 OpenAI Playground 或 ChatGPT 上实验。
如何打开更详细的调试信息？
运行时加 –debug 开关。除了日志文件，在控制台也会打印额外信息，如调用的 HTTP 请求、响应头、以及每一 chunk 如何处理等。但要小心，debug 模式可能打印大量内容，影响性能。
进阶问题
问题：如何在工作流中使用自定义变量？
有时你希望一个步骤的输出中提取出一部分，供后续步骤单独使用。目前 YAML 配置不支持对 AI 输出再加工变量，但可以通过设计 Prompt 实现。例如：
strategies:
- model: openrouter/openai/gpt-5-mini
prompt_name: extract_keywords
input_format: "<<text>>"
output_name: keywords # 模型将输出关键词列表
- model: openrouter/openai/gpt-5-mini
prompt_name: expand_on_keywords
input_format: |
关键词列表：
{{keywords}}
针对上述每个关键词，详细阐述含义和背景：
{{text}}
output_name: expanded
这里我们通过 Prompt 把第一步输出 {{keywords}} 嵌入第二步提示中，引导模型按关键点对全文做扩展解释。虽然不能直接编程式提取变量，但通过 prompt 设计也能达到类似效果。
问题：如何处理多个输入文件作为一个任务？
目前 app.py 接受一个输入源。如果你需要同时给模型提供多份资料，有几种方法：
- 将多个文件内容合并到一个文件/变量中，然后在 Prompt 中区分。例如在 input_format 写：“资料1:\n{{text1}}\n资料2:\n{{text2}}”，配置里定义多个 input_path 之类。这需要自行修改 app.py 支持，但目前没直接参数。
- 使用命令行管道和 –clipboard 组合：手动将几个文件内容拼起来。或者用脚本读多个文件内容拼接成一个临时文件供 app.py 处理。
- 如果只是批量处理（每个文件独立输出），就参考前面的批处理脚本案例即可。
问题：如何在自己应用中集成这个功能？
如果你想在自己 Python 脚本或应用中调用这些工作流，可以直接使用项目提供的接口。例如：
from app import ConfigManager, TextProcessor
# 加载配置
config = ConfigManager.load_config("extract_wisdom")
# 准备输入文本
text = open("article.txt").read()
# 处理文本
processor = TextProcessor(config)
result = processor.process_text(text)
print(result["wisdom_extracted"])
process_text 返回的是包含所有输出变量的字典。这样你就可以把这个库当作一个模块使用。
问题：如何自定义分块逻辑？
在极端情况下你可能需要特殊的分块行为。默认实现在 context_manager.py 里的 split_by_markdown_level，你可以修改它。不过更简单的是利用参数：
- 在 YAML 的 params 下设置 chunk_size 和 chunk_overlap（重叠部分大小）。
- 或 split_by 参数指定自定义分隔符。
如果要实现非常特殊的分块规则（比如按句子又不破坏段落），可能需要改写 TextProcessor._split_text 方法，这是更高级的修改了。
资源和支持
官方文档和项目链接：
- Workflows with Zen 项目 GitHub – 获取最新代码、提 Issue 和查看文档。
- Fabric 项目 – 提示词 Pattern 设计的灵感来源，可以参考其中模式模板来扩充自己的库。
- OpenRouter 文档 – 了解 OpenRouter 支持的模型列表、参数设置、限制等官方说明。
- LiteLLM 文档 – 本项目底层使用的 LLM 调用库文档，了解其更高级用法（如组合 Prompt 等）。
社区支持：
如果遇到疑难问题，可以尝试：
- 在项目的 GitHub 仓库提交 Issue，描述清楚问题和复现步骤。
- 查看 Discussions 区，社区可能已经讨论过类似问题。
- 寻找相关主题的开发者交流群（Discord、Telegram 等）提问。
提问技巧：
提问时提供尽可能多的上下文，有助于他人帮你排查：
- 错误提示或异常的完整信息（贴日志关键部分）。
- 使用的命令和对应的配置文件内容。
- 如果可能，提供能重现问题的输入文本片段。
- 环境信息：操作系统、Python 版本、所用模型版本等。
条理清晰、信息完整的问题往往能更快获得解答。
小结
本章涵盖了大部分你在使用过程中可能遇到的问题，包括：
- 安装和配置方面的常见错误（环境、密钥等）
- 运行时可能出现的错误及解决方案（找不到配置、超时、限流等）
- 输出质量的问题及调优方法（格式、完整性、稳定性、风格）
- 性能和费用的优化建议（模型选择、分块、并行等）
- 调试工具与方法（日志、单步测试、debug 模式）
- 一些高级需求的实现思路（多输入、API 集成、自定义分块）
遇到问题时，先不要慌，按照以上思路逐项检查，相信绝大多数问题都能迎刃而解。
从一开始的问题和需求出发，我们一步步构建了这个智能工作流系统。现在，你已经学会：
- 搭建和配置运行环境
- 理解工作流的原理和设计理念
- 使用内置工作流处理各种文本任务
- 自定义和优化工作流满足特殊需求
- 排查和解决常见问题
更重要的是，你领会了工作流思维这一方法论。当面对复杂任务时，不再试图让 AI 一步做到位，而是先拆解步骤，再各个击破，最后串联成完整解决方案。事实证明，这种思路能让 AI 的价值最大化，让我们的效率提升一个数量级。
AI 的价值不在于替代人类思考，而在于高效执行人类设计好的流程。通过巧妙的工作流设计，我们可以让 AI 成为强大的助手，承担繁重却明确的步骤，把人从重复劳动中解放出来，专注于更具创造性的部分。
现在，这套系统已经完全掌握在你手中。希望你可以大胆探索，根据自己的场景创造新的工作流。无论是个人提升，还是团队协作，这种人机协同的模式都大有可为。愿这份教程能帮助你在 AI 工作流的探索之旅中收获满满。
如果你有任何问题或好的建议，欢迎随时在 GitHub 项目 上交流。
祝你玩转 AI 工作流，让你的文字处理效率飞跃！