OpenSpec自定义步骤实战：从数据清洗到复杂工作流构建

1. 从“能用”到“好用”：为什么我们需要自定义 OpenSpec 步骤

最近在折腾一个AI驱动的报告生成项目，用上了OpenSpec这个框架。一开始挺顺利，基础的提示词一写，模型就能吐出结构化的JSON数据，再套个Handlebars模板，一份格式工整的报告就出来了。但用着用着，问题就来了：生成的报告内容总是“差点意思”。要么是某些专业术语表述不够精准，要么是数据呈现的逻辑顺序不符合行业习惯，要么就是格式上总有些小瑕疵，每次生成后还得手动调整半天。

这让我意识到，直接使用OpenSpec的默认流程，就像用一把万能钥匙去开所有的锁——能打开，但未必顺畅。默认的“生成-模板渲染”两步走，对于简单任务足够，但面对复杂、有特定领域要求的任务时，就显得力不从心了。核心痛点在于，我们无法在AI生成“生数据”之后、最终输出“熟文档”之前，插入我们自己的“烹饪”工序。比如，我想在数据生成后，自动校验关键数据的合理性，或者根据某些字段的值，动态决定下一段内容的生成策略，又或者对生成的内容进行二次润色和格式化。这些，都是默认流程无法满足的。

于是，“自定义OpenSpec步骤”就成了解决问题的关键。这不仅仅是写几个函数那么简单，它意味着你能够深度介入AI工作流，在关键节点植入你的领域知识、业务规则和品控标准，把一次性的“生成”变成一个可控、可迭代、可优化的“生产流水线”。简单说，就是从让AI“帮你写”，变成教AI“按你的方式写好”。

2. 拆解OpenSpec核心流程：理解“步骤”的插入点

要自定义，先得理解OpenSpec默认在干什么。抛开复杂的封装，其核心流程可以简化为一个清晰的链条。理解这个链条，你才知道你的“自定义手术刀”应该下在何处。

2.1 默认流程的三段论

一个典型的OpenSpec任务执行，可以粗略分为三个阶段：

1. 提示工程与调用阶段：这是起点。你定义好的OpenSpec对象，里面包含了给大语言模型的系统提示词、用户提示词以及各种参数（如模型、温度等）。框架会将这些信息组装成符合API规范的请求，发送给后端的大语言模型服务（如OpenAI、Azure OpenAI等）。
2. AI生成与原始解析阶段：模型返回一段文本（通常是JSON格式的字符串）。OpenSpec的核心能力之一，就是通过预设的response_format（例如{“type”: “json_object”}）和json_schema，引导模型输出结构化的数据。框架会尝试将这个文本解析成一个JavaScript/TypeScript对象。
3. 模板渲染与输出阶段：解析得到的对象，会被传递给一个模板引擎（默认是Handlebars）。你预先编写好的.hbs模板文件，会接收这个对象作为上下文，经过渲染，最终生成你需要的最终文本输出，比如Markdown、HTML甚至是一段代码。

这个过程看似顺畅，但“魔鬼在细节中”。问题往往出在第二阶段和第三阶段的交接处。模型返回的JSON，可能字段名不对、数据类型不符、甚至包含了一些你不需要的冗余信息。而Handlebars模板虽然灵活，但它主要擅长的是“展示逻辑”（if/else, each循环），对于复杂的“业务逻辑”（如数据验证、转换、跨字段计算）就显得捉襟见肘。

2.2 关键扩展点：Action与Step

OpenSpec的设计哲学是通过Action（动作）来组织工作流。一个Action可以包含多个Step（步骤）。默认的“生成-渲染”流程，其实就是由两个内置的Step组成的。

自定义步骤的本质，就是创建你自己的Step类，并将其插入到Action的执行序列中。你可以在模型调用前插入步骤（例如，动态修改提示词），可以在模型调用后、模板渲染前插入步骤（这是我们最常用的场景，用于加工原始生成数据），也可以在模板渲染后插入步骤（例如，对最终文本进行后处理或发送通知）。

最常见的插入点，就是在模型生成之后，模板渲染之前。在这里，你可以拿到AI返回的、已经初步解析的原始数据对象，对其进行任何你需要的操作，然后再将处理后的、更“干净”、更“规整”的数据对象传递给模板。这相当于在原材料进入模具前，进行了一次精加工。

3. 实战：编写一个数据清洗与增强的自定义步骤

