【Agent项目】既是一个Agent项目，又能用来学习Agent

项目GitHub地址：https://github.com/Earth-OL-Player/ai_learn_project

一、先说这个项目到底是什么

最近我把一个 AI Agent 学习平台整理成了开源项目。

它表面上是一个学习平台：有学习路线、有 AI 面试题、有 AI 智能刷题、有成长体系、有建议评论区，也有管理后台。往里看一层，它又是一个完整的 Agent 工程样例：Vue 3 前端负责交互，Spring Boot 后端负责业务状态、鉴权、题库和成长结算，FastAPI 服务负责模型调用、评分 Agent、讨论 Agent 和本地兜底。

我更愿意把它理解成两个学习入口：

入口一：学习 AI Agent、RAG、大模型应用开发 入口二：学习如何用 AGENTS.md 约束 AI 编程助手做项目

这两个入口刚好在一个仓库里碰上了。

项目首页大概是这样：

二、为什么我没有只做一个题库

刚开始整理 AI 应用开发资料时，我也想过做成一个简单资料站。放一堆链接，按 LangChain、LangGraph、RAG、向量数据库分组，看起来很快就能上线。

但这类资料站有一个问题：收藏很容易，真正学会很难。

AI Agent 和 RAG 这类知识，很多时候不是“知道概念”就够了。面试或者做项目时，更常遇到这些问题：

这些题只看标准答案，通常看不出自己能不能讲清楚。

于是我把项目做成了一个学习闭环：

学习路线 -> 热门面试题 -> AI 智能刷题 -> AI 评分和继续追问 -> 成长体系和刷题记录 -> 回到薄弱点继续补

用户先回答，再得到反馈，最后回到个人中心复盘。资料不再是孤零零的一页链接。

三、项目模块总览

当前仓库里主要有三个工程。

ai_learn_project ├── ai-learn-web # Vue 3 前端，负责页面、路由、刷题工作台和管理端 ├── ai-learn-backend # Spring Boot 后端，负责认证、题库、互动、成长和 AI 服务调用 ├── ai-service # FastAPI AI 服务，负责评分 Agent、讨论 Agent 和模型适配 ├── doc # 需求、架构、接口、中间件、迭代和截图资料 ├── xuanchuan # 各平台宣传稿 └── QUICK_START.md # 本地启动说明

从功能上看，它已经覆盖了这些模块：

这不是一个“只有前端页面”的展示项目。它有数据库迁移，有内部 AI 服务鉴权，有模型调用兜底，有流式接口，也有本地启动文档。

四、整体架构：Java 管业务，Python 管 AI

这个项目的一个核心取舍是：没有让前端直接调用模型，也没有把所有 AI 逻辑塞进 Java 后端。

整体调用链路如下：

用户浏览器 -> Vue 3 + Vite 前端 -> Spring Boot 业务后端 -> MySQL 业务数据库 -> FastAPI AI 服务 -> OpenAI 兼容模型或本地规则兜底

我这样拆有两个原因。

第一，业务状态应该在后端手里。题库、用户、登录态、刷题阶段、经验结算、徽章发放，这些都是业务规则，不应该交给前端或者模型服务自由处理。

第二，AI 生态在 Python 里更顺手。模型适配、LangChain、LangGraph、Pydantic schema、流式输出，这些放在 FastAPI 服务里改起来比较轻。

边界最后定成了这样：

这个边界听起来普通，放到 AI 应用里却很管用。模型输出只是一个“建议结果”，最终能不能落库、怎么展示、怎么结算，仍然要由业务系统判断。

五、AI 智能刷题是项目里最像 Agent 的部分

智能刷题页面长这样：

一次完整刷题链路如下：

用户选择题目分类 -> 后端按权重抽题 -> 用户提交答案 -> Java 后端请求 Python AI 服务评分 -> Python 评分 Agent 输出结构化结果 -> Java 后端校验结果并结算经验 -> 前端展示评分、问题点、参考答案和成长反馈 -> 用户围绕当前题继续追问 -> Python 讨论 Agent 通过 SSE 流式回复

