企业官网建设流程全解析

Budibase Agent 开发指南：基于 AGENTS.md 的仓库架构、开发流程与 AI 协作规范

【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase

Budibase 是一款面向 AI Agents、自动化与应用编排的低代码平台（Model agnostic），其开源仓库采用 Lerna 单体仓库（monorepo）结构，横跨 Node.js 后端、浏览器前端与共享 SDK。本文以仓库根目录的 AGENTS.md 为骨架，逐条展开其背后的真实工程实现：包职责划分、构建/测试命令、代码风格、测试工具、Git 协作规范以及完整的本地与云端开发环境（端口、Docker、健康检查）。读完本文，你既能按规范高效地提交代码与 PR，也能快速把仓库跑起来进行调试与二次开发。

一、仓库架构总览：Lerna 单体仓库与包职责划分

AGENTS.md 开篇即给出仓库的整体架构：Workspace 使用 Lerna 管理，所有子包集中在packages/目录下，包与包之间通过@budibase/作用域导入。这与根目录 package.json 中声明的"workspaces": { "packages": ["packages/*"] }、lerna.json 中"npmClient": "yarn"与"version": "independent"（各包独立版本）完全对应。

主要包可分为三类：

约定：后端包之间、后端与前端之间一律使用@budibase/*作用域导入，例如import { automations } from "@budibase/shared-core"；不要跨包使用相对路径引用源码。shared-core是唯一同时被 Node.js 与浏览器引用的共享包。

二、构建、检查与测试命令速查

AGENTS.md 列出的核心命令与根 package.json 的 scripts 一一对应：

yarn build # 全量构建（lerna run build --stream，含各包子包） yarn lint # 检查（eslint + prettier 双通道） yarn lint:fix # 自动修复 yarn check:types # 全仓类型检查（lerna run check:types） yarn test <filename> # 需在某个 packages/* 目录内执行

几个值得注意的实现细节：

• 根 package.json 中lint实际由lint:eslint（eslint packages）与lint:prettier（prettier --check "packages/**/*.{js,ts,svelte}"）两部分组成；lint:fix默认只作用于本次改动的文件（node ./scripts/lintChanged.js fix），全量修复请用lint:fix:all。
• 根 package.json 的engines声明了"node": ">=22.18.0 <23.0.0"，与根目录 .nvmrc 中的v22.22.2一致。AGENTS.md 明确要求：写代码或评审代码时，始终假定目标 Node 版本来自根目录.nvmrc。
• 首次开发必须先生成.env并构建：yarn dev:init（node scripts/dev/manage.js）生成环境变量，之后yarn build，再yarn dev。

packages/server的测试还有一个独有的能力：如果某个测试使用了datasourceDescribe函数，就可以通过DATASOURCE=环境变量把测试范围收窄到某一个具体数据库。可用的数据库字符串定义在 packages/server/src/integrations/tests/utils/index.ts 的DatabaseName枚举中：

export enum DatabaseName { POSTGRES = "postgres", POSTGRES_LEGACY = "postgres_legacy", MONGODB = "mongodb", MYSQL = "mysql", SQL_SERVER = "mssql", MARIADB = "mariadb", ORACLE = "oracle", SQS = "sqs", ELASTICSEARCH = "elasticsearch", DYNAMODB = "dynamodb", }

例如只跑 Postgres 相关的集成测试，可以在包目录内执行DATASOURCE=postgres yarn test <filename>；真实数据库容器由同文件导出的startContainer（来自@budibase/backend-core/tests的 testContainerUtils）按需拉起。

三、代码风格与 TypeScript 规范

AGENTS.md 对代码风格提出了非常具体的要求，其依据是根目录 .prettierrc.json：

{ "tabWidth": 2, "semi": false, "singleQuote": false, "trailingComma": "es5", "arrowParens": "avoid", "plugins": ["prettier-plugin-svelte"] }

即：无分号、双引号、2 空格缩进。在此基础上，AGENTS.md 补充了如下工程约定：

