DevOpsGPT APPS 配置结构升级全解:20230803 变更迁移指南(project → service 重构)

原创2026-10-09 17:28:182,213 阅读
文章标签:AI Agent后端AI 应用

DevOpsGPT APPS 配置结构升级全解:20230803 变更迁移指南(project → service 重构)

本文基于仓库内的官方变更记录 docs/CONFIG_CHANGE.md 撰写,围绕 20230803 版本对 APPS 配置字段的一次系统性重构展开。你将了解 DevOpsGPT 中“应用(APPS)”配置从 project 命名时代迁移到 service 命名时代的完整字段映射、新结构的语义变化,以及这些字段在源码中的真实落地位置,从而能够在升级版本后正确迁移自己的 env.yaml 与存量应用数据。

一、变更背景:APPS 配置在 DevOpsGPT 中的地位

DevOpsGPT 是一个将自然语言需求转化为可运行软件的多 Agent 系统,而 APPS 配置是整个开发流程的起点:产品使用者在开始开发前必须选择某个应用,系统随后依据该应用的信息(服务划分、目录结构、接口文档、库包与编码规范)来分析“应该如何设计和开发”(docs/DOCUMENT_CN.md 的 APPS 配置章节)。

在开源版本中,APPS 信息需要手动维护,因此其字段结构直接影响配置编写体验与系统解析逻辑。20230803 版本对 APPS 结构做了一次“去重、重命名、结构调整”的整理,官方变更记录如下(原文见 docs/CONFIG_CHANGE.md):

- remove service_structure
- remove repos
- rename project to service
- change project type dict to list[dict]
- add service.name(repo name)
- rename project.project_base_prompt to service.base_prompt
- rename project.project_info to service.intro
- rename project.project_lib to service.lib
- rename project.project_struct to service.struct
- rename project.project_code_require service.specification
- move api_doc_url to service.api_doc_url
- move api_doc to service.api_doc

这份变更看似只是字段改名,实则同时完成了**命名统一(project → service)、类型规范化(dict → list[dict])、信息归类(展示信息与开发信息分离)**三件事。下面逐一拆解。

二、变更速览:旧结构 → 新结构映射总表

变更动作 旧字段(project 时代) 新字段(service 时代) 说明
删除 service_structure — 顶层冗余字段,与 service.struct 重复
删除 repos — 仓库信息被 service 列表承载,不再单独维护
重命名 project service 语义更贴近“服务”而非“项目”
类型变更 project 为 dict service 为 list[dict] 一个应用可声明多个服务(后端、前端、微服务)
新增 — service.name 服务名称,即仓库名称(repo name),保持唯一
重命名 project.project_base_prompt service.base_prompt 基础起手 Prompt
重命名 project.project_info service.intro 服务基本信息
重命名 project.project_lib service.lib 服务可用的 lib 包列表
重命名 project.project_struct service.struct 服务文件目录结构
重命名 project.project_code_require service.specification lib 包使用规范(编码要求)
移动 顶层 api_doc_url service.api_doc_url 接口文档地址,随服务移动
移动 顶层 api_doc service.api_doc 当前接口文档内容,随服务移动

三、逐项详解:每个字段变更的含义与落地

1. 删除 service_structure 与 repos

  • service_structure:顶层冗余的服务结构描述。在新结构中,每个服务的目录结构统一由 service.struct 承载,顶层不再重复维护,避免“同一份结构两处配置、改一处漏一处”的维护陷阱。
  • repos:仓库列表。新结构中仓库信息被收敛为 service.name(仓库名)+ service.git_path(仓库路径),由服务列表天然表达“一个服务对应一个仓库”的关系。

从源码看,服务维度数据最终落在 ApplicationService 模型(backend/app/models/application_service.py),其中 name、git_path、git_workflow、struct_cache 等字段与服务一一对应,印证了“仓库/结构信息归属于服务”的设计。

2. 重命名 project → service,类型 dict → list[dict]

