用Qoder搭建PaiAgent项目脚手架

大家好，我是二哥呀。

过去这两三年的时间里，相信大家都能感受到，AI 的发展速度实在是太快了，快到让人有点紧张，也快到让人感觉机会突然变多了。

每家公司，不管是互联网大厂，还是中小厂，都在增加 AI 岗位；并且如果你有 AI 相关的开发经验，求职和晋升就会更容易。

这个 AI 项目不一定要多大，多复杂，也不一定要做出什么行业级突破，只要你能真正参与、真正理解，产出一个跑起来的 AI 应用，你的技术视野、工程能力、解决问题的方法都会提升一大截。

• 你能拿到一个比竞争对手更大的 offer
• 你在团队里更容易承担有技术含量的需求，晋升更快
• 你的编码习惯、架构思维会被 AI 逼着进步
• 你看问题的视野也会更加开阔、系统

所以接下来，我准备带大家从零开始做一个扎实的 AI 项目——PaiAgent，借助 Qoder 和 Qoder CLI 来构建的，一个真正能运行和学到东西的 AI Agent 项目。

源码已经开源到GitHub上：https://github.com/itwanger/PaiAgent

我会以这个项目作为载体，带大家从最基础的模块开始，逐步接触到 workflow 工作流、LLM 模型调用、MCP 工具调用等等一系列 AI 应用开发所必须的知识储备。

开发工具主要用到阿里的 AI Coding 工具 Qoder，以及命令行工具 Qoder CLI。一步步理解一个 AI 项目为什么这样设计，它的骨架怎么搭，模块之间怎么协作，以及你能从中获取什么开发能力。

在这个系列中，我会把所有踩过的坑、所有需要注意的工程细节、所有能写进简历的亮点，都完整拆解出来，让大家不仅“能做出来”，还“知道为什么这样做”。

如果你愿意跟我一起坚持下去，那么这个 PaiAgent 项目，最后会成为你技术成长中的一个重要里程碑。

一、下载安装 Qoder+Qoder CLI

工欲善其事，必先利其器。

要开始我们的 PaiAgent 项目，第一步当然是把开发工具准备好。这个系列里我们会大量使用 Qoder 和 Qoder CLI，它们是阿里在 AI Coding 方向做的一整套工具组合，一个 IDE，一个命令行，各司其职。

我们从最简单、最基础的安装开始，让每个人都能顺利跟上。

01、安装 Qoder

Qoder 的官方下载地址是：https://qoder.com/ macOS、 Windows 和 Linux 版本都有哈。

下载安装之后，可以新建一个文件夹，比如说 PaiAgent-One，用 Qoder 打开它，整个界面非常的清爽，左侧的基础菜单包括 Quest Mode、仓库 Wiki 等核心功能，中间是 IDE 编辑区，右侧是智能会话区。

我们等会儿会用 Quest Mode 来生成 PaiAgent 的完整脚手架。

02、安装 Qoder CLI

Qoder CLI 的安装非常简单，直接执行 curl -fsSL https://qoder.com/install | bash 就可以安装了。启动方式也非常简单，在任何一个终端窗口执行 qodercli 就可以。

后面我们很多编程任务、bug 解决也都会通过 Qoder CLI 来完成，非常强大、好用，相信你体验后也会爱不释手。

二、使用 Quest Mode 搭建项目骨架

Quest Mode 主打一个 AI 自主研发，我们只需要把工程任务扔给他，Quest Mode 就会把模糊的需求翻译为详细的需求和设计说明书，再去自动拆解任务、执行、联调，然后给我们汇报结果。

我们开发者只需要在这期间进行一些验收和调教就可以了，开发效率可以说是直线上升。

那接下来，我们进入 Quest Mode，点击侧边栏的【quest】小图标，然后点击【新建任务】。

把我们的需求告诉他：

我要构建一个含前端、后台、工作流引擎的 AI Agent 项目，核心的功能就是我附件中告诉你的，一个典型的“Agent 流图执行面板”，左侧菜单包括大模型节点、工具节点添加；画板包含用户输入、大模型节点、超拟人音频合成工具节点、结束节点；调试抽屉开启的时候，可以输入文字，然后对工作流进行测试，输入一串文字，最终会给我们一段音频，进行 AI 播客播放。

点击【发送】，Qoder 就开始工作了。

