AgentScope-Java 入门搭建 Review Copilot 项目骨架一句话导语这一篇先不急着讲复杂 Agent我们先搭出一个能运行的前后端项目并创建第一个ReviewJob。后面 6 篇都会在这个项目上继续加能力。成品演示说明这张 GIF 展示的是整个系列完成后的最终效果。第 1 篇只搭项目骨架后续文章会逐步实现这些能力。系列说明本文是「AgentScope-Java 2.0.0-RC4 项目式入门」系列第 1 篇。这个系列不按概念散讲而是围绕一个可运行项目推进AgentScope Review Copilot代码评审助手。项目目标很明确做一个本地 Git diff 代码评审助手。完成整个系列后它应该具备这些能力读取本地 Git diff。读取变更文件上下文。生成结构化ReviewFinding。通过 SSE 推送评审进度。输出 Markdown 评审报告。前端展示 findings、报告并支持一键复制。控制工具权限确保不修改被评审源码。通过 Middleware 记录模型调用和错误。系列仓库https://github.com/ynzz-j/agentscope-review-copilot.git本篇对应项目内容起点空项目分支chapter/01-skeleton完成 tagchapter-01-complete目标后端和前端都能启动并能创建最小评审任务为什么先做项目骨架很多 Agent 教程一上来就写agent.call(你好);这当然能跑但它离真实项目还有一段距离。真实应用里Agent 通常不是孤立存在的。它需要被 HTTP API 调用需要保存任务状态需要和前端交互也需要明确哪些配置可以替换。所以这个系列第一步不是写一个聊天 Demo而是搭一个真实项目的最小骨架agentscope-review-copilot/ ├── backend/ │ └── Spring Boot WebFlux ├── frontend/ │ └── Vue 3 TypeScript Vite └── README.md后端负责评审流程前端负责创建任务、看进度、看结果。技术栈选择后端技术用途JDK 17AgentScope-Java 和 Spring Boot 的基础运行环境Spring Boot WebFluxHTTP API 和 SSE 事件流AgentScope-Java 2.0.0-RC4Agent、模型、工具、MiddlewareMavenJava 项目构建前端技术用途Vue 3页面框架TypeScript类型约束Vite开发服务器和构建Vue Router页面路由Pinia评审任务状态管理设计要点这里本来想搞个纯CLI项目但为了方便展示流程SSE、状态、报告复制这些能力在前端显示让人更容易理解所以弄了一个简单的前端页面。创建项目结构以我本地的为例大家可自行更换先创建独立仓库目录cdD:\workspace\whd\ynzz\articlesmkdiragentscope-review-copilotcdagentscope-review-copilotgitinit-bmain后端包名固定为com.ynzz.agentscope.reviewcopilotMavengroupId固定为com.ynzz这是后续所有 Java 代码的边界。包名统一文章、代码、GitHub 仓库才能保持一致。后端最小依赖后端pom.xml的关键依赖如下!-- backend/pom.xml --dependencygroupIdorg.springframework.boot/groupIdartifactIdspring-boot-starter-webflux/artifactId/dependencydependencygroupIdio.agentscope/groupIdartifactIdagentscope-core/artifactIdversion2.0.0-RC4/version/dependency这里先引入agentscope-core而不是一开始就绑定某个模型提供商。原因很简单本系列不指定默认模型提供商其实是阿里云欠费了不想冲哪个还有余额用哪个~。模型选择应该由运行环境决定。你可以用 DashScope、OpenAI、Anthropic、Gemini、Ollama也可以走 AgentScope RC4 支持的其他方式。但项目骨架阶段只应该保留可替换的模型层。第一个健康检查接口先写一个最小HealthController// HealthController.javaRestControllerpublicclassHealthController{GetMapping(/health)publicMapString,Stringhealth(){returnMap.of(status,UP,application,agentscope-review-copilot,version,2.0.0-RC4);}}启动后端cdbackend mvn spring-boot:run验证curlhttp://localhost:8080/health预期输出{status:UP,application:agentscope-review-copilot,version:2.0.0-RC4}这是整个项目的第一个验收点。定义 ReviewRequest 和 ReviewJob评审助手的第一件事不是调用模型而是创建一个评审任务。请求对象// ReviewRequest.javapublicrecordReviewRequest(NotBlankStringrepoPath,DiffModediffMode,StringbaseRef,StringsessionId,ListReviewCategoryfocusCategories){}任务对象// ReviewJob.javapublicrecordReviewJob(Stringid,StringsessionId,StringrepoPath,DiffModediffMode,StringbaseRef,ListReviewCategoryfocusCategories,ReviewStatusstatus,InstantcreatedAt,InstantstartedAt,InstantfinishedAt,ListReviewFindingfindings,StringreportPath,StringerrorMessage){}第一篇只需要任务能创建状态是CREATED。后续文章会逐步补上RUNNINGCOMPLETEDFAILEDfindingsreportPatherrorMessageModelFactory不指定默认模型这里是本系列很重要的一个约束。我们不在项目里默认选择 DashScope也不默认选择任何 provider。模型工厂先保留抽象// ModelFactory.javapublicinterfaceModelFactory{StringMISSING_PROVIDER_MESSAGE未配置模型提供商。请在 application.yml 或环境变量中显式选择一个 AgentScope-Java RC4 支持的 provider。;ModelgetModel();booleanisConfigured();}为什么这么做因为模型 provider 是运行时决策不应该写死在入门项目里。否则读者的第一个问题就会变成“为什么必须用某个平台”。本项目的目标是学习 AgentScope-Java 的 Agent 工程结构不是绑定某个厂商。AgentFactory先封装 ReActAgentAgentScope-Java 的核心是ReActAgent。但业务代码不要到处直接写 builder。我们先用AgentFactory包一层// AgentFactory.javaComponentpublicclassAgentFactory{privatefinalModelFactorymodelFactory;privatefinalToolkittoolkit;privatefinalListMiddlewareBasemiddlewares;publicReActAgentcreate(StringsessionId){returnReActAgent.builder().name(AgentScope Review Copilot).sysPrompt(只评审传入的 Git diff 和源码上下文。).model(modelFactory.getModel()).toolkit(toolkit).middlewares(middlewares).maxIters(8).defaultSessionId(sessionId).build();}}设计要点AgentFactory是后续扩展点。模型、工具、状态、权限、Middleware 都从这里汇入不要散落在 controller 或 service 里。这里要强调一点第一篇只封装AgentFactory不调用模型。真正的最小 Agent 行为会在第 3 篇通过 diff 摘要接入完整模型评审会在第 6 篇接入。这样做是为了先把可运行骨架和模型 provider 边界讲清楚。最小 Review API第一篇只做一个最小接口POST /api/reviews请求{repoPath:D:\\workspace\\demo-project,diffMode:WORKING_TREE,sessionId:demo-session}响应{id:review-20260706-200440-c5bda7f1,sessionId:demo-session,repoPath:D:\\workspace\\demo-project,status:CREATED}这个阶段还不需要真的读 diff也不需要生成报告。我们先把“任务对象”打通。前端项目初始化前端使用 Vue 官方脚手架npmcreate vuelatest frontend选择项TypeScript: Yes JSX: No Vue Router: Yes Pinia: Yes Vitest: Yes E2E: No ESLint: Yes Prettier: Yes配置 Vite proxy// vite.config.tsserver:{proxy:{/api:http://localhost:8080}}第一篇前端只需要一个创建页输入仓库路径。选择 diff 范围。输入 sessionId。提交后调用POST /api/reviews。验证后端cdbackend mvntestmvn spring-boot:run健康检查curlhttp://localhost:8080/health创建任务curl-XPOST http://localhost:8080/api/reviews ^-HContent-Type: application/json^-d{\repoPath\:\D:\\workspace\\demo-project\,\diffMode\:\WORKING_TREE\,\sessionId\:\demo\}前端cdfrontendnpminstallnpmrun dev打开http://localhost:5173设计思考AgentScope 和 Spring AI 的入口不同如果你熟悉 Spring AI第一反应可能是“为什么不直接写一个 ChatClient”因为 AgentScope-Java 的设计中心不是 ChatClient而是 Agent。维度AgentScope-JavaSpring AI核心入口ReActAgentChatClient主要目标自主推理和工具行动Spring 生态内的模型集成工具循环Agent 内建 ReAct 循环通常需要手动编排或靠 Advisor状态AgentStateChatMemorySpring AI 更适合“把模型能力集成进 Spring 应用”。AgentScope-Java 更适合“构建一个会推理、会行动、会管理状态的 Agent 应用”。这个系列选 AgentScope-Java是因为我们要做的是代码评审助手而不是单轮问答接口。常见问题为什么第一篇不调用模型因为模型不是骨架的重点。第一篇要确认项目能启动。API 能调用。前端能访问后端。Agent 和模型抽象位置正确。模型调用放到后续文章更合适。为什么不用默认 DashScope因为默认 provider 会把教程绑定到某个平台。本系列保留ModelFactory实际运行时再显式选择 provider。为什么后端用 WebFlux因为后面要做 SSE 事件流而 AgentScope-Java 本身也全面使用 Reactor。WebFlux 能让后端的响应式链路更自然。本篇小结这一篇完成了 AgentScope Review Copilot 的最小骨架后端 Spring Boot WebFlux 项目。前端 Vue 3 TypeScript Vite 项目。/health健康检查。ReviewRequest和ReviewJob。POST /api/reviews。ModelFactory和AgentFactory抽象。现在项目还不会真正评审代码。下一篇我们给它加上 SSE 事件流让前端能实时看到评审进度。系列导航篇目标题状态1项目骨架与第一个 Review Job本文2SSE 流式评审进度待发布3工具调用Git diff、文件上下文、规则检查待发布4状态管理与评审报告待发布5权限边界与只读安全待发布6Middleware 审计待发布7前端完善、GitHub 发布与扩展路线待发布作者亦暖筑序系列仓库https://github.com/ynzz-j/agentscope-review-copilot.gitAgentScope-Java 版本2.0.0-RC4