它不是一个开放式聊天框。它有明确阶段。

前端类型也把阶段写死了，避免页面变成一堆散落的布尔值：

exporttypePracticePhase='QUESTIONING'|'ANSWERING'|'DISCUSSING';exporttypePracticeAction='QUESTION'|'GRADING'|'DISCUSSION'|'TIP';

这点对聊天类产品很有用。只要页面有“阶段”，按钮、输入框、提示语和接口行为就能跟着阶段走，后面不会越写越乱。

六、评分 Agent：不是让模型随便打个分

评分接口在 Python 服务里，路径是：

POST /internal/v1/practice/answer/grade

Java 后端会把这些字段传给 AI 服务：

{"userId":"用户ID占位符","questionCode":"SYS-RAG-0001","question":"RAG 的核心流程是什么？","questionType":"RAG","standardAnswer":"参考答案占位符","userAnswer":"用户答案占位符","modelConfig":{"modelName":"模型名占位符","modelProvider":"供应商占位符"}}

评分 Agent 的提示词不是简单一句“请给这段答案打分”。它会明确告诉模型：

题目、参考答案、用户答案使用标签分隔。 只能根据用户答案判断命中点。 不能把参考答案里出现但用户没写的内容算成命中。 如果用户只是复述题目，必须给 0 分。 输出必须包含 score、hitPoints、missingPoints、problems、improvementAdvice。

对应代码在：

ai-service/app/practice/prompts.py ai-service/app/practice/grading_agent.py ai-service/app/schemas/practice.py

核心代码简化后大概是这样：

defgrade_answer(self,request:PracticeGradeRequest,trace_id:str)->PracticeGradeAgentResult:"""使用结构化模型非流式完成答案评分。"""messages=self._prompt_builder.build_grade_messages(request)result=self._model_factory.grading_model(request.modelConfig).invoke([SystemMessage(content=GRADE_SYSTEM_PROMPT),*messages])grading=self._structured_grading_result(result,request.standardAnswer)returnPracticeGradeAgentResult(grading=grading,metrics=metrics)

这里做了两个工程化处理。

一是结构化输出。评分结果不是一段散文，而是一组固定字段。前端要展示命中点、缺失点、问题点、建议和参考答案，没有结构化结果就很难稳定。

二是观测指标。评分链路会记录 traceId、模型名、耗时、token 用量和错误分类。AI 功能一旦上线，排查问题不能只靠“用户说不好用”，日志里必须能看到是哪次调用、哪个模型、耗时多少、是否兜底。

七、讨论 Agent：带着题目上下文追问

评分结束后，用户可以继续问：

我这个答案扣分主要在哪里？ 面试时怎么讲得自然一点？ 能不能给一个真实项目里的回答版本？ 这道题如果继续深挖，面试官可能问什么？

这个功能看起来像聊天，但它不是普通聊天。

讨论 Agent 会拿到题目、参考答案、用户最近一次答案、评分摘要和当前题短期历史。也就是说，用户问“我哪里答得不好”，模型知道“我”指的是哪道题、哪次答案、哪次评分。

构造上下文的代码在PracticePromptBuilder：

defbuild_discuss_context_prompt(self,request:PracticeDiscussRequest)->str:"""构造本题讨论上下文提示词。"""grading_summary=request.gradingSummaryor"暂无评分摘要"last_answer=request.lastUserAnsweror"暂无"return(f"题目分类：{request.questionType}\n"f"题目：{request.question}\n"f"参考答案：{request.standardAnswer}\n"f"用户最近一次答案：{last_answer}\n"f"AI评分结果摘要：{grading_summary}\n""下面会继续给出当前题历史追问消息和本轮最新疑问。")

这段代码不花哨，但解决了一个常见问题：AI 讨论不能丢上下文。

如果只把用户最后一句话发给模型，回复很容易变泛。把题目、答案和评分摘要都带上，模型才会围绕这次练习继续讲。

八、SSE 流式输出：别让用户等一整段答案

讨论接口使用 SSE 流式返回：

