Backstage Well-known Skills通过.well-known端点向 AI 编程助手分发官方工程技能【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 除了文档和插件之外还发布了一套可被 AI 编程助手直接安装的 AI 技能skills——这些技能是针对 Backstage 常见工程任务前端系统迁移、MUI 到 BUI 的组件迁移、分析埋点、后端 OpenAPI 化编写的自包含指导文件托管在backstage.io的.well-known/skills/端点上。本文介绍这套 well-known 技能的清单与适用场景、一键安装方式并结合仓库中的技能源文件docs/.well-known/skills/与相关包源码说明每个技能背后的具体技术路径。读完本文你将能够把官方技能装进自己的仓库、为 AI 助手指定合适的技能并理解每个技能所覆盖的迁移或改造流程。什么是 Well-known SkillsBackstage 发布的AI 技能是一组自包含的指导文件教会 AI 编码助手如何执行常见的 Backstage 工程任务。技能统一发布到backstage.io的 well-known 端点并可通过skills.sh工具安装到任意仓库。核心安装命令只有一条npx skills add https://backstage.io该命令需要 Node.js 环境以运行npx会读取https://backstage.io/.well-known/skills/index.json中发布的技能索引让你从可用技能中勾选要安装到本仓库的部分。技能在仓库中的存放与发布机制技能的内容在 Backstage monorepo 中维护于docs/.well-known/skills/目录每个技能一个子目录以SKILL.md作为主入口另有一个index.json作为发布索引。当前仓库中该目录的结构为docs/.well-known/skills/ index.json # 所有技能的发布索引 app-frontend-system-migration/ SKILL.md mui-to-bui-migration/ SKILL.md onboard-to-openapi-server/ SKILL.md plugin-analytics-instrumentation/ SKILL.md plugin-full-frontend-system-migration/ SKILL.md plugin-new-frontend-system-support/ SKILL.mdSKILL.md需要包含一个 YAML front mattername与description字段其中name必须与目录名一致description会展示给用户浏览和安装。技能随后在 docs/.well-known/skills/index.json 中注册{ skills: [ { name: skill-name, description: 与 SKILL.md front matter 相同的描述, files: [SKILL.md] } ] }这与仓库 docs/.well-known/skills/index.json 的实际内容一致索引中登记了 6 个技能每个技能的files数组都只有SKILL.md。安装时skills.sh会把技能文件复制到仓库中它管理的目录通常是.github/skills/或类似位置具体取决于配置。安装后可以按项目惯例修改这些文件后续再次运行npx skills add时会提示合并上游变更。技能安装后在启动 AI 编码助手任务时引用对应的SKILL.md即可大多数编辑器内的 AI 助手会自动拾取已提交到仓库的指令文件。例如迁移某个插件的 MUI 导入时附上mui-to-bui-migration技能助手就会遵循正确的组件映射与导入模式。技能清单六大官方技能及其适用场景官方文档 docs/ai/well-known-skills.md 将技能分为四组前端系统迁移、UI 迁移、埋点Instrumentation与后端工具。下面逐一说明每个技能的定位并标注其在仓库中的源文件。前端系统迁移三个技能技能适用场景app-frontend-system-migration把一个 Backstage 应用packages/app从旧前端系统迁移到新前端系统。覆盖混合hybrid迁移阶段以及路由、侧边栏、插件、API、主题等应用级事项的全面迁移plugin-new-frontend-system-support在保持旧系统可用的前提下为现有插件新增新前端系统支持。适用于需要同时兼容新旧系统应用的已发布/共享插件plugin-full-frontend-system-migration把插件完整迁移到新前端系统彻底移除对旧系统的支持。适用于只服务单一应用的内部插件或已准备好完全去掉向后兼容的场景这三个技能分别对应源文件 docs/.well-known/skills/app-frontend-system-migration/SKILL.md、docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md 与 docs/.well-known/skills/plugin-full-frontend-system-migration/SKILL.md。应用迁移技能的核心路径从app-defaults到frontend-defaults从 app-frontend-system-migration 的 SKILL.md 可以看到迁移采取两阶段策略先用兼容助手把应用跑在混合模式再逐步移除旧代码。关键概念对照如下旧系统createApp来自backstage/app-defaults插件通过FlatRoutes里的Route元素安装手工维护AppRouterRoot应用外壳新系统createApp来自backstage/frontend-defaults插件以features形式安装扩展挂载到扩展树上无需手工应用外壳特性发现Feature discovery新系统可以从应用依赖中自动发现并安装插件无需手工导入——这是新应用默认行为迁移时应尽早启用混合模式新createApp配合backstage/core-compat-api提供的convertLegacyAppRoot与convertLegacyAppOptions桥接旧代码。这三个包在仓库中分别对应 packages/app-defaults、packages/frontend-defaults 与 packages/core-compat-api技能中引用的 API如convertLegacyAppOptions包装apis/icons/featureFlags/components/themes选项convertLegacyAppRoot把整个应用元素树转成 features正是这些包的公开能力。特性发现的启用方式也很直接——在app-config.yaml中app: packages: all还可以用include/exclude过滤被发现的范围或在保留发现的前提下按扩展粒度禁用# 只发现特定包 app: packages: include: - backstage/plugin-catalog - backstage/plugin-scaffolder# 发现全部排除特定包 app: packages: exclude: - backstage/plugin-techdocs# 保留包但禁用具体扩展 app: extensions: - page:techdocs: false - page:search: false需要注意的是想完全关闭特性发现应直接省略app.packages配置而不是写none特性发现依赖应用由backstage/cli构建这也是所有 Backstage 应用的默认情况。手动导入与自动发现重叠的插件会去重不会冲突——因此可以在显式导入需要.withOverrides()定制的插件的同时安全开启发现。插件双支持技能alpha.tsx双入口模式plugin-new-frontend-system-support 描述的是发布型插件的典型诉求不强迫消费方先迁移应用。其结果是插件通过双入口同时支持新旧系统保留现有src/plugin.ts旧系统backstage/core-plugin-api的createPlugin新增src/alpha.tsx新系统backstage/frontend-plugin-api的createFrontendPlugin旧系统页面经由createRoutableExtension路由定义在应用中新系统页面通过PageBlueprint创建路由归插件所有页面外壳上采用双 Header 模式旧页面用backstage/core-components的Page/Header/PageWithHeader而新系统的页面组件不应自带页面外壳——框架的PageLayout会渲染backstage/ui的PluginHeader。技能的示例代码展示了alpha.tsx的入口形态// src/alpha.tsx import { createFrontendPlugin, PageBlueprint, } from backstage/frontend-plugin-api; import { RiToolsLine } from remixicon/react; import { rootRouteRef } from ./routes; const myPage PageBlueprint.make({ params: { path: /my-plugin, routeRef: rootRouteRef, loader: () import(./components/MyPage).then(m m.NfsMyPage /), }, }); export default createFrontendPlugin({ pluginId: my-plugin, title: My Plugin, icon: RiToolsLine /, extensions: [myPage], routes: { root: rootRouteRef, }, externalRoutes: { // 与旧插件相同的外部路由 }, });同时需要在package.json中补充./alpha子路径导出与对应的typesVersions条目{ exports: { .: ./src/index.ts, ./alpha: ./src/alpha.tsx, ./package.json: ./package.json }, typesVersions: { *: { alpha: [src/alpha.tsx], package.json: [package.json] } } }PageBlueprint的title/icon参数仅在需要覆盖插件级设置时才填写插件图标推荐remixicon/react的 Remix Icons已有 MUI 图标可加fontSizeinherit保留。技能还建议开始前确认仓库根目录backstage.json中的版本不低于 1.49.x非强制但低于该版本可能遇到问题。插件完整迁移技能彻底移除core-plugin-apiplugin-full-frontend-system-migration 是上述双支持的终局形态入口只剩一个src/plugin.tsx只用createFrontendPlugin彻底删除对backstage/core-plugin-api的依赖路由改用backstage/frontend-plugin-api的createRouteRef页面统一依赖框架的PageLayout/PluginHeader组件内的遗留Route树换成SubPageBlueprint的制式标签页。一个体现新旧差异的典型例子是路由引用迁移——新 API 中createRouteRef()不再接受idID 由扩展推导子路由路径必须以/开头且不能以/结尾createExternalRouteRef()也不再接收id或optional// NEW (src/routes.ts) import { createRouteRef, createSubRouteRef, createExternalRouteRef, } from backstage/frontend-plugin-api; export const rootRouteRef createRouteRef(); export const detailsRouteRef createSubRouteRef({ path: /details/:id, parent: rootRouteRef, }); export const externalDocsRouteRef createExternalRouteRef({ defaultTarget: techdocs.docRoot, });技能特别强调迁移外部路由引用时应始终设置defaultTarget到最常见的绑定目标如scaffolder.root、techdocs.docRoot这样标准插件组合就不需要应用侧再显式bindRoutes。UI 迁移mui-to-bui-migrationmui-to-bui-migration 负责把插件从 Material-UImaterial-ui/core、material-ui/icons迁移到 Backstage UIbackstage/ui简称 BUI覆盖组件映射、导入更新和样式模式替换。前置步骤有两点安装 BUI 包yarn add backstage/ui在根文件通常是src/index.ts或应用入口加入 CSS 导入import backstage/ui/css/styles.css;技能随后给出了完整的 BUI 组件清单可对照仓库 packages/ui 包确认能力范围布局类Box、Container、Flex、FullPage、GridGrid.Root/Grid.ItemUI 类Accordion、Alert、Avatar、Badge、Buttonvariantprimary/secondary/tertiary、isDisabled、destructive、loading、ButtonIcon、ButtonLink、Card含CardHeader/CardBody/CardFooter、Checkbox/CheckboxGroup、DateRangePicker、DialogDialogTrigger/DialogHeader/DialogBody/DialogFooter、FieldLabel、Header、Link、List/ListRow、MenuMenuTrigger/MenuItem/MenuSection/MenuSeparator/SubMenuTrigger、PasswordField、PluginHeader、Popover、RadioGroup、SearchAutocomplete、SearchField、Select、Skeleton、Slider、Switch、Table配useTablehook、TablePagination、Tabs、Tag/TagGroup替代 MUI Chip、Text、TextField、ToggleButton/ToggleButtonGroup、TooltipTooltipTriggerTooltip、VisuallyHiddenHooksuseBreakpoint响应式断点、useTable数据管理支持complete、offset、cursor三种分页模式。迁移的第一步是替换导入// REMOVE these imports import { Box, Typography, Tooltip, Paper } from material-ui/core; import { makeStyles, Theme } from material-ui/core/styles; import SomeIcon from material-ui/icons/SomeIcon; // ADD these imports import { Box, Flex, Text, Tooltip, Card } from backstage/ui;仓库中还有一个与之直接呼应的辅助工具plugins/mui-to-bui/另见 scripts/mui-to-bui 下的迁移脚本说明用于批量处理插件中的 MUI 导入。技能与工具配合能同时完成AI 指导 脚本自动化两层改造。埋点plugin-analytics-instrumentationplugin-analytics-instrumentation 指导如何基于 Backstage Analytics API 为前端插件添加分析事件覆盖添加、评审与扩展事件捕获captureEvent、AnalyticsContext、判断某个交互是否值得埋点以及为分析行为编写测试。技能给出了三条核心原则值得在任何埋点工作前阅读少即是多——只埋点语义事件。只捕获插件语义上负责的领域动作如deploy、create、merge、approve、trigger、rerun和独特结果避免为导航点击、表单每个字段编辑、组件挂载/卸载等 UI 生命周期噪音埋点。检验标准是一句话能回答这个事件帮助回答什么问题。优先使用backstage/ui组件——点击已被内置埋点。BUI 的Link、ButtonLink、Tab、MenuItem、Tag及Table行点击都内置了 Analytics API 点击埋点用于导航时会自动发出带to属性的click事件。因此不要再手工captureEvent(click, ...)否则会产生重复事件确需自定义事件时用noTrack抑制默认事件import { Link } from backstage/ui; import { useAnalytics } from backstage/frontend-plugin-api; function ApproveLink({ requestId, href }: Props) { const analytics useAnalytics(); return ( Link noTrack href{href} onClick{() analytics.captureEvent(approve, requestId)} Approve /Link ); }注意noTrack的用途是替换默认事件而不是叠加第二个事件。拆分事件维度以保持分析灵活性。AnalyticsEvent有action、subject和由框架自动填充pluginId/extension的context各维度应保持可独立聚合。这一技能与 MUI→BUI 迁移技能天然衔接技能明确建议若某个普通a或 MUI 按钮承载了值得分析的导航/动作先迁移到 BUI 等价组件点击事件即免费获得手工埋点可以专注插件特有动作。后端工具onboard-to-openapi-serveronboard-to-openapi-server 把现有后端插件中手写的 Express router 迁移到类型化 OpenAPI 工具链。核心流程是从现有 Express router逆向推导出openapi.yaml用backstage-repo-tools生成服务端 stub再把 router 切换到createOpenApiRouter最后用yarn tsc 包内测试验证。技能强调OpenAPI 规格是事实来源router 只是起点。技能把整个流程拆成明确的步骤并区分必做与可选步骤必做 / 可选盘点 router → 编写openapi.yaml必做生成服务端 stub--server必做把 router 切换到createOpenApiRouter必做运行yarn tsc与插件既有测试必做生成类型化客户端--client-package pkg可选——先询问把 router 测试迁移到wrapServer可选——先询问编写 changesets可选——先询问前置条件包括在 monorepo 根目录操作、已运行yarn install、目标插件有可工作的 Express router通常是src/service/router.ts或src/service/createRouter.ts且测试通过——先建立绿色基线绝不在红色基线上开始迁移。盘点 router 时技能要求对每条路由记录HTTP 方法与路径含路径参数、path/query/header 参数及其必填性、请求体形状、各状态码的响应形状含错误响应、以及鉴权/权限装饰器如httpAuth.credentials、permissions.authorize——后者不在 OpenAPI 规格中表达但必须在迁移后的 router 中逐字保留。仓库中的 packages/repo-tools 即提供了技能所依赖的 OpenAPI 代码生成工具docs/openapi 目录下另有从 01-getting-started 到客户端生成的完整文档可配合阅读。如何选择与使用这些技能官方对三个前端迁移技能的选择建议很明确应用层面packages/app迁移→app-frontend-system-migration插件需要兼容新旧两套应用发布/共享插件→plugin-new-frontend-system-support内部插件只需在单一应用运行、或准备好移除全部向后兼容 →plugin-full-frontend-system-migration。一个常见的组合路径是先以mui-to-bui-migration完成组件层替换获得 BUI 内置埋点能力再用plugin-analytics-instrumentation补齐插件特有的领域事件后端侧则用onboard-to-openapi-server把手写 router 收口到类型化 OpenAPI 工具链。如何贡献新技能技能是 Backstage 已发布文档面的一部分贡献走标准的 pull request 流程。要点在docs/.well-known/skills/skill-name/下新建技能目录SKILL.md必须包含 front mattername与目录同名description为一到两句任务描述在 docs/.well-known/skills/index.json 中注册条目若有辅助文件需逐一列入files数组评审时关注四个维度准确性是否反映当前 API 与惯例、完整性是否覆盖最常见用例、安全性是否避免引入安全/正确性风险的模式、范围是否聚焦单一任务过大就拆分。小结Backstage 的 well-known skills 把专家级迁移经验沉淀为可分发的SKILL.md文件一条npx skills add https://backstage.io命令即可把官方技能装进仓库让 AI 助手在具体任务上遵循项目认可的组件映射、API 用法与流程约束。技能清单、安装机制与贡献流程的权威定义在 docs/ai/well-known-skills.md 与 docs/ai/skills.md各技能的完整操作细节则以docs/.well-known/skills/下对应的SKILL.md为准。对于正在进行前端系统升级、UI 组件替换或后端接口规范化的团队这些技能是现成的任务说明书也是观察 Backstage 各核心包frontend-defaults、core-compat-api、frontend-plugin-api、ui、repo-tools演进方向的一手材料。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Backstage Well-known Skills：通过 `.well-known` 端点向 AI 编程助手分发官方工程技能
Backstage Well-known Skills通过.well-known端点向 AI 编程助手分发官方工程技能【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstageBackstage 除了文档和插件之外还发布了一套可被 AI 编程助手直接安装的 AI 技能skills——这些技能是针对 Backstage 常见工程任务前端系统迁移、MUI 到 BUI 的组件迁移、分析埋点、后端 OpenAPI 化编写的自包含指导文件托管在backstage.io的.well-known/skills/端点上。本文介绍这套 well-known 技能的清单与适用场景、一键安装方式并结合仓库中的技能源文件docs/.well-known/skills/与相关包源码说明每个技能背后的具体技术路径。读完本文你将能够把官方技能装进自己的仓库、为 AI 助手指定合适的技能并理解每个技能所覆盖的迁移或改造流程。什么是 Well-known SkillsBackstage 发布的AI 技能是一组自包含的指导文件教会 AI 编码助手如何执行常见的 Backstage 工程任务。技能统一发布到backstage.io的 well-known 端点并可通过skills.sh工具安装到任意仓库。核心安装命令只有一条npx skills add https://backstage.io该命令需要 Node.js 环境以运行npx会读取https://backstage.io/.well-known/skills/index.json中发布的技能索引让你从可用技能中勾选要安装到本仓库的部分。技能在仓库中的存放与发布机制技能的内容在 Backstage monorepo 中维护于docs/.well-known/skills/目录每个技能一个子目录以SKILL.md作为主入口另有一个index.json作为发布索引。当前仓库中该目录的结构为docs/.well-known/skills/ index.json # 所有技能的发布索引 app-frontend-system-migration/ SKILL.md mui-to-bui-migration/ SKILL.md onboard-to-openapi-server/ SKILL.md plugin-analytics-instrumentation/ SKILL.md plugin-full-frontend-system-migration/ SKILL.md plugin-new-frontend-system-support/ SKILL.mdSKILL.md需要包含一个 YAML front mattername与description字段其中name必须与目录名一致description会展示给用户浏览和安装。技能随后在 docs/.well-known/skills/index.json 中注册{ skills: [ { name: skill-name, description: 与 SKILL.md front matter 相同的描述, files: [SKILL.md] } ] }这与仓库 docs/.well-known/skills/index.json 的实际内容一致索引中登记了 6 个技能每个技能的files数组都只有SKILL.md。安装时skills.sh会把技能文件复制到仓库中它管理的目录通常是.github/skills/或类似位置具体取决于配置。安装后可以按项目惯例修改这些文件后续再次运行npx skills add时会提示合并上游变更。技能安装后在启动 AI 编码助手任务时引用对应的SKILL.md即可大多数编辑器内的 AI 助手会自动拾取已提交到仓库的指令文件。例如迁移某个插件的 MUI 导入时附上mui-to-bui-migration技能助手就会遵循正确的组件映射与导入模式。技能清单六大官方技能及其适用场景官方文档 docs/ai/well-known-skills.md 将技能分为四组前端系统迁移、UI 迁移、埋点Instrumentation与后端工具。下面逐一说明每个技能的定位并标注其在仓库中的源文件。前端系统迁移三个技能技能适用场景app-frontend-system-migration把一个 Backstage 应用packages/app从旧前端系统迁移到新前端系统。覆盖混合hybrid迁移阶段以及路由、侧边栏、插件、API、主题等应用级事项的全面迁移plugin-new-frontend-system-support在保持旧系统可用的前提下为现有插件新增新前端系统支持。适用于需要同时兼容新旧系统应用的已发布/共享插件plugin-full-frontend-system-migration把插件完整迁移到新前端系统彻底移除对旧系统的支持。适用于只服务单一应用的内部插件或已准备好完全去掉向后兼容的场景这三个技能分别对应源文件 docs/.well-known/skills/app-frontend-system-migration/SKILL.md、docs/.well-known/skills/plugin-new-frontend-system-support/SKILL.md 与 docs/.well-known/skills/plugin-full-frontend-system-migration/SKILL.md。应用迁移技能的核心路径从app-defaults到frontend-defaults从 app-frontend-system-migration 的 SKILL.md 可以看到迁移采取两阶段策略先用兼容助手把应用跑在混合模式再逐步移除旧代码。关键概念对照如下旧系统createApp来自backstage/app-defaults插件通过FlatRoutes里的Route元素安装手工维护AppRouterRoot应用外壳新系统createApp来自backstage/frontend-defaults插件以features形式安装扩展挂载到扩展树上无需手工应用外壳特性发现Feature discovery新系统可以从应用依赖中自动发现并安装插件无需手工导入——这是新应用默认行为迁移时应尽早启用混合模式新createApp配合backstage/core-compat-api提供的convertLegacyAppRoot与convertLegacyAppOptions桥接旧代码。这三个包在仓库中分别对应 packages/app-defaults、packages/frontend-defaults 与 packages/core-compat-api技能中引用的 API如convertLegacyAppOptions包装apis/icons/featureFlags/components/themes选项convertLegacyAppRoot把整个应用元素树转成 features正是这些包的公开能力。特性发现的启用方式也很直接——在app-config.yaml中app: packages: all还可以用include/exclude过滤被发现的范围或在保留发现的前提下按扩展粒度禁用# 只发现特定包 app: packages: include: - backstage/plugin-catalog - backstage/plugin-scaffolder# 发现全部排除特定包 app: packages: exclude: - backstage/plugin-techdocs# 保留包但禁用具体扩展 app: extensions: - page:techdocs: false - page:search: false需要注意的是想完全关闭特性发现应直接省略app.packages配置而不是写none特性发现依赖应用由backstage/cli构建这也是所有 Backstage 应用的默认情况。手动导入与自动发现重叠的插件会去重不会冲突——因此可以在显式导入需要.withOverrides()定制的插件的同时安全开启发现。插件双支持技能alpha.tsx双入口模式plugin-new-frontend-system-support 描述的是发布型插件的典型诉求不强迫消费方先迁移应用。其结果是插件通过双入口同时支持新旧系统保留现有src/plugin.ts旧系统backstage/core-plugin-api的createPlugin新增src/alpha.tsx新系统backstage/frontend-plugin-api的createFrontendPlugin旧系统页面经由createRoutableExtension路由定义在应用中新系统页面通过PageBlueprint创建路由归插件所有页面外壳上采用双 Header 模式旧页面用backstage/core-components的Page/Header/PageWithHeader而新系统的页面组件不应自带页面外壳——框架的PageLayout会渲染backstage/ui的PluginHeader。技能的示例代码展示了alpha.tsx的入口形态// src/alpha.tsx import { createFrontendPlugin, PageBlueprint, } from backstage/frontend-plugin-api; import { RiToolsLine } from remixicon/react; import { rootRouteRef } from ./routes; const myPage PageBlueprint.make({ params: { path: /my-plugin, routeRef: rootRouteRef, loader: () import(./components/MyPage).then(m m.NfsMyPage /), }, }); export default createFrontendPlugin({ pluginId: my-plugin, title: My Plugin, icon: RiToolsLine /, extensions: [myPage], routes: { root: rootRouteRef, }, externalRoutes: { // 与旧插件相同的外部路由 }, });同时需要在package.json中补充./alpha子路径导出与对应的typesVersions条目{ exports: { .: ./src/index.ts, ./alpha: ./src/alpha.tsx, ./package.json: ./package.json }, typesVersions: { *: { alpha: [src/alpha.tsx], package.json: [package.json] } } }PageBlueprint的title/icon参数仅在需要覆盖插件级设置时才填写插件图标推荐remixicon/react的 Remix Icons已有 MUI 图标可加fontSizeinherit保留。技能还建议开始前确认仓库根目录backstage.json中的版本不低于 1.49.x非强制但低于该版本可能遇到问题。插件完整迁移技能彻底移除core-plugin-apiplugin-full-frontend-system-migration 是上述双支持的终局形态入口只剩一个src/plugin.tsx只用createFrontendPlugin彻底删除对backstage/core-plugin-api的依赖路由改用backstage/frontend-plugin-api的createRouteRef页面统一依赖框架的PageLayout/PluginHeader组件内的遗留Route树换成SubPageBlueprint的制式标签页。一个体现新旧差异的典型例子是路由引用迁移——新 API 中createRouteRef()不再接受idID 由扩展推导子路由路径必须以/开头且不能以/结尾createExternalRouteRef()也不再接收id或optional// NEW (src/routes.ts) import { createRouteRef, createSubRouteRef, createExternalRouteRef, } from backstage/frontend-plugin-api; export const rootRouteRef createRouteRef(); export const detailsRouteRef createSubRouteRef({ path: /details/:id, parent: rootRouteRef, }); export const externalDocsRouteRef createExternalRouteRef({ defaultTarget: techdocs.docRoot, });技能特别强调迁移外部路由引用时应始终设置defaultTarget到最常见的绑定目标如scaffolder.root、techdocs.docRoot这样标准插件组合就不需要应用侧再显式bindRoutes。UI 迁移mui-to-bui-migrationmui-to-bui-migration 负责把插件从 Material-UImaterial-ui/core、material-ui/icons迁移到 Backstage UIbackstage/ui简称 BUI覆盖组件映射、导入更新和样式模式替换。前置步骤有两点安装 BUI 包yarn add backstage/ui在根文件通常是src/index.ts或应用入口加入 CSS 导入import backstage/ui/css/styles.css;技能随后给出了完整的 BUI 组件清单可对照仓库 packages/ui 包确认能力范围布局类Box、Container、Flex、FullPage、GridGrid.Root/Grid.ItemUI 类Accordion、Alert、Avatar、Badge、Buttonvariantprimary/secondary/tertiary、isDisabled、destructive、loading、ButtonIcon、ButtonLink、Card含CardHeader/CardBody/CardFooter、Checkbox/CheckboxGroup、DateRangePicker、DialogDialogTrigger/DialogHeader/DialogBody/DialogFooter、FieldLabel、Header、Link、List/ListRow、MenuMenuTrigger/MenuItem/MenuSection/MenuSeparator/SubMenuTrigger、PasswordField、PluginHeader、Popover、RadioGroup、SearchAutocomplete、SearchField、Select、Skeleton、Slider、Switch、Table配useTablehook、TablePagination、Tabs、Tag/TagGroup替代 MUI Chip、Text、TextField、ToggleButton/ToggleButtonGroup、TooltipTooltipTriggerTooltip、VisuallyHiddenHooksuseBreakpoint响应式断点、useTable数据管理支持complete、offset、cursor三种分页模式。迁移的第一步是替换导入// REMOVE these imports import { Box, Typography, Tooltip, Paper } from material-ui/core; import { makeStyles, Theme } from material-ui/core/styles; import SomeIcon from material-ui/icons/SomeIcon; // ADD these imports import { Box, Flex, Text, Tooltip, Card } from backstage/ui;仓库中还有一个与之直接呼应的辅助工具plugins/mui-to-bui/另见 scripts/mui-to-bui 下的迁移脚本说明用于批量处理插件中的 MUI 导入。技能与工具配合能同时完成AI 指导 脚本自动化两层改造。埋点plugin-analytics-instrumentationplugin-analytics-instrumentation 指导如何基于 Backstage Analytics API 为前端插件添加分析事件覆盖添加、评审与扩展事件捕获captureEvent、AnalyticsContext、判断某个交互是否值得埋点以及为分析行为编写测试。技能给出了三条核心原则值得在任何埋点工作前阅读少即是多——只埋点语义事件。只捕获插件语义上负责的领域动作如deploy、create、merge、approve、trigger、rerun和独特结果避免为导航点击、表单每个字段编辑、组件挂载/卸载等 UI 生命周期噪音埋点。检验标准是一句话能回答这个事件帮助回答什么问题。优先使用backstage/ui组件——点击已被内置埋点。BUI 的Link、ButtonLink、Tab、MenuItem、Tag及Table行点击都内置了 Analytics API 点击埋点用于导航时会自动发出带to属性的click事件。因此不要再手工captureEvent(click, ...)否则会产生重复事件确需自定义事件时用noTrack抑制默认事件import { Link } from backstage/ui; import { useAnalytics } from backstage/frontend-plugin-api; function ApproveLink({ requestId, href }: Props) { const analytics useAnalytics(); return ( Link noTrack href{href} onClick{() analytics.captureEvent(approve, requestId)} Approve /Link ); }注意noTrack的用途是替换默认事件而不是叠加第二个事件。拆分事件维度以保持分析灵活性。AnalyticsEvent有action、subject和由框架自动填充pluginId/extension的context各维度应保持可独立聚合。这一技能与 MUI→BUI 迁移技能天然衔接技能明确建议若某个普通a或 MUI 按钮承载了值得分析的导航/动作先迁移到 BUI 等价组件点击事件即免费获得手工埋点可以专注插件特有动作。后端工具onboard-to-openapi-serveronboard-to-openapi-server 把现有后端插件中手写的 Express router 迁移到类型化 OpenAPI 工具链。核心流程是从现有 Express router逆向推导出openapi.yaml用backstage-repo-tools生成服务端 stub再把 router 切换到createOpenApiRouter最后用yarn tsc 包内测试验证。技能强调OpenAPI 规格是事实来源router 只是起点。技能把整个流程拆成明确的步骤并区分必做与可选步骤必做 / 可选盘点 router → 编写openapi.yaml必做生成服务端 stub--server必做把 router 切换到createOpenApiRouter必做运行yarn tsc与插件既有测试必做生成类型化客户端--client-package pkg可选——先询问把 router 测试迁移到wrapServer可选——先询问编写 changesets可选——先询问前置条件包括在 monorepo 根目录操作、已运行yarn install、目标插件有可工作的 Express router通常是src/service/router.ts或src/service/createRouter.ts且测试通过——先建立绿色基线绝不在红色基线上开始迁移。盘点 router 时技能要求对每条路由记录HTTP 方法与路径含路径参数、path/query/header 参数及其必填性、请求体形状、各状态码的响应形状含错误响应、以及鉴权/权限装饰器如httpAuth.credentials、permissions.authorize——后者不在 OpenAPI 规格中表达但必须在迁移后的 router 中逐字保留。仓库中的 packages/repo-tools 即提供了技能所依赖的 OpenAPI 代码生成工具docs/openapi 目录下另有从 01-getting-started 到客户端生成的完整文档可配合阅读。如何选择与使用这些技能官方对三个前端迁移技能的选择建议很明确应用层面packages/app迁移→app-frontend-system-migration插件需要兼容新旧两套应用发布/共享插件→plugin-new-frontend-system-support内部插件只需在单一应用运行、或准备好移除全部向后兼容 →plugin-full-frontend-system-migration。一个常见的组合路径是先以mui-to-bui-migration完成组件层替换获得 BUI 内置埋点能力再用plugin-analytics-instrumentation补齐插件特有的领域事件后端侧则用onboard-to-openapi-server把手写 router 收口到类型化 OpenAPI 工具链。如何贡献新技能技能是 Backstage 已发布文档面的一部分贡献走标准的 pull request 流程。要点在docs/.well-known/skills/skill-name/下新建技能目录SKILL.md必须包含 front mattername与目录同名description为一到两句任务描述在 docs/.well-known/skills/index.json 中注册条目若有辅助文件需逐一列入files数组评审时关注四个维度准确性是否反映当前 API 与惯例、完整性是否覆盖最常见用例、安全性是否避免引入安全/正确性风险的模式、范围是否聚焦单一任务过大就拆分。小结Backstage 的 well-known skills 把专家级迁移经验沉淀为可分发的SKILL.md文件一条npx skills add https://backstage.io命令即可把官方技能装进仓库让 AI 助手在具体任务上遵循项目认可的组件映射、API 用法与流程约束。技能清单、安装机制与贡献流程的权威定义在 docs/ai/well-known-skills.md 与 docs/ai/skills.md各技能的完整操作细节则以docs/.well-known/skills/下对应的SKILL.md为准。对于正在进行前端系统升级、UI 组件替换或后端接口规范化的团队这些技能是现成的任务说明书也是观察 Backstage 各核心包frontend-defaults、core-compat-api、frontend-plugin-api、ui、repo-tools演进方向的一手材料。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考