从0到1构建AI应用：Agent工作流与工程化实践

OpenAI Build Week 获奖项目揭晓之后，许多人把注意力放在获奖名单和炫酷 demo 上，但真正值得拆解的，是这些作品从 idea 到可运行产品的完整 build 过程。Build Week 这类活动比拼的不是谁记的 API 多，而是谁能在有限时间内完成从需求定义、原型设计、编码实现到测试部署的闭环。对正准备参加下一场 AI 黑客松，或者想用 AI 辅助方式从零做一个项目原型的开发者来说，先弄清楚 agent 工作流、API 接入、环境配置和排错链路，远比背一版获奖榜单更有用。

这篇内容就围绕“如何像一场 AI Build Week 那样，从 0 到 1 把 AI 应用真正落地”展开。你会看到一个以规划与执行为分工的 agent 工作流应该如何组织，如何准备 OpenAI API 环境，如何写出一个最小可运行项目，以及项目在构建、部署和演示阶段常见的报错怎么排查。

1. 获奖项目背后统一的技术主线：把 Agent 工作流当成工程来做

1.1 拆解获奖作品时，先看构建链路而不是只看效果

在 Build Week 这类限时活动中，能拿到高分的项目通常具备一个共同特征：它们有一个清晰的构建链路。这个链路包括需求拆解、技术选型、API 接入、验证方式、交付物演示和故障处理，而不是在一个 notebook 里写完 prompt 就结束。

很多初次参赛的开发者会犯同一个错误：花大量时间调一段提示词，却在项目结构、环境依赖和可复现性上留白。结果在评审演示时，项目无法在干净环境里跑起来，或在评委点开某个功能时因为缺少依赖直接报错。Build Week 的项目首先是一个 build 出来的软件，其次才是一个 AI 应用。这就意味着，项目的可运行性、可验证性和可交付性，通常比 prompt 的精细程度更重要。

1.2 AI Agent 不等于一条 prompt，它是多个组件的协作体

一个能完成实际任务的 agent 应用，往往由以下几个部分组成：

• 任务理解层：把用户需求翻译成结构化任务；
• 规划层：决定先做什么、后做什么、使用什么工具；
• 执行层：调用 API、读写文件、执行命令、处理结果；
• 记忆与上下文层：把历史操作和中间结果保存下来；
• 反馈与修正层：根据错误信息调整策略并重试。

在这样的结构里，OpenAI API 只是执行层的一部分。更常见的做法是把 agent 工作流拆成不同角色：负责规划的 agent、负责编码的 agent、负责验证的 agent。这样拆的好处是，每个 agent 的任务边界清晰，出错时反向追踪也更容易。

1.3 从社区项目里能直接观察到的三个趋势

从近期社区涌现的 AI 构建项目里，可以观察到三个明确趋势：

一是 agent 不再只做单轮问答，而是被设计成能够多步骤执行任务的工具，例如自动读取仓库、修改文件、运行测试并提交结果。二是开发者开始关注“可观测性”，也就是 agent 执行过程中发生了什么、调用了哪些工具、为什么选择了某个操作。三是项目普遍采用“计划与执行分离”的模式：负责计划的模块并不直接修改代码，负责执行的模块在拿到计划后才开始操作。

这种工程化思路同样适用于个人项目。你可以先写一个包含角色分工的规划文档，再让 agent 根据规划逐步实现，最后人工检查结果。这样写出来的代码，可读性和可维护性都远高于“一次性让 AI 生成整个项目”的做法。

2. 先想清楚是拆任务还是写代码：Plan Agent 与 Build Agent 的分工

2.1 Plan Agent 解决的是“做什么”的问题

Plan Agent 的目标不是立即输出代码，而是把模糊需求拆解成具体、有序、可验证的子任务。它需要回答几类问题：

• 这个功能涉及哪些输入输出？
• 需要哪些外部依赖？
• 数据从哪里来，存到哪里去？
• 有哪些边界条件和异常分支？
• 如何验证每一步是否成功？