POST /api/v1/practice/messages/stream

前端接收事件时，只关心三类事件：

exportfunctionsendPracticeMessageStream(payload:PracticeMessagePayload,handlers:PracticeMessageStreamHandlers,):Promise<void>{returnpostStream<PracticeMessagePayload>('/practice/messages/stream',payload,(event)=>{if(event.event==='message'){handlers.onMessageChunk(event.data);return;}if(event.event==='result'){handlers.onResult(JSON.parse(event.data)asPracticeMessageResult);return;}if(event.event==='error'){thrownewError(event.data||'发送失败');}});}

Java 后端这边没有把流式请求扔到公共线程池，而是配置了专用线程池：

ai-learn-backend/src/main/java/com/earth/online/player/ailearn/common/config/AiStreamExecutorConfig.java

它做了几件事：

专用线程名前缀：ai-sse-stream- 核心线程数、最大线程数、队列长度支持配置 线程池满时直接拒绝请求 暴露 active、pool.size、queue.size、rejected 等监控指标 关闭时等待正在读流的任务释放

AI 流式接口比普通接口慢，也更贵。如果没有线程池、限流和断开取消，用户连续点几次按钮，就可能把后端拖住。

九、兜底策略：模型不可用时流程不能直接断

AI 项目最容易被低估的地方，是失败处理。

模型服务可能超时，Key 可能没配，供应商可能限流，结构化输出可能解析失败。用户不关心这些细节，他只知道“我点了提交，页面卡住了”。

项目里做了两层兜底。

第一层在 Java 后端。调用 Python AI 服务评分失败时，后端会回退到本地规则评分：

Optional<PracticeAiGradingResult>aiGradingResult=practiceAiClient.grade(userId,question,userAnswer,modelConfig);booleanfallbackUsed=aiGradingResult.map(PracticeAiGradingResult::fallbackUsed).orElse(true);GradingResultgradingResult=aiGradingResult.map(PracticeAiGradingResult::gradingResult).orElseGet(()->answerGradingPort.grade(userId,question.getId(),question.getQuestion(),question.getStandardAnswer(),List.of(question.getQuestionType()),userAnswer));

第二层在 Python AI 服务。讨论 Agent 流式失败时，会生成本地兜底提示，而不是假装模型给出了完整回答。

这里我比较在意的是诚实。兜底不是“伪造一个完美 AI 答案”，而是告诉用户服务暂时不可用，并尽量提供可解释的替代结果。

十、成长体系：评分之后要留下痕迹

很多刷题系统只做到“本次得分”。这不够。

用户更关心的是：

这次比上次好吗？ 我有没有突破历史最高分？ 我练过哪些题？ 哪类题最薄弱？ 长期看有没有进步？

项目因此做了成长体系：

经验规则没有设计成“每答一次就加固定分”。规则是：

本次新增经验 = max(0, 本次得分 - 历史最高分)

举几个例子：

这套规则避免了重复刷同一道题刷经验，也能鼓励用户把答案越答越好。

后端结算代码在：

ai-learn-backend/src/main/java/com/earth/online/player/ailearn/practice/application/PracticeGrowthSettlementService.java

核心代码很好懂：

intpreviousBest=NumberUtils.toIntOrZero(oldStat.getBestScore());intscore=NumberUtils.clampPercentScore(gradingResult.score());intearnedExperience=Math.max(0,score-previousBest);practiceMapper.updateLockedStatAfterAnswer(oldStat.getId(),score);

刷题记录页面也能看到长期复盘数据：

十一、学习路线：内容不是堆链接

项目里还有一块学习路线页面：

它的技术难度不高，但确实有必要。很多人学 AI Agent 时不是没资料，而是资料太散。

当前路线大致按这个顺序组织：

Python -> LangChain -> LangGraph -> RAG -> LlamaIndex -> 向量数据库 -> Agent 和 RAG 项目实践

内容存放在：

ai-learn-web/src/content/learning-roadmap/AI应用开发学习路线和资料集.md

