dbgate 仓库的 AGENTS.md 深度解读:DBGM 错误码、Svelte4 GUI 与 Cypress E2E 协作规范

原创2026-10-14 09:25:411,405 阅读
文章标签:数据库客户端桌面应用后端前端数据可视化

dbgate 仓库的 AGENTS.md 深度解读:DBGM 错误码、Svelte4 GUI 与 Cypress E2E 协作规范

本文以 dbgate 仓库根目录的 AGENTS.md 为核心,逐条拆解这份面向 AI Agent 与开发者的仓库协作规范,并结合仓库内真实源码、自动化脚本与测试用例,讲清 DBGM 错误码占位符机制、Svelte4 GUI 约束、Cypress E2E 的 data-testid 命名体系,以及 storageModel.js 的代码生成保护。读完你将掌握在 dbgate 这类大型 monorepo 中提交高质量代码时需要遵循的关键约定,也能直接复用其"占位符 + 自动分配"的错误码管理思路。

一、AGENTS.md 在仓库中的定位:Agent 的"入场须知"

dbgate 是一个支持 MySQL、PostgreSQL、SQL Server、MongoDB、SQLite 等多种数据库的数据库管理工具,核心 GUI 位于 packages/web,后端 API 位于 packages/api,并配有完整的 E2E 测试目录 e2e-tests。仓库根目录的 AGENTS.md 全文虽短,却是 AI 编码代理(Agent)进入仓库后的第一份约束清单,共五条规则,涵盖四个层面:

规则 主题 约束对象
规则 1 错误码(DBGM) 新增代码中的 message/error codes
规则 2 GUI 技术栈 Svelte4(packages/web)
规则 3 E2E 测试 Cypress + data-testid 属性
规则 4 测试选择器命名 ComponentName_identifier 格式
规则 5 生成文件保护 storageModel.js 禁止手改

值得注意的是,CLAUDE.md 中第 107、109 行存在高度一致的表述("Error/message codes use DBGM-00000 as placeholder"、"E2E test selectors use data-testid attribute with format ComponentName_identifier")。这说明 AGENTS.md 是面向通用 Agent 工具的规则集中地,其内容与既有 Claude 协作规范相互印证,是 Agent 在动手改代码前必须阅读的"元规则"。

二、规则一:DBGM 错误码的占位符机制与自动分配

2.1 核心约定:新代码一律使用 DBGM-00000

AGENTS.md 第 5 行要求:新增代码中,消息/错误码统一写成 DBGM-00000,不要自行引入类似 DBGM-00316 这种新的编号码。这一约定在仓库中随处可见,例如:

而已经分配过正式编号的错误码也不在少数,例如 packages/web/src/utility/api.ts 第 250 行抛出的 DBGM-00437 API request ${route} returned ... instead of JSON。

2.2 底层支撑:assign-dbgm-codes.mjs 的自动分配脚本

为什么要求新代码统一写占位符?因为仓库提供了 common/assign-dbgm-codes.mjs 这一自动化脚本,负责把仓库内所有 DBGM-00000 占位符批量替换为全局唯一的新编号。其核心逻辑:

  1. 递归扫描:遍历指定目录下所有 .mjs/.cjs/.js/.ts/.jsx/.tsx 文件,自动跳过 node_modules、.git、dist、build 等目录以及脚本自身、package.json、README.md(第 10–22 行);
  2. 收集已占用的编号:用正则 DBGM-(\d{5}) 提取全仓库所有已分配的错误码数字部分(第 7、76–78 行);
  3. 分配最小可用编号:makeNextCodeFn 从 1 开始递增,找出第一个未被占用的正整数并格式化为 DBGM-NNNNN(第 43–61 行),保证分配结果全局唯一且紧凑;
  4. 原地替换:对每个含占位符的文件执行 replaceAll,将占位符逐一替换为下一个可用编号(第 106–109 行);
  5. 支持 --dry 预演:传入 --dry 参数时只打印 [dry] 变更清单而不写盘(第 26、114 行),便于在 CI 或本地提交前先审查。

该脚本运行方式(假设在仓库根目录):

node common/assign-dbgm-codes.mjs --dry .   # 预演,查看哪些文件将被改写
node common/assign-dbgm-codes.mjs .          # 实际执行,占位符被替换为唯一编号