这是本次变更影响最大的部分:

  • 命名:project 改为 service。官方配置说明中明确“app: 应用,包括多个服务,如:后端服务、前端服务、微服务”(docs/DOCUMENT_CN.md),因此 service 才是该层级最准确的语义。
  • 类型:project 由单个 dict 改为 service 为 list[dict]。这意味着一个应用(app)下可以声明多个服务,例如一个典型 Web 应用可以同时声明 backend、frontend 两个 service。

这一设计在数据库模型中得到印证:Application(应用)与 ApplicationService(服务)是一对多关系——ApplicationService.app_id 通过外键关联 application.app_id(backend/app/models/application_service.py),查询应用时通过 ApplicationService.get_services_by_app_id(app.app_id) 返回服务列表(backend/app/models/application.py)。可以推断,新配置中的 service: list[dict] 正是对这一对多数据模型的直接映射。

3. 新增 service.name(repo name)

service.name 是新增字段,用于标识服务名称,且保持唯一(docs/DOCUMENT_CN.md 中注明“service.name: 服务名称,保持唯一”),其取值即仓库名称(repo name)。源码中 ApplicationService.name 字段被标记为 nullable=False 并承担唯一服务标识角色;get_service_by_name 方法以 (appID, service_name) 为条件精确查找服务(backend/app/models/application_service.py),说明服务名在系统内是参与业务定位的关键标识。

4. 重命名 project_base_prompt → service.base_prompt

  • 旧:project.project_base_prompt
  • 新:service.base_prompt

base_prompt 是服务的基础起手 Prompt,官方文档强调它“会影响任务开发的效果”(docs/DOCUMENT_CN.md)。在开发流程中,它作为 appBasePrompt 被注入任务拆分环节:从源码可以确认,setpSubTask(requirementID, feature, appBasePrompt, serviceStruct, specification, serviceName) 将基础 Prompt、目录结构、编码规范一起传入子任务拆分器(backend/app/pkgs/prompt/subtask_basic.py)。因此迁移时务必原样保留该字段内容——它是影响生成代码风格与任务拆解质量的“起手式”。

5. 重命名 project_info → service.intro

intro 承载服务的基本信息,与 name 一样“仅用于显示”(docs/DOCUMENT_CN.md)。它服务于需求分析的第一步——setpReqChooseLib(分析与服务信息一起使用的库包选择)。迁移时直接更名即可,内容无需改动。

6. 重命名 project_lib → service.lib

lib 是服务可用的 lib 包列表,供 setpReqChooseLib 分析哪些库包与库列表一起使用(docs/DOCUMENT_CN.md)。

在源码层面,服务与库包同样是一对多关系:ApplicationServiceLib 模型通过 service_id 外键关联服务,get_libs_by_service_id 按服务查询库包列表(backend/app/models/application_service_lib.py),并在服务查询结果中内嵌 libs 字段返回(backend/app/models/application_service.py)。迁移时把原有 project_lib 内容平移至 service.lib 即可。

7. 重命名 project_struct → service.struct

struct 是服务的文件目录结构信息,官方文档注明它服务于 setp1Task(用于分子拆分任务)(docs/DOCUMENT_CN.md)。

源码印证:subtask_basic.py 中,服务目录结构以 service_struct 形式分别注入子任务拆分与伪代码生成环节——setpSubTask 将其拼入“Code directory structure”提示词(backend/app/pkgs/prompt/subtask_basic.py),setpPseudocode 将其作为“Existing Code directory structure”用于生成每个文件的伪代码(backend/app/pkgs/prompt/subtask_basic.py)。

值得注意的是,目录结构的取值在代码中实际来自 struct_cache 字段(service_info<a href="https://link.gitcode.com/i/6457801dd2ee73634813093df666894c" target="_blank">"struct_cache"],见 [backend/app/pkgs/prompt/subtask_basic.py),即数据库持久化的结构缓存。可以推断:配置中的 service.struct 是初始目录结构定义,系统会在应用创建/更新时将其写入 ApplicationService.struct_cache 供后续流程读取。迁移时保留原 project_struct 内容即可。

8. 重命名 project_code_require → service.specification