我们不需要把所有细节一次性想清楚，Quest Mode 会帮我们把模糊的想法往工程化的方向推进。

有不明确的地方，他会询问我们，让我们明确，比如说前端技术栈是选择 React 还是 Vue，后端技术栈是选择 Python 还是 Java，工作流引擎是自研还是基于已有的，数据是否需要持久化，大模型的接入方式要不要支持 OpenAI、DeepSeek 和通义千问，等等。

接着，他会根据技术选项为 PaiAgent 项目创建详细的设计文档。

如果确认没有问题，就可以点击【采纳】。如果有任何不满意的地方，也可以亲自下手去调整。

这份设计文稿会保存 .qoder/quests 目录下，使用 markdown 编辑工具打开预览的时候，就能够看到清晰的流程图，mermaid 格式的。

好，接下来，点击【开始任务】，Qoder 就开始自主完成开发了，我们只需要静静的欣赏即可。

如果你在开始任务后，突然有新的想法，比如说把 JDK 从 17 升级到 21，也可以放弃当前任务，重新开始一个新的。

当然，最好是在设计阶段多花一点时间，因为这会影响后续的开发质量。为了给大家最真实的体验，我在这一步删掉 Spring Security，以简化初期的项目开发任务。

再次【开始任务】，Qoder 根据我们最终确认的技术选型，把整个 PaiAgent 工程拆成一个可执行的任务图，规划好每一步要做的任务清单：

• 第一阶段：基础框架搭建
• 第二阶段：工作流引擎开发
• 第三阶段：前端画布开发
• 第四阶段：测试功能开发
• 第五阶段：工具节点开发

如果仔细观察的话，你会看到每一项任务都会进入——规划 → 执行 → 验证 → 完成这样一个流程，就像你在看一个自动化构建系统帮你搭项目一样，非常丝滑，非常谨慎。

每一个阶段完成后，Qoder 都会进行一个梳理和总结，打勾的就代表已完成，工作量可真的不小。

来看一下，第一阶段，完成了基础框架的搭建，后端用的是 Spring Boot 3.x + Java 21 + MyBatis-Plus，前端用的是 React 18 + TypeScript + Vite + ReactFlow。

第二阶段，完成了工作流引擎的开发，涉及到 DAG 解析器: 拓扑排序(Kahn) + 循环检测(DFS)，节点执行器: 工厂模式 + 适配器模式等。

第三阶段，完成了前端画布的开发，涉及到节点面板（可拖拽）、画布区域（ReactFlow 实现拖拽、连线、移动）、状态管理（Zustand 管理工作流状态）等。

第四阶段，完成了工作流测试功能的开发，涉及到执行接口的联调、结果的展示和日志输出，以及节点执行结果的可视化。

第五阶段，完成了 MCP 工具节点的开发，支持超拟人音频合成节点、音频播放等。

所有功能开发完成后，Quest Mode 会对整个任务进行一个总结，如果确认无误后，就可以点击【接受】结束本次任务。

三、通过智能会话验证 Quest Mode 的开发结果

本次任务接受，Qoder 会自动生成两份非常关键的文档：

• 一份项目总结文档 summary
• 一份用户说明手册 user_guide

它们是一份工程验收清单，告诉我们如何启动、构建和检查整个项目成果。

接下来，我们按照它们的说明，把项目真正跑起来。

当然了，我不打算自己来干这件事，能让 AI 干的事，咱一律不动手。哈哈 😄

启动 Qoder 的智能会话窗口，选择【智能体】和【极致性能】，输入：

Quest Mode 已经完成了项目骨架的开发，并且给了我一份启动手册 summary.md，我希望你能按照快速启动小节中的说明来验证整个项目的成果。

这样如果有什么问题，可以直接让 Qoder 帮我们解决。比如说 8080 端口如果占用的话，Qoder 帮我们 kill 掉进程。

OK，后端成功启动。

前端也没问题。

点击【预览】，我们甚至可以在 Qoder 中直接查看效果，这是登录页。

这是工作流画布页：

如果出现错误，我们可以直接将错误扔给 Qoder，比如说“加载节点类型出错了”，他会自动帮我们修复。比如说数据库密码忘记配置了，他会在 application.yml 文件中帮我们添加上。

好，我们在画布上添加两个节点，真正实现了拖拽，虽然还没有输入输出节点，也没有节点的配置，但整体的完成度还是非常高的。

后面的章节我还会在这个基础上进行优化和迭代的，不着急。