理论说再多不如一行代码。我们来看一个最实用的场景：AI生成了一份产品报告的数据，但我们需要确保数据质量，并补充一些衍生信息。

假设我们的OpenSpec定义期望生成如下JSON结构的数据：

{ "productName": "智能温控水杯", "targetUsers": ["户外运动爱好者", "办公室白领"], "keyFeatures": ["精准控温", "长效保温", "app互联"], "priceEstimate": 299 }

但实际中，AI可能会返回一些不太规范的数据，比如priceEstimate是字符串"约299元"，targetUsers可能是个用逗号分隔的字符串，或者keyFeatures里混入了一些不相关的描述。

我们的目标是创建一个步骤，在数据进入Handlebars模板前，对其进行清洗和增强。

3.1 创建自定义步骤类

首先，我们需要创建一个实现IStep接口的类。这里我用TypeScript来演示，思路同样适用于JavaScript。

// CustomDataProcessStep.ts import { IStep, StepContext, StepResult } from ‘openspec’; // 假设openspec导出这些类型 export class CustomDataProcessStep implements IStep { // 步骤的名称，用于日志和调试 name = ‘CustomDataProcessStep’; // 核心执行方法 async execute(context: StepContext): Promise<StepResult> { // 1. 从上下文中获取上一步（通常是模型生成步骤）的输出 // `context.previousStepOutput` 就是AI返回并解析后的数据对象 const rawData = context.previousStepOutput; // 2. 执行数据清洗逻辑 const processedData = this.cleanAndEnhanceData(rawData); // 3. 将处理后的数据存入上下文，供后续步骤（如模板渲染）使用 // 关键：必须返回一个StepResult对象，并将输出设置为处理后的数据 return { output: processedData, success: true, // 根据处理逻辑决定是否成功 }; } private cleanAndEnhanceData(rawData: any): any { // 深拷贝原始数据，避免污染 const result = { …rawData }; // 清洗1: 规范化价格字段 if (result.priceEstimate) { // 提取数字，如果失败则设为null或默认值 const priceMatch = String(result.priceEstimate).match(/(\d+(\.\d+)?)/); result.priceEstimate = priceMatch ? parseFloat(priceMatch[1]) : null; // 增强：根据价格添加一个分类标签 result.priceCategory = result.priceEstimate < 200 ? ‘经济型’ : result.priceEstimate < 500 ? ‘中端型’ : ‘高端型’; } // 清洗2: 确保targetUsers是数组 if (result.targetUsers && !Array.isArray(result.targetUsers)) { // 如果是字符串，按逗号、顿号等分割 if (typeof result.targetUsers === ‘string’) { result.targetUsers = result.targetUsers.split(/[,，、\s]+/).filter((u: string) => u.trim()); } else { result.targetUsers = []; } } // 清洗3: 过滤和修剪keyFeatures if (Array.isArray(result.keyFeatures)) { result.keyFeatures = result.keyFeatures .map((feat: string) => feat.trim()) // 去除首尾空格 .filter((feat: string) => feat.length > 0 && feat.length < 50); // 过滤空值和过长的描述 } // 增强：添加一个生成时间戳 result.processedAt = new Date().toISOString(); return result; } }

3.2 将自定义步骤集成到Action中

创建好步骤类后，我们需要在定义OpenSpec Action时使用它。

// 你的OpenSpec配置或执行文件 import { OpenSpec, HandlebarsTemplateEngine } from ‘openspec’; import { CustomDataProcessStep } from ‘./CustomDataProcessStep’; // 1. 定义你的OpenSpec const productReportSpec = new OpenSpec({ name: ‘ProductReportGenerator’, model: ‘gpt-4’, // 或你使用的其他模型 // … 其他模型参数（提示词等） }); // 2. 创建一个Action，并组装步骤 const generateReportAction = productReportSpec.createAction(‘generate’); // 方式一：完全自定义步骤序列（推荐，清晰可控） generateReportAction .addStep(new YourModelGenerationStep()) // 通常是内置的生成步骤 .addStep(new CustomDataProcessStep()) // 我们的自定义清洗步骤 .addStep(new HandlebarsTemplateEngine(‘./templates/product-report.hbs’)); // 内置的模板渲染步骤 // 方式二：使用辅助方法，并在中间插入自定义步骤 // 假设框架提供了 `withPrompt` 和 `withTemplate` 的链式调用 // generateReportAction // .withPrompt(yourPrompt) // .addStep(new CustomDataProcessStep()) // 在链式调用中间插入 // .withTemplate(‘./templates/product-report.hbs’); // 3. 执行Action const finalReport = await generateReportAction.execute({ /* 可能的输入参数 */ }); console.log(finalReport); // 输出的是经过清洗、增强后渲染的最终报告文本