这种"先写占位符、后统一分配"的模式,彻底消除了多人/多 Agent 并行开发时手工编号造成的冲突或跳号问题,也让错误码集中在一次提交中稳定落地。

2.3 测试如何校验错误码

错误码约定同样被测试用例覆盖。例如 packages/api/src/codex/credentials.test.js 中第 107 行断言 rejects.toThrow('DBGM-00000 Stored Codex credentials are invalid')、第 121 行断言 expect(error.message).toBe('DBGM-00000 Could not decrypt Codex credentials')。这意味着测试直接绑定错误消息文本,因此在正式分配编号后,需同步更新这些断言,或者保持"前缀 + 描述"的结构不变。

三、规则二:GUI 技术栈锁定 Svelte4(packages/web)

AGENTS.md 第 6 行明确:GUI 使用 Svelte4,位于 packages/web。这是对 Agent 的技术栈约束——不要擅自引入 Svelte5 语法、其他前端框架或改变目录结构。从仓库现状看,packages/web/src 下按功能划分了大量子目录(forms、datagrid、tabs、modals、settings、widgets 等),组件以 .svelte 为后缀,例如 LoginPage.svelte、ForgotPasswordPage.svelte。与之配套的构建配置位于 packages/web/rolldown.config.mjs 与 packages/web/package.json。

对 Agent 的实操含义是:新增或修改任何界面组件时,都应遵循 Svelte4 的组件写法,并把新组件放到语义对应的子目录中,保证与既有组件风格、数据流(stores.ts)一致。

四、规则三与规则四:Cypress E2E 与 data-testid 选择器体系

4.1 为什么必须用 data-testid

AGENTS.md 第 7–8 行要求:GUI 通过 e2e-tests 目录下的 Cypress 测试进行验证,组件中要使用 data-testid 属性以方便测试定位,格式为 ComponentName_identifier(组件名_标识符)。使用 data-testid 而非 CSS 类名或文本内容作为测试锚点,可以避免样式调整或文案变更导致测试大面积失效,这也是前端测试的通行最佳实践。

4.2 组件侧的写法

组件里按 组件名_语义标识 的格式打点,例如 LoginPage.svelte 中的:

<input ... data-testid="LoginPage_username" />
<input ... data-testid="LoginPage_password" />
<Link internalRedirect="/forgot-password.html" data-testid="LoginPage_forgotPassword">
<button ... data-testid="LoginPage_submitLogin">

ForgotPasswordPage.svelte 中也有 ForgotPasswordPage_backToLogin、ForgotPasswordPage_email、ForgotPasswordPage_submit 等选择器。命名规范带来的好处是:看到测试选择器即可反查所属组件,看到组件即可预判测试中会如何引用它。对于动态列表场景,规则允许在标识符中携带合理变量,例如 LoginPage.svelte 第 305 行的 `LoginPage_loginButton_${provider.name}`——同一"标识符位"使用可读的枚举值区分多个同类元素。

4.3 测试侧的引用

E2E 测试文件位于 e2e-tests/cypress/e2e/,例如 add-connection.cy.js 中大量通过 cy.get('[data-testid=...]') 驱动界面:

cy.get('[data-testid=ConnectionList_buttonNewConnection]').click();
cy.get('[data-testid=ConnectionDriverFields_connectionType]').select('MySQL');
cy.get('[data-testid=ConnectionDriverFields_user]').clear().type('root');
cy.get('[data-testid=ConnectionTab_buttonSave]').click();
cy.get('[data-testid=ConnectionTab_buttonConnect]').click();

这套选择器体系覆盖了连接管理、数据浏览、图表、Redis、AI 聊天、REST、团队协作等十余条测试链路(见 e2e-tests/cypress/e2e 下的 *.cy.js)。

4.4 E2E 的运行体系:从组件到 CI