前端用markdown-it渲染，用DOMPurify做 HTML 清洗，再用目录组件处理长文导航。相关文件：

ai-learn-web/src/pages/learning-roadmap/LearningRoadmapPage.vue ai-learn-web/src/components/common/MarkdownToc.vue ai-learn-web/src/utils/safeMarkdown.ts ai-learn-web/src/utils/markdownToc.ts ai-learn-web/src/styles/markdown.scss

这里有个设计取舍：学习资料不要写死在 Vue 组件里。

资料是内容，组件是交互。用 Markdown 管内容，后面补资料、换图片、改章节，成本低很多。

十二、为什么说它也能学习 AGENTS.md

现在很多人都在用 AI 写代码，但很多项目会遇到同一个问题：AI 能写，但它不知道项目的边界。

比如它可能会：

随手新增一个中间件，却不补文档 把真实 Token 写进示例配置 直接修改历史 Flyway 脚本 前端风格突然变成另一个产品 把 Controller 写成万能业务类 为了“完整性”顺手加一堆测试，和项目约定冲突

这个项目的AGENTS.md就是为了解决这类问题。它把项目要求写成明确规则。

节选几条：

新增或修改功能开始依赖 MySQL、Redis、Qdrant 等中间件时，必须同步补充中间件说明文档。 开源仓库内不得提交真实密码、Token、密钥、生产连接地址。 代码开发过程中禁止写单元测试代码，后续统一补。 前端界面 UI 风格要求清新简约大气。 涉及数据库修改，不要动历史 migration，而是新增新版本。

这类规则对人有用，对 Agent 更有用。

我的感受是，想让 AI 编程助手稳定参与项目，不能只在聊天框里临时说一句“按我的项目规范写”。规则要沉淀进仓库，让每次任务都有可读的项目上下文。

这个仓库能学两件事：

看业务代码：学习一个 AI Agent 刷题项目怎么做 看 AGENTS.md：学习怎么给 AI 编程助手设置项目边界

十三、项目文档也是工程的一部分

这个仓库里文档不是摆设。

主要文档如下：

我现在越来越觉得，项目文档不只是给后来的人看的，也是给 AI 看的。

当文档里写清楚“AI 服务不直接访问业务库”“内部接口使用X-Internal-Token”“新增中间件要补文档”，AI 在改代码时就更不容易乱跑。

十四、关键代码阅读路线

读源码时，我不建议从首页开始乱翻。可以按下面顺序看。

1. 先看启动入口和路由

ai-learn-web/src/router/index.ts ai-learn-backend/src/main/java/com/earth/online/player/ailearn/AiLearnBackendApplication.java ai-service/app/main.py

先知道页面怎么进、后端怎么启动、AI 服务怎么暴露接口。

2. 再看刷题主链路

ai-learn-web/src/pages/practice-agent/PracticeAgentPage.vue ai-learn-web/src/pages/practice-agent/usePracticeChat.ts ai-learn-web/src/api/practice.ts ai-learn-backend/src/main/java/com/earth/online/player/ailearn/practice/interfaces/PracticeController.java ai-learn-backend/src/main/java/com/earth/online/player/ailearn/practice/application/PracticeService.java ai-learn-backend/src/main/java/com/earth/online/player/ailearn/practice/application/PracticeGradingService.java ai-learn-backend/src/main/java/com/earth/online/player/ailearn/practice/application/PracticeDiscussionService.java

这条线能看到前端如何发起 SSE、后端如何根据阶段处理用户输入。

3. 然后看 AI 服务

ai-service/app/api/practice.py ai-service/app/practice/agent_service.py ai-service/app/practice/grading_agent.py ai-service/app/practice/discussion_agent.py ai-service/app/practice/prompts.py ai-service/app/practice/model_factory.py

这里能看到提示词、结构化评分、讨论 Agent、供应商适配和兜底策略。

4. 最后看成长和题库