通过这样的集成，数据流向就变成了：AI生成原始数据->CustomDataProcessStep清洗增强->Handlebars模板渲染。你的模板product-report.hbs接收到的数据对象，已经是规整后的processedData，包含了清洗后的字段和新增的priceCategory、processedAt等字段，模板逻辑可以写得更简洁、更健壮。

4. 更复杂的场景：多步骤协作与条件执行

单一的数据清洗步骤只是开始。自定义步骤的真正威力在于构建复杂的工作流。例如，一个完整的报告生成可能需要：

1. 步骤A（数据生成）：调用AI生成核心内容。
2. 步骤B（数据校验）：检查生成内容是否包含必填字段，数值是否在合理范围内。如果校验失败，可以抛出错误或触发一个修复步骤。
3. 步骤C（信息补全）：根据核心内容，调用另一个专门的AI步骤或外部API（如查询数据库）来补充详细信息（如竞品价格、市场趋势）。
4. 步骤D（内容润色）：对整合后的文本内容进行语法、风格上的优化。
5. 步骤E（模板渲染）：生成最终输出。

OpenSpec的StepContext对象提供了强大的上下文管理能力。每个步骤的output都会成为上下文的一部分，后续步骤可以通过context.previousStepOutput或context.getStepOutput(‘步骤名’)来获取特定步骤的结果。

4.1 实现一个带条件逻辑的步骤

下面是一个示例，展示如何根据上一步的结果决定是否执行，或执行不同的逻辑。