• 类型：启用 TypeScript strict 模式与consistent-type-imports；对象用interface，联合类型/原始类型用type；禁止把值强转为any或unknown。
• 导入顺序：外部依赖（npm 包）分组在前，内部@budibase/*包分组在后。
• 命名：变量使用 camelCase，未使用的参数以_前缀标记。
• 函数：优先箭头函数；异步优先async/await而非裸 Promise；错误处理用try/catch。
• 类型收敛：优先直接导入具名领域类型，避免通过索引访问推导类型。例如应使用RestTemplateId，而不是TemplateSelectionContext["restTemplateId"]——这在@budibase/types包中均有对应导出。
• 逻辑简洁：除非任务明确要求，不要添加向后兼容路径或"处理一切场景"的宽泛逻辑。
• 避免嵌套三元表达式；Svelte 组件优先采用 Svelte 5 写法而非 Svelte 4。
• Builder 上下文：builder 代码运行在浏览器中，因此不要用typeof window === "undefined"来守卫浏览器全局对象。
• 注释克制：只在确实需要解释不清行为的地方写注释。
• 多参数函数：新增或重构的函数若有多个入参，必须使用对象参数；只有保留既有外部 API 时才允许位置参数。
• 日志约定：应用代码用console.log（仓库已配置将 console.log 重定向到 pino），测试中禁止console.log，因为测试输出不会出现在 STDOUT，写了也是白写。
• 类型修复：被要求修复类型错误时，不要用// @ts-nocheck一关了之。

四、packages/server 测试风格与工具函数

AGENTS.md 单独为packages/server划定了测试规范，核心是三个工具：

1. 自动化测试构建器createAutomationBuilder：位于 packages/server/src/automations/tests/utilities/AutomationTestBuilder.ts，内部从@budibase/types导入Automation、AutomationActionStepId、AutomationTriggerStepId、BranchStepInputs、LoopV2StepInputs等类型，并注入BUILTIN_ACTION_DEFINITIONS（actions）与TRIGGER_DEFINITIONS（triggers）来构建可执行的自动化步骤。它支持触发器构建、分支（BranchConfig）、循环（LoopConfig，可指定迭代次数与结果聚合方式）等复杂编排。

2. 结构工厂函数basicTable等：位于 packages/server/src/tests/utilities/structures.ts。basicTable(datasource?, ...extra)会创建一张名为TestTable、含name/description两个字符串字段的表；如需扩展，通过extra参数合并Partial<Table>覆盖字段或约束。同文件还提供tableForDatasource、basicTableWithAttachmentField（含ATTACHMENTS字段）等工厂，覆盖表、数据源、查询及各种 Budibase 资源的构造需求。

3. 测试配置入口TestConfiguration：AGENTS.md 中写的是 packages/server/src/tests/TestConfiguration.ts（实际文件位于 packages/server/src/tests/utilities/TestConfiguration.ts）。每个 API 测试用例都应使用它：new TestConfiguration().api即获得测试 API 客户端，可用函数列表与请求/响应类型在 packages/server/src/tests/utilities/api 中定义。

测试本身的书写约定：使用 Jest 的describe/it结构，外部服务用nock打桩；只断言最终结果，不要对中间状态做断言或条件检查（除非有类型错误）；涉及 URL 的测试一律使用example.com作为域名。

五、Git 提交与 Pull Request 协作规范

AGENTS.md 对 Git 协作有严格的"权限"边界，核心是未经明确许可不做任何仓库变更：

• 不自动 commit、不自动 push、不自动 stage/add、不 unstage，每次 commit / push 都需要单独获得许可；只有当你显式发出git add, commit, push这类完整命令时才一次性执行。
• 创建或切换分支时，确保分支与 GitHub 远端保持同步，不要在旧代码上工作。

Pull Request 方面，规范要求始终遵循 pull_request_template.md 的格式。模板包含五个章节：

• ## Description：描述问题或功能，并附相关 issue 链接；
• ## Addresses：填写本 PR 解决的 issue 链接；
• ## App Export：如可能，附带应用导出文件以方便 QA 用最小配置测试；
• ## Screenshots：UI 类功能需提供 happy path 短视频与功能截图；
• ## Launchcontrol：用通俗语言描述本 PR 的成果，将用于发布说明。

其他 PR 约定：不必填写不相关的章节，但不要新增章节；PR 一律以 draft（草稿）状态打开供人工评审；推分支前确保分支已与 master 同步；修复 bug 的 PR 名称必须以方括号包裹的 bug ID 开头（如[BUDI-1234]），并把 bug 链接放进模板的Addresses章节。

六、本地开发：浏览器、端口与 LiteLLM

AGENTS.md 的 Browser use 与 LiteLLM 两节给出了本地联调的关键信息：

• 本地开发服务器地址为http://localhost:10000（由 Nginx 代理转发）；运行yarn dev前先确认开发服务器是否已在运行，避免端口冲突。
• 本地开发默认登录账号：邮箱local@budibase.com，密码cheekychuckles。
• 产品按 App 维度拆分：查找数据源、自动化等资源前，必须先选中一个 App。
• LiteLLM（AI 网关代理）本地开发时地址为localhost:4000，认证 token 为budibase。根 package.json 中的dev:agent脚本（BUDIBASE_DEV_STACK=core LITELLM_MASTER_KEY= lerna run --stream dev）可用于仅启动核心栈的 AI 开发场景。

关于 LiteLLM 的部署细节，可参考 hosting/docker-compose.dev.yaml：litellm-service使用litellm/litellm:main-v1.83.10-stable.patch.3镜像，映射${LITELLM_PORT:-4000}:4000，挂载 hosting/litellm_config.yaml 作为配置，后端使用 Postgres 16（litellm-db）持久化模型配置（STORE_MODEL_IN_DB: "True"允许通过 UI 添加模型）。

七、Cursor Cloud 开发环境详解

AGENTS.md 的最后一节针对 Cursor Cloud 场景给出了完整的本地服务拓扑，这也是把整个仓库跑起来的实际操作指南。

服务端口一览

对照 hosting/docker-compose.dev.yaml 可以确认：minio-service映射${MINIO_PORT}:9000、proxy-service映射${MAIN_PORT}:10000、couchdb-service映射${COUCH_DB_PORT}:5984与${COUCH_DB_SQS_PORT}:4984、redis-service映射${REDIS_PORT}:6379；MAIN_PORT、COUCH_DB_PORT、REDIS_PORT、MINIO_PORT等均由yarn dev:init生成的.env注入。

启动开发环境的标准流程

1. 确保 Docker 已启动。yarn dev会通过 packages/server/scripts/dev/manage.js 自动拉起开发栈（CouchDB、Redis、MinIO、Nginx，可选 LiteLLM）。该脚本本质是 docker-compose 的封装：up/down/nuke三个子命令分别对应upAll（或BUDIBASE_DEV_STACK=core时仅启动minio-service、proxy-service、couchdb-service、redis-service四个核心服务并停止 LiteLLM 相关容器）、stop与down -v --remove-orphans（连数据卷一起清除）。
2. yarn dev的执行链路（见根 package.json）：dev:init（生成.env）→kill-all（释放 3000/4001/4002/3001/4003 端口）→prebuild→lerna run --stream dev启动 server + worker + builder。
3. 健康检查：Worker 监听4002端口（由.env的WORKER_PORT决定），curl http://localhost:4002/health；Server 健康检查curl http://localhost:4001/health。
4. 通过 Nginx 代理访问完整应用：http://localhost:10000。

测试执行方式

• 包级测试需进入包目录执行：cd packages/<pkg> && yarn test <filename>。
• packages/server与packages/backend-core的测试通过各自scripts/test.sh包装 Jest（见 packages/server/scripts/test.sh、packages/backend-core/scripts/test.sh）。
• shared-core与string-templates的测试直接由jest运行（见各自jest.config.ts/jest.config.cjs）。

Cloud VM 中的 Docker

在嵌套容器环境下，Docker 已配置fuse-overlayfs存储驱动与iptables-legacy；Docker daemon 需先用sudo dockerd启动，随后通过chmod 666 /var/run/docker.sock赋予 socket 权限，使docker命令免 sudo 执行。

常见陷阱（Gotchas）

• lerna只是 devDependency，未全局安装。yarn dev之所以可用，是因为yarn会解析本地 bin；若直接执行lerna，应改用npx lerna或yarn lerna。
• postinstall钩子会执行husky install安装 git hooks（见根 package.json 的"postinstall": "husky install"），pre-push 钩子依赖git-lfs。
• 首次yarn dev之前必须先yarn build；之后 server/worker 由 nodemon 热重载，但对共享包（types、shared-core、backend-core）的改动可能需要重新构建才能生效（根目录也有build:dev脚本用lerna watch监听共享包自动重建）。

小结

AGENTS.md 虽然篇幅精炼，却是理解 Budibase 仓库工程规范的"总开关"：从 Lerna 包划分、构建测试命令、TypeScript 与样式约定，到 server 测试工具、Git/PR 纪律，再到可落地的本地与云端开发环境，每一节都能在仓库源码与配置中找到对应实现。对 AI Agent 或人类开发者而言，遵循这份指南意味着更低的协作摩擦、更一致的代码质量，以及更快的环境上手速度——这也是本文反复强调"以仓库实际内容为准"的原因：规范与实现相互印证，才是真正可靠的开发地图。

【免费下载链接】budibaseAI agents, automations and apps that run your operations. Model agnostic.项目地址: https://gitcode.com/GitHub_Trending/bu/budibase