specification 是 lib 包使用规范(即编码要求)。开发环节中,specification 被收集后存入存储上下文(storage.set("specification", specification),见 backend/app/pkgs/prompt/subtask_basic.py),随后作为“Development specification”注入伪代码生成提示词,要求“依据开发规范编写最终完整可运行的代码”(backend/app/pkgs/prompt/subtask_basic.py)。

同时,sys_lib 模型本身就带有 specification 字段(backend/app/models/sys_lib.py),用于描述每个系统库包的使用规范;需求分析时系统会将 lib 的 purpose 与 specification 组合成描述串(backend/app/pkgs/knowledge/app_info_basic.py)。可见 service.specification 是整个“规范驱动开发”链路中的关键输入,迁移时应完整保留。

9. 移动 api_doc_url、api_doc → service.api_doc_url、service.api_doc

  • service.api_doc_url:接口文档地址,用于动态获取接口文档(docs/DOCUMENT_CN.md)。升级前若写在应用顶层,需移动到对应服务下。
  • service.api_doc:当前的接口文档内容,同样随服务归属。

两者从顶层下移到服务层级,与“接口文档按服务划分”的实际开发场景一致——每个后端服务维护自己的一份接口文档。迁移时根据文档内容判断其属于哪个服务,移入该 service 节点即可。

四、迁移实操:新旧结构配置对照示例

旧结构(project 时代,示意)

APPS:
  - app: demo_app
    name: Demo App
    intro: 仅用于显示的应用简介
    service_structure: "..."
    repos:
      - repo_name: demo_backend
        url: https://github.com/org/demo_backend
    project:
      project_base_prompt: "..."
      project_info: "..."
      project_lib: ["fastapi", "sqlalchemy"]
      project_struct: "..."
      project_code_require: "..."
    api_doc_url: "..."
    api_doc: "..."

新结构(service 时代,按 20230803 迁移后)

APPS:
  - app: demo_app
    name: Demo App            # 仅用于显示
    intro: 仅用于显示的应用简介
    service:                  # list[dict],一个应用可声明多个服务
      - name: demo_backend    # 新增:服务名称(repo name),保持唯一
        git_path: org/demo_backend   # 需要包含 group
        base_prompt: "..."    # 原 project_base_prompt
        intro: "..."          # 原 project_info
        lib: ["fastapi", "sqlalchemy"]   # 原 project_lib
        struct: "..."         # 原 project_struct
        specification: "..."  # 原 project_code_require
        api_doc_url: "..."    # 自顶层移入
        api_doc: "..."        # 自顶层移入
      - name: demo_frontend   # 可继续声明第二个服务
        git_path: org/demo_frontend
        base_prompt: "..."
        ...

迁移要点总结:

  1. 删除顶层 service_structure 与 repos 两个键;
  2. 将 project 键重命名为 service,并把其值从单个 dict 改写为 list[dict];
  3. 若原 project 下无 name,新增 service.name(服务/仓库名,保持唯一);
  4. 按上表批量更名五个字段:project_base_prompt → base_prompt、project_info → intro、project_lib → lib、project_struct → struct、project_code_require → specification;
  5. 将顶层的 api_doc_url、api_doc 移动到对应 service 节点下;
  6. 多服务场景下,为每个服务分别维护其 intro、lib、struct、specification 与接口文档字段。

五、升级后的运维提醒

  • 以上字段在开源版本中需手动维护(官方文档明确“在开源版本中,这些信息需要手动维护”,AI 智能分析生成属于商业版能力,见 docs/DOCUMENT_CN.md),因此迁移配置时请逐字段核对,避免因更名遗漏导致应用无法被正确解析。
  • 如果开启了 Git 拉取功能(GIT_ENABLED: true),还需配合配置 service.git_path(包含 group 的仓库路径)与 service.git_workflow(开启 Github CI 时的 workflow 名称),配置模板详见 env.yaml.tpl。
  • 本变更记录面向 20230803 版本;不同发行版本可能存在差异,升级前请以你所使用版本对应的 docs/CONFIG_CHANGE.md 与 docs/DOCUMENT_CN.md 为准。
登录后查看全文
DevOpsGPT