DevOpsGPT APPS 配置结构升级全解:20230803 变更迁移指南(project → service 重构)
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: "..."
...
迁移要点总结:
- 删除顶层
service_structure与repos两个键; - 将
project键重命名为service,并把其值从单个 dict 改写为 list[dict]; - 若原
project下无name,新增service.name(服务/仓库名,保持唯一); - 按上表批量更名五个字段:
project_base_prompt→base_prompt、project_info→intro、project_lib→lib、project_struct→struct、project_code_require→specification; - 将顶层的
api_doc_url、api_doc移动到对应 service 节点下; - 多服务场景下,为每个服务分别维护其
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 为准。