AutoGPT Platform 工程指南Monorepo 结构、环境配置机制与开发规范【免费下载链接】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本文以 AutoGPT 仓库中autogpt_platform目录下的开发者指南CLAUDE.md 仅包含一行AGENTS.md引用其实际内容即 autogpt_platform/AGENTS.md并向下引用 backend/AGENTS.md 与 frontend/AGENTS.md为骨架系统梳理 AutoGPT Platform 的 Monorepo 组成、环境变量分层机制、Docker Compose 服务编排以及分支策略、PR 规范、TDD 流程与前后端代码风格约定。读完本文你可以在不逐行翻找文档的情况下独立完成 Platform 的本地环境初始化、配置覆盖和服务启动。仓库结构三部分组成的 Monorepoautogpt_platform/AGENTS.md 开篇将 AutoGPT Platform 定义为一个 Monorepo包含三个主要部分Backendbackend/Python FastAPI 服务端支持异步Frontendfrontend/Next.js React 应用Shared Librariesautogpt_libs/通用 Python 工具库如 autogpt_libs/autogpt_libs/api_key/keysmith.py 密钥工具、auth 鉴权模块、logging 日志组件等。除三大主目录外autogpt_platform/下还有若干支撑目录可直接在仓库中查看db/数据库 Docker 编排与初始化脚本db/docker/docker-compose.yml、db/init/00-init.sqlsingle-container/单容器部署形态含 entrypoint.sh、supervisor 等installer/一键安装脚本setup-autogpt.sh、setup-autogpt.batgraph_templates/随仓库提供的 Agent 图模板如 Discord Bot Chat To LLM_v5.jsonanalytics/留存与用量分析的 SQL 查询集analytics/queries/。五个核心概念指南用五个术语概括了 Platform 的业务模型这是理解后文所有配置项的钥匙Agent Graphs代理图以 JSON 存储的工作流定义由后端执行仓库中 backend/agents/ 目录下保存了大量agent_*.json示例如 calculator-agent.json。Blocks块位于backend/blocks/的可复用组件每个块完成特定任务Integrations集成按用户存储的 OAuth 与 API 连接Store商店用于共享代理模板的市场Virus Scanning病毒扫描通过 ClamAV 集成保障文件上传安全——这一点在 docker-compose.yml 中有对应的clamav服务见下文。环境配置机制三层文件与四级加载顺序配置文件层级指南规定了三层环境配置文件每一层都是默认值文件 用户覆盖文件的成对结构作用域默认值文件纳入 git 跟踪用户覆盖文件gitignoreBackendbackend/.env.defaultbackend/.envFrontendfrontend/.env.defaultfrontend/.envPlatform 根.env.default.env仓库中的 Makefile 提供了init-env目标正是这一层级的落地命令init-env: cp -n .env.default .env || true cd backend cp -n .env.default .env || true cd frontend cp -n .env.default .env || truecp -n表示仅在目标不存在时拷贝因此首次执行会把三套默认值复制为.env之后用户的本地改动不会被覆盖——这就是默认值随仓库走、覆盖值留在本地的实现方式。Docker 环境加载顺序指南明确了 Docker 环境下配置的生效优先级从高到低应结合第 3、4 条理解.env.default文件提供基础配置跟踪在 git 中.env文件提供用户级覆盖gitignoreDocker Compose 的environment:段提供服务级覆盖Shell 环境变量拥有最高优先级。文档同时给出三条关键实现要点均可在 docker-compose.yml 中验证所有服务在 docker-compose 文件中都使用硬编码默认值不使用${VARIABLE}插值。例如db服务直接写死POSTGRES_USER: postgres与POSTGRES_PASSWORD: your-super-secret-and-long-postgres-passwordenv_file指令在运行时把变量加载进容器因此容器内实际生效的是文件变量与environment:段的组合结果Backend/Frontend 服务通过 YAML 锚点YAML anchors获得一致配置Supabase 数据库服务db/docker/docker-compose.yml也遵循同一模式。根级 .env.default数据库凭据的单一事实来源autogpt_platform/.env.default 全文只描述数据库凭据其注释明确说明这些值就是db服务在 docker-compose.yml 中硬编码的凭据如果改动请同步更新docker-compose.platform.yml的DATABASE_URL/DIRECT_URL、backend/.env(.default)与frontend/.env(.default)。内容如下POSTGRES_HOSTdb POSTGRES_DBpostgres POSTGRES_PORT5432 # default user is postgres POSTGRES_PASSWORDyour-super-secret-and-long-postgres-password文件头部还有一条醒目警告上生产环境前必须更换该密码。backend/.env.default关键变量逐项解读backend/.env.default 是 Platform 本地开发的核心配置清单按指南标注在 settings.py 中有可用默认值的变量不在此列出。以下摘录并解读关键分组原文含外部网址的注释行已省略数据库连接必填DB_USERpostgres DB_PASSyour-super-secret-and-long-postgres-password DB_NAMEpostgres DB_PORT5432 DB_HOSTlocalhost DB_CONNECTION_LIMIT12 DB_CONNECT_TIMEOUT60 DB_POOL_TIMEOUT300 DB_SCHEMAplatform DATABASE_URLpostgresql://${DB_USER}:${DB_PASS}${DB_HOST}:${DB_PORT}/${DB_NAME}?schema${DB_SCHEMA}connect_timeout${DB_CONNECT_TIMEOUT} DIRECT_URLpostgresql://${DB_USER}:${DB_PASS}${DB_HOST}:${DB_PORT}/${DB_NAME}?schema${DB_SCHEMA}connect_timeout${DB_CONNECT_TIMEOUT} PRISMA_SCHEMApostgres/schema.prisma注意DB_SCHEMAplatform与00-init.sql注释的对应关系docker-compose.yml 将 db/init/00-init.sql 挂载到/docker-entrypoint-initdb.d/在新卷上创建platformschema 及兼容历史 Prisma 迁移的auth.users兼容表DATABASE_URL与DIRECT_URL的区分是 Prisma 的经典做法——前者给连接池如 PgBouncer使用后者给 Prisma 迁移工具直连使用。中间件凭据必填REDIS_HOSTlocalhost REDIS_PORT17000 RABBITMQ_DEFAULT_USERrabbitmq_user_default RABBITMQ_DEFAULT_PASSk0VMxyIJF9S35f3x2uaw5IWAl6Y536O7Redis 集群三节点compose 中的redis-0/1/2通过 17000 端口暴露给宿主机RabbitMQ 是异步任务处理的队列见 backend/AGENTS.md 的 Architecture 一节。鉴权JWTJWT_JWKS_URLhttp://localhost:3000/api/auth/jwks # JWKS_ALLOW_INSECURE_TRANSPORTfalse JWT_VERIFY_KEYyour-super-secret-jwt-token-with-at-least-32-characters-long配置文件的注释交代了完整的安全语义JWT_JWKS_URL指向内嵌在前端的 Better Auth 服务的 JWKS 端点后端用 ES256 非对称签名校验 JWT由于后端信任该 URL 返回的一切签名密钥注释专门警告——本机与单主机容器间流量用 http 没问题如默认的http://frontend:3000但跨机器的不可信网络上必须用 https否则网络攻击者可替换密钥伪造令牌。为此提供JWKS_ALLOW_INSECURE_TRANSPORTfalse开关当JWT_JWKS_URL为指向非本地主机的明文 http 时后端默认拒绝启动。JWT_VERIFY_KEY是 HS256 共享密钥校验的遗留通道仅用于旧 Supabase GoTrue 会话仍在流通的过渡期之后可移除。加密与推送必填安全密钥ENCRYPTION_KEYdvziYgz0KSK8FENhju0ZYi8-fRTfAdlz6YLhdB_jhNw UNSUBSCRIBE_SECRET_KEYHlP8ivStJjmbf6NKi78m_3FnOogut0t5ckzjsIqeaio VAPID_PRIVATE_KEY17hBPdSdn6TR_yAgQxA0TjTcvRj3Lf6znHnASZ4HQQNLUeiEfzD42zWSlrvY1PR12bs VAPID_CLAIM_EMAILmailto:devexample.com注释给出了 Fernet 密钥的生成命令from cryptography.fernet import Fernet; Fernet.generate_key().decode()VAPID 密钥对Web Push 用附有一段 Python 生成脚本并明确标注以下为仅开发用密钥任何非本地部署前必须自行重新生成VAPID_CLAIM_EMAIL按 RFC 8292 在推送服务的 410 Gone 报告中被引用生产环境应设置为真实邮箱。AutoPilot 本地 LLM 路由CHAT_*CHAT_API_KEY CHAT_BASE_URL CHAT_USE_LOCALfalse这段注释是仓库内关于本地模型接入最完整的说明设置CHAT_USE_LOCALtrue后AutoPilot 会改走 OpenAI 兼容端点如宿主机上 Ollama 的http://host.docker.internal:11434/v1CHAT_API_KEY可为任意非空字符串CHAT_*_MODEL必须填本地后端提供的裸模型名如llama3.2:3bOpenRouter 风格的 provider/model 前缀无法解析扩展思考模式在该传输下会自动降级为 fast。另有一个重要的分层规则在托管云平台BEHAVE_AScloud下CHAT_*_MODEL是 AutoPilot 模型解析的最底层——backend/data/llm_registry/catalog.py 中的 LLM 目录路由表与每用户 LaunchDarkly 标志优先而在自托管安装中目录路由表被跳过这些环境变量保持权威地位。其余分组backend/.env.default 全文可查包括Graphiti/FalkorDB 时序知识图谱内存GRAPHITI_*、Langfuse 提示词管理、OAuth 凭据GitHub/Notion/Google/Twitter/Linear/Todoist/Discord/Reddit回调统一为frontend_url/auth/integrations/oauth_callback、Stripe 支付、Postmark 邮件、Sentry、LaunchDarkly 特性开关、各媒体/搜索服务 API Key、CoPilot 聊天桥接Discord/Slack/Telegram以及 PostHog 分析等——全部为按需填写、可留空的可选项。Docker Compose 服务拓扑锚点复用与启动门控docker-compose.yml 的结构本身就在演示指南所说的YAML 锚点获得一致配置x-agpt-services: agpt-services networks: - app-network - shared-network services: rest_server: : *agpt-services extends: file: ./docker-compose.platform.yml service: rest_server每个服务先合并agpt-services锚点统一挂载到app-network与shared-network两个网络再通过extends从 docker-compose.platform.yml 继承镜像、端口与依赖等细节。当前编排的完整服务清单为基础设施migratePrisma 迁移、redis-0/1/2redis-initRedis 集群、falkordbGraphiti 图数据库、rabbitmq、clamav、dbPostgres pgvector后端进程rest_server、executor、copilot_executor、websocket_server、database_manager、scheduler_server、notification_server、platform_linking_manager仅botprofile前端frontend本地编排辅助deps与deps_backend——仅localprofile 下生效的 busybox 服务command: /bin/true纯粹用depends_on形成依赖树便于一次性拉起整栈并等待就绪。两个值得注意的实现细节db服务的启动门控。注释说明db等待rabbitmq:service_healthy才启动原因是 E2B 环境中并发创建容器会与 RabbitMQ 写.erlang.cookie竞争导致 broker 启动时报eacces由于migrate与所有后端服务都depends_on db:service_healthy只门控db一个点就能级联到整栈。db镜像固定为pgvector/pgvector:pg15注释解释与生产和开发所跑的托管 Postgres 大版本保持一致测试比生产更新的版本是我们不想要的偏差。ClamAV 服务对应 AGENTS.md 中Virus Scanning概念使用clamav/clamav-debian:latest暴露 3310 端口关键限制参数为CLAMD_CONF_StreamMaxLength50M、MaxFileSize100M、MaxScanSize100M、MaxThreads12、ReadTimeout300健康检查执行clamdscan --version扫描数据持久化到clamav-data卷。常用 Make 目标Makefile 为日常操作提供了快捷入口目标作用make start-coredocker compose up -d deps仅后台启动核心服务Postgres/Redis/RabbitMQ 等依赖树make stop-coredocker compose stopmake reset-db停止 db、删除data/db/data卷然后依次执行prisma migrate deploy、prisma generate、gen-prisma-stubmake logs-core跟踪核心服务日志make format后端poetry run format 前端pnpm format/pnpm lintmake init-env三层.env.default→.env初始化见上节make migrate后端数据库迁移与 Prisma 类型生成make run-backendcd backend poetry run appmake run-frontendcd frontend pnpm devmake test-data运行测试数据创建脚本make load-store-agents将agents/目录中的商店代理加载进测试库分支策略与 Pull Request 规范分支策略指南将分支角色规定为两条主分支加一条例外通道dev是主开发分支所有 PR 都应指向devmaster是生产分支仅用于生产发布例外LLM 目录的纯目录差异仅改动backend/data/llm_registry/catalog.py可以走hotfix/*分支直接指向master用于事故级变更模型下线、路由切换合并即触发 CD 部署。完整参考文档是 docs/platform/contributing/managing-llm-models.md。PR 的 Why / What / How 结构创建 PR 时指南要求按关注点拆分 PR——每个 PR 只解决一个明确问题。例如用量跟踪和积分扣费即使相关也应拆成两个 PR混合关注点会让评审者难以判断各改动归属分支名要有描述性如feature/add-new-block提交信息遵循 Conventional Commits见下节PR 描述必须按 Why / What / How 组织——Why动机解决什么问题、缺了它会坏什么What变更的高层摘要How方案、关键实现细节或架构决策。评审者需要三者齐备才能判断方案是否匹配问题使用--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 保证代码质量PR 正文使用仓库内.github/PULL_REQUEST_TEMPLATE.md模板。Conventional Commits 规范提交信息与 PR 标题统一使用以下类型类型含义feat引入新功能fix修复缺陷refactor既非修 bug 也非加功能的重构移除功能也归此类ciCI 配置变更docs纯文档变更dx开发者体验改进推荐的基础 scope 有platform同时影响前后端、frontend、backend、infra、blocks单个块的增改并可进一步使用子 scope如backend/executor、backend/db、frontend/builder含块 UI 组件变更、infra/prod。测试驱动开发与测试约定三步 TDD 流程指南autogpt_platform/AGENTS.md 与 backend/AGENTS.md对修 bug 或加功能规定了统一的 test-first 流程先写一个失败的测试——复现 bug 或验证新行为后端标记pytest.mark.xfail、前端Playwright标记.fixme并运行确认它因正确的原因失败实现最小修复/功能让测试通过移除 xfail 标记跑完整测试套件确认没有破坏其他内容。backend/AGENTS.md 给出了具体示例# 1. 写一个标记 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. 运行它——确认失败XFAIL # poetry run pytest path/to/test.py::test_widget_handles_empty_input -xvs # 3. 实现修复 # 4. 移除 xfail 再跑——确认通过原则是每个 bug 修复都应附带一个本可以抓住该 bug 的测试。后端测试要点使用 pytest 快照测试API 响应测试文件与源码同目录*_test.py快照存放于 backend/snapshots/首次写测试或预期输出变化时用poetry run pytest path/to/test.py --snapshot-update更新快照提交前务必git diff复核在使用处而非定义处打 mock重构后同步更新 mock 目标模块路径异步函数用AsyncMock块Block有专门的验证测试poetry run pytest backend/blocks/test/test_block.py -xvs验证所有块正常工作也可单独跑test_available_blocks[GetCurrentTimeBlock]这样的参数化用例。前端完工前检查强制frontend/AGENTS.md 规定前端任何代码改动后报告完成、提交或开 PR 之前必须按顺序执行pnpm format—— 自动修复格式问题pnpm lint—— 修复出现的 lint 错误pnpm types—— 修复类型错误pnpm test:unit—— 运行集成测试并修复失败。任何一条报错都必须修到干净为止若类型检查持续失败指南要求停下来向用户求助而不是硬改。架构与代码风格约定后端架构backend/AGENTS.md 将后端架构概括为六条API 层FastAPI同时提供 REST 与 WebSocket 端点数据库PostgreSQL Prisma ORM含 pgvector 向量扩展——数据模型定义在 backend/schema.prisma关键模型包括User认证与档案、AgentGraph带版本控制的工作流定义、AgentGraphExecution执行历史与结果、AgentNode工作流中的单个节点、StoreListing商店上架迁移脚本位于 backend/migrations/百余个时间戳目录如 20241212141024_agent_store_v2队列系统RabbitMQ 处理异步任务执行引擎独立的 executor 服务进程处理代理工作流对应 compose 中的executor与copilot_executor两个服务认证基于 JWT配合前端内嵌的认证服务安全缓存保护中间件防止敏感数据被浏览器/代理缓存——位于backend/api/middleware/security.py默认对所有端点下发Cache-Control: no-store, no-cache, must-revalidate, private采用白名单方式CACHEABLE_PATHS显式放行可缓存路径静态资源、健康检查、公开商店页、文档同时应用于主 API 与外部 API 应用。后端代码风格后端规范中信息密度最高的几条仅顶层导入禁止函数内局部导入重型可选依赖如openpyxl除外跨包用绝对导入from backend.module import ...同包兄弟模块允许单点相对导入禁用双点相对导入禁止鸭子类型——不用hasattr/getattr/isinstance做类型分发改用类型化接口/联合类型/Protocol用 Pydantic 模型而非 dataclass/namedtuple/dict 承载结构化数据禁止 linter 抑制符——不写# type: ignore、# noqa、# pyright: ignore直接修类型/代码日志插值分场景——debug语句用%s延迟插值logger.debug(Processing %s items, count)其余场景用 f-string错误信息清洗路径——用os.path.basename()避免泄露目录结构TOCTOU 意识——文件访问与积分扣费避免 check-then-act 模式认证依赖用Security()而非Depends()以获得正确的 OpenAPI 安全声明Redis 管道多步操作用transactionTrue保证原子性SSE 协议——data:行承载前端解析的事件须匹配 Zod schema: comment行承载心跳/状态规模约束——文件控制在约 300 行内函数约 40 行内超限按职责拆分主函数/类置顶辅助函数放其下自顶向下阅读顺序。前端架构与风格frontend/AGENTS.md 描述的架构框架Next.js 15 App Routerclient-first数据获取Orval React Query 生成的类型安全 API hooks由pnpm generate:api从 OpenAPI 规格生成hook 命名模式use{Method}{Version}{OperationName}状态管理服务端状态交给 React QueryUI 状态就近放在组件/hooks组件结构渲染逻辑.tsx与业务逻辑use*.tshooks分离工作流编辑器基于 xyflow/react 的可视化图编辑器UIshadcn/uiRadix 原语 Tailwind CSS图标仅用 Hugeiconsstroke-rounded且必须经过Icon原子渲染——直接渲染HugeiconsIcon是禁止的原子负责应用 2px 设计系统线宽特性开关LaunchDarkly 集成错误处理分工渲染错误用 ErrorCardmutation 用 toast异常上报 Sentry测试矩阵Vitest React Testing Library MSW 的集成测试为主约 90%Playwright 负责 E2EStorybook 负责设计系统组件的可视化。前端代码风格要点符号中缩写词全大写graphID、useBackendAPI组件/处理器用函数声明而非箭头函数禁用dark:Tailwind 类深色模式由设计系统处理站内跳转必须用 Next.jsLink而非裸a文件控制在约 200 行、渲染函数与 hook 约 50 行内除非确实要求优化不用useCallback/useMemohook 返回值交给 TypeScript 推断而不显式标注避免索引文件与 barrel 文件。常见开发任务速查指南还内嵌了三个高频任务的操作路径均指向仓库内真实文件1. 新增/编辑/下线 LLM 模型模型定义、成本与 AutoPilot 路由以目录即代码形式存放在backend/data/llm_registry/catalog.py——改文件、开 PR目录是单一事实来源元数据与计费字典在 import 时从它派生。块可选模型还须在backend/data/llm_registry/llm_models.py加一行LLMModel名称import 时检查强制配对仅 copilot 用的模型只需目录条目。下线模型 目录 PRis_enabled: False 运行python -m backend.data.llm_registry.retire slug --replacement slug --yes迁移既有图节点默认 dry-run、可回滚。全文参考 docs/platform/contributing/managing-llm-models.md。2. 新增 Block按 docs/platform/block-sdk-guide.md 的完整流程在backend/blocks/建新文件 → 在_config.py用ProviderBuilder配置 provider → 继承Block基类 → 用BlockSchema定义输入输出 → 实现异步run方法 → 用uuid.uuid4()生成唯一块 ID → 跑poetry run pytest backend/blocks/test/test_block.py验证。指南特别提醒批量新增块时先审视各块接口在图编辑器里能否连得起来输入输出是否咬合。涉及文件处理的块应使用store_media_file()backend.util.file其return_format取for_local_processing返回本地路径供 ffmpeg/PIL 处理、for_external_api返回 data URI 供外部 API、for_block_output智能适配CoPilot 下返回workspace://图中返回 data URI——块输出应默认使用for_block_output不要手写 workspace 判断。3. 修改 API更新backend/api/features/中的路由 → 同目录更新 Pydantic 模型 → 路由旁写测试 →poetry run test验证。4. 涉及工作区与媒体文件时先读 docs/platform/workspace-media-architecture.md它覆盖WorkspaceManager会话级持久化存储、store_media_file()媒体归一化管线以及病毒扫描与持久化的职责边界——这与 backend/AGENTS.md 中 ClamAV 扫描、platform_linking等服务职责互相印证。小结autogpt_platform目录的开发者文档体系呈清晰的三层引用结构CLAUDE.md → AGENTS.mdMonorepo 总览、环境配置机制、分支与 PR 规范、TDD、Conventional Commits→ backend/AGENTS.md 与 frontend/AGENTS.md各侧命令、架构、代码风格与强制检查流程。配合 Makefile、docker-compose.yml、.env.default / backend/.env.default 等真实文件开发者可以获得从复制默认环境到跑测试、开 PR的完整闭环而配置加载顺序、硬编码默认值与 YAML 锚点这几条设计约定是理解整个 Platform 自托管部署行为的关键钥匙。【免费下载链接】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），仅供参考