在工程实践中，Plan Agent 的产物通常是一份结构化的任务清单，包含任务 ID、依赖关系、验收条件和预计改动文件。它不会直接写业务逻辑，而是先产出施工图。

如果是在团队协作里，Plan Agent 对应的不是“架构师”这个头衔，而是一份高质量的 PR 描述或 issue 拆解。把任务拆分清楚，后续无论使用人工编码还是 AI 编码，都会顺畅很多。

2.2 Build Agent 解决的是“怎么做”的问题

Build Agent 接收计划后，开始真正产出代码、配置文件和测试用例。它需要具备以下能力：

• 阅读现有项目结构；
• 理解依赖关系；
• 写出与项目风格一致的代码；
• 运行构建命令；
• 根据编译错误或测试失败结果修正代码。

一个合格的 Build Agent 不是一次性生成完代码就结束，而是进入“生成、验证、修复、再验证”的循环。这个循环最短的周期可能是几秒钟，例如发现一个 TypeScript 类型错误后立即修改；也可能会持续很长时间，例如多次修改后仍无法通过集成测试，需要返回 Plan Agent 重新定义方案。

2.3 实际开发中如何模拟这种分工

即使不使用任何 agent 框架，一个人也可以用流程模拟这种分工。

先写一份 plan 文档：

# 目标：实现一个汇率查询 CLI 工具 ## 任务拆分 1. 创建项目目录和 Python 虚拟环境 2. 安装 openai、python-dotenv 依赖 3. 实现汇率获取函数，支持 USD、EUR、CNY 4. 实现命令行入口，参数为 base 金额 5. 用 mock 数据编写测试用例 6. 运行测试并修复错误 ## 验收标准 - 命令可执行：python main.py --amount 100 --from USD --to CNY - 输出结果保留两位小数 - 缺少 API Key 时给出明确错误提示

然后再让编码环节按这个计划逐步落地。这个过程把“计划”和“执行”分层，最大的好处是：当项目出问题时，你可以快速判断是计划定义错了，还是执行实现错了，而不是把所有问题混在一起调试。

在 Build Week 场景中，获奖项目往往不会只有一个 agent 在干活。常被提到的分工模式是“build agent 和 plan agent 的区别”：build agent 贴近代码和执行环境，负责把任务变成真实的文件变更；plan agent 靠近需求侧，负责理解和拆解问题。两者通过一个共享的任务上下文协同工作，例如 plan agent 输出的 JSON 计划，由 build agent 读取后逐项执行。

3. 环境准备：API Key、Codex 和依赖初始化

3.1 环境版本不能拍脑袋，先做兼容性确认

在做任何 AI 项目前，先确认本地环境，再开始写代码。常见项目依赖如下：

如果原始项目没有给出明确版本，落地前要先确认依赖版本。这一点在团队协作中尤其重要，因为版本不一致会导致“我本地能跑，到你机器上就跑不了”的经典问题。

3.2 安装 OpenAI 依赖并管理 API Key

OpenAI 官方提供 Python SDK，最小安装命令是：

python -m venv .venv source .venv/bin/activate # Windows 下使用 .venv\Scripts\activate pip install --upgrade openai python-dotenv

API Key 不要直接写进代码，而是放到.env文件，并在.gitignore中忽略它。

.env示例：

OPENAI_API_KEY=sk-xxxx MODEL_NAME=gpt-4.1-mini MAX_TOKENS=1024

.gitignore至少包含：

.venv/ .env __pycache__/ dist/ node_modules/

这里要说明一个常见问题：API Key 是敏感凭据，如果被提交到公开仓库，可能导致额度被刷、账单异常甚至服务被恶意调用。无论项目多小，都要从第一天开始把.env隔离，不要把密钥写死在代码里。

3.3 OpenAI Codex 的接入方式

OpenAI 将 Codex 作为开源 agent 项目开放之后，开发者可以直接在本地环境里使用它，而不是只通过网页界面操作。仓库地址是github.com/openai/codex，安装和运行方式以官方仓库最新 README 为准。

一般通过 npm 或 brew 安装 CLI 工具：

npm install -g @openai/codex

运行前确认OPENAI_API_KEY已经写入环境变量：

