Backstage 仓库协作规范与 AI Agent 开发指南从目录结构到贡献流程的完整实践【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage导读AGENTS.md 是 Backstage 主仓库为人类开发者与 AI 编码助手共同准备的一份「仓库操作说明书」。它定义了 TypeScript 单仓库monorepo的目录布局、包命名规则、代码与文档标准、日常开发命令以及面向发布流程的 changeset 规范。阅读本文后你将能在一个大型多包仓库中快速定位代码位置、判断新旧前端系统与后端系统的边界、按项目约定运行测试与类型检查并正确地为改动准备 changeset 与拉取请求PR。一、仓库概览一个基于 Yarn Workspaces 的 TypeScript 单仓库Backstage 是一个用于构建开发者门户developer portal的开源平台本仓库是它的核心源码库。正如 AGENTS.md 所述这是一个使用 Yarn Workspaces 管理的 TypeScript 单仓库根目录的 package.json 中明确声明了工作区范围workspaces: [ packages/*, plugins/* ]也就是说packages/与plugins/下的每一个目录都是一个独立的工作区包。所有包的发布版本、依赖关系和测试都在根目录统一协调这决定了几乎所有命令都应在仓库根目录执行。根目录 package.json 还揭示了当前仓库的运行时环境与工具链约束这是任何 Agent 在动手前都应当确认的「前提条件」项目值说明包管理器yarn4.8.1packageManager字段必须使用仓库内置的 Yarn 版本Node.js22 \|\| 24engines字段超出此范围的 Node 版本不受支持测试框架Jest~30.2.0 Playwright单元测试与 e2e 测试分离代码格式化Prettierbackstage/cli/config/prettier配置由 CLI 包统一提供二、关键目录与包命名约定三分钟定位任意代码2.1 顶层目录一览AGENTS.md 用一张精简清单概括了最重要的目录结合 docs/contribute/project-structure.md 可以进一步展开路径作用packages/核心框架包包名前缀为backstage/plugins/插件包包名前缀为backstage/plugin-*packages/app基于新前端系统的主示例应用Apppackages/app-legacy基于旧前端系统的示例应用packages/backend本地开发用的示例后端docs/全量 Markdown 文档对应官网 backstage.io/docscontrib/社区贡献的示例与资源.changeset/changeset 文件目录每个文件描述一次发布变更2.2 包前缀即系统标识这是理解 Backstage 架构演进的钥匙AGENTS.md 明确给出了三套命名前缀的语义——core-前缀如backstage/core-plugin-api属于旧前端系统frontend-前缀如backstage/frontend-plugin-api属于新前端系统backend-前缀如backstage/backend-plugin-api属于后端系统。从源码结构看这种命名不是装饰性的新前端系统的核心包 packages/frontend-plugin-api/src 内部分布着blueprints/Blueprint 扩展模型、wiring/扩展接线、routing/路由引用等与旧系统完全不同的组织单元而旧系统核心包backstage/core-plugin-api则承载createPlugin、ApiRef等经典 API。改动任何前端代码前先根据包前缀判断你身处哪个系统是避免用错 API 的第一步。示例后端 packages/backend/src/index.ts 则展示了后端系统的典型形态通过createBackend()创建实例用backend.add(import(backstage/plugin-...))逐个挂载插件甚至可以用createBackendFeatureLoader按配置条件延迟加载特性import { createBackend } from backstage/backend-defaults; import { coreServices, createBackendFeatureLoader } from backstage/backend-plugin-api; const backend createBackend(); const searchLoader createBackendFeatureLoader({ deps: { config: coreServices.rootConfig }, *loader({ config }) { yield import(backstage/plugin-search-backend); if (config.has(search.elasticsearch)) { yield import(backstage/plugin-search-backend-module-elasticsearch); } }, }); backend.add(import(backstage/plugin-auth-backend)); backend.add(searchLoader); // ... backend.start();这段代码同时印证了 AGENTS.md 中「后端由插件拼装而成」的描述packages/backend本身不实现业务而是把plugin-*系列包组合成可运行的后端。三、写作与代码标准进入仓库前的「软约束」3.1 文档写作标准对文档的任何改动都应遵循 docs/contribute/doc-style-guide.md。这份风格指南的核心要求包括使用美式英语采用简洁、专业、面向同行的口吻使用Docusaurus admonition:::note、:::tip、:::caution、:::danger做提示框并保持简短聚焦代码块必须使用正确的语言标识ts、yaml、shell、log、diff等界面元素用加粗新术语用斜体文件名、路径、包名与内联代码一律用行内代码链接用有描述性的文字如 See the configuration file避免裸链接。3.2 代码标准与版权头AGENTS.md 列出了四份必须遵守的规范文件文件内容CONTRIBUTING.md全面的贡献指南克隆、构建、PR 流程、AI 使用政策STYLE.md代码风格与公共 API 设计约定REVIEWING.mdPR 审查与 changeset 写作约定SECURITY.md安全相关规范docs/architecture-decisions/架构决策记录ADR如 ADR006「避免 React.FC」其中有一条容易被 AI 工具忽略的硬性规则所有新增源码文件.ts、.tsx、.js、.jsx必须包含当前年份的 Apache 2.0 版权头但生成文件、配置文件JSON、YAML与文档文件除外同时不要修改既有文件中的版权年份。在仓库中搜索Copyright 20\d\d The Backstage Authors几乎每个源码文件例如 plugins/catalog/src/alpha/apis.tsx都以同样的头部开头——新代码必须与之一致。此外还有两条体现仓库「包内一致性优先」原则的约定跟随每个包既有的编码风格单仓库内不同包可能有不同约定包内一致性比仓库级一致性更重要测试宁精勿多优先写少量、包含多个断言的完整测试使用 React Testing Library 时优先用screen和.findBy*查询而非waitFor且不要在实现代码中添加 test ID。STYLE.md 进一步补充了类型系统层面的约定例如接口名不加I前缀、私有属性不加_前缀、一律使用undefined而非null、index.ts只做再导出、用static create()/static fromConfig()等工厂方法替代公开构造函数。任何生成 TypeScript 代码的 Agent 都应以这些约定为默认输出标准。四、开发流程日常命令的精确用法AGENTS.md 强调以上所有命令运行前必须先执行yarn install。随后即可在仓库根目录使用如下命令矩阵任务命令关键约束安装依赖yarn install一切命令的前置步骤测试CI1 yarn test path必须提供文件或目录路径避免全量测试类型检查yarn tsc只能在根目录运行不带任何参数代码格式化yarn prettier --write ...paths只针对确认改动的文件不要对整个目录运行Lintyarn lint --fix在根目录运行API 报告yarn build:api-reports改动任何工作区包后、提交 PR 前必须运行本地开发yarn start前端运行在:3000后端运行在:7007脚手架yarn new创建新插件、包或模块4.1 测试与类型检查的细节测试环境变量CI1会关闭交互式监听适合在 CI 与脚本中使用根 package.json 中test脚本同时启用了--experimental-vm-modules以支持 ESM 工作区。yarn tsc直接调用仓库根目录的tsconfig.json配置并受NODE_OPTIONS--max-old-space-size8192的内存上限保护见 package.json 的tsc脚本——不要在其他目录尝试运行类型检查也不要附加额外参数。4.2 哪些事「绝对不能做」AGENTS.md 对 Agent 划出了一条明确的红线不得通过yarn build、yarn changesets version或yarn release参与构建与发布——构建和发布由独立的 CI 工作流负责。同时除非被明确要求不得修改 ESLint、Prettier 或 TypeScript 配置文件不得改动 docs/releases/ 下的历史发布记录。这些约束是为了避免 Agent 的中间产物污染仓库状态即使你只读本仓库也应当知悉。4.3 与 CONTRIBUTING.md 的衔接CONTRIBUTING.md 提供了更完整的命令全景与 AGENTS.md 相互印证yarn start:docker可用 Docker 启动示例应用含 Postgres、OpenSearch、Redis 依赖yarn build:api-reports plugins/your-plugin-with-changes可只对单个插件生成 API 报告。它还特别给出了本地配置约定app-config.local.yaml会被 Git 忽略并与app-config.yaml合并适合存放 GitHub Token 等机密——这解释了为何 AGENTS.md 要求先yarn install再执行任何命令因为配置文件加载是本地开发的第一环。五、Changeset 规范为每个发布级改动留痕任何影响packages/或plugins/下已发布包的改动都必须附带一个 changeset而docs/、根配置文件等目录外的改动则不需要。关键规则总结如下5.1 版本号决策矩阵改动类型包版本 1.0.0包版本 ≥ 1.0.0Breaking changeminormajor新增 API / 特性非破坏patchminor其他非破坏改动patchpatch5.2 写作要求面向采纳者adopter而非贡献者用通俗语言描述用户可见的行为变化禁止引用未公开的类名、函数名、变量名等内部实现细节破坏性改动必须加粗标注BREAKING并在必要时附带需要用户更新的 diff一个跨多包的改动常常需要为每个包分别创建 changeset确保信息针对单个包定制changeset 存放在 .changeset/ 目录本仓库当前已有大量形如add-logviewer-copy-button.md、bright-common-...的示例文件应直接手写 changeset 文件绝不使用 changeset CLI。从 .changeset/ 目录的实际文件可以看出这套机制同时服务于「生成 CHANGELOG」与「CI 校验」两个目的因此即使改动很小遗漏 changeset 也会导致 PR 无法通过检查。六、PR 流程与 AI 使用政策6.1 提交流程要点动手前先检查是否已有针对同一改动的开放 PR避免重复劳动PR 描述必须使用 .github/PULL_REQUEST_TEMPLATE.md 模板只勾选实际完成的清单项不要删除或改写模板描述应简短如需长篇设计说明建议开一个 GitHub issue 并在 PR 中链接与既有 issue 相关的改动在 PR 描述中链接该 issue涉及新特性或行为变更的改动必须在 TSDoc 注释、包 README 或 docs/ 中同步更新文档并遵循 docs/contribute/doc-style-guide.md。6.2 对 AI 生成内容的态度CONTRIBUTING.md 中有一段与 AGENTS.md 精神一致的重要政策鼓励使用 AI 工具辅助写码但你必须能理解和解释自己提出的每个改动——The AI did it 不是合格答案未亲自理解与测试的 AI 生成 PR 会被直接关闭。AI 助手应被当作代码库探索工具但不要盲信 LLM 对 Backstage 工作方式的断言应以官方文档与源码为准。这与 AGENTS.md「跟随每个包既有风格、包内一致性优先」的要求一脉相承生成代码的质量责任始终在提交者一方。七、仓库结构延伸阅读AGENTS.md 最后将读者导向 docs/contribute/project-structure.md。该文档详细解释了packages/内各核心包的职责例如packages/cli封装 eslint、webpack 等工具的统一 CLI避免直接调用底层工具导致版本漂移packages/catalog-modelSoftware Catalog 的Entity定义与校验逻辑前后端通用packages/config 与 packages/config-loader前者负责合并多个配置对象后者只负责读取文件因此只被后端使用plugins/插件按「前端 / 后端」以-backend等后缀区分命名甚至核心功能如 catalog也是插件形态。结合 AGENTS.md 的顶层清单与这份详细目录你就能在数千个文件中建立起「根目录 → packages/plugins → 具体包 → src」的导航路径。总结AGENTS.md 表面上只是一份给 AI 助手的短说明书实际上浓缩了 Backstage 主仓库的全部协作共识前缀命名告诉你代码属于哪套系统目录约定告诉你代码放在哪里命令矩阵告诉你如何验证改动changeset 规范告诉你如何让改动进入发布流。对开发者与 Agent 而言把它与 CONTRIBUTING.md、STYLE.md、docs/contribute/project-structure.md 三份文档配合使用即可安全、高效地在 Backstage 单仓库中完成从定位代码到提交 PR 的完整闭环。【免费下载链接】backstageBackstage is an open framework for building developer portals项目地址: https://gitcode.com/GitHub_Trending/ba/backstage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考