dbgate 仓库的 AGENTS.md 深度解读:DBGM 错误码、Svelte4 GUI 与 Cypress E2E 协作规范
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/api/src/auth/authProvider.js 第 347 行:
logger.error(\DBGM-00000 Unknown AUTH_PROVIDER value "${authProvider}", all logins will be denied`)` - packages/api/src/codex/credentials.js 第 26、37、44、63、72 行:解密、读取、保存、删除 Codex 凭据失败时均抛出带
DBGM-00000前缀的 Error - packages/api/src/codex/oauth.js 第 33、54、115、128 行:Codex OAuth 相关错误同样使用占位符
而已经分配过正式编号的错误码也不在少数,例如 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 占位符批量替换为全局唯一的新编号。其核心逻辑:
- 递归扫描:遍历指定目录下所有
.mjs/.cjs/.js/.ts/.jsx/.tsx文件,自动跳过node_modules、.git、dist、build等目录以及脚本自身、package.json、README.md(第 10–22 行); - 收集已占用的编号:用正则
DBGM-(\d{5})提取全仓库所有已分配的错误码数字部分(第 7、76–78 行); - 分配最小可用编号:
makeNextCodeFn从 1 开始递增,找出第一个未被占用的正整数并格式化为DBGM-NNNNN(第 43–61 行),保证分配结果全局唯一且紧凑; - 原地替换:对每个含占位符的文件执行
replaceAll,将占位符逐一替换为下一个可用编号(第 106–109 行); - 支持 --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 五条规则与仓库实现,可提炼出一份可直接执行的检查清单:
- 新增任何报错/日志消息:一律写成
DBGM-00000 ...占位符,不要自编号;提交前用node common/assign-dbgm-codes.mjs .统一分配,并用--dry先审阅影响面;若错误消息被测试断言引用(如 credentials.test.js),需同步核对。 - GUI 改动:仅限
packages/web,使用 Svelte4 语法,组件放入语义对应子目录。 - 新增交互元素:为关键按钮、输入框、链接等打上
data-testid,格式严格为组件名_标识符(动态场景可用有意义的枚举后缀),并保证 E2E 测试中能通过cy.get('[data-testid=...]')稳定定位。 - E2E 验证:新功能优先考虑补充或扩展现有
e2e-tests/cypress/e2e/*.cy.js,本地可运行yarn test:<模块>或yarn cy:open验证,避免破坏 CI 中的yarn test:ci全量链路。 - 存储模型相关改动:只改
storage-db下的模型定义,再执行yarn storage-json重新生成 packages/api/src/storageModel.js,绝不直接手改生成文件。
结语
AGENTS.md 虽短,却是 dbgate 团队把工程纪律"机器可读化"的缩影:占位符 + 脚本自动分配的错误码体系消除了并行协作的编号冲突,data-testid 统一命名让组件与测试形成可双向追溯的契约,生成文件保护避免了手改产物带来的模型漂移。对任何准备向 dbgate 贡献代码的开发者或 AI Agent 而言,先读懂这五条规则,就是避免无效返工的第一步。