1. 项目概述从“能用”到“好用”的质变最近在折腾 OpenSpec 的朋友估计都遇到过这样的场景你精心设计了一个提示词让它帮你生成一段代码或者一份文档结果它要么跑偏了要么生成的内容格式乱七八糟要么干脆就漏掉了你强调的关键信息。你不得不一遍遍地调整提示词或者手动去修改、拼接它的输出结果整个过程就像在跟一个不太灵光的助手反复沟通效率低下不说还特别心累。这正是我最初接触 OpenSpec 时的真实写照。OpenSpec 作为一个强大的 AI 驱动规范与代码生成工具其核心能力依赖于我们输入的“步骤”Steps。默认的步骤模板虽然通用但就像一件均码的衣服很难完全贴合我们每个具体项目的独特身材。这时“自定义 OpenSpec 步骤”就不再是一个可选项而是提升生成结果质量、让工具真正为你所用的必经之路。简单来说它关乎的是如何将你的专业意图精准、无损耗地传递给 AI从而获得稳定、可靠、符合预期的产出。这个项目的核心就是深入 OpenSpec 的步骤定义机制通过自定义步骤模板特别是利用像 Handlebars 这样的模板引擎来改造工作流。它解决的不仅仅是“生成内容”的问题更是“如何高效、可控地生成高质量内容”的问题。无论你是希望生成统一风格的 API 文档、确保代码符合团队规范还是想自动化一些复杂的、多步骤的生成任务自定义步骤都能为你提供一套可复用的“模具”。接下来我会结合我自己的踩坑经验从设计思路到实操细节完整地拆解如何通过自定义步骤来显著改进 OpenSpec 的生成结果。如果你已经受够了反复调整提示词的折腾或者想让团队的 AI 应用流程标准化那么这篇内容会非常适合你。2. 核心思路将模糊指令转化为结构化模板为什么默认步骤常常不尽如人意根源在于“模糊性”。一个简单的文本提示词对于人类来说可能包含了许多隐含的上下文和约定俗成的格式要求但 AI 模型需要更明确、更结构化的指引。自定义步骤的精髓就在于将这种模糊的、依赖临场发挥的指令转化为结构清晰、变量明确、逻辑固定的模板。2.1 从“规划方向”到“执行路径”网络热词中提到的“规划方向”是一个很好的起点但它只是一个高层目标。自定义步骤要做的是将这个方向分解为具体的、可执行的路径。例如你的规划方向是“生成一个用户注册模块的 RESTful API 接口代码”。一个粗糙的提示词可能是“写一个用户注册的 API用 Node.js 和 Express要验证邮箱和密码。” 这个提示词会有什么问题呢它没有规定响应格式是纯代码还是包含解释没有指定代码风格用 CommonJS 还是 ES Module没有明确验证规则的具体细节密码长度复杂度也没有说明是否需要数据库交互的示例。而一个自定义步骤模板则会将这些都固化下来。它会定义好输入变量如moduleName用户注册、frameworkExpress、languageJavaScript ES6。输出格式明确要求输出一个独立的.js文件内容包含 JSDoc 注释。内容结构模板会预先写好代码的骨架比如导入语句、路由定义、控制器函数占位符然后将变量填充进去。对于验证逻辑可以调用另一个预定义的“数据验证规则”子模板。风格约束在模板中直接写明使用const而非var、使用箭头函数、错误处理中间件标准格式等。这样每次你需要生成类似模块时只需提供moduleName等几个关键参数就能得到风格统一、结构完整、质量稳定的代码省去了大量重复描述和事后修正的工作。2.2 Handlebars动态模板的引擎“Handlebars”作为相关热搜词出现绝非偶然。在自定义 OpenSpec 步骤中Handlebars 这类模板引擎扮演着核心角色。它允许你在步骤模板中插入动态变量如{{projectName}}、使用条件判断{{#if isProduction}}和循环{{#each endpoints}}从而将一个静态的文本模板变成一个能根据输入数据动态渲染的“智能模板”。OpenSpec 的步骤本质上是一段带有特定元数据如步骤类型、描述、输入输出定义的文本。当你使用 Handlebars 语法时OpenSpec 会在执行步骤前先用你提供的上下文数据来自前序步骤的输出或手动输入去渲染这个模板生成最终发送给 AI 模型的提示词。这意味着你的提示词不再是写死的而是数据驱动的。例如一个用于生成 API 端点描述的模板请为以下 RESTful API 端点生成详细的 OpenAPI 3.0 规格描述 - 项目名称{{projectName}} - 端点路径{{endpoint.path}} - HTTP 方法{{endpoint.method}} - 简要功能{{endpoint.description}} 请严格按照以下结构输出 1. **summary**: 一句话总结。 2. **parameters**: {{#each endpoint.parameters}} - name: {{this.name}} in: {{this.in}} required: {{this.required}} schema: {{this.schema}} {{/each}} 3. **requestBody** (如果适用): ... 4. **responses**: ...当endpoint.parameters是一个数组时Handlebars 的{{#each}}块会自动循环生成所有参数的描述行。这使得模板能够灵活适应不同数量、不同结构的输入数据极大地提升了步骤的复用能力和适应性。注意Handlebars 语法相对简单但要注意避免在模板中编写过于复杂的逻辑。模板的主要职责是“数据展示与简单条件分支”复杂的业务逻辑应该尽量在生成输入数据的前置步骤中处理以保持模板的清晰和可维护性。3. 自定义步骤的实战设计与创建理解了核心思路后我们进入实战环节。创建一个有效的自定义步骤远不止是写一个带变量的文本。它需要系统的设计包括清晰的输入输出定义、严谨的模板编写和充分的测试。3.1 步骤设计四要素在动手写代码或配置之前先明确你的步骤设计。我总结为四个要素目标与范围这个步骤具体要完成什么任务边界在哪里例如是“生成单个函数的代码”还是“生成包含路由、控制器、模型的完整模块”范围越小步骤越专注复用性越高但也可能导致流程步骤增多。需要权衡。输入契约步骤需要哪些信息才能工作这些信息就是输入变量。为每个变量定义清晰的名称、类型和描述。例如interfaceName: string接口名称、fields: Array{name: string, type: string}字段列表。清晰的输入契约是团队协作和流程串联的基础。输出规范步骤会产出什么是纯文本、JSON、YAML 还是代码块输出应该具有怎样的结构明确输出规范有助于后续步骤直接消费其结果。例如输出可以约定为{ “code”: “生成的代码字符串” “summary”: “功能摘要” }这样的 JSON 对象。模板与提示工程这是核心。模板不仅要包含 Handlebars 变量更要融入“提示工程”的技巧。比如角色设定在模板开头明确 AI 的角色如“你是一位经验丰富的 Node.js 后端架构师”。任务分解将复杂任务在模板中分解成几个有序的小指令。示例引导在模板中提供一两个输入输出示例Few-Shot Learning能极大提升 AI 对格式和内容质量的理解。格式约束使用明确的标记如“用 javascript 代码块包裹输出”来强制输出格式。3.2 创建自定义步骤的实操流程OpenSpec 中创建自定义步骤的具体方式可能因版本和部署方式而异本地安装、云服务等但核心逻辑相通。以下是一个通用的、基于配置文件的创建流程假设我们创建一个用于生成 TypeScript 接口的步骤。第一步定义步骤元数据通常在一个配置文件如steps.yaml或custom_steps.json中定义。- name: generate_typescript_interface description: 根据提供的字段列表生成 TypeScript 接口定义。 category: Code Generation inputs: - name: interfaceName type: string description: 要生成的接口名称使用 PascalCase。 required: true - name: fields type: array description: 接口字段列表每个字段包含 name 和 type。 required: true items: type: object properties: name: type: string description: 字段名使用 camelCase。 type: type: string description: TypeScript 类型如 string, number, boolean, User[]。 output: type: string description: 生成的 TypeScript 接口代码字符串。第二步编写 Handlebars 模板将模板内容保存在一个单独的文件中如generate_ts_interface.hbs。模板内容融合了提示词和结构。你是一位专业的 TypeScript 开发专家。你的任务是根据用户提供的字段信息生成严格符合 TypeScript 语法和通用最佳实践的接口定义。 # 输入信息 - 接口名称{{interfaceName}} - 字段列表 {{#each fields}} - 字段名{{this.name}} 类型{{this.type}} {{/each}} # 要求 1. 生成的接口必须使用 export interface 导出。 2. 每个字段必须显式定义其类型不使用 any。 3. 如果字段是可选的请在字段名后添加 ?。 4. 为接口添加清晰的 JSDoc 注释简要说明接口用途。 5. 输出 **仅包含** 最终的 TypeScript 接口代码不要有任何额外的解释、描述或前言。 # 示例 输入{ interfaceName: UserProfile, fields: [ {name: id, type: number}, {name: email, type: string} ] } 输出 /** * 用户个人资料信息 */ export interface UserProfile { id: number; email: string; } 现在请根据上面的输入信息生成接口代码。第三步集成与测试将步骤元数据和模板文件配置到 OpenSpec 中。具体方法需参考官方文档如修改插件配置、在管理界面添加等。集成后最关键的一步是测试。单元测试使用不同的输入组合调用该步骤检查输出是否严格符合模板要求格式、内容、是否包含多余文本。集成测试将该步骤放入一个实际的工作流中看它是否能与其他步骤如“生成实体类”、“生成 API 文档”顺畅衔接。边界测试测试空字段列表、包含特殊字符的接口名、嵌套类型如ArrayCustomType等边界情况确保模板的健壮性。实操心得模板中的“示例”部分威力巨大。它相当于给 AI 提供了一个“标准答案”范式能非常有效地对齐输出格式和质量。在编写复杂步骤时我通常会花最多的时间来构思这个示例确保它覆盖了各种典型情况和格式要求。4. 高级技巧组合步骤与条件逻辑当单个步骤无法满足复杂需求时我们就需要将多个步骤组合起来形成一条“流水线”。同时利用 Handlebars 的条件逻辑可以让单个步骤变得更智能。4.1 构建步骤工作流一个常见的场景是生成一个完整的 CRUD 模块。这可以分解为步骤A生成数据模型接口使用上面的generate_typescript_interface。步骤B生成 Service 类骨架输入模型接口名输出包含基础 CRUD 方法签名的类。步骤C生成 Controller 路由处理器输入Service 类名和模型接口输出 Express/Koa 路由处理函数。步骤D生成 API 文档片段输入Controller 信息输出 OpenAPI 描述。在 OpenSpec 中你可以通过图形化的工作流编辑器或配置文件将这些步骤按顺序连接起来。前一个步骤的输出可以作为后一个步骤的输入上下文。例如步骤A生成的接口代码字符串可以被步骤B的模板通过{{previousStep.output}}或一个解析后的变量如{{modelInterfaceName}}所引用。关键点在设计工作流时要定义好步骤间传递的数据结构。最好约定使用 JSON 等结构化数据作为输出方便后续步骤解析和引用特定字段而不是传递一大段需要手动解析的文本。4.2 在模板中使用条件逻辑Handlebars 提供了{{#if}}、{{#unless}}、{{#with}}等助手可以让模板根据输入数据动态改变内容。这在创建适配不同场景的通用步骤时非常有用。例如一个生成函数注释的模板可以根据函数是否有参数来调整注释格式/** * {{functionDescription}} {{#if parameters}} * param { {{#each parameters}}{{this.type}}{{#unless last}} | {{/unless}}{{/each}} } {{#each parameters}}{{this.name}}{{#unless last}}, {{/unless}}{{/each}} - 参数说明。 {{/if}} * returns { {{returnType}} } 返回值说明。 */ function {{functionName}}({{#each parameters}}{{this.name}}{{#unless last}}, {{/unless}}{{/each}}) { // 函数体将由 AI 填充 }在这个模板中{{#if parameters}}块只有在parameters数组存在且不为空时才会渲染param注释行。{{#unless last}}则用于在循环中判断是否为最后一个元素从而决定是否添加分隔符如“|”或“,”。这种条件渲染使得同一个模板既能处理无参数的工具函数也能处理多参数的复杂方法通用性大大增强。避坑指南过度使用复杂的 Handlebars 逻辑会让模板难以阅读和维护。如果发现模板中嵌套了多层{{#if}}和{{#each}}就应该考虑是否可以将这个步骤拆分成多个更简单的步骤或者将部分逻辑移到生成输入数据的前置脚本中。模板的首要目标是清晰和可预测。5. 效果评估与迭代优化创建了自定义步骤并投入使用了但这并不是终点。我们需要一套方法来评估其效果并持续迭代优化。5.1 建立评估标准不能凭感觉说“好像变好了”。需要定义可衡量的标准格式合规率生成的内容100%符合模板中指定的格式要求如代码块、JSON结构的比例。内容完整性是否包含了所有要求的信息点有没有遗漏关键字段或部分逻辑正确性对于代码生成生成的逻辑是否基本正确对于文档生成描述是否准确无歧义人工修改量为了达到可直接使用的标准平均需要人工修改或调整多少内容生成稳定性用同一组输入多次运行输出结果是否高度一致你可以抽样一批生成结果对照这些标准进行手动打分或者编写简单的校验脚本进行自动化检查如检查输出是否包含特定关键字、是否符合某种语法。5.2 常见的优化方向根据评估结果可以从以下几个方向对步骤进行优化提示词精炼这是最常见的优化点。如果 AI 理解有偏差就在模板中把指令写得更精确、更无歧义。使用更明确的动词如“列出”、“生成”、“对比”避免模糊词汇。提供更优质的示例如果输出格式不稳定在模板中提供更典型、更全面的输入输出示例。示例就是 AI 学习的“样板间”。调整输入数据结构如果发现某些信息总是需要从一大段文本中“抠”出来作为输入很痛苦。考虑优化前置步骤使其输出结构化的数据或者修改当前步骤的输入契约使其更易于填写。步骤拆分与合并如果一个步骤过于复杂导致效果不佳就拆分成多个专注的步骤。如果几个步骤总是连续执行且耦合紧密可以考虑合并成一个更大的步骤减少上下文传递的损耗。引入验证步骤在工作流中增加一个“验证”或“审查”步骤。这个步骤可以是一个简单的规则检查如代码风格检查也可以调用另一个 AI 步骤对前一步的输出进行质量评估并提出修改建议形成一个自我改进的循环。5.3 迭代流程从数据中学习将自定义步骤的优化视为一个数据驱动的迭代过程收集在实际使用中收集“失败案例”或“不满意案例”的输入和输出对。分析分析这些案例找出是模板指令不清、示例覆盖不足还是输入数据本身有问题。假设基于分析提出对模板或工作流的修改假设如“增加一个关于错误处理的明确要求”。实验创建一个步骤的新版本如generate_typescript_interface_v2应用修改。测试用收集到的失败案例和新的测试用例对比新旧版本的效果。部署如果新版本效果显著提升则替换旧版本。这个过程可以手动进行也可以随着使用量的增加逐渐形成一套半自动化的评估和优化机制。6. 实战案例构建一个“数据库模型生成器”工作流让我们通过一个综合案例将前面所有知识串联起来。目标是构建一个工作流输入简单的数据表描述字段名、类型自动生成 TypeScript 实体接口、Prisma Schema 以及基础的 RESTful API 控制器代码。工作流设计步骤1解析原始描述可选如果输入是自然语言可用一个 AI 步骤将其解析为结构化 JSON。步骤2生成 TypeScript 实体接口复用我们之前创建的generate_typescript_interface但增强一下为每个字段生成更详细的 JSDoc并处理关系字段如posts: Post[]。步骤3生成 Prisma Schema新建一个步骤输入是结构化的字段列表输出是model User { ... }格式的 Prisma 数据模型。步骤4生成 REST 控制器骨架新建一个步骤输入实体接口名和字段输出 Express 控制器文件包含基本的 CRUD 方法框架。步骤3生成Prisma Schema的模板示例你是一位精通 Prisma ORM 的开发者。请根据以下信息生成一个 Prisma 数据模型定义。 # 实体信息 - 模型名称{{modelName}} - 字段列表 {{#each fields}} - 字段名{{this.name}} 类型{{this.prismaType}} 是否必填{{this.required}} 是否唯一{{this.unique}} 默认值{{this.defaultValue}} {{/each}} {{#if relations}} - 关系定义 {{#each relations}} - 关系类型{{this.type}} 关联模型{{this.targetModel}} 字段{{this.field}}可选 {{/each}} {{/if}} # 要求 1. 严格使用 Prisma Schema 语法。 2. 根据 prismaType 映射到正确的 Prisma 标量类型如 string, Int, Boolean, DateTime。 3. 根据 required, unique, defaultValue 添加对应的属性id, unique, default。 4. 根据 relations 信息正确添加 relation 字段。 5. 为模型添加 map 或字段添加 map 以指定数据库中的实际表名/列名如果提供了 dbName。 6. 输出 **仅包含** 从 model {{modelName}} { 到 } 的完整模型定义代码块。 开始生成步骤间的数据流转步骤2的输出TypeScript接口可能包含一些类型信息如Post[]这可以被步骤3的模板用来推断或生成关系定义。在实际配置中我们需要一个“数据准备”步骤将用户的原始输入转换成同时包含fields用于步骤2和prismaFields、relations用于步骤3的完整上下文对象然后分别传递给步骤2和步骤3。这体现了工作流设计中对数据结构的精心规划。通过这个案例你可以看到自定义步骤和模板如何像乐高积木一样通过清晰的定义和接口输入输出组合成一个强大的自动化生成流水线。从最初简单的接口生成到如今能产出可直接用于项目起点的、相互关联的多种产物生产力的提升是显而易见的。7. 常见问题与排查技巧实录在实际操作中你肯定会遇到各种问题。以下是我总结的一些典型问题及其解决方法希望能帮你少走弯路。问题1AI 完全忽略了模板中的格式要求输出了一堆解释性文字。排查首先检查模板中格式指令是否足够强硬和明确。像“请只输出代码”、“输出必须包含在 json 代码块中”这样的指令需要放在提示词的显著位置如开头或结尾并且可以重复强调。解决在模板中使用“强制分隔符”。例如在最后加上“你的输出必须且只能从下一行开始typescript”。同时在示例中严格展示这种格式。如果问题依旧可能是 AI 模型本身的问题尝试在步骤配置中调整“温度”Temperature参数将其调低如 0.2以减少随机性让输出更确定性。问题2Handlebars 变量没有被正确替换模板中留下了{{xxx}}原始标签。排查确认提供给步骤的上下文数据中确实包含了模板所引用的变量名大小写敏感。检查数据路径是否正确特别是在工作流中前序步骤的输出可能需要通过类似{{steps.step_id.output.fieldName}}的方式来引用。解决在 OpenSpec 的步骤调试或日志中查看步骤执行前渲染的“最终提示词”。确认{{xxx}}是否已被替换为实际值。如果没有检查数据绑定配置。一个技巧是在模板中暂时添加一个调试部分调试信息输入数据是 {{json contextData}}但记得在正式使用前移除。问题3生成的代码或文档存在细微但恼人的风格不一致。排查这通常是因为模板中的约束不够细致。例如只说了“使用 const”但没有规定缩进是 2 空格还是 4 空格行尾是否加分号。解决在模板的“要求”部分将代码风格规则具体化。甚至可以引用一个知名的风格指南如“遵循 Airbnb JavaScript Style Guide”。更好的做法是将风格检查作为一个独立的后续步骤例如调用 Prettier 或 ESLint 的格式化功能而不是完全依赖 AI 来保证。问题4步骤在工作流中运行很慢影响了整体效率。排查可能是单个步骤的提示词过长或过于复杂导致 AI 模型处理时间增加。也可能是工作流中串行步骤太多。解决优化模板移除冗余的说明和示例保持简洁。如果步骤之间没有严格的依赖关系考虑在 OpenSpec 支持的情况下将一些步骤改为并行执行。对于非常耗时的生成任务可以评估是否值得或者将其拆分为更小的、可缓存结果的步骤。问题5自定义步骤在团队中难以共享和统一管理。排查每个人都在本地修改自己的步骤文件导致版本混乱。解决将步骤定义YAML/JSON和模板文件.hbs纳入版本控制系统如 Git。建立一个共享的步骤仓库。使用 OpenSpec 的“步骤库”或“插件”功能如果支持进行集中管理和分发。为步骤编写清晰的文档说明其输入、输出和用途。自定义 OpenSpec 步骤是一个持续打磨的过程。它没有一劳永逸的“最佳模板”只有最适合你当前团队和项目需求的“当前最优解”。保持迭代的心态从每次不理想的输出中分析原因持续优化你的模板和工作流你会发现AI 生成的代码和文档正变得越来越像一位真正理解你需求的资深搭档所交付的作品。
OpenSpec自定义步骤实战：用Handlebars模板引擎提升AI生成质量与效率
1. 项目概述从“能用”到“好用”的质变最近在折腾 OpenSpec 的朋友估计都遇到过这样的场景你精心设计了一个提示词让它帮你生成一段代码或者一份文档结果它要么跑偏了要么生成的内容格式乱七八糟要么干脆就漏掉了你强调的关键信息。你不得不一遍遍地调整提示词或者手动去修改、拼接它的输出结果整个过程就像在跟一个不太灵光的助手反复沟通效率低下不说还特别心累。这正是我最初接触 OpenSpec 时的真实写照。OpenSpec 作为一个强大的 AI 驱动规范与代码生成工具其核心能力依赖于我们输入的“步骤”Steps。默认的步骤模板虽然通用但就像一件均码的衣服很难完全贴合我们每个具体项目的独特身材。这时“自定义 OpenSpec 步骤”就不再是一个可选项而是提升生成结果质量、让工具真正为你所用的必经之路。简单来说它关乎的是如何将你的专业意图精准、无损耗地传递给 AI从而获得稳定、可靠、符合预期的产出。这个项目的核心就是深入 OpenSpec 的步骤定义机制通过自定义步骤模板特别是利用像 Handlebars 这样的模板引擎来改造工作流。它解决的不仅仅是“生成内容”的问题更是“如何高效、可控地生成高质量内容”的问题。无论你是希望生成统一风格的 API 文档、确保代码符合团队规范还是想自动化一些复杂的、多步骤的生成任务自定义步骤都能为你提供一套可复用的“模具”。接下来我会结合我自己的踩坑经验从设计思路到实操细节完整地拆解如何通过自定义步骤来显著改进 OpenSpec 的生成结果。如果你已经受够了反复调整提示词的折腾或者想让团队的 AI 应用流程标准化那么这篇内容会非常适合你。2. 核心思路将模糊指令转化为结构化模板为什么默认步骤常常不尽如人意根源在于“模糊性”。一个简单的文本提示词对于人类来说可能包含了许多隐含的上下文和约定俗成的格式要求但 AI 模型需要更明确、更结构化的指引。自定义步骤的精髓就在于将这种模糊的、依赖临场发挥的指令转化为结构清晰、变量明确、逻辑固定的模板。2.1 从“规划方向”到“执行路径”网络热词中提到的“规划方向”是一个很好的起点但它只是一个高层目标。自定义步骤要做的是将这个方向分解为具体的、可执行的路径。例如你的规划方向是“生成一个用户注册模块的 RESTful API 接口代码”。一个粗糙的提示词可能是“写一个用户注册的 API用 Node.js 和 Express要验证邮箱和密码。” 这个提示词会有什么问题呢它没有规定响应格式是纯代码还是包含解释没有指定代码风格用 CommonJS 还是 ES Module没有明确验证规则的具体细节密码长度复杂度也没有说明是否需要数据库交互的示例。而一个自定义步骤模板则会将这些都固化下来。它会定义好输入变量如moduleName用户注册、frameworkExpress、languageJavaScript ES6。输出格式明确要求输出一个独立的.js文件内容包含 JSDoc 注释。内容结构模板会预先写好代码的骨架比如导入语句、路由定义、控制器函数占位符然后将变量填充进去。对于验证逻辑可以调用另一个预定义的“数据验证规则”子模板。风格约束在模板中直接写明使用const而非var、使用箭头函数、错误处理中间件标准格式等。这样每次你需要生成类似模块时只需提供moduleName等几个关键参数就能得到风格统一、结构完整、质量稳定的代码省去了大量重复描述和事后修正的工作。2.2 Handlebars动态模板的引擎“Handlebars”作为相关热搜词出现绝非偶然。在自定义 OpenSpec 步骤中Handlebars 这类模板引擎扮演着核心角色。它允许你在步骤模板中插入动态变量如{{projectName}}、使用条件判断{{#if isProduction}}和循环{{#each endpoints}}从而将一个静态的文本模板变成一个能根据输入数据动态渲染的“智能模板”。OpenSpec 的步骤本质上是一段带有特定元数据如步骤类型、描述、输入输出定义的文本。当你使用 Handlebars 语法时OpenSpec 会在执行步骤前先用你提供的上下文数据来自前序步骤的输出或手动输入去渲染这个模板生成最终发送给 AI 模型的提示词。这意味着你的提示词不再是写死的而是数据驱动的。例如一个用于生成 API 端点描述的模板请为以下 RESTful API 端点生成详细的 OpenAPI 3.0 规格描述 - 项目名称{{projectName}} - 端点路径{{endpoint.path}} - HTTP 方法{{endpoint.method}} - 简要功能{{endpoint.description}} 请严格按照以下结构输出 1. **summary**: 一句话总结。 2. **parameters**: {{#each endpoint.parameters}} - name: {{this.name}} in: {{this.in}} required: {{this.required}} schema: {{this.schema}} {{/each}} 3. **requestBody** (如果适用): ... 4. **responses**: ...当endpoint.parameters是一个数组时Handlebars 的{{#each}}块会自动循环生成所有参数的描述行。这使得模板能够灵活适应不同数量、不同结构的输入数据极大地提升了步骤的复用能力和适应性。注意Handlebars 语法相对简单但要注意避免在模板中编写过于复杂的逻辑。模板的主要职责是“数据展示与简单条件分支”复杂的业务逻辑应该尽量在生成输入数据的前置步骤中处理以保持模板的清晰和可维护性。3. 自定义步骤的实战设计与创建理解了核心思路后我们进入实战环节。创建一个有效的自定义步骤远不止是写一个带变量的文本。它需要系统的设计包括清晰的输入输出定义、严谨的模板编写和充分的测试。3.1 步骤设计四要素在动手写代码或配置之前先明确你的步骤设计。我总结为四个要素目标与范围这个步骤具体要完成什么任务边界在哪里例如是“生成单个函数的代码”还是“生成包含路由、控制器、模型的完整模块”范围越小步骤越专注复用性越高但也可能导致流程步骤增多。需要权衡。输入契约步骤需要哪些信息才能工作这些信息就是输入变量。为每个变量定义清晰的名称、类型和描述。例如interfaceName: string接口名称、fields: Array{name: string, type: string}字段列表。清晰的输入契约是团队协作和流程串联的基础。输出规范步骤会产出什么是纯文本、JSON、YAML 还是代码块输出应该具有怎样的结构明确输出规范有助于后续步骤直接消费其结果。例如输出可以约定为{ “code”: “生成的代码字符串” “summary”: “功能摘要” }这样的 JSON 对象。模板与提示工程这是核心。模板不仅要包含 Handlebars 变量更要融入“提示工程”的技巧。比如角色设定在模板开头明确 AI 的角色如“你是一位经验丰富的 Node.js 后端架构师”。任务分解将复杂任务在模板中分解成几个有序的小指令。示例引导在模板中提供一两个输入输出示例Few-Shot Learning能极大提升 AI 对格式和内容质量的理解。格式约束使用明确的标记如“用 javascript 代码块包裹输出”来强制输出格式。3.2 创建自定义步骤的实操流程OpenSpec 中创建自定义步骤的具体方式可能因版本和部署方式而异本地安装、云服务等但核心逻辑相通。以下是一个通用的、基于配置文件的创建流程假设我们创建一个用于生成 TypeScript 接口的步骤。第一步定义步骤元数据通常在一个配置文件如steps.yaml或custom_steps.json中定义。- name: generate_typescript_interface description: 根据提供的字段列表生成 TypeScript 接口定义。 category: Code Generation inputs: - name: interfaceName type: string description: 要生成的接口名称使用 PascalCase。 required: true - name: fields type: array description: 接口字段列表每个字段包含 name 和 type。 required: true items: type: object properties: name: type: string description: 字段名使用 camelCase。 type: type: string description: TypeScript 类型如 string, number, boolean, User[]。 output: type: string description: 生成的 TypeScript 接口代码字符串。第二步编写 Handlebars 模板将模板内容保存在一个单独的文件中如generate_ts_interface.hbs。模板内容融合了提示词和结构。你是一位专业的 TypeScript 开发专家。你的任务是根据用户提供的字段信息生成严格符合 TypeScript 语法和通用最佳实践的接口定义。 # 输入信息 - 接口名称{{interfaceName}} - 字段列表 {{#each fields}} - 字段名{{this.name}} 类型{{this.type}} {{/each}} # 要求 1. 生成的接口必须使用 export interface 导出。 2. 每个字段必须显式定义其类型不使用 any。 3. 如果字段是可选的请在字段名后添加 ?。 4. 为接口添加清晰的 JSDoc 注释简要说明接口用途。 5. 输出 **仅包含** 最终的 TypeScript 接口代码不要有任何额外的解释、描述或前言。 # 示例 输入{ interfaceName: UserProfile, fields: [ {name: id, type: number}, {name: email, type: string} ] } 输出 /** * 用户个人资料信息 */ export interface UserProfile { id: number; email: string; } 现在请根据上面的输入信息生成接口代码。第三步集成与测试将步骤元数据和模板文件配置到 OpenSpec 中。具体方法需参考官方文档如修改插件配置、在管理界面添加等。集成后最关键的一步是测试。单元测试使用不同的输入组合调用该步骤检查输出是否严格符合模板要求格式、内容、是否包含多余文本。集成测试将该步骤放入一个实际的工作流中看它是否能与其他步骤如“生成实体类”、“生成 API 文档”顺畅衔接。边界测试测试空字段列表、包含特殊字符的接口名、嵌套类型如ArrayCustomType等边界情况确保模板的健壮性。实操心得模板中的“示例”部分威力巨大。它相当于给 AI 提供了一个“标准答案”范式能非常有效地对齐输出格式和质量。在编写复杂步骤时我通常会花最多的时间来构思这个示例确保它覆盖了各种典型情况和格式要求。4. 高级技巧组合步骤与条件逻辑当单个步骤无法满足复杂需求时我们就需要将多个步骤组合起来形成一条“流水线”。同时利用 Handlebars 的条件逻辑可以让单个步骤变得更智能。4.1 构建步骤工作流一个常见的场景是生成一个完整的 CRUD 模块。这可以分解为步骤A生成数据模型接口使用上面的generate_typescript_interface。步骤B生成 Service 类骨架输入模型接口名输出包含基础 CRUD 方法签名的类。步骤C生成 Controller 路由处理器输入Service 类名和模型接口输出 Express/Koa 路由处理函数。步骤D生成 API 文档片段输入Controller 信息输出 OpenAPI 描述。在 OpenSpec 中你可以通过图形化的工作流编辑器或配置文件将这些步骤按顺序连接起来。前一个步骤的输出可以作为后一个步骤的输入上下文。例如步骤A生成的接口代码字符串可以被步骤B的模板通过{{previousStep.output}}或一个解析后的变量如{{modelInterfaceName}}所引用。关键点在设计工作流时要定义好步骤间传递的数据结构。最好约定使用 JSON 等结构化数据作为输出方便后续步骤解析和引用特定字段而不是传递一大段需要手动解析的文本。4.2 在模板中使用条件逻辑Handlebars 提供了{{#if}}、{{#unless}}、{{#with}}等助手可以让模板根据输入数据动态改变内容。这在创建适配不同场景的通用步骤时非常有用。例如一个生成函数注释的模板可以根据函数是否有参数来调整注释格式/** * {{functionDescription}} {{#if parameters}} * param { {{#each parameters}}{{this.type}}{{#unless last}} | {{/unless}}{{/each}} } {{#each parameters}}{{this.name}}{{#unless last}}, {{/unless}}{{/each}} - 参数说明。 {{/if}} * returns { {{returnType}} } 返回值说明。 */ function {{functionName}}({{#each parameters}}{{this.name}}{{#unless last}}, {{/unless}}{{/each}}) { // 函数体将由 AI 填充 }在这个模板中{{#if parameters}}块只有在parameters数组存在且不为空时才会渲染param注释行。{{#unless last}}则用于在循环中判断是否为最后一个元素从而决定是否添加分隔符如“|”或“,”。这种条件渲染使得同一个模板既能处理无参数的工具函数也能处理多参数的复杂方法通用性大大增强。避坑指南过度使用复杂的 Handlebars 逻辑会让模板难以阅读和维护。如果发现模板中嵌套了多层{{#if}}和{{#each}}就应该考虑是否可以将这个步骤拆分成多个更简单的步骤或者将部分逻辑移到生成输入数据的前置脚本中。模板的首要目标是清晰和可预测。5. 效果评估与迭代优化创建了自定义步骤并投入使用了但这并不是终点。我们需要一套方法来评估其效果并持续迭代优化。5.1 建立评估标准不能凭感觉说“好像变好了”。需要定义可衡量的标准格式合规率生成的内容100%符合模板中指定的格式要求如代码块、JSON结构的比例。内容完整性是否包含了所有要求的信息点有没有遗漏关键字段或部分逻辑正确性对于代码生成生成的逻辑是否基本正确对于文档生成描述是否准确无歧义人工修改量为了达到可直接使用的标准平均需要人工修改或调整多少内容生成稳定性用同一组输入多次运行输出结果是否高度一致你可以抽样一批生成结果对照这些标准进行手动打分或者编写简单的校验脚本进行自动化检查如检查输出是否包含特定关键字、是否符合某种语法。5.2 常见的优化方向根据评估结果可以从以下几个方向对步骤进行优化提示词精炼这是最常见的优化点。如果 AI 理解有偏差就在模板中把指令写得更精确、更无歧义。使用更明确的动词如“列出”、“生成”、“对比”避免模糊词汇。提供更优质的示例如果输出格式不稳定在模板中提供更典型、更全面的输入输出示例。示例就是 AI 学习的“样板间”。调整输入数据结构如果发现某些信息总是需要从一大段文本中“抠”出来作为输入很痛苦。考虑优化前置步骤使其输出结构化的数据或者修改当前步骤的输入契约使其更易于填写。步骤拆分与合并如果一个步骤过于复杂导致效果不佳就拆分成多个专注的步骤。如果几个步骤总是连续执行且耦合紧密可以考虑合并成一个更大的步骤减少上下文传递的损耗。引入验证步骤在工作流中增加一个“验证”或“审查”步骤。这个步骤可以是一个简单的规则检查如代码风格检查也可以调用另一个 AI 步骤对前一步的输出进行质量评估并提出修改建议形成一个自我改进的循环。5.3 迭代流程从数据中学习将自定义步骤的优化视为一个数据驱动的迭代过程收集在实际使用中收集“失败案例”或“不满意案例”的输入和输出对。分析分析这些案例找出是模板指令不清、示例覆盖不足还是输入数据本身有问题。假设基于分析提出对模板或工作流的修改假设如“增加一个关于错误处理的明确要求”。实验创建一个步骤的新版本如generate_typescript_interface_v2应用修改。测试用收集到的失败案例和新的测试用例对比新旧版本的效果。部署如果新版本效果显著提升则替换旧版本。这个过程可以手动进行也可以随着使用量的增加逐渐形成一套半自动化的评估和优化机制。6. 实战案例构建一个“数据库模型生成器”工作流让我们通过一个综合案例将前面所有知识串联起来。目标是构建一个工作流输入简单的数据表描述字段名、类型自动生成 TypeScript 实体接口、Prisma Schema 以及基础的 RESTful API 控制器代码。工作流设计步骤1解析原始描述可选如果输入是自然语言可用一个 AI 步骤将其解析为结构化 JSON。步骤2生成 TypeScript 实体接口复用我们之前创建的generate_typescript_interface但增强一下为每个字段生成更详细的 JSDoc并处理关系字段如posts: Post[]。步骤3生成 Prisma Schema新建一个步骤输入是结构化的字段列表输出是model User { ... }格式的 Prisma 数据模型。步骤4生成 REST 控制器骨架新建一个步骤输入实体接口名和字段输出 Express 控制器文件包含基本的 CRUD 方法框架。步骤3生成Prisma Schema的模板示例你是一位精通 Prisma ORM 的开发者。请根据以下信息生成一个 Prisma 数据模型定义。 # 实体信息 - 模型名称{{modelName}} - 字段列表 {{#each fields}} - 字段名{{this.name}} 类型{{this.prismaType}} 是否必填{{this.required}} 是否唯一{{this.unique}} 默认值{{this.defaultValue}} {{/each}} {{#if relations}} - 关系定义 {{#each relations}} - 关系类型{{this.type}} 关联模型{{this.targetModel}} 字段{{this.field}}可选 {{/each}} {{/if}} # 要求 1. 严格使用 Prisma Schema 语法。 2. 根据 prismaType 映射到正确的 Prisma 标量类型如 string, Int, Boolean, DateTime。 3. 根据 required, unique, defaultValue 添加对应的属性id, unique, default。 4. 根据 relations 信息正确添加 relation 字段。 5. 为模型添加 map 或字段添加 map 以指定数据库中的实际表名/列名如果提供了 dbName。 6. 输出 **仅包含** 从 model {{modelName}} { 到 } 的完整模型定义代码块。 开始生成步骤间的数据流转步骤2的输出TypeScript接口可能包含一些类型信息如Post[]这可以被步骤3的模板用来推断或生成关系定义。在实际配置中我们需要一个“数据准备”步骤将用户的原始输入转换成同时包含fields用于步骤2和prismaFields、relations用于步骤3的完整上下文对象然后分别传递给步骤2和步骤3。这体现了工作流设计中对数据结构的精心规划。通过这个案例你可以看到自定义步骤和模板如何像乐高积木一样通过清晰的定义和接口输入输出组合成一个强大的自动化生成流水线。从最初简单的接口生成到如今能产出可直接用于项目起点的、相互关联的多种产物生产力的提升是显而易见的。7. 常见问题与排查技巧实录在实际操作中你肯定会遇到各种问题。以下是我总结的一些典型问题及其解决方法希望能帮你少走弯路。问题1AI 完全忽略了模板中的格式要求输出了一堆解释性文字。排查首先检查模板中格式指令是否足够强硬和明确。像“请只输出代码”、“输出必须包含在 json 代码块中”这样的指令需要放在提示词的显著位置如开头或结尾并且可以重复强调。解决在模板中使用“强制分隔符”。例如在最后加上“你的输出必须且只能从下一行开始typescript”。同时在示例中严格展示这种格式。如果问题依旧可能是 AI 模型本身的问题尝试在步骤配置中调整“温度”Temperature参数将其调低如 0.2以减少随机性让输出更确定性。问题2Handlebars 变量没有被正确替换模板中留下了{{xxx}}原始标签。排查确认提供给步骤的上下文数据中确实包含了模板所引用的变量名大小写敏感。检查数据路径是否正确特别是在工作流中前序步骤的输出可能需要通过类似{{steps.step_id.output.fieldName}}的方式来引用。解决在 OpenSpec 的步骤调试或日志中查看步骤执行前渲染的“最终提示词”。确认{{xxx}}是否已被替换为实际值。如果没有检查数据绑定配置。一个技巧是在模板中暂时添加一个调试部分调试信息输入数据是 {{json contextData}}但记得在正式使用前移除。问题3生成的代码或文档存在细微但恼人的风格不一致。排查这通常是因为模板中的约束不够细致。例如只说了“使用 const”但没有规定缩进是 2 空格还是 4 空格行尾是否加分号。解决在模板的“要求”部分将代码风格规则具体化。甚至可以引用一个知名的风格指南如“遵循 Airbnb JavaScript Style Guide”。更好的做法是将风格检查作为一个独立的后续步骤例如调用 Prettier 或 ESLint 的格式化功能而不是完全依赖 AI 来保证。问题4步骤在工作流中运行很慢影响了整体效率。排查可能是单个步骤的提示词过长或过于复杂导致 AI 模型处理时间增加。也可能是工作流中串行步骤太多。解决优化模板移除冗余的说明和示例保持简洁。如果步骤之间没有严格的依赖关系考虑在 OpenSpec 支持的情况下将一些步骤改为并行执行。对于非常耗时的生成任务可以评估是否值得或者将其拆分为更小的、可缓存结果的步骤。问题5自定义步骤在团队中难以共享和统一管理。排查每个人都在本地修改自己的步骤文件导致版本混乱。解决将步骤定义YAML/JSON和模板文件.hbs纳入版本控制系统如 Git。建立一个共享的步骤仓库。使用 OpenSpec 的“步骤库”或“插件”功能如果支持进行集中管理和分发。为步骤编写清晰的文档说明其输入、输出和用途。自定义 OpenSpec 步骤是一个持续打磨的过程。它没有一劳永逸的“最佳模板”只有最适合你当前团队和项目需求的“当前最优解”。保持迭代的心态从每次不理想的输出中分析原因持续优化你的模板和工作流你会发现AI 生成的代码和文档正变得越来越像一位真正理解你需求的资深搭档所交付的作品。