e2e-tests/package.json 提供了完整的运行矩阵,每组功能都有三套脚本:

  • start:*:先清理测试数据(node clearTestingData),可选执行 e2e-tests/init/*.js 数据初始化脚本,再启动打包后的服务(node packer/build/bundle.js --listen-api --run-e2e-tests);
  • cy:run:*:以 cypress run --spec cypress/e2e/<模块>.cy.js 运行单个 spec;
  • test:*:通过 start-server-and-test 把"启动服务 + 等待 http://localhost:3000 就绪 + 跑 Cypress"串联成一条命令,例如 test:add-connection、test:charts、test:redis、test:ai-chat。

根目录 package.json 中的 cy:open 脚本则用于交互式打开 Cypress 调试。运行配置见 e2e-tests/cypress.config.js:setupNodeEvents 在 before:spec 阶段按 spec 文件名自动拉起对应的 start:* 服务并 waitOn 端口 3000,测试截图统一落盘到 e2e-tests/screenshots/。CI 侧由 workflow-templates/e2e-pro.yaml 执行 yarn test:ci(等价于全部 test:* 串行),失败截图会上传为构建产物。

五、规则五:storageModel.js 的生成文件保护

5.1 规则内容

AGENTS.md 第 9 行:不要修改 storageModel.js 的内容——它是由 table YAML 通过 yarn storage-json 命令生成的。

5.2 生成链路验证

根目录 package.json 第 48 行定义了生成命令:

"storage-json": "node packages/dbmodel/bin/dbmodel.js model-to-json storage-db packages/api/src/storageModel.js --commonjs"

链路为:packages/dbmodel/bin/dbmodel.js 的 model-to-json <modelFolder> <jsonFile> 子命令(第 151–162 行)→ 调用 dbgateApi.dbModelToJson({ modelFolder, outputFile, commonjs }),将 storage-db 目录下的表模型(YAML/JSON 定义)转换为 CommonJS 模块。产物 packages/api/src/storageModel.js 是一个约 2800 行的 module.exports = { "tables": [...] } 文件,其中每个表都包含列名、数据类型、自增、非空约束等完整结构描述(如 audit_log 表的 id/created/modified/user_id 等列定义)。

5.3 对 Agent 的实操意义

这条规则的本质是**"改源头,不改进程产物"**:如果存储模型需要调整(新增表、改列类型等),正确做法是修改 storage-db 下的表模型定义,然后重新运行 yarn storage-json 再生成一次。直接手改生成的 JSON 文件,改动会在下次生成时被覆盖,且容易与模型定义产生不一致。同理,dbmodel.js 还提供了反向命令 json-to-model <jsonFile> <modelFolder>(第 140–148 行),用于把 JSON 模型还原为目录结构,方便在两个形态之间迁移。

六、给 Agent 的落地清单:如何在 dbgate 中安全地改动代码

综合 AGENTS.md 五条规则与仓库实现,可提炼出一份可直接执行的检查清单:

  1. 新增任何报错/日志消息:一律写成 DBGM-00000 ... 占位符,不要自编号;提交前用 node common/assign-dbgm-codes.mjs . 统一分配,并用 --dry 先审阅影响面;若错误消息被测试断言引用(如 credentials.test.js),需同步核对。
  2. GUI 改动:仅限 packages/web,使用 Svelte4 语法,组件放入语义对应子目录。
  3. 新增交互元素:为关键按钮、输入框、链接等打上 data-testid,格式严格为 组件名_标识符(动态场景可用有意义的枚举后缀),并保证 E2E 测试中能通过 cy.get('[data-testid=...]') 稳定定位。
  4. E2E 验证:新功能优先考虑补充或扩展现有 e2e-tests/cypress/e2e/*.cy.js,本地可运行 yarn test:<模块> 或 yarn cy:open 验证,避免破坏 CI 中的 yarn test:ci 全量链路。
  5. 存储模型相关改动:只改 storage-db 下的模型定义,再执行 yarn storage-json 重新生成 packages/api/src/storageModel.js,绝不直接手改生成文件。

结语

AGENTS.md 虽短,却是 dbgate 团队把工程纪律"机器可读化"的缩影:占位符 + 脚本自动分配的错误码体系消除了并行协作的编号冲突,data-testid 统一命名让组件与测试形成可双向追溯的契约,生成文件保护避免了手改产物带来的模型漂移。对任何准备向 dbgate 贡献代码的开发者或 AI Agent 而言,先读懂这五条规则,就是避免无效返工的第一步。

登录后查看全文
dbgate