文章目录
- 概述
- 一、项目概览
- 1.1 PlanNotebook 是什么？
- 1.2 核心技术栈
- 1.3 系统架构
- 二、环境准备
- 2.1 安装 JDK 17
- 2.2 安装 Maven 3.6+
- 2.3 获取 DashScope API Key
- 2.4 配置环境变量
- 2.5 准备 AgentScope Java SDK
- 三、项目骨架搭建
- 3.1 完整目录结构
- 3.2 创建目录
- 四、pom.xml：Maven依赖配置
- 五、配置文件
- 5.1 application.yml
- 5.2 logback.xml
- 六、Spring Boot 启动类
- 七、DTO层：数据传输对象
- 7.1 ChatRequest.java
- 7.2 SubTaskRequest.java
- 7.3 SubTaskResponse.java
- 7.4 PlanResponse.java
- 八、Service层：核心业务逻辑
- 8.1 FileToolMock.java：自定义工具
- 8.2 PlanService.java：计划管理服务
- 8.3 AgentService.java：核心Agent服务（精华解析）
- 8.3.1 初始化流程
- 8.3.2 SSE事件映射
- 8.3.3 人在回路（HITL）实现
- 九、Controller层：REST API
- 9.1 ChatController.java
- 9.2 PlanController.java
- 十、前端Web界面
- 十一、构建与运行
- 11.1 构建
- 11.2 运行
- 十二、测试验证指南
- 12.1 功能测试用例
- 用例1：简单对话
- 用例2：多步骤任务
- 用例3：人在回路暂停
- 用例4：健康检查
- 用例5：重置
- 12.2 REST API 测试脚本
- 12.3 日志验证
- 十三、常见问题排查
- Q1：启动报错 "DASHSCOPE_API_KEY environment variable is required"
- Q2：编译报错 "package io.agentscope.core does not exist"
- Q3：端口8080被占用
- Q4：Agent响应异常或无输出
- Q5：SSE流中断或前端无响应
- Q6：模型不显示"思考"过程
- 附录A：完整API参考
- Chat API
- Plan API
- SSE事件协议
- 总结
概述
2026年，AI Agent正在从概念走向落地。与传统的"一问一答"式对话机器人不同，AI Agent能够自主规划、调用工具、分步执行复杂任务，并在执行过程中接受人类干预——这正是"人在回路"（Human-in-the-Loop, HITL）的核心思想。
今天，我们将基于AgentScope Java SDK和Spring Boot WebFlux，从零构建一个名为PlanNotebook的AI智能计划助手Web应用。它不仅能通过对话式交互帮你拆解复杂任务，还能实时可视化展示执行计划，并支持你在Agent执行中途随时暂停、审查甚至修改计划后再继续。本文覆盖从环境搭建到API调用的全流程，所有代码均可直接运行。
一、项目概览
1.1 PlanNotebook 是什么？
PlanNotebook是一个基于ReAct（Reasoning + Acting）范式的AI Agent Web应用，具备以下核心能力：
| 能力 | 实现方式 |
|---|---|
| 对话式任务拆解 | Agent通过自然对话理解用户意图，自动创建结构化执行计划 |
| SSE实时流式输出 |
