AutoGPT Platform 开发协作规范AGENTS.md 中的环境配置、分支策略与 Conventional Commits 实践【免费下载链接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.项目地址: https://gitcode.com/GitHub_Trending/au/AutoGPTautogpt_platform/AGENTS.md是 AutoGPT Platform 面向编码 AgentCoding Agent的顶层协作指南它定义了该 monorepo 的模块划分、环境配置加载机制、分支与 Pull Request 流程、TDD 工作流以及 Conventional Commits 规范。读完本文你将掌握在 AutoGPT Platform 仓库中安全地新增代码、配置环境、发起 PR 并保证变更可验证所需的完整规范体系并能对照 后端指南 与 前端指南 深入具体技术栈。一、仓库结构一个 Backend / Frontend / 共享库三分的 MonorepoAGENTS.md 开篇将 AutoGPT Platform 定义为一个包含三大组件的 monorepo组件路径技术栈BackendbackendPython FastAPI 服务器支持异步FrontendfrontendNext.js React 应用Shared Librariesautogpt_libs通用 Python 工具库顶层 AGENTS.md 本身不重复各组件的细节而是通过交叉引用把读者导向两份更细的子文档Backend见 backend/AGENTS.md涵盖后端命令、架构与常见开发任务Frontend见 frontend/AGENTS.md涵盖前端命令、架构与开发模式。这种总纲 分卷的组织方式值得借鉴顶层文档保持精简只保留跨组件的约定环境变量、分支、PR、提交规范组件级细节下沉到各自目录避免单文件过长。从后端子文档的架构章节可以补充几个实现层面的事实API 层为 FastAPIREST WebSocket数据库是 PostgreSQL Prisma ORM含 pgvector队列系统使用 RabbitMQ 做异步任务处理执行引擎是独立的 executor 服务进程认证基于 JWT 并与 Supabase 集成安全层则由防缓存中间件保护敏感数据。这些与顶层文档中提到的五大核心概念一一对应。二、核心领域概念顶层 AGENTS.md 列出了理解这个平台必须掌握的五个核心概念Agent Graphs代理图以 JSON 形式存储的工作流定义由后端执行。对应 Prisma schema 中的AgentGraph模型带版本控制以及AgentGraphExecution执行历史与结果、AgentNode工作流中的单个节点模型定义见 schema.prismaBlocks块位于backend/backend/blocks/的可复用组件执行具体任务。新增块需遵循 Block SDK GuideProviderBuilder配置、BlockSchema输入输出定义、异步run方法等Integrations集成按用户存储的 OAuth 与 API 连接Store用于分享代理模板的商城/市场对应StoreListing模型Virus Scanning病毒扫描通过 ClamAV 集成保障文件上传安全。后端子文档还给出了数据库关键模型清单可作为理解各概念的锚点User认证与个人资料、AgentGraph、AgentGraphExecution、AgentNode、StoreListing。三、环境配置机制重点环境配置是顶层 AGENTS.md 篇幅最大的技术章节它解释了三层配置文件如何协作、Docker 中的环境变量按什么顺序生效。这部分在仓库中有充分的配置证据可以印证。3.1 配置文件分层.env.default→.env文档定义了默认值文件 用户覆盖文件的两层结构服务默认文件git 跟踪用户覆盖gitignoreBackendbackend/.env.defaultbackend/.envFrontendfrontend/.env.defaultfrontend/.envPlatformSupabase/共享.env.default.env仓库中的 Makefile 提供了init-env目标正是这一分层约定的工程化落地——注意它使用cp -n不覆盖已存在的.envinit-env: cp -n .env.default .env || true cd backend cp -n .env.default .env || true cd frontend cp -n .env.default .env || true三个.env.default文件在仓库中真实存在且内容即文档所述基础默认值autogpt_platform/.env.defaultPlatform 层记录数据库凭据POSTGRES_HOST、POSTGRES_PASSWORD等注释中明确要求上生产前修改密码并说明若改动 docker-compose.yml 中的硬编码凭据需同步更新docker-compose.platform.yml与前后端.env(.default)中的DATABASE_URL/DIRECT_URLbackend/.env.default后端层包含数据库连接DB_USER/DB_PASS/DB_CONNECTION_LIMIT12/DB_CONNECT_TIMEOUT60/DB_POOL_TIMEOUT300、Redis、RabbitMQ 凭据、JWT_JWKS_URLBetter Auth 服务的 JWKS 端点、ENCRYPTION_KEY、UNSUBSCRIBE_SECRET_KEY、VAPID 推送密钥以及各类可选的 LLM/OAuth API 密钥frontend/.env.default前端层包含BETTER_AUTH_SECRET、NEXT_PUBLIC_AGPT_SERVER_URL、NEXT_PUBLIC_AGPT_WS_SERVER_URL等。后端.env.default的头部注释还说明了一个重要的设计原则在settings.py中已有可用默认值的变量不会出现在.env.default里该文件只包含必须设置的变量。这对自托管者很有参考价值先读默认文件再按需覆写。3.2 Docker 环境加载顺序4 级优先级文档给出的加载顺序从低到高.env.default文件提供基础配置git 跟踪.env文件提供用户级覆盖gitignoredDocker Compose 的environment:段提供特定服务的覆盖Shell 环境变量具有最高优先级。这一顺序在 docker-compose.platform.yml 中可以直接验证。文档中说的.env可选覆盖对应 compose 文件里带required: false的锚点定义# Common env_file configuration for backend services x-backend-env-files: backend-env-files env_file: - backend/.env.default # Base defaults (always exists) - path: backend/.env # User overrides (optional) required: false前端服务同样按先默认、后覆盖加载environment:段则负责容器内网络地址的替换Docker 服务名覆盖 env 文件中的 localhost 地址# Load environment variables in order (later overrides earlier) env_file: - path: ./frontend/.env.default # Base defaults (always exists) - path: ./frontend/.env # User overrides (optional) required: false environment: # Server-side environment variables (Docker service names) # These override the localhost URLs from env files when running in Docker AGPT_SERVER_URL: http://rest_server:8006/api AGPT_WS_SERVER_URL: ws://websocket_server:8001/ws3.3 四个关键要点Key Points顶层文档还总结了四个容易踩坑的要点均有 compose 配置佐证所有服务在 docker-compose 文件中都使用硬编码默认值不使用${VARIABLE}替换。例如 compose 文件中DIRECT_URL直接写死为postgresql://postgres:...db:5432/postgres?connect_timeout60schemaplatformenv_file指令在运行时把变量加载进容器——它负责的是容器内可见哪些变量而不是在 compose 解析阶段做插值Backend/Frontend 服务通过 YAML 锚点如x-backend-env-files、x-redis-node、x-agpt-services实现配置一致性docker-compose.yml 还大量使用extends继承docker-compose.platform.yml中的服务定义Supabase 服务db/docker/docker-compose.yml遵循同样的模式——默认文件进 git、.env做本地覆盖。理解这四点的实际收益是排查为什么我在.env里改了值却没生效时应依次检查 env_file 是否被environment:段或 shell 变量覆盖而排查为什么容器连不上 localhost时应记住environment:段会把 localhost 地址替换为容器网络内的服务名。四、分支策略与 Pull Request 流程4.1 分支策略dev主开发、master生产、hotfix/*例外文档规定dev是主开发分支所有 PR 都应指向devmaster是生产分支仅用于生产发布例外仅涉及 LLM catalog 的 diffbackend/data/llm_registry/catalog.py可以走hotfix/*分支直接指向master用于事故级变更模型下线、路由切换合并即触发 CD 部署。该例外场景的完整参考见 Managing LLM Models——catalog 是单一事实源模型元数据与计费字典都在导入时从它派生。4.2 创建 PR 的六条规则PR 目标分支为dev按关注点拆分 PRSplit PRs by concern——每个 PR 只服务一个清晰目的。文档给出例子即便use tracking与credit charging相互关联也应拆成两个 PR混合多个关注点会让审查者难以判断改动归属分支名要描述性强如feature/add-new-block使用 Conventional Commit 消息见第六节PR 描述按 Why / What / How 三段式组织——Why动机解决什么问题、缺了它会坏什么What改动的高层摘要How实现方式、关键细节或架构决策。审查者需要三者齐备才能判断方案是否匹配问题填写 .github/PULL_REQUEST_TEMPLATE.md 模板作为 PR 描述。模板文件与文档描述完全对应包含 Why/What/How 注释、Changes 清单以及两组 Checklist代码变更需列出测试计划模板自带示例从零创建含至少 3 个块的 agent 并执行、上传/导入 marketplace 验证等配置变更需确认.env.default与docker-compose.yml已同步更新并在 PR 描述中列出配置变更清单。文档特别强调用--body-file传 PR 正文以避免 shell 对反引号和特殊字符的解析PR_BODY$(mktemp) cat $PR_BODY PREOF ## Summary - use backticks freely here PREOF gh pr create --title ... --body-file $PR_BODY --base dev rm $PR_BODY最后一条提交前运行 GitHub pre-commit hooks 保证代码质量。五、测试驱动开发TDD先用会失败的测试钉住行为顶层 AGENTS.md 给出的三步法适用于修 bug 或加功能先写一个失败的测试——复现 bug 或验证新行为标记为pytest.mark.xfail后端 pytest或.fixmePlaywright E2E运行确认它因正确的原因失败实现修复/功能——写让测试通过的最小代码移除 xfail 标记——测试通过后去掉xfail/.fixme注解再跑完整测试套件确认没有破坏其他东西。这个流程保证每次变更都有测试覆盖且测试确实验证了预期行为。后端子文档补充了配套细节使该流程可操作快照测试用poetry run pytest path/to/test.py --snapshot-update生成/更新快照提交前必须git diff审查快照变化快照文件集中在 backend/snapshots/测试文件与源码同目录存放*_test.pymock 打在使用符号的位置而非定义处异步函数用AsyncMock后端 TDD 示例代码# 1. Write a failing test marked xfail pytest.mark.xfail(reasonBug #1234: widget crashes on empty input) def test_widget_handles_empty_input(): result widget.process() assert result Widget.EMPTY_RESULT # 2. Run it — confirm it fails (XFAIL) # poetry run pytest path/to/test.py::test_widget_handles_empty_input -xvs # 3. Implement the fix # 4. Remove xfail, run again — confirm it passes前端侧则要求新页面/功能默认先写 Vitest React Testing Library MSW 的集成测试约占 90%E2E 用 Playwright组件视觉用 Storybook详见 frontend/TESTING.md 与 backend/TESTING.md。六、Conventional Commits类型、基础 scope 与子 scope提交消息与 PR 标题统一采用 Conventional Commits 格式。类型Type类型含义feat引入新功能fix修复 bugrefactor既不修 bug 也不加功能的代码变更移除功能也归此类ciCI 配置变更docs仅文档变更dx开发者体验改进推荐的基础 scopeplatform同时影响前后端的变更frontendbackendinfrablocks单个块的新增/修改子 scope 示例用/表示更细的模块边界backend/executorbackend/dbfrontend/builder包含 block UI 组件的改动infra/prod文档要求在所有提交消息中统一使用这些 scope 与子 scope以保证一致性——结合分支策略看scope 也是审查者快速定位这次改动会动到 executor 还是 db 层的索引。七、PR 审查与回应评论文档推荐两个快捷命令/pr-review审查 PR/pr-address回应评论。手动拉取评论时给出三条gh api调用注意 inline 评论必须翻页否则会漏掉第一页之后的内容# 顶层 reviews gh api repos/{owner}/{repo}/pulls/{N}/reviews --paginate # inline review comments务必翻页 gh api repos/{owner}/{repo}/pulls/{N}/comments --paginate # PR 会话评论 gh api repos/{owner}/{repo}/issues/{N}/comments八、实操速查把规范串成一条工作流结合顶层规范与两份子文档在 AutoGPT Platform 中做一轮完整变更的标准动作如下后端所有带 Python 依赖的操作必须走poetry runpoetry install # 安装依赖 poetry run prisma migrate dev # 数据库迁移 docker compose up -d # 启动 db、redis、rabbitmq、clamav poetry run app # 运行后端 poetry run test # 运行测试 poetry run pytest path/to/test.py::test_name # 单个测试 poetry run format # Black isort优先用它直接修好 poetry run lint # ruff前端任何代码改动后必须按顺序跑完全绿才算完成pnpm i # 安装依赖 pnpm dev # 开发服务器 pnpm generate:api # 从 OpenAPI spec 重新生成类型安全的 API 客户端 pnpm format # 1. 自动修复格式 pnpm lint # 2. 修复 lint 错误 pnpm types # 3. 修复类型错误 pnpm test:unit # 4. 运行集成测试并修复失败仓库级 Makefile 目标见 autogpt_platform/Makefilemake start-core仅启动 Postgres/Redis/RabbitMQ、make init-env生成三个.env、make migrate迁移 prisma generate 生成 Prisma stub、make run-backend/make run-frontend、make test-data造测试数据、make load-store-agents把agents/目录的 agent 载入测试库。流程上的硬性约定从dev切出描述性分支如feature/add-new-block→ 按 TDD 三步法实现 → 跑 pre-commit hooks → 按 Why/What/How 填写 PR 模板、用--body-file提交 PR 指向dev→ 标题使用 Conventional Commit含 scope。九、小结autogpt_platform/AGENTS.md 的写法本身也有参考价值它把给 AI 编码助手看的协作规范当作一等公民文档来维护——模块边界用交叉引用而非复制环境配置讲清 4 级加载优先级并给出 compose 锚点级的实现佐证分支策略明确唯一的例外路径LLM catalog 的 hotfixPR 与提交规范全部可机械执行模板、命令、scope 清单。对于同样采用 monorepo 多服务 CI/CD 的项目这套总纲 分卷 可执行命令的组织方式值得直接参照。【免费下载链接】AutoGPTAutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.项目地址: https://gitcode.com/GitHub_Trending/au/AutoGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考