AutoGPT Platform 开发协作规范：AGENTS.md 中的环境配置、分支策略与 Conventional Commits 实践

autogpt_platform/AGENTS.md 是 AutoGPT Platform 面向编码 Agent（Coding Agent）的顶层协作指南，它定义了该 monorepo 的模块划分、环境配置加载机制、分支与 Pull Request 流程、TDD 工作流以及 Conventional Commits 规范。读完本文，你将掌握在 AutoGPT Platform 仓库中安全地新增代码、配置环境、发起 PR 并保证变更可验证所需的完整规范体系，并能对照 后端指南 与 前端指南 深入具体技术栈。

一、仓库结构：一个 Backend / Frontend / 共享库三分的 Monorepo

AGENTS.md 开篇将 AutoGPT Platform 定义为一个包含三大组件的 monorepo：

组件	路径	技术栈
Backend	backend	Python FastAPI 服务器，支持异步
Frontend	frontend	Next.js React 应用
Shared Libraries	autogpt_libs	通用 Python 工具库

顶层 AGENTS.md 本身不重复各组件的细节，而是通过交叉引用把读者导向两份更细的子文档：

• Backend：见 backend/AGENTS.md，涵盖后端命令、架构与常见开发任务；
• Frontend：见 frontend/AGENTS.md，涵盖前端命令、架构与开发模式。

这种"总纲 + 分卷"的组织方式值得借鉴：顶层文档保持精简，只保留跨组件的约定（环境变量、分支、PR、提交规范），组件级细节下沉到各自目录，避免单文件过长。

从后端子文档的架构章节可以补充几个实现层面的事实：API 层为 FastAPI（REST + WebSocket），数据库是 PostgreSQL + Prisma ORM（含 pgvector），队列系统使用 RabbitMQ 做异步任务处理，执行引擎是独立的 executor 服务进程，认证基于 JWT 并与 Supabase 集成，安全层则由防缓存中间件保护敏感数据。这些与顶层文档中提到的五大核心概念一一对应。

二、核心领域概念

顶层 AGENTS.md 列出了理解这个平台必须掌握的五个核心概念：

1. Agent Graphs（代理图）：以 JSON 形式存储的工作流定义，由后端执行。对应 Prisma schema 中的 AgentGraph 模型（带版本控制），以及 AgentGraphExecution（执行历史与结果）、AgentNode（工作流中的单个节点），模型定义见 schema.prisma；
2. Blocks（块）：位于 backend/backend/blocks/ 的可复用组件，执行具体任务。新增块需遵循 Block SDK Guide（ProviderBuilder 配置、BlockSchema 输入输出定义、异步 run 方法等）；
3. Integrations（集成）：按用户存储的 OAuth 与 API 连接；
4. Store：用于分享代理模板的商城/市场，对应 StoreListing 模型；
5. Virus Scanning（病毒扫描）：通过 ClamAV 集成保障文件上传安全。

后端子文档还给出了数据库关键模型清单，可作为理解各概念的锚点：User（认证与个人资料）、AgentGraph、AgentGraphExecution、AgentNode、StoreListing。

三、环境配置机制（重点）

环境配置是顶层 AGENTS.md 篇幅最大的技术章节，它解释了三层配置文件如何协作、Docker 中的环境变量按什么顺序生效。这部分在仓库中有充分的配置证据可以印证。

3.1 配置文件分层：.env.default → .env

文档定义了"默认值文件 + 用户覆盖文件"的两层结构：

服务	默认文件（git 跟踪）	用户覆盖（gitignore）
Backend	backend/.env.default	backend/.env
Frontend	frontend/.env.default	frontend/.env
Platform（Supabase/共享）	.env.default	.env

仓库中的 Makefile 提供了 init-env 目标，正是这一分层约定的工程化落地——注意它使用 cp -n（不覆盖已存在的 .env）：