export class ConditionalEnhancementStep implements IStep { name = ‘ConditionalEnhancementStep’; async execute(context: StepContext): Promise<StepResult> { const data = context.previousStepOutput; // 场景：如果产品价格高于500，则调用一个“高端市场分析”的辅助AI步骤 if (data.priceEstimate > 500) { // 这里可以动态创建并执行一个子Action，或者调用外部服务 const marketAnalysis = await this.generateHighEndMarketAnalysis(data.productName); data.highEndAnalysis = marketAnalysis; data.reportComplexity = ‘高级’; } else { data.reportComplexity = ‘标准’; } // 场景：如果目标用户包含“老年人”，则必须检查是否有“操作简便”特性 if (data.targetUsers && data.targetUsers.some((user: string) => user.includes(‘老年’))) { const hasSimpleFeature = data.keyFeatures.some((feat: string) => feat.includes(‘简便’) || feat.includes(‘易用’) || feat.includes(‘大字体’) ); if (!hasSimpleFeature) { // 不是错误，而是自动添加一个建议特性 data.keyFeatures.push(‘操作界面简洁易懂（建议添加）’); data.autoAddedSuggestion = true; } } return { output: data, success: true }; } private async generateHighEndMarketAnalysis(productName: string): Promise<string> { // 这里可以内嵌一个简单的OpenSpec调用，或者调用另一个配置好的Action // 模拟一个异步调用 return `针对${productName}的高端市场分析：...`; } }

这个步骤展示了如何将业务规则（价格阈值、用户群体特征）转化为自动化的工作流逻辑，极大地提升了生成内容的针对性和质量。

4.2 错误处理与步骤回退

一个健壮的生产流程必须考虑异常。在自定义步骤中，良好的错误处理至关重要。

export class SafeDataValidationStep implements IStep { name = ‘SafeDataValidationStep’; async execute(context: StepContext): Promise<StepResult> { try { const data = context.previousStepOutput; // 关键数据校验 if (!data.productName || data.productName.trim().length === 0) { // 方式一：标记失败，停止后续步骤 // return { output: null, success: false, error: new Error(‘产品名称为空’) }; // 方式二（更友好）：尝试使用默认值修复，并记录警告 data.productName = ‘未命名产品’; context.logger.warn(‘产品名称为空，已使用默认值’); } if (data.priceEstimate && (data.priceEstimate < 0 || data.priceEstimate > 10000)) { // 价格异常，可以尝试触发一个“重新估算”的备用步骤 // 这里我们将其置为null，让模板引擎处理缺失值 data.priceEstimate = null; context.logger.error(`价格估计值${data.priceEstimate}超出合理范围，已置空`); } return { output: data, success: true }; } catch (error) { // 捕获步骤执行过程中的意外错误 context.logger.error(`步骤[${this.name}]执行失败:`, error); // 可以选择返回一个兜底数据，或者直接让整个Action失败 return { output: { error: ‘数据处理过程发生异常’, fallback: true }, success: false, // 取决于你的流程设计，有时标记为success: false但返回兜底数据也是策略 }; } } }

在Action层面，你可以通过监听事件或检查最终结果中的success标志来决定整体流程是成功、部分成功还是失败，并据此进行后续操作（如重试、通知人工审核等）。

5. 超越数据加工：自定义步骤的多样化应用

自定义步骤的用途远不止于处理JSON数据。它的本质是一个插件化的执行单元，几乎可以在工作流的任何位置做任何事情。

应用一：动态提示词工程在模型调用前插入步骤，根据运行时的输入参数或环境变量，动态修改系统提示词或用户提示词。例如，根据用户选择的报告语言（中/英），动态切换提示词模板；或者根据当前时间，在提示词中加入“生成季度总结报告”的指令。

export class DynamicPromptStep implements IStep { async execute(context: StepContext): Promise<StepResult> { const userInput = context.initialInput; // 获取Action执行时的初始输入 const season = this.getCurrentSeason(); // 一个业务函数 const enhancedPrompt = `你是一位资深产品经理。当前是${season}季度，请基于以下信息生成报告：${userInput}`; // 将动态生成的提示词放入上下文，供后续的模型生成步骤读取 context.set(‘enhancedPrompt’, enhancedPrompt); // 注意：这里不直接返回数据给下一步，而是修改上下文。具体实现取决于OpenSpec的API设计。 // 一种常见模式是返回一个包含`modifiedContext`的对象。 return { output: { prompt: enhancedPrompt }, success: true }; } }

应用二：多模型投票或融合在生成步骤后，可以插入一个步骤，将同一个问题发送给多个不同的模型（如GPT-4、Claude、本地模型），然后对返回的结果进行投票、评分或智能融合，选出最优解或生成综合答案，再将这个“共识”结果传递给模板。

应用三：外部系统集成在数据生成后，调用外部API获取实时数据来补充或验证AI生成的内容。比如，生成产品描述时，调用电商API获取实时价格和库存；生成代码后，调用一个代码格式化工具（如Prettier）进行标准化。

应用四：输出后处理在模板渲染完成后，插入一个步骤对最终文本进行处理。例如，自动将生成的Markdown报告上传到云存储（如S3、OSS）并返回链接；或者调用一个文本转语音服务，生成报告的音频版本；甚至进行敏感词过滤和内容安全审核。

6. 调试、测试与性能考量

当你开始编写复杂的自定义步骤时，调试和测试就变得非常重要。

调试技巧：

• 充分利用日志：在步骤的execute方法中，使用context.logger（如果提供）或console.log进行分级日志输出（debug, info, warn, error）。记录输入、关键处理节点和输出。
• 单元测试你的步骤：将每个自定义步骤类当作一个纯函数（尽管它可能是异步的）来测试。伪造一个StepContext对象，传入模拟的previousStepOutput，断言其execute方法的返回结果是否符合预期。这能极大保证核心逻辑的可靠性。
• 隔离测试Action：在开发环境中，创建一个使用Mock模型（直接返回固定数据）的Action，并串联你的自定义步骤，观察数据在每个步骤间的流转和变化。

性能考量：

• 避免阻塞操作：execute方法是异步的，但要确保其中没有长时间的同步阻塞操作。对于耗时的外部API调用或文件IO，务必使用异步方式。
• 缓存策略：如果某个步骤的计算成本很高，且输入相同的情况下输出总是相同（例如，根据产品ID查询静态信息），可以考虑引入简单的内存缓存（如LRU Cache）或分布式缓存。
• 步骤的粒度：不要在一个步骤里做太多事情。遵循单一职责原则，将大的处理流程拆分成多个小的、可复用的步骤。这样不仅易于测试和维护，也便于你在不同的Action中灵活组合它们。例如，将“数据清洗”、“业务校验”、“外部数据获取”拆分成三个独立的步骤。

自定义OpenSpec步骤，是将一个通用的AI调用框架，打磨成贴合你自身业务需求的精密工具的关键。它要求你不仅会写提示词，还要懂一点代码，更重要的是，需要你深入思考你希望AI如何参与到你的工作流中。从被动接受到主动编排，这一步的跨越，带来的生成结果改进将是质的变化。