Wasp 教程动作执行器（TACTE）：从 MDX 教程文档到可运行 Wasp 应用的自动化流水线

Wasp 教程动作执行器TACTE从 MDX 教程文档到可运行 Wasp 应用的自动化流水线【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp导读Wasp 官方文档内置了一套引导开发者从零构建完整 Wasp 应用的分步教程每一节教程中都嵌入了TutorialAction组件来标注创建新 Wasp 应用添加认证创建 Task 实体等机器可执行动作。web/tutorial-actions-executor目录下的 Tutorial Actions ExecutorTACTE正是负责读取这些教程文件、抽取动作并按序执行、最终产出完整可运行 Wasp 应用的命令行工具。阅读本文你将掌握 TACTE 的三大命令generate-app、edit-patch-action、list-actions的完整用法、教程 MDX 文件的动作标注格式、Patch 文件管理机制以及它如何借助 Git 提交历史实现修改某个动作并自动重放后续动作的编辑能力。1. 背景TACTE 要解决什么问题Wasp 文档的分步教程覆盖了从项目初始化、页面、实体、查询、动作到认证的完整开发过程。这些教程文档以 MDX 形式存放于web/docs/tutorial/每个文档步骤用编号前缀命名如01-create.md、02-project-structure.md、03-pages.md、04-entities.md、05-queries.md、06-actions.md、07-auth.md并通过TutorialAction组件标注每一步对应的可执行动作。TACTE 的核心使命见 README.md是读取这些教程文件抽取其中定义的TutorialAction动作按文档顺序逐一执行最终生成一个完整可用的 Wasp 应用。这意味着教程文档不只是给人读的文字还变成了一份可以被机器执行的食谱。TutorialAction组件本身定义在 web/docs/tutorial/TutorialAction.tsx 中其注释明确说明它与 TACTE 的关联在开发模式下它渲染出带action类型和id的调试信息条便于作者排查在生产环境则直接透传子内容。该组件支持三种动作类型源码中的ActionProps类型INIT_APP初始化应用需额外提供starterTemplateName属性APPLY_PATCH应用一个 Git PatchMIGRATE_DB执行数据库迁移。组件注释还强调修改动作类型时必须同步更新 src/actions/actions.ts 中的 TypeScript 类型定义——这正是文档组件与执行器之间契约的体现。2. 整体架构从 MDX 到可运行 App 的执行流水线TACTE 是一个基于 Commander注册了generate-app、edit-patch-action、list-actions三个子命令。从源码结构看完整流水线可分为三个阶段2.1 抽取解析 MDX定位 TutorialAction 节点extract-actions/mdxParsing.ts 使用mdast-util-from-markdown配合micromark-extension-mdx-jsx扩展把 MDX 文件解析为 AST随后 astTraversal.ts 通过unist-util-visit遍历 AST找出所有名为TutorialAction的mdxJsxFlowElement节点并读取其属性id与action为必填属性缺失时直接抛出错误starterTemplateName仅在INIT_APP动作中使用。文件读取顺序由 fileOperations.ts 保证只读取.md/.mdx文件并按文件名数字前缀01-、02-…升序排列从而保证动作的执行顺序与教程步骤一致。2.2 映射从 JSX 节点到内部 Action 模型nodeMapping.ts 负责把 AST 节点映射为 actions.ts 中定义的联合类型Action InitAppAction | ApplyPatchAction | MigrateDbAction。每种动作都携带id唯一标识与sourceTutorialFilePath来源文件动作类型额外字段执行时行为INIT_APPwaspStarterTemplateName调用wasp new app-name -t template创建应用并初始化 Git 仓库APPLY_PATCHpatchFilePath、displayName用git apply应用对应的 Patch 文件MIGRATE_DB无运行wasp db migrate-dev --name action-id生成并应用迁移2.3 执行逐动作执行并逐个提交核心执行循环位于 execute-actions.ts。对每个动作按kind分发处理并在动作完成后统一调用commitActionChanges提交INIT_APP→ init.ts 中的initWaspAppWithGitRepo先清空旧目录再调用 waspCli.ts 中的waspNew即wasp new name -t minimal随后执行git init并把主分支重命名为mainAPPLY_PATCH→ 先尝试applyPatchForAction底层即 git.ts 的git apply --verbose若失败则进入重新生成 Patch流程见第 5 节MIGRATE_DB→ 调用waspDbMigrate执行wasp db migrate-dev --name migrationName。注意 waspCli.ts 中对该命令显式设置了stdio: [ignore, pipe, pipe]源码注释说明这是为了避免非交互环境如 e2e 测试下命令因等待 stdin 输入而挂起。每个动作执行后都会以动作的id作为提交信息生成一个独立的 Git commit见 git.ts 的commitAllChangesgit add .git commit -m message。这一设计是后续edit-patch-action能够回退重放的基础也是 e2e 快照测试校验 Git 历史的依据。3. 命令一generate-app —— 一键生成完整应用npm run generate-app # 可选指定自定义的 Wasp CLI 二进制/命令 npm run generate-app -- --wasp-cli-command wasp该命令执行以下流程generate-app/index.ts读取教程目录下所有按编号命名的教程文件从每个文件的TutorialAction组件中抽取动作按序执行每个动作初始化应用、应用 Patch、迁移数据库全部完成后输出成功信息并给出生成应用的目录路径。命令会先打印Found N actions in tutorial files.以确认抽取到的动作总数。如果某个 Patch 应用失败generate-app会暂停并进入人工解决流程详见第 5 节。在仓库中运行package.json中预设的脚本已绑定默认参数--app-name TodoApp --tutorial-dir ../docs/tutorial即直接针对web/docs/tutorial/下真实教程生成TodoApp应用。4. 命令二edit-patch-action —— 修改某个 Patch 并自动重放后续动作当教程内容调整后某个 Patch 可能不再准确。edit-patch-action让你修改指定动作的代码并自动把后续所有动作重新应用到新的基础上# 非交互式按 ID 直接指定 npm run edit-patch-action -- --action-id create-task-entity # 交互式从列表中选择要编辑的动作 npm run edit-patch-action # 可选参数 # - 跳过编辑前的应用生成 npm run edit-patch-action -- --skip-generating-app # - 指定自定义 Wasp CLI npm run edit-patch-action -- --wasp-cli-command wasp该命令的完整逻辑见 edit-patch-action/index.ts生成应用除非传入--skip-generating-app先完整执行一遍generate-app使每个动作都对应一个独立的 Git commit回退到目标动作通过 git.ts 中的findCommitSHAForExactMessage按提交信息即动作id精确查找对应 commit然后git switch --force-create fixes commit创建一个名为fixes的分支并切到该动作的提交进入编辑态执行git reset --soft HEAD~1把该 commit 的改动放回暂存区接着调用 git.ts 的askUserToEditAndCreatePatch——如果设置了$EDITOR环境变量editor.ts 会询问是否用该编辑器打开生成的应用目录./.result/app-name随后用inquirer/prompts的confirm提示你改完后回车确认生成新 Patch 并提交把工作区改动导出为新的 Patch 文件内部通过临时提交 →git show→git reset --hard HEAD~1实现再应用该 Patch 并以动作id重新提交重放后续动作把fixes分支 rebase 回main分支之上git switch maingit rebase fixes。如果后续动作与你的修改产生冲突命令会暂停并提示你手动解决后回车继续回写 Patch 文件extractCommitsIntoPatches遍历所有APPLY_PATCH动作从各自的 commit 重新生成 Patch 内容并写回patches目录保证磁盘上的 Patch 文件与新的提交历史保持一致。其中选择要编辑的动作支持两种方式传入--action-id时精确匹配找不到会报Apply patch action with ID ... not found.未传参时用inquirer/prompts的select弹出交互式列表。5. 命令三list-actions —— 盘点全部教程动作npm run list-actionslist-actions/index.ts 会读取全部教程动作按来源文件名分组展示每个动作的id和kind并按类型着色INIT_APP黄色、APPLY_PATCH绿色、MIGRATE_DB蓝色。这在修改教程、核对动作完整性时非常实用输出形如04-entities.md - prisma-task (APPLY_PATCH) - migration-add-task (MIGRATE_DB)6. 公共选项三个命令的必填配置三个命令共享 tacteCommand.ts 中定义的公共选项用于配置教程应用生成环境选项说明默认值是否必填--app-name name要生成的应用名称也是输出目录下的子目录名—是makeOptionMandatory--output-dir path应用生成目录./.result否--tutorial-dir path包含教程 MDX 文件的目录—是makeOptionMandatory另外 commonOptions.ts 提供--wasp-cli-command command选项默认值为wasp用于覆盖执行wasp new/wasp db migrate-dev时使用的 CLI 命令例如传入wasp-cli或自定义路径。示例npm run generate-app -- --app-name MyApp --output-dir ./custom-output --tutorial-dir ./my-tutorial路径解析规则见 tutorialApp.ts生成应用的目录为output-dir/app-namePatch 目录固定为tutorial-dir/patches。7. Patch 文件管理命名、缺失与冲突处理7.1 命名规范Patch 文件必须存放在教程目录下的patches子目录中。文件名由来源教程文件名去扩展名与动作id拼接而成格式为tutorial-file-name__action-id.patch见 actions/index.ts 的getPatchFilename。以仓库真实数据为例web/docs/tutorial/patches/ 下的文件03-pages__prepare-project.patch、04-entities__prisma-task.patch、06-actions__action-create-task.patch等分别对应03-pages.md中的prepare-project动作、04-entities.md中的prisma-task动作。每个文件内容是一份标准 Git Diff例如 04-entities__prisma-task.patch 展示了向schema.prisma追加Task模型的改动。7.2 缺失或无法应用时的交互流程如果某个 Patch 文件缺失或git apply失败generate-app会暂停并执行 actions/git.ts 中的regeneratePatchForAction若旧 Patch 文件存在先删除它打开生成的应用目录./.result/app-name提示你按当前TutorialAction的描述手动修改代码回车确认后工具会把工作区改动导出为新的 Patch 文件写入patches目录并自动以该动作id提交之后重新应用新 Patch 并继续后续动作。注意流程中所有提交都由执行器自动完成不要在生成的应用里手动提交否则会破坏每动作一提交的对应关系。7.3 与 LLM 配合的 Human-in-the-Loop 工作流README 明确给出了一套与 LLM 协作的流程让generate-app保持运行采用人在回路模式——当提示指向当前动作时请 LLM 修改./.result/app-name中该动作对应的代码人工审查改动后在终端确认如此反复直至命令成功跑完。这也是在教程需要批量更新、Patch 大面积失效时借助 LLM 自动生成新 Patch 的实用方式。8. 教程文件格式如何用TutorialAction标注动作教程文件是 MDX动作通过 JSX 组件TutorialAction标注并用它包裹与该动作关联的教程正文# Step 4: Create Task Entity In this action, well create the Task entity: TutorialAction idcreate-task-entity actionAPPLY_PATCH prisma model Task { id Int id default(autoincrement()) } /TutorialAction关键属性id动作的唯一标识同时也是 Git 提交信息必须唯一action动作类型可选INIT_APP、APPLY_PATCH、MIGRATE_DB。在真实仓库中INIT_APP的用法可见 01-create.mdTutorialAction idcreate-wasp-app actionINIT_APP starterTemplateNameminimal包裹了wasp new TodoApp -t minimal的命令MIGRATE_DB的用法可见 04-entities.mdTutorialAction idmigration-add-task actionMIGRATE_DB /是自闭合标签紧随其后的正文是wasp db migrate-dev命令。e2e 测试夹具e2e-tests/fixtures/tutorial/提供了最简可运行示例01-init.mdINIT_APPstarterTemplateNameminimal、02-patch.mdAPPLY_PATCH 新增src/testUtils.ts、03-migrate.mdAPPLY_PATCH 新增Post模型 MIGRATE_DB 迁移与之配套的 Patch 文件位于e2e-tests/fixtures/tutorial/patches/。9. 测试体系单元测试 e2e 快照测试项目同时包含单元测试与端到端e2e快照测试运行全部测试npm run test9.1 单元测试tests/目录下的单元测试覆盖了解析与执行的关键环节extract-actions/测试 MDX 解析、AST 遍历、节点映射与文件操作如数字前缀排序actions/测试 Git 相关操作与动作创建工厂commands/测试list-actions的分组展示逻辑。9.2 E2E 快照测试e2e 测试generate-app.test.ts验证完整的教程动作执行流程采用快照对比首次运行把执行器的输出生成的文件清单、src/testUtils.ts内容、schema.prisma、Git 提交历史等保存为快照后续运行再与快照比对确保行为没有意外变化。目录结构约定测试夹具e2e-tests/fixtures/tutorial/最小化的教程文件生成输出e2e-tests/.result/快照存储e2e-tests/__snapshots__/。测试通过WASP_CLI_COMMAND环境变量指定所用的 Wasp CLI默认wasp-cli并在比对前把 Prisma 迁移文件名中的时间戳归一化处理避免时间戳差异导致快照误报。当你有意修改了执行器行为、需要更新快照时使用更新模式npm test -- -u10. 总结TACTE 的价值与适用场景TACTE 把撰写教程与验证教程合二为一文档中的每一步都变成可执行的机器指令Git 提交历史成为动作的账本Patch 文件成为动作的可复用载体。从源码实现看这套设计带来了三个直接收益教程可验证任何对教程内容的改动都可以通过generate-app立即验证能否生成可运行应用list-actions帮助快速盘点动作全貌改动可追溯每个动作一个 commitedit-patch-action通过分支 rebase 实现了对历史步骤的安全修改与自动重放人力成本可替代配合 LLM 的 human-in-the-loop 流程即使 Patch 大面积失效也可以半自动地重建整套教程产物。如果你需要为 Wasp 的教程体系贡献内容或排查生成问题从 web/tutorial-actions-executor/README.md 出发结合 src/commands/generate-app/execute-actions.ts 与 src/extract-actions/mdxParsing.ts 两处核心实现即可快速建立完整的代码心智模型。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考