如果你用 AI 代码生成工具写过稍大一点的项目大概会经历这个场景让模型写一个 Python 函数它写得又快又好让它补全一个类或一个模块也能将就用。但当你给出完整需求让它从 0 直接生成一个可以 clone 下来、装好依赖、启动服务、跑通测试的软件仓库结果往往是一份“看起来五脏俱全、实际处处对不上”的目录。问题不出在模型不会写代码而出在生成方式本身。今天我们讨论的“从 0 生成完整软件仓库”和“动态架构进化”正是为了解决这个仓库级 AI 代码生成的卡点。这篇文章先定位真正的痛点再拆解“动态架构进化”的原理最后给出一套可落地的编排器示例代码和工程建议。如果你正在做 AI 代码生成、大模型应用或者想把大模型引入研发流程这篇文章值得收藏。1. 从“代码补全”到“完整软件仓库”核心痛点到底在哪先说结论代码生成这件事最难的不是“生成代码”而是“生成一个软件系统”。单文件代码生成本质是补全能力。模型只需要理解当前上下文输出一段逻辑自洽的代码。但软件仓库是一个多模块、多文件、多配置的组合体它有目录结构约束、模块依赖约束、配置一致性约束、构建验证约束。一个文件写得再漂亮如果requirements.txt没有对应依赖、模块之间引用路径错了、数据库连接配置缺失整个仓库就跑不起来。从工程实践来看仓库级 AI 代码生成主要卡在四个地方第一结构感缺失。模型一次性输出时容易出现“接口定义在 A 模块B 模块不知道接口签名”的情况。目录层级不统一命名规范漂移模块之间缺少契约。第二上下文断裂。生成一个仓库往往需要生成几十个文件单次上下文窗口放不下多次生成又容易产生前后不一致。后面生成的模块不知道前面已经生成了什么自然就会出现重复定义和遗漏。第三验证反馈缺失。传统代码生成是“生成完就结束”没有把编译错误、依赖缺失、测试失败这些信号回传给模型。模型下一次生成同类项目时仍然会犯同样的错误。第四架构决策被压缩成一次性动作。真实工程里的架构是在约束、反馈、修正中逐渐收敛的而“一次性生成整个仓库”等于让模型在没有任何构建反馈的情况下直接提交一份最终图纸。所以从 0 生成完整软件仓库并不是“AI 代码生成”的加强版而是一个需要重新设计生成流程的大模型应用问题。这也是“动态架构进化”想要解决的核心问题。本文适合这几类读者正在做 AI 辅助研发工具的开发工程师计划用大模型批量生成业务模块的技术负责人以及对 AGENT 编排、代码生成工作流感兴趣的大模型应用开发者。2. 三个层级代码补全、单文件生成、仓库级生成为了讲清楚“动态架构进化”的定位我们需要先明确当前 AI 代码生成大致处于哪几个层级。层级典型工具形态输入输出主要难点代码补全IDE 插件、补全模型当前文件上下文、光标位置几行到几十行代码续写自然、语法正确单文件生成对话式编程助手一段需求、约束说明单个文件的完整代码逻辑完整性、风格统一仓库级生成项目脚手架、仓库生成编排器项目需求描述、技术栈约束多文件、多模块、可运行仓库结构一致性、依赖正确、可构建代码补全的核心是“下一步预测”单文件生成的核心是“局部需求理解”而仓库级生成的核心是“系统架构编排”。很多人误以为仓库级生成就是把单文件生成重复几十次。实际上它要求模型解决一个更复杂的问题在架构约束下生成相互协作的模块集合。如果说单文件生成是“写一个零件”仓库级生成就是“设计整条生产线并让所有零件协同工作”。也正因为如此仓库级生成是大模型应用从“辅助编程”走向“工程化交付”的试金石。如果一个生成方案只能出代码片段不能出完整仓库它就很难真正嵌入企业软件交付流程。3. 动态架构进化解决仓库级代码生成的关键思路“动态架构进化”不是某个具体产品的功能名而是一种工程生成策略。它的核心判断是仓库级代码生成不应该是一次性静态输出而应该是一个多阶段、可反馈、可修正的架构演进过程。我们用盖房子来类比。传统的单次生成模式相当于让建筑师不看地基、不验收材料直接一次性画出从结构到水电到装修的全部图纸。而动态架构进化模式相当于先确定建筑方案再出结构图边施工边验收发现承重问题就立刻回传修改最后整栋楼才可能真正交付。具体来说动态架构进化由四个机制组成。第一个机制是“规划先行”。生成代码之前先让模型输出架构蓝图模块划分、目录结构、技术栈、模块间依赖关系。这一步输出的是结构化信息而不是代码目的是让后续所有代码生成都服从同一个顶层设计。第二个机制是“模块契约”。架构蓝图确定后模块之间通过接口和数据结构形成契约。生成某个模块时模型必须遵循前期定义的接口签名、数据格式和配置约定而不是自由发挥。第三个机制是“增量生成”。按模块逐个生成同时把已有文件清单和当前目录结构回传到大模型上下文让模型在“知道全局”的前提下生成局部。这比一次性生成全部文件更节省上下文也更容易保持一致性。第四个机制是“反馈修正”。生成完成后运行静态校验和构建命令把错误日志返回给模型让模型分析原因并给出修复补丁。这个循环可以执行多轮直到仓库通过基础校验。对比一下两种方式对比维度一次性静态生成动态架构进化是否先做架构规划通常没有先产出架构蓝图模块之间如何协作依赖模型随机记忆依赖显式模块契约生成过程中是否回传上下文一般不会每轮回传已有文件清单是否有构建反馈没有有校验与修复循环适用仓库规模小型演示项目中大型工程仓库这就是“进化”的意思架构不是一开始就完全确定的而是在生成、校验、修复的过程中不断收敛。大模型应用在这一思路里承担的不再只是“写代码”而是“参与架构演进”。4. 环境准备与编排器目录设计接下来进入实操部分。我们要实现的是一个“仓库生成编排器”它会调用大模型 API按动态架构进化的流程生成一个软件仓库。以下环境是演示编排器所需的版本以你实际使用的服务商和本地环境为准。建议环境Python 3.10 及以上版本pip 和 venv 虚拟环境一个兼容 OpenAI Chat Completions 接口的大模型 API 服务可选Docker、Java/Node 运行时用于验证不同技术栈的生成仓库不需要本地 GPU大模型请求统一走 API 接口。需要注意你在配置 API Key 时不要硬编码到公开仓库建议使用环境变量。我们先把编排器项目目录设计为codegen_orchestrator/ ├── orchestrator.py # 主编排入口 ├── prompts.yaml # 分阶段提示词模板 ├── validator.py # 静态校验与构建日志收集 ├── requirements.txt # Python 依赖 └── output/ # 生成仓库的输出目录在这里“output”目录最终会保存生成出来的完整软件仓库。如果一次生成不理想可以清空后重新生成不影响编排器代码本身。安装依赖cd codegen_orchestrator python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install -r requirements.txtrequirements.txt内容如下版本请以你实际安装为准openai1.0.0 PyYAML6.0如果你在本地环境初始化阶段就卡住比如在某些 Linux 发行版上配置基础软件仓库时出错可以先检查系统软件源和 Python 是否可用。这类环境问题不是核心不必花太多时间纠结。5. 核心流程拆解从需求描述到仓库落地动态架构进化的编排流程可以拆成五步。每一步解决一个层面的问题。5.1 需求解析与架构蓝图第一步不是写代码而是让模型输出架构蓝图。我们需要把用户的需求描述传给模型并强制它输出结构化的 JSON包含模块名、模块职责、模块依赖、目录树和技术栈建议。这一步的关键是提示词约束。要明确告诉模型只输出 JSON不要输出解释文字。否则后续解析会非常痛苦。常见错误是模块划分过细或过粗。过细会导致几十个模块管理成本过高过粗又无法支撑后续增量生成。实际项目中建议让模型先给出模块清单再由人工确认后进入下一步。5.2 模块契约定义架构蓝图确定之后只划定了“有哪些模块”还没定义“模块之间怎么协作”。所以在生成代码之前应该让模型补全接口签名、数据结构、配置项和模块间依赖关系。这一步可以看作“接口先行”。后续生成模块时模型必须遵守这些接口约定。没有契约约束A 模块调用 B 模块时很容易出现字段对不上的问题。在示例编排器中我们通过把架构蓝图 JSON 作为上下文传给每一步的代码生成间接实现约束传递。5.3 增量生成与上下文回传这是整个流程最核心的执行步骤。我们按模块逐个生成代码文件并在生成每个模块时把“架构设计 当前模块 已生成文件列表”一起传给模型。这样做的好处是模型知道全局但只需要专注局部。它不会被整个仓库的所有细节淹没同时又能依据已有文件结构给出风格一致的代码。实际工程中这一步可以按拓扑顺序生成模块从最底层、无依赖的模块开始避免生成上层模块时下层模块还未落盘。5.4 静态校验与构建检查代码生成完成后必须进入验证阶段。示例中我们用compileall做 Python 语法检查同时检查关键文件是否缺失。真实的项目里可以替换为mvn compile、npm run build、pytest等命令。这里真正容易踩坑的地方是不要把校验只停留在“文件是否存在”。一个文件只要存在语法错误和依赖错误都会被忽略。所以校验阶段必须真正执行构建或等价命令并把输出日志保留下来。5.5 构建反馈与自动修复如果构建日志中包含错误我们就把它作为输入再次调用大模型让它分析失败原因并输出修复后的文件内容。这一步是整个流程的价值高峰。没有反馈的生成是单向输出有反馈的生成才叫演进。多轮修复后仓库质量会逐步逼近可运行状态。实际使用时要注意不要把超长构建日志整段塞给模型。截取前几千字符通常就足够了避免消耗无谓的上下文空间。6. 完整示例仓库生成编排器代码实现现在我们给出一个可运行的编排器示例。整体逻辑覆盖了“架构生成 - 增量代码生成 - 校验修复”三个核心环节。先看提示词模板文件prompts.yamlarchitecture: system: | 你是一名资深软件架构师。用户会提供一个软件项目的需求描述。 请输出一份 JSON不要包含任何解释文字。 JSON 结构如下 { modules: [ { name: 模块名, description: 模块职责说明, dependencies: [依赖的模块名] } ], tree: [相对路径1, 相对路径2], stack: 推荐技术栈及理由 } 要求模块划分合理目录结构清晰模块依赖关系不要成环。 user: | 请为以下需求设计架构 {requirement} codegen: system: | 你是一名资深工程师。你会拿到项目的架构设计、当前模块和已经生成的目录结构。 请为当前模块生成完整的源码和配置输出 JSON。 JSON 的 key 是相对路径value 是文件内容。 要求 1. 严格遵循已有目录结构 2. 文件内容完整可运行 3. 不要生成架构设计中不存在的模块。 user: | 架构设计 {architecture} 当前模块 {module} 已生成文件列表 {existing_files} 请生成该模块。 repair: system: | 你是一名代码评审和修复专家。下面是构建校验日志。 请分析失败原因输出 JSON {analysis: 原因分析, fix_files: {相对路径: 修复后的代码}} 如果没有任何错误直接输出 {analysis: ok}。 user: | 构建校验日志 {build_log}然后是主编排脚本orchestrator.py# 文件路径codegen_orchestrator/orchestrator.py from pathlib import Path import json import yaml from openai import OpenAI BASE_DIR Path(__file__).parent OUTPUT_DIR BASE_DIR / output PROMPTS yaml.safe_load((BASE_DIR / prompts.yaml).read_text(encodingutf-8)) # 大模型客户端配置请按你实际使用的服务商填写 client OpenAI( base_urlhttps://your-endpoint.example.com/v1, api_keyyour-api-key, ) def call_model(system_prompt: str, user_content: str) - str: response client.chat.completions.create( modelyour-model-name, messages[ {role: system, content: system_prompt}, {role: user, content: user_content}, ], temperature0.2, ) return response.choices[0].message.content def parse_json(text: str) - dict: # 兼容模型输出外层带 json 代码块的情况 text text.strip() if text.startswith(): lines text.splitlines() if lines and lines[0].startswith(): lines lines[1:] if lines and lines[-1].strip() : lines lines[:-1] text \n.join(lines) return json.loads(text) def generate_architecture(requirement: str) - dict: call PROMPTS[architecture] content call_model(call[system], call[user].format(requirementrequirement)) return parse_json(content) def write_file(relative_path: str, content: str) - None: target OUTPUT_DIR / relative_path target.parent.mkdir(parentsTrue, exist_okTrue) target.write_text(content, encodingutf-8) def main(requirement: str) - None: print([1/4] 生成架构蓝图) arch generate_architecture(requirement) print(json.dumps(arch, ensure_asciiFalse, indent2)) print([2/4] 写入目录骨架) tree arch.get(tree, []) for path in tree: write_file(path, # placeholder\n) print([3/4] 分模块生成代码) for module in arch.get(modules, []): content call_model( PROMPTS[codegen][system], PROMPTS[codegen][user].format( architecturejson.dumps(arch, ensure_asciiFalse), modulejson.dumps(module, ensure_asciiFalse), existing_filesjson.dumps(tree, ensure_asciiFalse), ), ) files parse_json(content) for rel_path, file_content in files.items(): write_file(rel_path, file_content) print(f 生成模块: {module.get(name)} (共 {len(files)} 个文件)) print([4/4] 构建校验与自动修复) from validator import validate_repo, run_build errors validate_repo(OUTPUT_DIR) if errors: print(静态校验发现问题) for error in errors: print( -, error) build_log run_build(OUTPUT_DIR) print(构建日志) print(build_log) if errors or SyntaxError in build_log or Error in build_log: print(调用模型分析并修复问题...) repair_resp call_model( PROMPTS[repair][system], PROMPTS[repair][user].format( build_log(build_log or \n.join(errors))[:4000] ), ) repair parse_json(repair_resp) for rel_path, content in repair.get(fix_files, {}).items(): if isinstance(content, str): write_file(rel_path, content) else: write_file(rel_path, str(content)) print(修复完成重新执行构建校验) print(run_build(OUTPUT_DIR)) print(生成结束仓库位于:, OUTPUT_DIR) if __name__ __main__: import sys default_requirement ( 生成一个基于 FastAPI SQLite 的待办事项管理服务 包含创建、查询、更新、删除待办事项的 REST API 并提供 README、requirements.txt、Dockerfile 和基础测试。 ) requirement sys.argv[1] if len(sys.argv) 1 else default_requirement main(requirement)最后是校验脚本validator.py# 文件路径codegen_orchestrator/validator.py from pathlib import Path import subprocess REQUIRED_FILES [README.md, requirements.txt, Dockerfile] def validate_repo(repo_root: Path) - list[str]: errors [] if not repo_root.exists(): return [输出目录不存在无法校验] for filename in REQUIRED_FILES: if not (repo_root / filename).exists(): errors.append(f缺少关键文件: {filename}) python_files list(repo_root.rglob(*.py)) if not python_files: errors.append(未发现 Python 源码文件) return errors def run_build(repo_root: Path) - str: # 使用 compileall 做语法级校验实际项目中可替换为 pytest、mvn compile 等命令 result subprocess.run( [python, -m, compileall, -q, str(repo_root)], capture_outputTrue, textTrue, ) return result.stdout result.stderr这段代码有四个关键逻辑点。第一parse_json对模型输出做了容错处理解决“模型返回外层 json 代码块”的问题。没有这个处理JSON 解析很容易失败。第二生成模块时arch和tree被序列化后传入提示词让模型始终知道全局架构和已生成文件。这是模块契约和上下文回传的具体落地。第三校验和修复循环不是简单的“报错就停止”而是把错误日志喂回模型生成修复补丁。修复后再跑一次构建形成二次验证。第四所有生成结果都写入output/目录不会污染编排器源码目录。多次生成时建议清空output/后再运行。7. 运行效果与验证方法运行示例编排器cd codegen_orchestrator python orchestrator.py 生成一个基于 FastAPI SQLite 的待办事项管理服务包含增删改查 REST API提供 README、requirements.txt、Dockerfile 和测试预期的输出大致分为四个阶段架构蓝图阶段模型输出模块清单、目录树、技术栈建议。目录骨架阶段output/下按蓝图创建目录和占位文件。分模块生成阶段逐个模块生成源码文件并打印模块名和文件数。校验修复阶段打印静态校验结果和构建日志存在问题时自动调用模型修复。一个合理的生成结果大致是下面的目录结构。注意输出内容取决于你用的大模型和服务商以下只是演示预期output/ ├── README.md ├── requirements.txt ├── Dockerfile ├── app/ │ ├── __init__.py │ ├── main.py │ ├── models.py │ ├── schemas.py │ └── routers/ │ ├── __init__.py │ └── todos.py └── tests/ └── test_todos.py判断生成是否成功的标准有三个第一静态校验通过关键文件存在。README.md、requirements.txt、Dockerfile这些文件不应该缺失。第二构建命令没有语法错误。在示例中compileall不报错就说明所有 Python 文件语法合法。第三模块间引用路径正确。目录结构、import路径、依赖包声明这三个维度要保持一致。如果你生成的不是 Python 项目可以把validator.py里的run_build替换成对应技术栈的命令。Java 项目可以执行mvn -q compileNode 项目可以执行npm run build。反馈信号越接近真实构建修复效果越好。8. 常见问题与排查思路在实际使用这个编排器时以下几个问题最容易出现。问题现象可能原因排查方式解决方案解析 JSON 报错模型输出中带有解释文字或 markdown 代码块打印原始返回内容至命令行用parse_json容错处理提示词中强制“只输出 JSON”生成目录结构不一致后续模块生成时没有回传已有文件列表查看 prompts.yaml 中是否传入existing_files增量生成时始终把当前目录树加入上下文模块间 import 路径错误模块契约缺失模型自由发挥检查架构蓝图中的dependencies先让模型输出接口签名和依赖清单再生成代码构建日志过长导致模型上下文超限没有截断日志查看 API 请求长度截取前 3000-4000 字符作为修复输入修复后仍然失败修复循环只执行了一轮查看二次构建日志外层加循环最多修复 2-3 轮修复文件内容不是字符串模型把单个文件内容输出成数组或对象打印repair结构确认类型在写入前增加类型判断如isinstance(content, str)特别提醒一下“上下文超限”这个问题。仓库级代码生成很容易遇到长文本因为架构蓝图、模块说明、已生成文件列表加起来已经不小。实际工程中建议用关键信息摘要替代全量文件内容或者使用支持更长上下文的模型。9. 最佳实践、总结与后续学习方向把动态架构进化的思路落进真实项目时有几件事值得提前考虑。第一从内部工具项目开始验证。不要在第一个试点就直接生成核心业务系统。选一个内部工具服务把“架构规划 - 增量生成 - 构建反馈”这条回路跑通再逐步扩展。第二重视提示词的可维护性。把提示词 动态架构进化：解决仓库级AI代码生成的关键策略
如果你用 AI 代码生成工具写过稍大一点的项目大概会经历这个场景让模型写一个 Python 函数它写得又快又好让它补全一个类或一个模块也能将就用。但当你给出完整需求让它从 0 直接生成一个可以 clone 下来、装好依赖、启动服务、跑通测试的软件仓库结果往往是一份“看起来五脏俱全、实际处处对不上”的目录。问题不出在模型不会写代码而出在生成方式本身。今天我们讨论的“从 0 生成完整软件仓库”和“动态架构进化”正是为了解决这个仓库级 AI 代码生成的卡点。这篇文章先定位真正的痛点再拆解“动态架构进化”的原理最后给出一套可落地的编排器示例代码和工程建议。如果你正在做 AI 代码生成、大模型应用或者想把大模型引入研发流程这篇文章值得收藏。1. 从“代码补全”到“完整软件仓库”核心痛点到底在哪先说结论代码生成这件事最难的不是“生成代码”而是“生成一个软件系统”。单文件代码生成本质是补全能力。模型只需要理解当前上下文输出一段逻辑自洽的代码。但软件仓库是一个多模块、多文件、多配置的组合体它有目录结构约束、模块依赖约束、配置一致性约束、构建验证约束。一个文件写得再漂亮如果requirements.txt没有对应依赖、模块之间引用路径错了、数据库连接配置缺失整个仓库就跑不起来。从工程实践来看仓库级 AI 代码生成主要卡在四个地方第一结构感缺失。模型一次性输出时容易出现“接口定义在 A 模块B 模块不知道接口签名”的情况。目录层级不统一命名规范漂移模块之间缺少契约。第二上下文断裂。生成一个仓库往往需要生成几十个文件单次上下文窗口放不下多次生成又容易产生前后不一致。后面生成的模块不知道前面已经生成了什么自然就会出现重复定义和遗漏。第三验证反馈缺失。传统代码生成是“生成完就结束”没有把编译错误、依赖缺失、测试失败这些信号回传给模型。模型下一次生成同类项目时仍然会犯同样的错误。第四架构决策被压缩成一次性动作。真实工程里的架构是在约束、反馈、修正中逐渐收敛的而“一次性生成整个仓库”等于让模型在没有任何构建反馈的情况下直接提交一份最终图纸。所以从 0 生成完整软件仓库并不是“AI 代码生成”的加强版而是一个需要重新设计生成流程的大模型应用问题。这也是“动态架构进化”想要解决的核心问题。本文适合这几类读者正在做 AI 辅助研发工具的开发工程师计划用大模型批量生成业务模块的技术负责人以及对 AGENT 编排、代码生成工作流感兴趣的大模型应用开发者。2. 三个层级代码补全、单文件生成、仓库级生成为了讲清楚“动态架构进化”的定位我们需要先明确当前 AI 代码生成大致处于哪几个层级。层级典型工具形态输入输出主要难点代码补全IDE 插件、补全模型当前文件上下文、光标位置几行到几十行代码续写自然、语法正确单文件生成对话式编程助手一段需求、约束说明单个文件的完整代码逻辑完整性、风格统一仓库级生成项目脚手架、仓库生成编排器项目需求描述、技术栈约束多文件、多模块、可运行仓库结构一致性、依赖正确、可构建代码补全的核心是“下一步预测”单文件生成的核心是“局部需求理解”而仓库级生成的核心是“系统架构编排”。很多人误以为仓库级生成就是把单文件生成重复几十次。实际上它要求模型解决一个更复杂的问题在架构约束下生成相互协作的模块集合。如果说单文件生成是“写一个零件”仓库级生成就是“设计整条生产线并让所有零件协同工作”。也正因为如此仓库级生成是大模型应用从“辅助编程”走向“工程化交付”的试金石。如果一个生成方案只能出代码片段不能出完整仓库它就很难真正嵌入企业软件交付流程。3. 动态架构进化解决仓库级代码生成的关键思路“动态架构进化”不是某个具体产品的功能名而是一种工程生成策略。它的核心判断是仓库级代码生成不应该是一次性静态输出而应该是一个多阶段、可反馈、可修正的架构演进过程。我们用盖房子来类比。传统的单次生成模式相当于让建筑师不看地基、不验收材料直接一次性画出从结构到水电到装修的全部图纸。而动态架构进化模式相当于先确定建筑方案再出结构图边施工边验收发现承重问题就立刻回传修改最后整栋楼才可能真正交付。具体来说动态架构进化由四个机制组成。第一个机制是“规划先行”。生成代码之前先让模型输出架构蓝图模块划分、目录结构、技术栈、模块间依赖关系。这一步输出的是结构化信息而不是代码目的是让后续所有代码生成都服从同一个顶层设计。第二个机制是“模块契约”。架构蓝图确定后模块之间通过接口和数据结构形成契约。生成某个模块时模型必须遵循前期定义的接口签名、数据格式和配置约定而不是自由发挥。第三个机制是“增量生成”。按模块逐个生成同时把已有文件清单和当前目录结构回传到大模型上下文让模型在“知道全局”的前提下生成局部。这比一次性生成全部文件更节省上下文也更容易保持一致性。第四个机制是“反馈修正”。生成完成后运行静态校验和构建命令把错误日志返回给模型让模型分析原因并给出修复补丁。这个循环可以执行多轮直到仓库通过基础校验。对比一下两种方式对比维度一次性静态生成动态架构进化是否先做架构规划通常没有先产出架构蓝图模块之间如何协作依赖模型随机记忆依赖显式模块契约生成过程中是否回传上下文一般不会每轮回传已有文件清单是否有构建反馈没有有校验与修复循环适用仓库规模小型演示项目中大型工程仓库这就是“进化”的意思架构不是一开始就完全确定的而是在生成、校验、修复的过程中不断收敛。大模型应用在这一思路里承担的不再只是“写代码”而是“参与架构演进”。4. 环境准备与编排器目录设计接下来进入实操部分。我们要实现的是一个“仓库生成编排器”它会调用大模型 API按动态架构进化的流程生成一个软件仓库。以下环境是演示编排器所需的版本以你实际使用的服务商和本地环境为准。建议环境Python 3.10 及以上版本pip 和 venv 虚拟环境一个兼容 OpenAI Chat Completions 接口的大模型 API 服务可选Docker、Java/Node 运行时用于验证不同技术栈的生成仓库不需要本地 GPU大模型请求统一走 API 接口。需要注意你在配置 API Key 时不要硬编码到公开仓库建议使用环境变量。我们先把编排器项目目录设计为codegen_orchestrator/ ├── orchestrator.py # 主编排入口 ├── prompts.yaml # 分阶段提示词模板 ├── validator.py # 静态校验与构建日志收集 ├── requirements.txt # Python 依赖 └── output/ # 生成仓库的输出目录在这里“output”目录最终会保存生成出来的完整软件仓库。如果一次生成不理想可以清空后重新生成不影响编排器代码本身。安装依赖cd codegen_orchestrator python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install -r requirements.txtrequirements.txt内容如下版本请以你实际安装为准openai1.0.0 PyYAML6.0如果你在本地环境初始化阶段就卡住比如在某些 Linux 发行版上配置基础软件仓库时出错可以先检查系统软件源和 Python 是否可用。这类环境问题不是核心不必花太多时间纠结。5. 核心流程拆解从需求描述到仓库落地动态架构进化的编排流程可以拆成五步。每一步解决一个层面的问题。5.1 需求解析与架构蓝图第一步不是写代码而是让模型输出架构蓝图。我们需要把用户的需求描述传给模型并强制它输出结构化的 JSON包含模块名、模块职责、模块依赖、目录树和技术栈建议。这一步的关键是提示词约束。要明确告诉模型只输出 JSON不要输出解释文字。否则后续解析会非常痛苦。常见错误是模块划分过细或过粗。过细会导致几十个模块管理成本过高过粗又无法支撑后续增量生成。实际项目中建议让模型先给出模块清单再由人工确认后进入下一步。5.2 模块契约定义架构蓝图确定之后只划定了“有哪些模块”还没定义“模块之间怎么协作”。所以在生成代码之前应该让模型补全接口签名、数据结构、配置项和模块间依赖关系。这一步可以看作“接口先行”。后续生成模块时模型必须遵守这些接口约定。没有契约约束A 模块调用 B 模块时很容易出现字段对不上的问题。在示例编排器中我们通过把架构蓝图 JSON 作为上下文传给每一步的代码生成间接实现约束传递。5.3 增量生成与上下文回传这是整个流程最核心的执行步骤。我们按模块逐个生成代码文件并在生成每个模块时把“架构设计 当前模块 已生成文件列表”一起传给模型。这样做的好处是模型知道全局但只需要专注局部。它不会被整个仓库的所有细节淹没同时又能依据已有文件结构给出风格一致的代码。实际工程中这一步可以按拓扑顺序生成模块从最底层、无依赖的模块开始避免生成上层模块时下层模块还未落盘。5.4 静态校验与构建检查代码生成完成后必须进入验证阶段。示例中我们用compileall做 Python 语法检查同时检查关键文件是否缺失。真实的项目里可以替换为mvn compile、npm run build、pytest等命令。这里真正容易踩坑的地方是不要把校验只停留在“文件是否存在”。一个文件只要存在语法错误和依赖错误都会被忽略。所以校验阶段必须真正执行构建或等价命令并把输出日志保留下来。5.5 构建反馈与自动修复如果构建日志中包含错误我们就把它作为输入再次调用大模型让它分析失败原因并输出修复后的文件内容。这一步是整个流程的价值高峰。没有反馈的生成是单向输出有反馈的生成才叫演进。多轮修复后仓库质量会逐步逼近可运行状态。实际使用时要注意不要把超长构建日志整段塞给模型。截取前几千字符通常就足够了避免消耗无谓的上下文空间。6. 完整示例仓库生成编排器代码实现现在我们给出一个可运行的编排器示例。整体逻辑覆盖了“架构生成 - 增量代码生成 - 校验修复”三个核心环节。先看提示词模板文件prompts.yamlarchitecture: system: | 你是一名资深软件架构师。用户会提供一个软件项目的需求描述。 请输出一份 JSON不要包含任何解释文字。 JSON 结构如下 { modules: [ { name: 模块名, description: 模块职责说明, dependencies: [依赖的模块名] } ], tree: [相对路径1, 相对路径2], stack: 推荐技术栈及理由 } 要求模块划分合理目录结构清晰模块依赖关系不要成环。 user: | 请为以下需求设计架构 {requirement} codegen: system: | 你是一名资深工程师。你会拿到项目的架构设计、当前模块和已经生成的目录结构。 请为当前模块生成完整的源码和配置输出 JSON。 JSON 的 key 是相对路径value 是文件内容。 要求 1. 严格遵循已有目录结构 2. 文件内容完整可运行 3. 不要生成架构设计中不存在的模块。 user: | 架构设计 {architecture} 当前模块 {module} 已生成文件列表 {existing_files} 请生成该模块。 repair: system: | 你是一名代码评审和修复专家。下面是构建校验日志。 请分析失败原因输出 JSON {analysis: 原因分析, fix_files: {相对路径: 修复后的代码}} 如果没有任何错误直接输出 {analysis: ok}。 user: | 构建校验日志 {build_log}然后是主编排脚本orchestrator.py# 文件路径codegen_orchestrator/orchestrator.py from pathlib import Path import json import yaml from openai import OpenAI BASE_DIR Path(__file__).parent OUTPUT_DIR BASE_DIR / output PROMPTS yaml.safe_load((BASE_DIR / prompts.yaml).read_text(encodingutf-8)) # 大模型客户端配置请按你实际使用的服务商填写 client OpenAI( base_urlhttps://your-endpoint.example.com/v1, api_keyyour-api-key, ) def call_model(system_prompt: str, user_content: str) - str: response client.chat.completions.create( modelyour-model-name, messages[ {role: system, content: system_prompt}, {role: user, content: user_content}, ], temperature0.2, ) return response.choices[0].message.content def parse_json(text: str) - dict: # 兼容模型输出外层带 json 代码块的情况 text text.strip() if text.startswith(): lines text.splitlines() if lines and lines[0].startswith(): lines lines[1:] if lines and lines[-1].strip() : lines lines[:-1] text \n.join(lines) return json.loads(text) def generate_architecture(requirement: str) - dict: call PROMPTS[architecture] content call_model(call[system], call[user].format(requirementrequirement)) return parse_json(content) def write_file(relative_path: str, content: str) - None: target OUTPUT_DIR / relative_path target.parent.mkdir(parentsTrue, exist_okTrue) target.write_text(content, encodingutf-8) def main(requirement: str) - None: print([1/4] 生成架构蓝图) arch generate_architecture(requirement) print(json.dumps(arch, ensure_asciiFalse, indent2)) print([2/4] 写入目录骨架) tree arch.get(tree, []) for path in tree: write_file(path, # placeholder\n) print([3/4] 分模块生成代码) for module in arch.get(modules, []): content call_model( PROMPTS[codegen][system], PROMPTS[codegen][user].format( architecturejson.dumps(arch, ensure_asciiFalse), modulejson.dumps(module, ensure_asciiFalse), existing_filesjson.dumps(tree, ensure_asciiFalse), ), ) files parse_json(content) for rel_path, file_content in files.items(): write_file(rel_path, file_content) print(f 生成模块: {module.get(name)} (共 {len(files)} 个文件)) print([4/4] 构建校验与自动修复) from validator import validate_repo, run_build errors validate_repo(OUTPUT_DIR) if errors: print(静态校验发现问题) for error in errors: print( -, error) build_log run_build(OUTPUT_DIR) print(构建日志) print(build_log) if errors or SyntaxError in build_log or Error in build_log: print(调用模型分析并修复问题...) repair_resp call_model( PROMPTS[repair][system], PROMPTS[repair][user].format( build_log(build_log or \n.join(errors))[:4000] ), ) repair parse_json(repair_resp) for rel_path, content in repair.get(fix_files, {}).items(): if isinstance(content, str): write_file(rel_path, content) else: write_file(rel_path, str(content)) print(修复完成重新执行构建校验) print(run_build(OUTPUT_DIR)) print(生成结束仓库位于:, OUTPUT_DIR) if __name__ __main__: import sys default_requirement ( 生成一个基于 FastAPI SQLite 的待办事项管理服务 包含创建、查询、更新、删除待办事项的 REST API 并提供 README、requirements.txt、Dockerfile 和基础测试。 ) requirement sys.argv[1] if len(sys.argv) 1 else default_requirement main(requirement)最后是校验脚本validator.py# 文件路径codegen_orchestrator/validator.py from pathlib import Path import subprocess REQUIRED_FILES [README.md, requirements.txt, Dockerfile] def validate_repo(repo_root: Path) - list[str]: errors [] if not repo_root.exists(): return [输出目录不存在无法校验] for filename in REQUIRED_FILES: if not (repo_root / filename).exists(): errors.append(f缺少关键文件: {filename}) python_files list(repo_root.rglob(*.py)) if not python_files: errors.append(未发现 Python 源码文件) return errors def run_build(repo_root: Path) - str: # 使用 compileall 做语法级校验实际项目中可替换为 pytest、mvn compile 等命令 result subprocess.run( [python, -m, compileall, -q, str(repo_root)], capture_outputTrue, textTrue, ) return result.stdout result.stderr这段代码有四个关键逻辑点。第一parse_json对模型输出做了容错处理解决“模型返回外层 json 代码块”的问题。没有这个处理JSON 解析很容易失败。第二生成模块时arch和tree被序列化后传入提示词让模型始终知道全局架构和已生成文件。这是模块契约和上下文回传的具体落地。第三校验和修复循环不是简单的“报错就停止”而是把错误日志喂回模型生成修复补丁。修复后再跑一次构建形成二次验证。第四所有生成结果都写入output/目录不会污染编排器源码目录。多次生成时建议清空output/后再运行。7. 运行效果与验证方法运行示例编排器cd codegen_orchestrator python orchestrator.py 生成一个基于 FastAPI SQLite 的待办事项管理服务包含增删改查 REST API提供 README、requirements.txt、Dockerfile 和测试预期的输出大致分为四个阶段架构蓝图阶段模型输出模块清单、目录树、技术栈建议。目录骨架阶段output/下按蓝图创建目录和占位文件。分模块生成阶段逐个模块生成源码文件并打印模块名和文件数。校验修复阶段打印静态校验结果和构建日志存在问题时自动调用模型修复。一个合理的生成结果大致是下面的目录结构。注意输出内容取决于你用的大模型和服务商以下只是演示预期output/ ├── README.md ├── requirements.txt ├── Dockerfile ├── app/ │ ├── __init__.py │ ├── main.py │ ├── models.py │ ├── schemas.py │ └── routers/ │ ├── __init__.py │ └── todos.py └── tests/ └── test_todos.py判断生成是否成功的标准有三个第一静态校验通过关键文件存在。README.md、requirements.txt、Dockerfile这些文件不应该缺失。第二构建命令没有语法错误。在示例中compileall不报错就说明所有 Python 文件语法合法。第三模块间引用路径正确。目录结构、import路径、依赖包声明这三个维度要保持一致。如果你生成的不是 Python 项目可以把validator.py里的run_build替换成对应技术栈的命令。Java 项目可以执行mvn -q compileNode 项目可以执行npm run build。反馈信号越接近真实构建修复效果越好。8. 常见问题与排查思路在实际使用这个编排器时以下几个问题最容易出现。问题现象可能原因排查方式解决方案解析 JSON 报错模型输出中带有解释文字或 markdown 代码块打印原始返回内容至命令行用parse_json容错处理提示词中强制“只输出 JSON”生成目录结构不一致后续模块生成时没有回传已有文件列表查看 prompts.yaml 中是否传入existing_files增量生成时始终把当前目录树加入上下文模块间 import 路径错误模块契约缺失模型自由发挥检查架构蓝图中的dependencies先让模型输出接口签名和依赖清单再生成代码构建日志过长导致模型上下文超限没有截断日志查看 API 请求长度截取前 3000-4000 字符作为修复输入修复后仍然失败修复循环只执行了一轮查看二次构建日志外层加循环最多修复 2-3 轮修复文件内容不是字符串模型把单个文件内容输出成数组或对象打印repair结构确认类型在写入前增加类型判断如isinstance(content, str)特别提醒一下“上下文超限”这个问题。仓库级代码生成很容易遇到长文本因为架构蓝图、模块说明、已生成文件列表加起来已经不小。实际工程中建议用关键信息摘要替代全量文件内容或者使用支持更长上下文的模型。9. 最佳实践、总结与后续学习方向把动态架构进化的思路落进真实项目时有几件事值得提前考虑。第一从内部工具项目开始验证。不要在第一个试点就直接生成核心业务系统。选一个内部工具服务把“架构规划 - 增量生成 - 构建反馈”这条回路跑通再逐步扩展。第二重视提示词的可维护性。把提示词