init-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.default：Platform 层，记录数据库凭据（POSTGRES_HOST、POSTGRES_PASSWORD 等），注释中明确要求上生产前修改密码，并说明若改动 docker-compose.yml 中的硬编码凭据，需同步更新 docker-compose.platform.yml 与前后端 .env(.default) 中的 DATABASE_URL / DIRECT_URL；
• backend/.env.default：后端层，包含数据库连接（DB_USER/DB_PASS/DB_CONNECTION_LIMIT=12/DB_CONNECT_TIMEOUT=60/DB_POOL_TIMEOUT=300）、Redis、RabbitMQ 凭据、JWT_JWKS_URL（Better 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 级优先级）

文档给出的加载顺序（从低到高）：

1. .env.default 文件提供基础配置（git 跟踪）；
2. .env 文件提供用户级覆盖（gitignored）；
3. Docker Compose 的 environment: 段提供特定服务的覆盖；
4. 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/ws

3.3 四个关键要点（Key Points）

顶层文档还总结了四个容易踩坑的要点，均有 compose 配置佐证：

• 所有服务在 docker-compose 文件中都使用硬编码默认值（不使用 ${VARIABLE} 替换）。例如 compose 文件中 DIRECT_URL 直接写死为 postgresql://postgres:...@db:5432/postgres?connect_timeout=60&schema=platform；
• env_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 都应指向 dev；
• master 是生产分支，仅用于生产发布；
• 例外：仅涉及 LLM catalog 的 diff（backend/data/llm_registry/catalog.py）可以走 hotfix/* 分支直接指向 master，用于事故级变更（模型下线、路由切换），合并即触发 CD 部署。该例外场景的完整参考见 Managing LLM Models——catalog 是单一事实源，模型元数据与计费字典都在导入时从它派生。

4.2 创建 PR 的六条规则

1. PR 目标分支为 dev；
2. 按关注点拆分 PR（Split PRs by concern）——每个 PR 只服务一个清晰目的。文档给出例子：即便"use tracking"与"credit charging"相互关联，也应拆成两个 PR，混合多个关注点会让审查者难以判断改动归属；
3. 分支名要描述性强，如 feature/add-new-block；
4. 使用 Conventional Commit 消息（见第六节）；
5. PR 描述按 Why / What / How 三段式组织——Why：动机（解决什么问题、缺了它会坏什么）；What：改动的高层摘要；How：实现方式、关键细节或架构决策。审查者需要三者齐备才能判断方案是否匹配问题；
6. 填写 .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 或加功能：

1. 先写一个失败的测试——复现 bug 或验证新行为，标记为 @pytest.mark.xfail（后端 pytest）或 .fixme（Playwright E2E），运行确认它因正确的原因失败；
2. 实现修复/功能——写让测试通过的最小代码；
3. 移除 xfail 标记——测试通过后去掉 xfail/.fixme 注解，再跑完整测试套件确认没有破坏其他东西。

这个流程保证每次变更都有测试覆盖，且测试确实验证了预期行为。后端子文档补充了配套细节，使该流程可操作：

• 快照测试用 poetry run pytest path/to/test.py --snapshot-update 生成/更新快照，提交前必须 git diff 审查快照变化（快照文件集中在 backend/snapshots/）；
• 测试文件与源码同目录存放（*_test.py），mock 打在使用符号的位置而非定义处，异步函数用 AsyncMock；
• 后端 TDD 示例代码：

# 1. Write a failing test marked xfail
@pytest.mark.xfail(reason="Bug #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	修复 bug
refactor	既不修 bug 也不加功能的代码变更；移除功能也归此类
ci	CI 配置变更
docs	仅文档变更
dx	开发者体验改进

推荐的基础 scope：

• platform：同时影响前后端的变更
• frontend
• backend
• infra
• blocks：单个块的新增/修改

子 scope 示例（用 / 表示更细的模块边界）：

• backend/executor
• backend/db
• frontend/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 run）：

poetry 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/Makefile）：make 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 的 hotfix），PR 与提交规范全部可机械执行（模板、命令、scope 清单）。对于同样采用 monorepo + 多服务 + CI/CD 的项目，这套"总纲 + 分卷 + 可执行命令"的组织方式值得直接参照。