AgentScope-Java 入门：搭建代码评审小助手项目骨架

亦暖筑序
0 阅读8分钟

AgentScope-Java 入门：搭建 Review Copilot 项目骨架

一句话导语：这一篇先不急着讲复杂 Agent，我们先搭出一个能运行的前后端项目，并创建第一个 ReviewJob。后面 6 篇都会在这个项目上继续加能力。

成品演示

展示.gif

说明：这张 GIF 展示的是整个系列完成后的最终效果。第 1 篇只搭项目骨架，后续文章会逐步实现这些能力。

系列说明

本文是「AgentScope-Java 2.0.0-RC4 项目式入门」系列第 1 篇。

这个系列不按概念散讲，而是围绕一个可运行项目推进：AgentScope Review Copilot（代码评审助手）。

项目目标很明确：做一个本地 Git diff 代码评审助手。

完成整个系列后，它应该具备这些能力：

  • 读取本地 Git diff。
  • 读取变更文件上下文。
  • 生成结构化 ReviewFinding。
  • 通过 SSE 推送评审进度。
  • 输出 Markdown 评审报告。
  • 前端展示 findings、报告，并支持一键复制。
  • 控制工具权限，确保不修改被评审源码。
  • 通过 Middleware 记录模型调用和错误。

系列仓库：

获取方式见作者主页说明。

本篇对应：

项目内容
起点空项目
分支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 17+AgentScope-Java 和 Spring Boot 的基础运行环境
Spring Boot WebFluxHTTP API 和 SSE 事件流
AgentScope-Java 2.0.0-RC4Agent、模型、工具、Middleware
MavenJava 项目构建

前端：

技术用途
Vue 3页面框架
TypeScript类型约束
Vite开发服务器和构建
Vue Router页面路由
Pinia评审任务状态管理

设计要点：这里本来想搞个纯CLI项目，但为了方便展示流程，SSE、状态、报告复制这些能力在前端显示让人更容易理解，所以弄了一个简单的前端页面。

project-architecture-agentscope-review-copilot-1600x900.png

图：AgentScope Review Copilot 的最小项目骨架。

创建项目结构（以我本地的为例，大家可自行更换）

先创建独立仓库目录：

cd D:\workspace\whd\ynzz\articles
mkdir agentscope-review-copilot
cd agentscope-review-copilot
git init -b main

后端包名固定为：

com.ynzz.agentscope.reviewcopilot

Maven groupId 固定为：

com.ynzz

这是后续所有 Java 代码的边界。包名统一，文章、代码、GitHub 仓库才能保持一致。

后端最小依赖

后端 pom.xml 的关键依赖如下：

<!-- backend/pom.xml -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-core</artifactId>
    <version>2.0.0-RC4</version>
</dependency>

这里先引入 agentscope-core，而不是一开始就绑定某个模型提供商。

原因很简单：本系列不指定默认模型提供商（其实是阿里云欠费了，不想冲，哪个还有余额用哪个~）。

模型选择应该由运行环境决定。你可以用 DashScope、OpenAI、Anthropic、Gemini、Ollama，也可以走 AgentScope RC4 支持的其他方式。但项目骨架阶段只应该保留可替换的模型层。

第一个健康检查接口

先写一个最小 HealthController：

// HealthController.java
@RestController
public class HealthController {

    @GetMapping("/health")
    public Map<String, String> health() {
        return Map.of(
                "status", "UP",
                "application", "agentscope-review-copilot",
                "version", "2.0.0-RC4");
    }
}

启动后端：

cd backend
mvn spring-boot:run

验证：

curl http://localhost:8080/health

预期输出：

{
  "status": "UP",
  "application": "agentscope-review-copilot",
  "version": "2.0.0-RC4"
}

这是整个项目的第一个验收点。

定义 ReviewRequest 和 ReviewJob

评审助手的第一件事不是调用模型，而是创建一个评审任务。

请求对象：

