Medusa Workflows Diagram Generator:用一条命令把工作流自动生成 Mermaid 图【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusaMedusa 的workflows-diagrams-generator是一个面向文档场景的内部 beta 工具,位于 www/utils/packages/workflows-diagrams-generator/README.md。它扫描工作流文件或目录,解析出每个 Workflow 的步骤定义,并自动渲染成 Mermaid 流程图,支持 docs、markdown、mermaid、console、svg、png、pdf 七种输出形态。读完本文,你将掌握该工具的完整命令行参数、各输出类型的落盘行为,以及它如何借助medusajs/orchestration的WorkflowManager与DiagramBuilder把工作流的flow_定义递归翻译成 Mermaid 语法的实现原理。工具定位:为 Medusa 文档生成工作流图README 开头明确说明,这是一个用于生成 Mermaid 工作流图的内部工具,并且处于 beta 阶段,其创建目的是为 Medusa 官方文档生产可复用的工作流示意图:Note: This tool is a beta tool created to generate diagrams that can be used in the Medusa documentation.从包元信息看,该工具尚未对外发布(package.json 中version为0.0.0,尽管配置了publishConfig.access: public),但它的依赖选择透露了底层技术栈:medusajs/workflows-sdklatest:提供工作流定义与注册能力;mermaid-js/mermaid-cli^10.6.1:用于把.mermaid文件渲染成 svg/png/pdf;commander^11.1.0:命令行参数解析;ts-node^10.9.1typescript^5.6.2:直接以 TypeScript 源码方式运行 CLI。包内脚本start实际执行ts-node src/index.ts,因此文档中的yarn start run ...等价于用 ts-node 拉起 CLI 入口 src/index.ts。若未来以产物形式运行,其 bin 名为workflow-diagrams-generator(对应dist/index.js)。命令行用法与参数详解工具只有一个子命令run,在 src/index.ts 中用 commander 注册:yarn start run ./path/to/workflow -o ./path/to/output/dir参数语义如下:参数必填说明workflowPath是工作流文件路径,或包含多个工作流文件的目录-o, --output output是输出目录(源码中通过requiredOption声明为必填)-t, --type type否输出类型,可选值被Option.choices严格限定,默认docs--no-theme否去掉 Medusa 默认主题(默认开启主题)--pretty-names否把步骤名的 slug/驼峰格式美化为首字母大写的可读名称(默认关闭)需要注意-t使用了Option的.choices()约束,即只接受docs、markdown、mermaid、console、svg、png、pdf七种取值,输入其他值会被 commander 直接拒绝;而--no-theme在 commander 中默认值为开启(theme 为 true),传入后才会把主题配置从图中剥离。七种输出类型:每种类型的落盘行为输出分支的实现集中在 src/commands/generate.ts,对每个注册成功的工作流按options.type执行不同写文件逻辑:docs(默认):为每个工作流创建output/workflowName/子目录,其中写入两个文件——diagram.mermaid(图)与code.ts(工作流源码原文)。这一形态专为文档站点组织素材:图和代码分文件存放、按工作流分目录。markdown:为每个工作流生成workflowName.md,内容是一个 text %%{ init: { theme: base, themeVariables: { background: #FFFFFF, mainBkg: #FFFFFF, primaryColor: #FFFFFF, primaryTextColor: #030712, primaryBorderColor: #D1D5DB, nodeBorder: #D1D5DB, lineColor: #11181C, fontFamily: Inter, fontSize: 13px, tertiaryColor: #F3F4F6, tertiaryBorderColor: #D1D5DB, tertiaryTextColor: #030712 } } }%%从源码结构看,这套主题变量定义了白底、#030712 深色文字、#D1D5DB 边框、Inter 字体与 13px 字号,是 Medusa 文档视觉风格的一部分。README 同时给出一个重要限制:**Medusa 主题不支持 dark mode**,因此在深色渲染环境下使用时应显式传入 --no-theme: bash yarn start run ./path/to/workflow -o ./path/to/output/dir --no-theme去掉主题后,图定义会直接以flowchart TB开头,且整体缩进层级会前移一级(主题配置存在时步骤定义使用两层缩进,否则为一层)。--pretty-names:步骤名的可读性格式化传入--pretty-names后,步骤显示名会由formatStepName()处理:先把连字符替换为空格,再按大写字母边界拆分驼峰词,最后对每个单词做首字母大写。例如createOrderStep会被渲染为Create Order Step。README 将这一选项描述为把步骤的 slug 与 camel-case 名称改为大写开头的可读名称,适用于制作展示型图示;而在文档场景下保留原始步骤名(如createOrderStep)则方便读者与源码对应。工作流如何被发现与注册入口参数workflowPath的文件收集逻辑在 src/utils/register-workflows.ts 中,它决定了工具能识别什么样的工作流:单文件模式:路径指向文件时,直接对该文件做动态import(),读取其源码文本备用;目录模式:路径指向目录时,用 glob 匹配**/*.{ts,js},对每个文件并行执行同样的动态导入;工作流识别:导入后检查default导出(或模块的全部导出),对每个导出调用getWorkflowName()——只有当导出的值是函数且带有getName()方法时,才被认为是 Medusa Workflow,取其getName()返回值作为工作流名;最终返回一个MapworkflowId, sourceCode。code只有在docs输出类型下会被写到code.ts中,其他类型只用 id。这个函数 getName()的识别方式与medusajs/orchestration中 Workflow 类的运行时结构一致:工作流定义注册后,src/commands/generate.ts 再通过WorkflowManager.getWorkflow(name)取出工作流实例,取其flow_(即TransactionStepsDefinition类型的步骤定义)交给DiagramBuilder绘图。TransactionStepsDefinition的定义位于 packages/core/orchestration/src/transaction/types.ts,其中next?: TransactionStepsDefinition | TransactionStepsDefinition[]字段既支持顺序步骤也支持并行步骤数组——这正是后续图形构建中分支处理的依据。从 flow 定义到 Mermaid:DiagramBuilder 的递归翻译src/classes/diagram-builder.ts 是图生成的核心,buildDiagram()的输出结构为:主题配置(可选) flowchart TB(自上而下) 步骤定义块 连接箭头块。其getSteps()方法对flow_做递归翻译,关键行为有:步骤节点:每个带action的步骤被渲染为步骤id(显示名)形式的节点定义;步骤 id 由getEscapedStepName()生成,实现是把名称中的连字符全部剔除(replaceAll(-, )),避免 Mermaid 节点 id 中出现非法字符;顺序链接:若某步骤存在next,递归处理子步骤后,为当前步骤与每个后续步骤生成idA -- idB形式的链接行;并行子图:当flow_顶层是数组且长度大于 1 时,判定这些步骤并行执行,将它们包裹进subgraph parallel随机串 [Parallel] ... end子图中(随机串由 src/utils/get-random-string.ts 提供,避免多个并行子图命名冲突);若数组只有一项或子步骤没有action名,则退化为普通步骤,不产生子图;缩进格式:行与行之间用制表符缩进(SPACING),主题开启时整体多一层缩进,保证生成的.mermaid文件可直接阅读。formatLinks()目前只是把链接行拼接输出;源码中保留了一段被注释掉的按每行最多 N 个节点分行逻辑,并标注了 TODO,说明图布局的进一步优化(长图自动折行)仍处于待探索状态——这也符合 README 对 beta 阶段的定位。一次完整的运行示例假设仓库中有一个工作流目录,典型调用如下:# 输出 docs 结构(默认):output/workflowName/diagram.mermaid code.ts yarn start run ./workflows -o ./diagrams # 生成可直接嵌入文档的 markdown 图,并美化步骤名 yarn start run ./workflows/create-order.ts -o ./diagrams -t markdown --pretty-names # 渲染 PNG 用于文档配图(耗时较长,依赖 mermaid-cli 的浏览器渲染管线) yarn start run ./workflows -o ./diagrams -t png几点适用前提与限制需要留意:目录模式会动态import()每个.ts/.js文件,因此被扫描的文件必须是当前 Node/ts-node 环境可加载的模块,导入失败或不含工作流导出的文件会被静默跳过(仅当workflowId与源码都非空时才计入结果);docs输出会把工作流源码原样写入code.ts,如果源码中含敏感信息需自行注意输出目录的可见范围;svg/png/pdf 三种类型依赖mermaid-js/mermaid-cli,首次渲染可能需要下载 Chromium 组件,且速度明显慢于文本类输出;工具本身是只读消费方:它只导入并读取工作流定义,不会修改任何工作流源码。小结workflows-diagrams-generator虽然只是一个 beta 内部工具,但它完整演示了运行时读取框架产物 → 递归翻译为可视化语法 → 多格式落地的文档工程化链路:commander 严格约束的 CLI 参数、按类型分派的七种输出策略、与medusajs/orchestration的WorkflowManager/flow_结构对齐的识别逻辑,以及DiagramBuilder对顺序/并行步骤的 Mermaid 翻译规则,都可以在 www/utils/packages/workflows-diagrams-generator/src 下逐文件对照源码验证。对于维护 Medusa 文档或需要为自己的工作流项目生产架构示意图的开发者,这套实现可以直接复用或作为起点改造。【免费下载链接】medusaThe worlds most flexible commerce platform for agents and developers项目地址: https://gitcode.com/GitHub_Trending/me/medusa创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考