咱们一步步来，希望的曙光就在眼前。

四、如何把 PaiAgent 写到简历上？

我把提示词也分享出来：

OK，整体的流程我们已经跑通了一部分，可以把大模型节点和超拟人合成节点添加到画布上了，前后端也都完成了，但还不完善，不着急，我们慢慢来。现在我需要总结一下目前完成的内容，并且把整个项目写到简历上。按照这样一个格式：

项目名 职位 周期

项目简介：

技术栈：

核心职责：

1、用到了什么技术栈，解决了什么问题，实现了什么业务，有哪些量化数据

2、xxx

要求至少 5 条以上的核心职责，有深度，专业。

整体效果非常不错，完全可以直接粘贴到简历上。

PaiAgent - AI Agent 工作流编排平台 | 全栈开发工程师 | 2025.11

项目简介: 基于 DAG(有向无环图)的 AI Agent 工作流可视化编排平台,支持通过拖拽式界面设计复杂的 AI 处理流程,实现大模型调用、音频合成等多节点协同工作。

技术栈: Spring Boot 3.4.1、Java 21、MyBatis-Plus 3.5.5、MySQL 8.0、Kahn 拓扑排序算法、DFS 循环依赖检测

核心职责:

• 自研 DAG 工作流引擎架构设计与实现,基于 Kahn 算法实现 O(V+E)时间复杂度的拓扑排序,配合 DFS 算法进行循环依赖检测,确保工作流正确执行。
• 采用工厂模式+适配器模式设计节点执行器框架,支持 6 种节点类型(OpenAI、DeepSeek、通义千问、TTS 等)的动态注册和扩展,单个工作流支持 100+节点的复杂编排场景
• 设计并实现大模型适配层统一封装,抽象出标准化的 LLM 调用接口,屏蔽 OpenAI、DeepSeek、通义千问等不同厂商 API 差异。
• 通过策略模式实现模型动态切换,支持温度、Token 数等参数精细化控制,为上层业务提供一致的调用体验,减少 70%的重复代码
• 基于 ReactFlow 构建可视化流程编辑器,实现拖拽式节点添加、连线编辑、画布缩放等交互功能。通过 Zustand 进行全局状态管理,解决节点状态同步的闭包陷阱问题。采用 HMR 热更新机制,前端构建时间控制在 200ms 以内
• 开发超拟人音频合成节点执行器(260+行核心代码),集成 TTS API 框架,实现文本到语音的转换能力。
• 建立基于 Token 的认证机制与权限拦截器,使用 Spring AOP 实现统一的请求拦截和 Token 校验,保障 API 接口安全。

五、小节

做完这一整套流程之后，很难不感慨一句：Qoder 的完成度，已经远远超出一个“代码生成工具”该有的表现。

特别是这次我们完整使用下来，Quest Mode 和智能会话这两个核心能力，几乎定义了未来开发的一种“新范式”。

• Quest Mode 不仅能理解我们的意图，而且能把我们的想法拆成标准的工程任务，逐步构建、逐步验证，最后给我们一个真正能运行的项目。
• 智能会话也不再只是聊天，它更像是一个全程参与的合作伙伴，会在关键节点提出补充建议、提醒我们遗漏的地方、帮我们弥补工程缺口。

这些本来是一个工程师需要 2 ～ 3 周才能完善的内容，Qoder 直接在几十分钟内就帮我们铺好底座。

我录了个屏，整个过程，完全是由 Qoder 操刀来完成，等于说后续我们只需要在这个骨架上进行迭代升级就可以了。

更关键的是，它生成的代码质量、配置结构、模块划分，已经不是“能跑就行”的水平，而是工程化程度非常高、可扩展性很强、能继续迭代的专业产物。

如果一个开发者要独立完成这些内容，可能要翻几十篇文档、查大量配置、踩一堆依赖冲突的坑；而 Qoder 在智能会话和 Quest Mode 的配合下，把这些步骤完全自动化了。

在后面的教程里，我们会继续基于这个骨架，构建真正能跑的 AI Agent，扩展节点能力，加入模型调用、工具调用、多模态处理，把 PaiAgent 从“能跑”做到“能打”。

我相信，随着 AI Coding 的继续进化，Qoder 会成为我们最可靠的工程助手，把想法一点点落地。未来 AI 开发的方式，就是这样被一步步推动起来的。