export OPENAI_API_KEY="sk-xxxx" # Windows PowerShell 使用 $env:OPENAI_API_KEY="..." codex

Codex 会把任务拆解成多个步骤，在执行过程中自动读取文件、修改代码和运行命令。它比较适合做“有一个明确任务，但不确定实现细节”的场景，例如“修复这个项目里的类型错误”或“给仓库补一个 README 并生成示例”。

需要注意，类似 Codex 的工具执行速度取决于模型响应和本地命令运行速度，不要在高并发生产环境里直接把它当作自动化运维入口。使用前先在小仓库里跑通流程，确认它不会执行你不期望的破坏性命令。

3.4 初始化项目目录

一个可演示的 AI 项目，目录结构不用很复杂，但要保证职责清晰：

ai-build-week-demo/ ├── .env ├── .gitignore ├── README.md ├── requirements.txt ├── main.py ├── agent/ │ ├── __init__.py │ ├── planner.py │ └── executor.py └── tests/ └── test_planner.py

看到这个结构时，别人能在几分钟内理解项目由哪些部分组成。相比把所有代码堆在单个文件里，这种结构也方便后续接入 agent 工具，因为 agent 可以按目录定位到具体模块。

4. 从最小闭环开始：写一个能调通 OpenAI API 的示例

4.1 用什么业务场景做最小闭环

建议用一个“输入问题，返回结构化答案”的 CLI 工具作为最小闭环。它不是最复杂的 agent，但足够验证 API Key、依赖、代码结构和输出结果是否都正常。

main.py的简化实现：

import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client = OpenAI() MODEL = os.getenv("MODEL_NAME", "gpt-4.1-mini") def ask(question: str, max_tokens: int = 500) -> str: """向 OpenAI 发送问题并返回文本答案。""" try: response = client.responses.create( model=MODEL, input=question, max_output_tokens=max_tokens, ) return response.output_text except Exception as exc: return f"[ERROR] {exc}" if __name__ == "__main__": question = input("请输入你的问题: ") if not question.strip(): question = "用一句话解释什么是 agent harness" print(ask(question))

用这个例子启动项目时，Python 会按以下顺序工作：

1. load_dotenv()读取.env文件，加载 API Key；
2. OpenAI()客户端使用环境变量初始化；
3. client.responses.create()调用对话生成接口；
4. 返回结果通过response.output_text取出；
5. 异常会被捕获并显示完整错误信息。

运行方式：

python main.py

预期输出是一个包含答案的文本，例如“Agent harness 是运行 agent 时所需的上下文、工具和调度逻辑的集合”。如果 API Key 不合法，则会出现 401 错误提示。

4.2 把规划逻辑抽出来：Planner 模块

实际项目里，不要让单个函数做完所有事。把规划逻辑抽到agent/planner.py：

from typing import List def build_plan(goal: str) -> List[dict]: """根据目标生成简单的任务计划。""" return [ {"id": 1, "task": "理解需求", "detail": goal}, {"id": 2, "task": "设计方案", "detail": "拆分子任务并确定依赖"}, {"id": 3, "task": "实现代码", "detail": "调用 API 完成核心逻辑"}, {"id": 4, "task": "验证结果", "detail": "运行测试确认行为符合预期"}, ]

这个模块解决的是“任务拆分”问题。后续要接入更复杂的 agent 框架时，可以把这里的计划列表替换成由大模型动态生成的任务清单。

4.3 把执行逻辑抽出来：Executor 模块

agent/executor.py负责真正执行某个任务。示例中只实现打印和模拟执行：

from typing import Dict def run_step(step: Dict[str, object]) -> bool: print(f"执行任务 {step.get('id')}: {step.get('task')}") print(f" 任务详情: {step.get('detail')}") return True

这样拆分之后，main.py 变成为：读取目标、生成计划、逐项执行。

from agent.planner import build_plan from agent.executor import run_step goal = input("请输入项目目标: ") for step in build_plan(goal): if not run_step(step): print("任务执行失败，流程中断") break