ai-learn-backend/src/main/java/com/earth/online/player/ailearn/practice/application/QuestionSelectionService.java ai-learn-backend/src/main/java/com/earth/online/player/ailearn/practice/application/PracticeGrowthSettlementService.java ai-learn-backend/src/main/java/com/earth/online/player/ailearn/growth/application/GrowthService.java ai-learn-backend/src/main/java/com/earth/online/player/ailearn/growth/application/GrowthAwardService.java ai-learn-backend/src/main/resources/db/migration/

这部分能看到抽题权重、经验结算、徽章发放和数据库迁移。

十五、本地启动大概需要哪些东西

项目本地跑起来需要：

启动顺序可以按这个来：

# 1. 启动 MySQL，创建 ai_learn 数据库和本地账号# 2. 启动 AI 服务cd ai-service python-m venv.venv.\.venv\Scripts\Activate.ps1 pip install-r requirements.txt uvicorn app.main:app--host 0.0.0.0--port 8000# 3. 启动后端cd..\ai-learn-backend mvn spring-boot:run# 4. 启动前端cd..\ai-learn-web npm install npm run dev

环境变量不要直接写真实值进仓库。示例配置里都应该使用占位符：

DATABASE_URL="jdbc:mysql://127.0.0.1:3306/ai_learn?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=false" DATABASE_USERNAME="本地MySQL用户名占位符" DATABASE_PASSWORD="本地MySQL密码占位符" JWT_SECRET="至少32字节本地JWT随机密钥占位符" AI_SERVICE_ENABLED="true" AI_SERVICE_BASE_URL="本地AI服务地址占位符，例如 127.0.0.1:8000" AI_SERVICE_TOKEN="AI_SERVICE_TOKEN本地占位符" AI_GRADING_BASE_URL="模型服务地址占位符，例如 模型服务域名/v1/chat/completions" AI_GRADING_API_KEY="AI_GRADING_API_KEY占位符" AI_GRADING_MODEL="LOCAL_RULE"

如果没有配置真实模型，AI_GRADING_MODEL=LOCAL_RULE可以走本地规则兜底，至少能把基础刷题流程跑通。

十六、这个项目适合怎么用

想学 AI Agent，可以先按这个顺序用项目：

先看学习路线 -> 挑一个方向看热门面试题 -> 进入 AI 智能刷题自己答一遍 -> 看评分里的缺失点 -> 围绕当前题追问 -> 回个人中心看刷题记录

想学工程实现，可以反过来：

先跑项目 -> 看一次完整刷题请求 -> 跟 PracticeController 到 PracticeService -> 跟 PracticeAiClient 到 FastAPI -> 看 grading_agent.py 的结构化评分 -> 看 discussion_agent.py 的流式输出 -> 看 GrowthSettlement 怎么结算经验

想学怎么让 AI 编程助手参与项目，就看：

AGENTS.md doc/2.架构设计/2.2开发规范.md doc/2.架构设计/2.3接口规范.md doc/中间件/

这些文档比“某次聊天里的口头要求”更稳定，也更适合反复约束 Agent。

十七、我从这个项目里得到的几个经验

第一，Agent 项目不要只关注模型调用。真正麻烦的是业务状态、失败兜底、日志、限流、配置安全和上下文管理。

第二，评分类功能一定要结构化输出。前端要展示命中点、缺失点和建议，后端也要校验结果，散文式回答不适合直接进业务链路。

第三，讨论 Agent 必须带上下文。题目、参考答案、用户答案、评分摘要和短期历史都要传进去，否则回答会飘。

第四，AGENTS.md不是装饰文件。规则写得越清楚，AI 编程助手越不容易越界。尤其是数据库迁移、中间件文档、敏感配置、测试约束这类内容，最好直接沉淀到仓库里。

第五，学习平台不能只堆资料。能答题、能反馈、能复盘，用户才更容易知道自己哪里没掌握。

十八、结尾

这个项目还会继续迭代，但现在已经可以当成一个可运行的 AI Agent 学习样例来看。

它一边回答“AI Agent 学习平台怎么做”，一边也回答另一个问题：当我们开始让 AI 参与写代码时，项目应该怎样把规则、文档、边界和上下文准备好。

后一个问题会越来越绕不开。