使用 /openspec-apply 落地已批准的 OpenSpec 变更：Midway 仓库的规范驱动开发实施指南

后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载本文围绕 Midway 仓库内置的 Cursor 命令 .cursor/commands/openspec-apply.md完整讲解将已批准的 OpenSpec 提案变为真实代码、并保持任务清单同步的标准流程。读者将掌握openspec-apply的执行步骤、守护规则、配套校验命令并能结合仓库中真实的add-functional-web-routing-api变更案例理解从proposal.md到packages/core/src/functional/api.ts实现的完整落地链路。一、openspec-apply 是什么一个规范驱动开发的落地命令在 Midway 仓库的.cursor/commands/目录下有三个相互配套的 OpenSpec 命令openspec-apply是其中负责实现阶段的入口命令文件职责阶段openspec-proposal.md起草变更提案并严格校验Stage 1openspec-apply.md实现已批准的变更、同步任务清单Stage 2openspec-archive.md变更部署后归档、更新 specsStage 3openspec-apply.md本身采用 Cursor 命令的标准格式YAML frontmatter 声明命令元数据name: /openspec-apply、id、category: OpenSpec、description正文被包裹在!-- OPENSPEC:START --与!-- OPENSPEC:END --标记中便于工具链识别。命令正文由三部分组成Guardrails守护规则、Steps执行步骤与Reference参考命令。该命令的核心定位是只做实现不做设计。它要求先读取变更目录下的提案与任务文档确认范围再按任务清单逐项、最小化地修改代码全部完成后才把清单中的每一项勾选为- [x]确保tasks.md始终反映真实进度。二、前置背景OpenSpec 三阶段工作流openspec-apply不是孤立存在的它属于 OpenSpec 规范驱动开发工作流的中间一环。仓库根目录的 openspec/AGENTS.md 对完整流程给出了权威定义Stage 1创建变更Creating Changes——当需要新增功能、破坏性变更、架构调整、性能优化或安全模式更新时创建proposal.md、tasks.md、可选的design.md以及每个受影响 capability 的 delta specs。此阶段不写任何代码openspec-proposal 命令明确要求Do not write any code during the proposal stage。Stage 2实现变更Implementing Changes——提案获批后按tasks.md顺序实现这就是/openspec-apply的战场。Stage 3归档变更Archiving Changes——部署后把changes/[name]/移入changes/archive/YYYY-MM-DD-[name]/并同步更新specs/。三个阶段的目录状态可概括为changes/是提案中未构建specs/是已构建并部署archive/是已完成。Specs 是真相Changes 是提案二者必须保持同步——这正是openspec-apply存在的意义。三、/openspec-apply 的守护规则与执行步骤3.1 Guardrails实现阶段的行为底线命令开篇给出了两条硬性守护规则与 openspec/AGENTS.md 中Simplicity First最佳实践一脉相承优先做直白、最小化的实现只有被明确要求或确有需要时才增加复杂度。仓库侧的配套建议是默认不超过 100 行新代码、单文件实现直到被证明不够用、避免无明确理由引入框架、选择经过验证的成熟模式。变更范围严格收敛到被请求的结果不得顺手重构无关模块。需要更多 OpenSpec 约定时查阅openspec/目录内的AGENTS.md若看不到该文件可运行ls openspec或openspec update生成。3.2 Steps五步落地流程/openspec-apply要求将以下步骤作为 TODO 跟踪并逐一完成读文档确认范围读取changes/id/proposal.md、design.md若存在与tasks.md确认变更范围和验收标准。按序实现逐个完成任务清单中的条目编辑保持最小化聚焦于被请求的变更。确认完成再更新状态更新状态前必须确保tasks.md中每一项都已完成——不要先勾选、后补实现。同步清单所有工作结束后更新 checklist使每个任务标记为- [x]并反映真实情况。按需补充上下文需要额外上下文时引用openspec list或openspec show item。3.3 Reference实现过程中的辅助命令命令同时给出两个参考命令openspec show id --json --deltas-only实现过程中需要从提案补充上下文时使用可精确输出该变更的 delta 定义便于核对需求措辞。openspec/AGENTS.md 中还提供了完整的 CLI 速查openspec list列出活动变更、openspec list --specs列出既有 capability、openspec show [item]查看详情、openspec validate [item]校验、openspec archive change-id [--yes|-y]归档以及调试组合openspec show [change] --json --deltas-only与openspec validate [change] --strict --no-interactive。四、apply 阶段读取的三份关键文档/openspec-apply第 1 步要求读取的文档各有分工仓库中的真实变更 openspec/changes/add-functional-web-routing-api/ 是理解它们的最佳标本4.1 proposal.md为什么改、改什么、影响什么proposal.md 采用固定三段式结构Why说明问题与机会。该提案指出 Midway 的 Web 入口仍以Controller、Get、Post等类/方法装饰器为核心在 React/Vue 前端工程化场景中用户更习惯函数式声明与跨运行时共享模块因此需要与defineConfiguration对齐的 Functional 路由形态。What Changes逐条列出变更内容破坏性变更需标注BREAKING。该提案的核心是新增functional-web-routingcapability首选defineApi(/prefix, api ({ ... }))链式 DSL并导出到midwayjs/core/functional。Impact列出受影响的 specs 与代码、兼容性说明。该提案明确向后兼容装饰器 API 保持不变Functional API 作为增量能力引入并给出预期的实施路径packages/core/src/functional/*、webRouterService.ts、packages/react/*等。4.2 tasks.md可勾选、可验证的实施清单tasks.md 把工作拆成小步、可验证的条目例如1.1 冻结按协议分别导出的入口签名与命名HTTP: defineApiWS: defineWebSocketApi等、2.1 定义 FunctionalControllerOptions、FunctionalRouteDefinition、FunctionalRouteOptions 类型。清单按阶段分组API 设计冻结、路由定义协议与类型、与核心路由系统对齐、用户文档与示例、验证与验收每组内部有序号化子项方便逐项跟踪。该文件的全部条目均已勾选- [x]正是/openspec-apply第 4 步让清单反映现实的产出形态。4.3 design.md技术决策的记录按需创建design.md 不是必须文件openspec/AGENTS.md 给出了创建判据跨模块/新架构模式、新增外部依赖或重大数据模型变更、安全/性能/迁移复杂度、或需要在编码前澄清歧义。它采用Context → Goals/Non-Goals → Decisions → Risks/Trade-offs → Migration Plan → Open Questions的最小骨架。该提案的 design.md 给出了极具参考价值的架构分层Definition Layer → Compile Layer → Runtime Adapter Layer → Service Bridge Layer和装饰器演进矩阵现有装饰器族当前代表装饰器Functional 草案客户端草案Web HTTPControllerGet/Post/...defineApiHTTPhttpApiClientfetch/axiosWebSocketWSControllerOnWSMessagedefineWebSocketApiwsApiClientSocket.IOWSController socket 事件defineSocketIOApisocketIoApiClientgRPC / 微服务Provider/Consumer、KafkaListener、RabbitMQListenerdefineRpcApi/defineMessageApigrpcApiClient/messageApiClientServerless TriggerServerlessTriggerdefineServerlessApi后续阶段functionInvokeClient后续阶段Task / QueueQueue、TaskLocal、ScheduledefineTaskApitaskClient调度/入队矩阵明确不采用defineApi({ protocol })统一入口而是按协议分别导出对应 define API演进维度与现有装饰器族一一对应。五、实例纵深defineApi 在 core 中的真实实现规范文本定义的是用户怎么写而 packages/core/src/functional/api.ts 展示的是/openspec-apply落地后的运行时怎么实现。读这份源码能验证提案中复用现有装饰器元数据、不引入平行元数据体系的承诺。5.1 链式 DSL 的实现机制defineApi(prefix, factory, controllerOptions?)接收前缀与工厂函数工厂内暴露get/post/put/delete/patch/options/head/all八个方法默认 path 均为/每个方法返回一个RouteBuilder。RouteBuilder通过input()/output()/middleware()/meta()/handle()链式累积定义其中handle(fn)是终止操作调用__build()返回完整的FunctionalRouteDefinition包含method、path、options、handle。若未调用.handle(fn)__build()会抛出 Functional route is missing handler 错误——这是类型层面之外的另一道运行时防线。5.2 路由注册完全复用装饰器协议实现的关键在于defineApi内部把函数式声明转换成等价的类装饰器声明createNamedFunctionalController根据 prefix 与路由名生成一个内部匿名类类名形如FunctionalApi_prefix_hash用 sha1 哈希保证唯一性对每条路由通过Object.defineProperty在类原型上定义 handler 方法对该方法调用RequestMapping({ path, requestMethod, routerName, middleware, summary, description, ignoreGlobalPrefix })——即复用了Get/Post等装饰器背后的同一元数据定义函数对生成的类调用Controller(prefix, controllerOptions)同样复用Controller的元数据收集协议最终通过DecoratorManager.saveModule(CONTROLLER_KEY, FunctionalApiController)与MetadataManager.defineMetadata(FUNCTIONAL_API_CONTROLLER_KEY, true, ...)把生成的 controller 登记进统一路由收集流程。从源码结构可以推断functional 路由与装饰器路由在底层走的是同一条收集管道因此 spec.md 中混用不引入平行元数据体系统一冲突检测与排序等需求得以自然成立。FUNCTIONAL_API_MODULE_META_KEY__midwayApiMeta与FUNCTIONAL_API_CONTROLLER_CLASS_KEY__midwayApiControllerClass定义在 packages/core/src/functional/constants.ts用于在返回的路由对象上携带 controller 级元信息prefix、ignoreGlobalPrefix、version、versionType、versionPrefix。5.3 schema 校验与 IoC两个运行时细节输入输出校验getInputFromContext从 ctx 提取params/query/body/headersvalidateInput与runSchemaValidation按safeParseAsync → safeParse → parseAsync → parse的优先级调用 schema兼容 zod 等校验库校验失败统一抛出MidwayCommonError错误信息含Functional API input.params validation failed之类的定位标签。这印证了 spec 中非法输入会触发统一的校验失败行为。hooks 风格 IoCpackages/core/src/functional/hooks.ts 提供useContext、useLogger、useInject、useInjectSync、useConfig、useApp、useMainApp、useInjectClient、useInjectDataSource等函数。其中useInject(identifier, args?)优先从请求级requestContext取实例无请求上下文时回退到主应用的应用上下文——这就是提案中IoC 使用体验保持连续使用 useInjecthooks 风格的落地。5.4 最小可运行样例仓库提供了纯函数式服务的可运行样例 samples/functional-api-service其中 src/api/health.api.ts 用defineApi(/health, api ({ ... }))定义了pingGET与echoPOST两个路由并通过.meta({ routerName: healthPing })指定路由名src/configuration.ts 则展示了注册方式使用defineConfiguration搭配ESModuleFileDetector显式发现 API 模块不需要web.apis嵌套注册——正是 spec 中直觉化注册需求的实证。六、任务清单同步纪律为什么先完成、后勾选/openspec-apply在步骤 3、4 中反复强调完成确认先于状态更新只有tasks.md中每一项都真正完成才允许把条目改为- [x]。这是一条防止虚假进度的工程纪律具体落地建议来自 openspec/AGENTS.md按顺序实现任务保持编辑最小化每个任务都应是小步、可验证的能产出用户可见的进展更新清单应在所有工作完成之后统一进行使清单整体反映现实若发现上下文缺失如某个 spec 语义不清先读project.md、检查相关 specs、浏览近期归档仍不清楚再提问而不是在清单上打勾蒙混。七、实现过程中的校验与调试命令/openspec-apply与配套工作流中最常被引用的命令集中在 openspec/AGENTS.md 的 CLI 速查中# 查看当前上下文 openspec list # 列出活动变更 openspec list --specs # 列出既有 capability 规范 openspec show [item] # 查看变更或规范详情 # 实现阶段调试Reference 中推荐 openspec show id --json --deltas-only # 仅输出 delta 定义核对需求措辞 openspec validate id --strict --no-interactive # 严格校验变更 # 全文检索需求与场景用 ripgrep rg -n Requirement:|Scenario: openspec/specs关键 flag 语义--json输出机器可读结果--strict做全面校验应始终使用--no-interactive禁用交互提示适合自动化--skip-specs仅用于纯工具型变更的归档--yes/-y跳过归档确认。调试场景中还可配合openspec show [change] --json | jq .deltas检查 delta 解析结果。八、常见校验失败与恢复策略实现阶段最容易踩的坑集中在 delta 格式上openspec/AGENTS.md 给出了明确的排错路径Change must have at least one delta检查changes/[name]/specs/目录是否存在且含.md文件并确认文件头使用## ADDED Requirements等操作前缀。Requirement must have at least one scenario场景必须用四个井号的#### Scenario: 名称格式禁止用列表项或加粗充当场景标题——格式不严格会导致静默解析失败。MODIFIED 的经典陷阱修改既有需求时必须粘贴完整需求块标题 全部场景再编辑否则归档时会把原有细节丢弃若只是新增关注点而不是修改现有需求应放在## ADDED Requirements下新增。恢复顺序带--strict重跑 → 看 JSON 输出细节 → 核对 spec 文件格式 → 确认场景格式必要时用openspec show [change] --json --deltas-only定位静默解析问题。九、三个命令的边界与配合理解openspec-apply还需要看清它与兄弟命令的边界/openspec-proposal负责 Stage 1明确禁止写实现代码只产出proposal.md、tasks.md、design.md与 spec deltas并要求openspec validate id --strict --no-interactive全部通过后才分享提案它还要求在动笔前用rg/ls摸清现状、识别含糊点并提问。/openspec-apply只能在提案已批准后使用只管实现与清单同步。/openspec-archive负责 Stage 3先用openspec list确认变更 ID无法唯一确认时宁可不做再openspec archive id --yes执行归档最后openspec validate --strict --no-interactive复核。三者环环相扣共同构成 Midway 仓库从想法 → 提案 → 实现 → 归档的完整规范驱动闭环。对仓库贡献者而言在开始任何实现前建议先运行openspec list与openspec list --specs检查是否有冲突的活动变更并阅读 openspec/project.md 了解 Midway 的技术栈、代码风格与测试约束再调用/openspec-apply进入实现阶段。赞分享后端微服务云原生【免费下载链接】midway A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 项目地址https://gitcode.com/gh_mirrors/mi/midway点击查看免费下载相关推荐用 OpenSpec 工作流驱动变更落地imewlconverter 仓库 openspec-apply-change 技能实战解析用 OpenSpec 工作流驱动变更落地imewlconverter 仓库 openspec apply change 技能实战解析 导读 本文围绕深蓝词库转桌面应用CLI开发工具从 spec 到代码在 Halo 仓库中用 openspec-apply-change 技能驱动 OpenSpec 变更实施从 spec 到代码在 Halo 仓库中用 openspec apply change 技能驱动 OpenSpec 变更实施 本篇指南以仓库内的 opensp后端前端CMSScyllaDB 客户端与节点间 TLS/SSL 加密配置指南Data in Transit: Client to NodeScyllaDB 客户端与节点间 TLS/SSL 加密配置指南Data in Transit: Client to Node 导读 本文讲解如何在 Scyl后端微服务云原生上一篇如何把洛雪音乐助手用成免费的全网音乐播放器下一篇innerself高级技巧如何实现组件连接和状态订阅的终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考