这已经不是一条 prompt，而是一个具备基本职责划分的 agent 雏形。后续可以扩展的地方包括：让 plan 模块调用大模型生成结构化计划，让 executor 模块真正调用 OpenAI API，把执行日志保存到文件。

4.4 这个最小闭环教会你什么

它验证了技术链路是否可用，包括环境变量读取、SDK 调用、错误处理和模块拆分。在 Build Week 的语境下，先让“最小闭环跑通”比“实现所有功能”更重要。一个能在三分钟内运行并输出结果的简单项目，已经比一个功能复杂但无法在评审机器上启动的项目有竞争力得多。

5. 把项目变成可演示的产品：Docker、数据库和构建脚本

5.1 为什么演示环境会比开发环境更容易出问题

开发环境通常已经装好了 Python、Node、数据库和各种工具，因此很多问题不会被暴露。演示环境则完全不同，它可能是评委的电脑、一台云服务器或者一台刚重置的虚拟机。任何依赖缺失都可能让演示失败。

所以，项目要做成“可复现构建”，而不仅是“本地能跑”。可复现的最低要求是：有一份清晰的安装文档，依赖版本被锁定，启动命令是唯一的。

5.2 用 Docker Compose 把后端和数据库一次性拉起来

一个常见的演示架构包含一个业务后端和一个 MySQL 数据库。可以在项目根目录放一份docker-compose.yml：

version: "3.9" services: mysql: image: mysql:8.0 container_name: ai-demo-mysql environment: MYSQL_ROOT_PASSWORD: root123 MYSQL_DATABASE: ai_demo ports: - "3306:3306" volumes: - mysql_data:/var/lib/mysql app: build: . container_name: ai-demo-app depends_on: - mysql env_file: - .env ports: - "8000:8000" volumes: mysql_data:

启动命令：

docker compose up -d --build

这条命令会先构建镜像，再启动 MySQL 和应用容器。depends_on只保证容器启动顺序，不保证数据库已就绪，所以应用代码里要做重试逻辑。

需要注意，如果在执行docker compose up -d --build时出现镜像拉取失败，常见原因是网络问题或镜像仓库访问不稳定。可以先单独拉取基础镜像，排除网络因素后再构建。

5.3 构建脚本要保证可重复执行

无论是前端还是后端，都建议把“构建”和“运行”分开。例如：

npm install npm run build npm run preview

或：

pip install -r requirements.txt python main.py

构建脚本不建议包含容易受环境影响的逻辑，比如硬编码当前用户路径、读取非标准环境变量。更稳妥的做法是把所有配置项都从.env或命令行参数读取，而不是写死在脚本里。

5.4 演示时的“保底演示流程”

至少准备两条演示线路。主线路是完整功能演示，从启动到结束不超过 10 分钟；保底线路是只演示最小闭环，即打开应用、输入一个固定问题、展示输出结果。

如果主线路中涉及外部 API 不稳定，保底线路可以使用本地缓存的返回结果，或者一个离线可运行的 mock 接口。这样即使 API 服务临时不可用，评审也能看到产品的交互和流程。

6. 构建链路常见报错与排查路径

6.1 报错排查要有固定顺序

任何一个构建问题，都建议按以下顺序排查：

1. 输入是否正确，包括命令参数、文件路径和配置项；
2. 环境变量是否已加载，.env是否被读取；
3. 依赖版本是否锁定，各包是否兼容；
4. 构建配置是否正确，比如 TypeScript、Docker、Maven 的配置；
5. 权限、端口、网络是否满足要求；
6. 日志里的具体异常信息是什么；
7. 是否是工具本身限制或已知问题。

只有按这个顺序排查，才不会在环境变量没配置时去改业务代码。

6.2 高频构建问题速查表

下面这份表格覆盖了 Build Week 项目常见的几类报错。

6.3 遇到问题先看日志，再看堆栈

很多新手在项目无法构建时，会反复修改代码，却没有看过完整日志。实际上，大多数错误信息已经指明了方向。比如 Docker 构建失败时，使用：

docker compose build --progress=plain