// ReviewRequest.java
public record ReviewRequest(
        @NotBlank String repoPath,
        DiffMode diffMode,
        String baseRef,
        String sessionId,
        List<ReviewCategory> focusCategories) {
}

任务对象：

// ReviewJob.java
public record ReviewJob(
        String id,
        String sessionId,
        String repoPath,
        DiffMode diffMode,
        String baseRef,
        List<ReviewCategory> focusCategories,
        ReviewStatus status,
        Instant createdAt,
        Instant startedAt,
        Instant finishedAt,
        List<ReviewFinding> findings,
        String reportPath,
        String errorMessage) {
}

第一篇只需要任务能创建，状态是 CREATED。

后续文章会逐步补上：

  • RUNNING
  • COMPLETED
  • FAILED
  • findings
  • reportPath
  • errorMessage

ModelFactory：不指定默认模型

这里是本系列很重要的一个约束。

我们不在项目里默认选择 DashScope，也不默认选择任何 provider。

模型工厂先保留抽象：

// ModelFactory.java
public interface ModelFactory {

    String MISSING_PROVIDER_MESSAGE =
            "未配置模型提供商。请在 application.yml 或环境变量中显式选择一个 AgentScope-Java RC4 支持的 provider。";

    Model getModel();

    boolean isConfigured();
}

为什么这么做？

因为模型 provider 是运行时决策，不应该写死在入门项目里。否则读者的第一个问题就会变成“为什么必须用某个平台”。

本项目的目标是学习 AgentScope-Java 的 Agent 工程结构，不是绑定某个厂商。

AgentFactory：先封装 ReActAgent

AgentScope-Java 的核心是 ReActAgent。

但业务代码不要到处直接写 builder。我们先用 AgentFactory 包一层：

// AgentFactory.java
@Component
public class AgentFactory {

    private final ModelFactory modelFactory;
    private final Toolkit toolkit;
    private final List<MiddlewareBase> middlewares;

    public ReActAgent create(String sessionId) {
        return ReActAgent.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，也不需要生成报告。

我们先把“任务对象”打通。

review-job-created-flow-1600x900.png

图：第一篇只打通从前端提交到 ReviewJob.CREATED 的最小链路。

前端项目初始化

前端使用 Vue 官方脚手架：

npm create vue@latest frontend

选择项：

TypeScript: Yes
JSX: No
Vue Router: Yes
Pinia: Yes
Vitest: Yes
E2E: No
ESLint: Yes
Prettier: Yes

配置 Vite proxy：

// vite.config.ts
server: {
  proxy: {
    '/api': 'http://localhost:8080'
  }
}

第一篇前端只需要一个创建页：

  • 输入仓库路径。
  • 选择 diff 范围。
  • 输入 sessionId。
  • 提交后调用 POST /api/reviews。

验证

后端：

cd backend
mvn test
mvn spring-boot:run

健康检查：

curl http://localhost:8080/health

创建任务：

curl -X POST http://localhost:8080/api/reviews ^
  -H "Content-Type: application/json" ^
  -d "{\"repoPath\":\"D:\\workspace\\demo-project\",\"diffMode\":\"WORKING_TREE\",\"sessionId\":\"demo\"}"

前端：

cd frontend
npm install
npm run dev

打开：

http://localhost:5173

设计思考：AgentScope 和 Spring AI 的入口不同

如果你熟悉 Spring AI，第一反应可能是：

“为什么不直接写一个 ChatClient？”

因为 AgentScope-Java 的设计中心不是 ChatClient，而是 Agent。

维度AgentScope-JavaSpring AI
核心入口ReActAgentChatClient
主要目标自主推理和工具行动Spring 生态内的模型集成
工具循环Agent 内建 ReAct 循环通常需要手动编排或靠 Advisor
状态AgentStateChatMemory

Spring 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 发布与扩展路线待发布

作者：亦暖筑序
系列仓库：获取方式见作者主页说明。
AgentScope-Java 版本：2.0.0-RC4

avatar
文章
阅读
粉丝