AutoGPT Platform 协作贡献指南:目录结构、代码规范、测试流程与 PR 约定全解

本文基于仓库根目录的 AGENTS.md(AutoGPT Platform Contribution Guide)展开,面向所有修改 autogpt_platform 目录的开发者与 AI 编码 Agent。读完后,你将掌握:平台四大目录的职责划分、前后端格式化与 lint 管线的底层实现、前端页面/组件的标准文件结构、Orval 生成式 API Hook 的命名与再生成方式、前后端测试命令背后的隔离机制,以及 Conventional Commits 与 Pull Request 的硬性规则。

1. 指南定位:为谁写的"平台改动说明书"

AGENTS.md 开篇明确声明:本文档为编码 Agent 更新 autogpt_platform 目录时提供上下文。它不是一份泛泛的社区规范,而是把"改平台代码前必须知道的事"压缩成四块:

1. 目录总览 —— 改之前先知道文件在哪个子系统;
2. 代码风格 —— 前后端各自的格式化命令;
3. 前端指南 —— 页面、组件、数据获取、样式、测试、代码约定的快速参考;
4. 测试、提交与 PR 流程 —— 提交前必须跑什么、commit message 怎么写、PR 有哪些硬性检查项。

平台环境搭建细节可参考 docs/platform/getting-started.md。

2. 目录总览:autogpt_platform 的四大子系统

AGENTS.md 给出的目录结构如下,四者共同构成一个可本地开发的多服务栈:

目录/文件	职责
autogpt_platform/backend	基于 FastAPI 的后端服务(含 blocks、executor、api、cli 等模块)
autogpt_platform/autogpt_libs	共享 Python 库(认证、日志、KeySmith 密钥工具等)
autogpt_platform/frontend	Next.js + TypeScript 前端
autogpt_platform/docker-compose.yml	开发环境服务栈

后端以 Poetry 项目管理,autogpt_platform/backend/pyproject.toml 中注册了大量可直接调用的可执行入口,例如 app(FastAPI 主服务)、executor(图执行器)、format/lint(代码风格)、test(测试入口)、prisma 相关的 gen-prisma-stub 等。autogpt_libs 以本地路径依赖的方式被后端引用(autogpt-libs = { path = "../autogpt_libs", develop = true }),这意味着改共享库会同时影响后端,提交前需要两边都通过检查。

仓库根 autogpt_platform/Makefile 进一步把这些常用操作固化成 target:start-core(只起 Postgres/Redis/RabbitMQ)、migrate、format(后端 poetry run format + 前端 pnpm format/pnpm lint)、run-backend、run-frontend、reset-db 等,是日常开发的高频入口。

3. 代码风格:两条格式化管线的底层实现

AGENTS.md 给出两条命令:

• 后端(Python):poetry run format
• 前端(TypeScript):pnpm format

这两条命令背后各自是一条多阶段管线,理解它才能知道"format 到底做了什么"。

3.1 后端:poetry run format 的五步管线

format 入口指向 backend/scripts/linter.py 的 format() 函数,它依次执行:

ruff check --fix . ../autogpt_libs   # 1. 自动修复 lint 问题
ruff format ../autogpt_libs          # 2. ruff 格式化共享库
isort --profile black .               # 3. 导入排序(black 风格)
black .                               # 4. black 格式化后端
gen-prisma-stub                      # 5. 生成 Prisma 类型桩
pyright . ../autogpt_libs             # 6. 类型检查

lint() 函数(linter.py)则是只检查不修改的版本:ruff check、ruff format --check、isort --check、black --check 与 pyright 全部通过后才算通过;任一失败会提示 Lint failed, try running 'poetry run format' to fix the issues。值得注意的是,格式化与 lint 同时覆盖 . 和 ../autogpt_libs 两个目录——这与第 2 节中"共享库被后端以 develop 模式引用"的结构相呼应。

gen-prisma-stub 步骤的注释说明了原因:先于 pyright 生成 Prisma 类型桩,是为了"防止类型检查预算耗尽"(prevent type budget exhaustion),即 Prisma 客户端生成的类型体积庞大,需要先产出精简 stub 再做全量类型检查。