能看到完整的构建上下文和每一条 RUN 命令的输出，包括依赖下载失败的具体 URL。比如 Python 依赖安装失败时，用：

pip install -r requirements.txt -v

可以得到详细网络请求信息。

日志是排错最重要的输入，比任何猜测都有价值。排查问题前，先问自己一个问题：完整日志里最后三行代码告诉我什么？

6.4 本地能跑，但演示环境不能跑怎么办

这是 Build Week 最常见的现场事故。缓解方法包括：

• 使用 Docker 固定操作系统、运行时版本和依赖；
• 在 README 中写明强制要求，例如 Python 版本、Node 版本、内存要求；
• 在项目里加一个scripts/check_env.sh脚本，启动时自动检查环境变量和命令是否存在；
• 准备好一次“无网络也能演示”的离线路径；
• 在正式演示前，用一台干净机器从头跑一遍安装流程。

这些措施不需要很高的技术含量，但能显著降低演示风险。

7. 提交前的检查清单与后续扩展方向

7.1 评审前可以逐项自检的清单

把下面这份清单打印出来，在提交或演示前逐项确认：

• 项目是否能在另一台机器上从零运行，并且有可复现的启动命令；
• .env是否被忽略，API Key 是否没有进入 Git 历史；
• README 是否包含项目简介、环境要求、安装步骤、启动命令和示例输出；
• 功能代码是否区分了核心逻辑和演示数据，没有把 mock 数据和真实逻辑混在一起；
• 测试是否覆盖了核心函数，至少包含一个正常路径和一个异常路径；
• 错误提示是否友好，比如缺少 API Key 时是否能给出明确提示，而不是抛裸异常；
• 是否有使用的模型和 token 消耗说明，避免评审时因为调用超时或额度不足而中断；
• 项目是否有日志输出，方便评审时观察执行过程；
• 演示是否能控制在最短时间内完成，并且不需要依赖复杂网络条件；
• 是否记录了已知问题和后续改进方向，体现工程上的完整性。

7.2 从最小项目到完整 Agent 的扩展路径

完成最小闭环后，可以按下面几个阶段扩展：

第一阶段，加入模型生成的计划。把build_plan函数改为调用大模型生成 JSON 格式的任务列表，再让 executor 读取并执行。

第二阶段，接入 Web 界面。用 FastAPI 或 Flask 暴露接口，前端提供一个聊天窗口或任务面板，让用户能看到 agent 每一步的执行过程。

第三阶段，加入工具调用。让 agent 能读取文件、运行命令、调用数据库查询，而不是只生成文本。

第四阶段，加入反馈回路。把测试结果和错误日志喂回给模型，让 agent 根据反馈修正代码。

第五阶段，面向生产环境做完善。包括日志结构化、监控指标、API Key 轮换、限流、缓存、审计记录和回滚机制。

7.3 代码审查和结果评估值得提前做

很多人低估了评估的重要性。使用大模型生成代码后，至少要做三类检查：

第一类是构建检查，确认项目能编译或解释执行；第二类是功能检查，运行测试用例确认行为正确；第三类是安全审查，检查有没有密钥泄露、危险命令、数据库删除操作等风险点。

如果项目里使用了 agent 自动执行命令，评估时还要特别关注它是否会执行高权限操作。安全策略应该在 agent 设计时就要体现，而不是等项目上线后再补救。

这几点虽然听起来基础，却是一个 AI 项目能否从“demo”走向“真正可用”的关键分界线。

7.4 从 Build Week 带走的最重要经验

回顾整个构建过程，最重要的不是某一个 API 的调用方式，也不是某个框架的最新版本，而是要有一套稳定的构建与验证流程。流程稳定之后，AI 工具才能最大程度发挥作用；流程缺失时，AI 生成代码越多，不确定性就越大。

下一次参加 Build Week 或同类活动，可以先不急着写代码。把 30 分钟用来确定项目目标、任务拆分、环境准备和验证方式，然后让 Plan Agent 和 Build Agent 在清晰边界内工作。这样写出来的作品，既能在评审时顺利运行，也能在活动结束后继续迭代成一个真实产品。