关于 creating-backstage-scaffolder-action
面向 Backstage Scaffolder 开发者的技能指南，说明如何创建模板可调用的后端 Action，并将其注册到模块中。涵盖独立修改与脚手架生成两种方式，以及运行上下文和常见注意事项。
主要功能
- 01创建 Scaffolder Template Action
- 02注册后端模块
- 03支持独立与脚手架生成模式
- 04处理日志、输出与取消
- 05配置 dry-run 行为
适用场景
- 01为模板添加自定义后端操作
- 02扩展现有 scaffolder-backend-module
- 03为耗时 Action 提供运行日志
- 04在 dry-run 时跳过副作用
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/creating-backstage-scaffolder-action确认已加载。
附带文件references/module-registration.mdreferences/template-action.md
详细介绍
创建 Backstage Scaffolder Action
何时使用此技能
- 构建供 Scaffolder 模板调用的自定义 Action（例如
acme:user:create、myorg:slack:notify） - 编辑现有的
scaffolder-backend-module-*插件
构建内容
Scaffolder Action 是一个后端模块（createBackendModule({ pluginId: 'scaffolder', ... })），它会向 scaffolderActionsExtensionPoint 注册一个 TemplateAction。包含两部分：
- Action 本身（通过
createTemplateAction创建） - 注册该 Action 的模块
选择合适的模式
| 构建内容 | 参考资料 |
|---|---|
| Action 本身 | references/template-action.md |
| 将 Action 接入的模块 | references/module-registration.md |
两种调用模式
- 独立模式：编辑现有的 scaffolder-backend-module-*。
- Scaffolder 后调用（由
creating-backstage-plugin为scaffolder-backend-module调用）：同时创建两个文件——Action 定义和模块注册。
常见注意事项
- Action 的
id遵循<namespace>:<name>（或<namespace>:<group>:<name>）约定。命名空间由你选择；请选择一个稳定的名称，避免与已安装模块目录中的其他 Action 冲突。 - Schema 是工厂函数，而非原始 Zod schema：
input: { name: z => z.string() }（而不是input: { name: z.string() }）。Backstage 使用此模式在内部固定其 Zod 版本——请对照../backstage/plugins/scaffolder-node/src/actions/createTemplateAction.ts验证写法。 - Action 处理程序上下文（
ctx）提供：ctx.logger、ctx.workspacePath、ctx.input（根据输入 schema 进行类型标注）、用于输出结果的ctx.output(name, value)、用于获取用户身份的ctx.getInitiatorCredentials()、用于沙盒化工作的ctx.createTemporaryDirectory()、用于取消操作的ctx.signal（AbortSignal），以及用于试运行模式的ctx.isDryRun。 - 长时间运行的 Action 应定期调用
ctx.logger.info——Scaffolder UI 会向用户实时显示日志。 - 如需支持试运行，请设置
supportsDryRun: true，并在处理程序中检查ctx.isDryRun，以跳过副作用。 - 模板可以使用
if: ${{ always() }}和if: ${{ failure() }}控制失败后的步骤执行：always()无条件运行，failure()仅在先前步骤失败时运行。这些功能内置于模板引擎中；Action 作者无需做任何处理即可支持它们。
评论
支持 Markdown