3.2 前端:pnpm format 与配套脚本

autogpt_platform/frontend/package.json 中定义:

"format": "next lint --fix; prettier --write .",
"lint":   "next lint && prettier --check .",
"types":  "tsc --noEmit"

前端贡献文档建议提交前跑 pnpm format && pnpm lint && pnpm types 三连(frontend/CONTRIBUTING.md),分别覆盖"修复格式"、"只检查格式"与"TypeScript 类型检查"。

4. 前端指南:页面、组件与数据获取的硬约定

AGENTS.md 的 Frontend guidelines 是"快速参考",完整模式在 autogpt_platform/frontend/CONTRIBUTING.md。下面逐条继承其要求并补充仓库佐证。

4.1 页面:标准三件套目录

新建页面放在 src/app/(platform)/feature-name/page.tsx,配套约定:

1. 有逻辑的页面旁边加 useXxxPage.ts hook(业务逻辑与渲染分离);
2. 子组件放入页面局部的 components/ 目录;
3. 需要鉴权的页面必须位于 (platform) 路由组内。

示例结构(来自前端贡献文档):

app/(platform)/dashboard/
  page.tsx
  useDashboardPage.ts
  components/
    StatsPanel/
      StatsPanel.tsx
      useStatsPanel.ts

4.2 组件:ComponentName 目录 + Hook + helpers

