AutoGPT Store 后端模块解析routes、model、db 与 media 四层实现剖析【免费下载链接】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 Platform 后端 Store 模块 README 为骨架系统讲解 AutoGPT Store应用市场后端 API 的分层设计routes.py路由层、model.py校验层、db.py数据访问层与media.py媒体上传层的职责划分与真实实现。读完本文你将能掌握 Store API 的完整端点地图含 README 未覆盖的统一混合搜索、AI 图片生成、缓存指标等端点、媒体上传的安全校验细节MIME 魔数双重校验、50MB 限制、病毒扫描以及分页/排序/过滤参数的默认值与取值约束从而能够基于该模块开发对接、调试或扩展 Store 功能。模块总览一个目录如何撑起整个应用市场README 开篇给出了模块定位Store 模块实现了 AutoGPT Store 的后端 API负责 agentsAgent 列表、creators创作者、profiles用户档案、submissions提交审核以及 media uploads媒体上传。从目录结构看该模块位于 autogpt_platform/backend/backend/api/features/storeREADME 提及的四个核心文件之外当前仓库还演化出了若干配套文件文件README 中的定位当前仓库的实际职责routes.pyFastAPI 路由处理619 行含 Profile / Search / Agent / Creator / Submissions / Cache Metrics 六组端点model.pyPydantic 请求/响应模型410 行含分页模型、提交请求体、管理端视图、统一搜索响应db.pyPrisma ORM 数据库访问1948 行承载全部业务查询与数据校验逻辑media.pyGCS 媒体上传204 行含魔数校验、大小限制、病毒扫描、GCS 异步上传此外README 未列出但已实际存在的文件还包括 cache.py四个带 TTL 的共享缓存装饰封装、exceptions.py自定义异常层次、embeddings.py 与 hybrid_search.py混合检索实现、image_gen.py基于图属性的 AI 封面图生成。从源码结构看README 是对早期四文件结构的描述后续迭代将缓存、搜索、异常拆分为独立文件这是理解文档描述 vs 当前实现差异的关键前提。模块的主要测试文件为 routes_test.py853 行、db_test.py1142 行与 media_test.py可作为行为验证的直接依据。routes.py端点分组、认证标签与路由细节README 将routes.py概括为四类端点Profile、Agent、Creator、Store submission、Media upload。当前实现的routes.py以fastapi.APIRouter()定义路由并划分为六个区段其中前四类与 README 一一对应统一搜索Search与缓存指标Cache Management是文档未提及的新增区段。认证模型public 与 private 标签README 的 Authentication 一节说明大部分端点需要通过 AutoGPT 认证中间件鉴权公开端点带 public 标签。在routes.py中这体现为两类 FastAPI 标签与Security依赖的组合私有端点tags[store, private]dependencies[Security(autogpt_libs.auth.requires_user)]并通过user_id: str Security(autogpt_libs.auth.get_user_id)注入当前用户 ID公开端点tags[store, public]不声明requires_user依赖。以GET /profile为例routes.pyrouter.get( /profile, summaryGet user profile, tags[store, private], dependencies[Security(autogpt_libs.auth.requires_user)], ) async def get_profile( user_id: str Security(autogpt_libs.auth.get_user_id), ) - store_model.ProfileDetails: Get the profile details for the authenticated user. profile await store_db.get_user_profile(user_id) if profile is None: raise NotFoundError(User does not have a profile yet) return profile未注册档案的用户会收到NotFoundError映射为 404。POST /profile则调用store_db.update_profile实现更新或创建语义返回ProfileDetails。Agent 端点列表、详情、版本与下载GET /agentsroutes.py是市场列表的核心端点其查询参数在 README分页列表之外给出了完整约束参数类型默认值说明featuredboolFalse仅返回精选 Agentcreatorstr | NoneNone按创作者用户名过滤categorystr | NoneNone按分类过滤search_querystr | NoneNone名称与描述上的字面 语义混合搜索sorted_byStoreAgentsSortOptions| NoneNone排序字段提供search_query时排序被忽略按相关性pageint1页码ge1page_sizeint20每页条数ge1端点 docstring 明确了它的六类消费场景首页精选/热门、搜索结果、Agent 详情页的同创作者其他 Agent 与相似 Agent、创作者详情页。请求并不直接打到数据库而是先进入 cache.py 的共享缓存cached(maxsize5000, ttl_seconds300, shared_cacheTrue) async def _get_cached_store_agents( featured: bool, creator: str | None, sorted_by: store_db.StoreAgentsSortOptions | None, search_query: str | None, category: str | None, page: int, page_size: int, ): Cached helper to get store agents. return await store_db.get_store_agents(...)也就是说不同查询组合对应不同缓存条目Agent 列表与创作者列表缓存 5 分钟ttl_seconds300Agent 详情缓存同样 300 秒、maxsize200。缓存层还有clear_all_caches()统一清空入口其删除行为由 test_cache_delete.py 验证。单个 Agent 详情GET /agents/{username}/{agent_name}支持include_changelog查询参数默认False返回模型中对应可选的changelog: list[ChangelogEntry] | None。值得注意的实现细节路径参数先经过urllib.parse.unquote(...).lower()归一化保证 URL 编码的名称如含中文或空格能正确匹配数据库记录。围绕按版本取数还有三个端点GET /listings/versions/{store_listing_version_id}按列表版本 ID 取 Agent 详情需登录GET /listings/versions/{store_listing_version_id}/graph返回该版本对应的图大纲GraphModelWithoutNodes需登录GET /listings/versions/{store_listing_version_id}/graph/download公开端点将图序列化为 JSON 并以Content-Disposition: attachment; filenameagent_{id}_v{version}.json下载这正是 docs/platform/download-agent-from-marketplace-local.md 所述从市场下载 Agent流程的服务端落点。评论能力对应 README 中的 Reviews and ratingsPOST /agents/{username}/{agent_name}/review接收StoreReviewCreatestore_listing_version_idscore 可选comments委托store_db.create_store_review落库并返回StoreReview。统一搜索端点README 未覆盖的新增能力GET /searchroutes.py是一个公开端点跨所有内容类型市场 Agent、Block、文档做混合搜索results, total await search_engine.unified_hybrid_search( queryquery, content_typescontent_types, user_iduser_id, pagepage, page_sizepage_size, )其中content_types为prisma.enums.ContentType列表可缺省以搜索全部user_id通过get_optional_user_id可选注入——即使匿名请求也能搜索。响应模型 UnifiedSearchResult 同时暴露combined_score/semantic_score/lexical_score三个分数从字段命名可以推断该实现结合了向量语义检索与词法文本检索两路结果后加权融合具体融合逻辑位于 hybrid_search.py并有 hybrid_search_test.py 覆盖。GET /agents的search_query参数描述 Literal semantic search 也是同一检索思路在 Agent 维度的体现。Submissions提交工作流完整链路README 将 Agent submission workflow 列为关键特性。当前实现的端点构成如下端点方法认证功能/my-unpublished-agentsGETprivate列出当前用户未发布的 Agent可分页、按most_recent/name排序、search_query上限 100 字符/submissionsGETprivate列出我的提交statuses支持逗号分隔多状态sort_key取submitted/runssort_dir取asc/desc/submissionsPOSTprivate创建提交进入审核队列/submissions/{store_listing_version_id}PUTprivate编辑处于待定状态的提交/submissions/{submission_id}DELETEprivate删除提交/submissions/mediaPOSTprivate上传提交媒体返回 URL 字符串/submissions/generate_imagePOSTprivate依据图属性 AI 生成封面图两个值得注意的实现细节组织多租户支持。创建/编辑/删除/列表等提交端点都额外通过autogpt_libs.auth.get_request_context注入RequestContext并取org_id getattr(ctx, org_id, None)传给store_db。代码注释解释这是防御性写法在集成测试等绕过 FastAPI 依赖注入的路径上ctx可能是未解析的Security()哨兵对象用getattr可安全降级为None。状态过滤的兼容解析。_parse_status_filterroutes.py专门处理前端 Orval fetch client 将数组参数序列化为逗号拼接字符串?statusesPENDING,APPROVED的场景逐个解析为prisma.enums.SubmissionStatus遇到非法枚举值抛 422——这是一个典型的前后端约定不一致时在后端做防御的案例。创建提交的请求体 StoreSubmissionRequest 的字段约束如下可直接用于构造 API 调用class StoreSubmissionRequest(pydantic.BaseModel): graph_id: str pydantic.Field(..., min_length1, descriptionGraph ID cannot be empty) graph_version: int pydantic.Field(..., gt0, descriptionGraph version must be greater than 0) slug: str name: str sub_heading: str video_url: str | None None agent_output_demo_url: str | None None image_urls: list[str] [] description: str instructions: str | None None categories: list[str] [] changes_summary: str | None None recommended_schedule_cron: str | None None路由层对changes_summary缺省回填Initial Submission其余字段原样透传给store_db.create_store_submission。编辑请求体StoreSubmissionEditRequest字段集合相同但不含graph_id/graph_version/slug这些在创建时固化。AI 图片生成端点POST /submissions/generate_image是 README 完全未提及的能力routes.py。其调用链为backend.data.graph.get_graph(graph_id, versionNone, user_iduser_id)校验图归属以agent_{graph_id}.jpeg为候选文件名调用store_media.check_media_exists检查是否已生成过命中则直接复用幂等设计未命中则store_image_gen.generate_agent_image(agentgraph)基于图属性生成 JPEG封装成fastapi.UploadFile后走与手动上传相同的upload_media(user_id, file, use_file_nameTrue)通道保证生成图也经过大小/类型/病毒扫描校验。缓存指标端点GET /metrics/cacheroutes.py以 Prometheus 文本格式暴露四个缓存store_agents、agent_details、store_creators、creator_details的store_cache_entries与store_cache_utilization_percent两个 gauge。其中对无界缓存maxsizeNone做了显式防御——注释指出直接比较None 0会抛异常导致端点 500这是源码中可见的一个真实踩坑点。model.pyPydantic 模型与分页约定README 概括 model.py 包含分页模型、Agent/创作者/档案/提交模型、全部端点的请求/响应模型。当前实现中Pagination复用自 backend/util/models.py各列表响应统一遵循{items: list[...], pagination: Pagination}结构例如class StoreAgentsResponse(pydantic.BaseModel): agents: list[StoreAgent] pagination: Pagination几个模型设计点值得展开StoreAgent.from_dbmodel.py从 Prisma 视图对象做防御性映射agent_image为空时回退creator_username缺失时回退Needs Profile保证前端列表渲染不出现空头像/空创作者。StoreAgentDetails额外携带versions/graph_versions版本历史、active_version_id、has_approved_version与可选changelog其from_db实现中has_approved_versionTrue的注释说明了原因——StoreAgent数据库视图本身只包含已批准 Agent。提交状态机。StoreSubmission.status直接采用prisma.enums.SubmissionStatus配合reviewed_at/reviewer_id/review_comments对创作者可见与SubmissionStatstotal/approved/pending/total_runs/average_rating构成完整审核视图。SubmissionStats的 docstring 特别解释了为什么统计必须服务端聚合客户端只对当前页求和会静默少算。管理端模型分层。StoreSubmissionAdminView继承StoreSubmission并追加私有字段internal_commentsStoreListingWithVersionsAdminView则把单个 listing 的完整版本历史打包服务管理员审核界面。管理端路由见 store_admin_routes_test.py 所覆盖的 admin 路由。外部 API 复用。store_model同时被 external/v1/routes.py 复用其path/store/agents等对外端点直接调用同一套store_cache/store_db说明内部 REST 与外部 v1 API 共享同一数据访问实现。db.pyPrisma 数据访问层README 将db.py定位为使用 Prisma ORM 的数据库访问函数承载业务逻辑与数据校验。当前该文件约 1900 行是被路由层唯一直接调用的数据入口routes.py顶部from . import db as store_db对外暴露的典型函数包括档案与创作者get_user_profile、update_profile、get_store_creatorAgent 查询get_store_agents列表 过滤 排序 混合搜索、get_store_agent_details、get_store_agent_by_version_id、get_available_graph、get_agent供下载端点序列化;提交工作流get_my_agents、get_store_submissions、create_store_submission、edit_store_submission、delete_store_submission均接收可选organization_id参数做多租户隔离评论create_store_review。数据模型侧的支撑来自 schema.prisma 中的StoreListing/StoreListingVersion/Profile/Creator等模型以及大量 Prisma 视图与物化视图如StoreAgent视图。migrations/目录下的一系列迁移20241212141024_agent_store_v2、20241212150828_agent_store_v2_views、20250904171522_update_store_agent_view_with_availability、20260228114302_improve_store_entity_relations 等勾勒出该层从 v2 重构、视图优化到组织关系改进的演化轨迹。行为层面db_test.py1142 行对查询与业务规则提供了较完整的测试覆盖是验证文档描述行为与实际实现行为的首选材料。media.pyGCS 媒体上传的完整安全链路README 对media.py的描述是校验文件类型与大小、处理图片/视频上传、存入 GCS bucket、返回公开 URL。media.py 的实际实现比这一句话丰富得多可拆成四个环节1. 常量与白名单media.pyALLOWED_IMAGE_TYPES {image/jpeg, image/png, image/gif, image/webp} ALLOWED_VIDEO_TYPES {video/mp4, video/webm} MAX_FILE_SIZE 50 * 1024 * 1024 # 50MB2. 魔数magic bytes双重校验。upload_media先读前 1KB 内容不仅检查content_type是否在白名单内还校验文件签名与声明类型一致JPEG 须以\xff\xd8\xff开头、PNG 须以\x89PNG\r\n\x1a\n开头、GIF 须以GIF87a/GIF89a开头、WebP 须为RIFF....WEBP、MP4 校验ftypbox、WebM 须以\x1a\x45\xdf\xa3开头。签名与content_type不匹配即抛InvalidFileTypeError——这堵住了改扩展名/改 Content-Type 绕过类型白名单的常见绕过路径。3. 配置与大小校验。函数先检查settings.config.media_gcs_bucket_name未配置则抛StorageConfigError对应 exceptions.py 的异常体系随后按 8KB 分块流式累加大小超过 50MB 立即抛FileSizeTooLargeError避免整文件读入内存。4. 存储路径、病毒扫描与公开 URL。文件名默认使用uuid4 原扩展名use_file_nameTrue时保留原文件名供 AI 生成图的幂等复用存储路径为users/{user_id}/{images|videos}/{filename}。上传前调用scan_content_safe(file_bytes, filename...)做病毒扫描扫描异常类型VirusDetectedError/VirusScanError同时被 onboarding_dump/routes.py 复用随后通过gcloud.aio.storage纯异步客户端上传到settings.config.media_gcs_bucket_name指定的 bucket并拼接https://storage.googleapis.com/{bucket}/{path}作为公开 URL 返回。check_media_exists则分别探测users/{user_id}/images/与users/{user_id}/videos/两个前缀下的对象元数据实现生成图已存在则复用。该模块的全部行为由 media_test.py213 行覆盖。错误处理与异常映射README 最后指出所有数据库与存储操作包含完善的错误处理与日志错误映射到合适的 HTTP 状态码。在源码中这一约定落实为 exceptions.py 的异常层次MediaUploadError为基类派生InvalidFileTypeError、FileSizeTooLargeError、FileReadError、StorageConfigError、StorageUploadError等media.py中统一采用except store_exceptions.MediaUploadError: raise透传业务异常、外层兜底logger.exception后转译为MediaUploadError的模式配合upload_submission_media端点routes.py将结果简化为仅返回 URL 字符串的接口形态。数据层的NotFoundError等则来自 backend/util/exceptions.py 的通用异常体系。小结与延伸阅读Store 模块的架构脉络可以概括为routes 只做参数解析、认证注入与响应整形 → cache 拦截读路径并施加 300 秒 TTL → model 用 Pydantic 固化契约 → db 用 Prisma 承载全部业务规则 → media/exceptions 独立承接上传安全链路。README 作为模块入口文档给出了这一分层的原始蓝图而当前源码在其之上补齐了混合搜索、AI 图片生成、组织多租户与 Prometheus 缓存指标等演进能力。若要深入具体行为建议按以下路径继续端点行为与请求契约routes_test.py、model.py数据层查询与视图db_test.py、schema.prisma上传安全链路media_test.py、exceptions.py用户侧使用文档提交 Agent 到市场、从市场下载 Agent【免费下载链接】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），仅供参考