组件按 ComponentName/ComponentName.tsx + useComponentName.ts + helpers.ts 组织;渲染逻辑与业务逻辑分离,状态尽量就近下沉(colocate state)。设计系统组件位于 src/components/(atom / molecule / organism 三级),严禁使用 src/components/__legacy__/*。

AGENTS.md 给出的代码约定清单(与前端贡献文档一致)值得完整对照执行:

• 组件 props 用 interface Props { ... },除非需要被外部引用,否则不导出;
• 组件与 handler 用函数声明(function declaration),箭头函数只用于回调;
• 状态就地放置,避免巨型组件,必要时拆入本地 components/ 子目录;
• hook 过大时把纯逻辑抽到 helpers.ts;
• 禁止 barrel 文件与 index.ts 再导出;
• 代码极复杂时才写注释;
• 不要主动使用 useCallback / useMemo,除非被要求做性能优化;
• hook 返回值交给 TypeScript 推断,不要手动标注类型;
• 永远不用 any,没有类型时退而求其次用 unknown。

4.3 数据获取:Orval 生成的 API Hook

所有 API Hook 由后端 OpenAPI 规范经 Orval 自动生成,放在 src/app/api/__generated__/endpoints/,命名模式为:

use{Method}{Version}{OperationName}

例如 GET /api/v2/library/agents 对应 useGetV2ListLibraryAgents,DELETE /api/v2/store/submissions/{id} 对应 useDeleteV2DeleteStoreSubmission。

典型用法(来自前端贡献文档):

import { useGetV2ListLibraryAgents } from "@/app/api/__generated__/endpoints/library/library";

export function useAgentList() {
  const { data, isLoading, isError, error } = useGetV2ListLibraryAgents();

  return {
    agents: data?.data || [],
    isLoading,
    isError,
    error,
  };
}

当后端接口变动时,在 frontend 目录执行 pnpm generate:api 重新生成。从 package.json 可确认该脚本的真实实现是:

"generate:api": "npx --yes tsx ./scripts/generate-api-queries.ts && orval --config ./orval.config.ts"

即先运行 scripts/generate-api-queries.ts 拉取/处理 OpenAPI 规范,再由 orval.config.ts 驱动 Orval 产出 typed client、React Query hooks 以及配套的 MSW mock handler(测试章节还会用到它)。pnpm dev 也会先执行 API 客户端再生成,保证开发服务器拿到最新 hook。

同时,贡献文档明确 BackendAPI 与 src/lib/autogpt-server-api/* 已视为废弃,不得新增使用。

4.4 样式与图标

• 只用 Tailwind CSS,优先使用 design tokens,Phosphor 图标(AGENTS.md 原文);
• 组件优先取用 src/components 设计系统,而不是直接引用底层 UI 原语。

需要注意一处文档间差异:AGENTS.md 写的是 "Phosphor Icons only",而 frontend/CONTRIBUTING.md 明确要求"只用 Hugeicons,且必须经由 Icon atom 渲染"。两者指向不同时期的图标库约定,实际动手前建议以设计系统 src/components/atoms/Icon/ 的现状与前端贡献文档为准,避免引入已被废弃的图标库。

4.5 测试与响应式基线

• 集成测试(Vitest + RTL + MSW)是默认测试形态(约占 90%,页面级),Playwright 用于关键 E2E 流程,Storybook 用于设计系统组件,详见 frontend/TESTING.md;
• 移动优先:从 375px 视宽(iPhone SE)起必须观感良好,并在 375 / 768 / 1024 / 1280 断点验证。

5. 测试体系:每条命令背后发生了什么

5.1 后端:poetry run test = Docker Postgres + Prisma + pytest

AGENTS.md 说后端测试"runs pytest with a docker based postgres + prisma"。其入口是 backend/scripts/run_tests.py 的 test() 函数,完整流程为:

1. docker compose -f docker-compose.test.yaml up -d 拉起专用测试库(定义见 docker-compose.test.yaml);
2. 轮询 pg_isready 等待 PostgreSQL 就绪(最多 5 次、每次间隔 5 秒);
3. 创建独立数据库 agpt_test,并显式将 DATABASE_URL / DIRECT_URL 指向它——源码注释强调这是"承重墙"式的安全措施:防止误把 prisma migrate reset --force 打到开发者的本地开发库上;
4. 对测试库执行 prisma migrate reset --force --skip-seed 后再 prisma migrate deploy,得到干净且最新的 schema;
5. 注入测试环境后运行 pytest(支持透传参数,如 poetry run test -k xxx);
6. 无论成败,最后 docker compose ... down 清理测试容器。

此外 pyproject.toml 的 pytest 配置也值得了解:asyncio_mode = "auto"、单条测试超过 5 分钟触发 faulthandler_timeout 转储线程栈(用于自证"挂死"而非"慢")、以及 supplementary / integration / slow 三个自定义 marker。

5.2 前端:集成测试与 E2E 的分工

类型	命令	说明
后端	poetry run test	pytest + Docker Postgres + Prisma
前端集成	pnpm test:unit	Vitest + React Testing Library + MSW(主力,vitest run --coverage)
前端 E2E	pnpm test 或 pnpm test-ui	Playwright,先执行生产构建再跑 8 个 *-happy-path.spec.ts 用例;test-ui 额外带 UI 面板
Storybook	pnpm storybook	设计系统组件本地预览

TESTING.md 给出集成测试的写法模板:用 @/tests/integrations/test-utils 的 render()(内置 QueryClientProvider 等 Provider),用 Orval 生成的 MSW handler(如 getGetV2ListLibraryAgentsMockHandler200())模拟接口,再用 screen.findByText 断言:

import { render, screen } from "@/tests/integrations/test-utils";
import { server } from "@/mocks/mock-server";
import { getGetV2ListLibraryAgentsMockHandler200 } from "@/app/api/__generated__/endpoints/library/library.msw";
import LibraryPage from "../page";

test("renders agent list", async () => {
  server.use(getGetV2ListLibraryAgentsMockHandler200());
  render(<LibraryPage />);
  expect(await screen.findByText("My Agents")).toBeDefined();
});

注意 pnpm test / pnpm test-ui 都会设置 NEXT_PUBLIC_PW_TEST=true——这正是前端贡献文档中提到的"本地开发与 Playwright 使用 mock feature flag 值"的开关。测试文件放在被测页面/组件旁边的 __tests__/ 目录,命名为 main.test.tsx、search.test.tsx 这类描述性名称。

AGENTS.md 还给出两条总原则:提交前必须跑相关 linter 和测试;遵循 TDD 工作流(先写失败测试 → 实现 → 去掉 .fixme 注解跑全量)。

6. 提交规范:Conventional Commits 的 Type 与 Scope 全集

AGENTS.md 要求所有 commit 使用 conventional commit message(例如 feat(backend): add API),并给出两套枚举,这是本仓库提交信息的完整合法取值表:

Types:

type	含义
feat	新功能
fix	修复
refactor	重构
ci	CI 相关
dx	开发者体验

Scopes: platform、platform/library、platform/marketplace、backend、backend/executor、frontend、frontend/library、frontend/marketplace、blocks。

scope 的粒度设计可以看出平台内部的模块边界:library 与 marketplace 是平台内两条独立产品线,backend/executor 单独成 scope 则对应 backend/exec.py 图执行器这一关键子系统。

7. Pull Request:硬性检查项

AGENTS.md 的 PR 章节与 .github/PULL_REQUEST_TEMPLATE.md 互为表里,合并前必须满足:

1. 使用 PR 模板:模板要求写清 Why / What / How,并勾选 Changes 与 Checklist。Checklist 区分"代码变更"(列变更、制定测试计划、按计划实测,模板内置示例:从零创建含 ≥3 个 block 的 agent 并执行、文件导入 agent、市场上传/导入、monitor 中编辑 agent 等)与"配置变更"(.env.default、docker-compose.yml 是否同步更新,配置变更清单必须写进 Changes);
2. 依赖 pre-commit 检查完成 lint 与格式化,不要绕过;
3. commit 标题带 scope 的 conventional 格式(如 feat(frontend): add feature);
4. 范围外改动控制在 PR 的 20% 以内——这是量化红线,超出的无关改动会被要求拆 PR;
5. PR 描述必须完整;
6. 触碰 data/*.py 时,必须验证 user ID 检查逻辑,或书面说明为何不需要。后端数据访问层(autogpt_platform/backend/data/)承担多租户隔离职责,这条规则对应其中按 user_id 过滤查询的普遍模式;
7. 新增受保护前端路由时,更新前端 middleware。AGENTS.md 原文写作 frontend/lib/supabase/middleware.ts;从当前仓库源码结构看,该文件位于 autogpt_platform/frontend/src/lib/auth/middleware.ts(路径已迁移,职责不变:对受保护路由做鉴权拦截);
8. 若提供了 Linear ticket,按 ticket 的分支结构命名分支(文档示例:codex/open-1668-resume-dropped-runs)。

8. 延伸阅读:按任务类型选读

任务	首选文档	佐证源码
改后端 Python 代码	AGENTS.md 第 3/5 节	backend/scripts/linter.py、backend/scripts/run_tests.py
改共享库 autogpt_libs	AGENTS.md 第 2 节	backend/pyproject.toml(develop 依赖)
新建前端页面/组件	frontend/CONTRIBUTING.md	frontend/package.json、frontend/orval.config.ts
写/修测试	frontend/TESTING.md、AGENTS.md 第 5 节	backend/conftest.py、docker-compose.test.yaml
提 PR	.github/PULL_REQUEST_TEMPLATE.md	AGENTS.md 第 7 节

9. 小结

AGENTS.md 用约 70 行文字划定了 AutoGPT Platform 的协作契约:目录先分清 backend / autogpt_libs / frontend 三层,风格上后端走 poetry run format(ruff + isort + black + pyright 管线)、前端走 pnpm format(ESLint + Prettier),测试上后端依赖 Docker 隔离测试库跑 pytest、前端以 Vitest+MSW 页面级集成测试为默认;提交与 PR 层面则以"Conventional Commits + 20% 范围红线 + data 层 user ID 校验 + 受保护路由 middleware 同步"作为硬性闸门。对编码 Agent 而言,把这份指南当作 autogpt_platform 的"操作手册",再按第 8 节的路由表深入具体文档,即可在不破坏现有架构的前提下安全地进行修改。