第 1 章：为什么不是普通聊天机器人

1. 先看业务问题

产品运营同学提了一个真实工作里很常见的需求：

text

帮我分析最近 7 天新用户留存下降的原因，并给我一份下周拉活活动方案。

如果我们把这句话直接丢给普通 ChatBot，它可能很快给出一段报告：

text

新用户留存下降可能和用户体验、渠道质量、活动吸引力有关。
建议优化新手引导，增加优惠券召回，并通过推送触达沉默用户。

这段话看起来像回事。

但产品运营真正会继续追问：

你查了最近 7 天真实留存数据吗？
是所有渠道都下降，还是某几个渠道下降？
新用户激活率有没有一起下降？
最近有没有改版、活动、投放或注册流程变化？
历史上类似问题怎么处理？
这个活动方案有没有合规风险？
方案能不能保存，后续任务能不能创建？

普通 ChatBot 在这里就露馅了。

它能生成文字，但没有完成任务。

所以本章要先建立第一个核心判断：

text

产品运营要的不是一个会聊天的机器人，而是一个能围绕业务目标执行任务的 Agent 工作台。

2. 这一章为什么要学？

如果不先分清 ChatBot 和 Agent 工作台，后面代码会越写越偏。

常见错误是：

接一个大模型接口，就以为做了 AI 系统。
写几个 Prompt，就以为做了运营助手。
模型能回答问题，就以为做了 Agent。

真实项目不是这样。

产品运营关心的是：

数据准不准。
分析有没有依据。
方案能不能用。
文案能不能直接改。
风险有没有提醒。
最后能不能形成报告。
能不能少做重复劳动。

这些不是一个模型接口能单独解决的。

模型只是“语言理解和生成能力”。Agent 工作台还需要后端工具、知识库、权限、状态、流程和人工确认。

本章先把这个边界讲清楚。后面再接入 Spring AI Alibaba，才不会把系统写成“会聊天但不能办事”的 demo。

3. 这一章学完能做什么？

学完后，你能做到：

解释普通 ChatBot 为什么不能安全完成复杂运营任务。
说清楚 Agent 工作台需要补齐哪些后端能力。
跑通一个 JDK 17 + Spring Boot 接口，返回结构化业务分析。
看懂当前工程最小分层：api、application、domain。

本章不接入模型。

这不是偷懒，而是刻意设计。

第一章只解决边界问题：先知道为什么不能只靠 ChatBot，再进入模型调用。

4. 前置知识

需要：

JDK 17。
Maven。
Spring Boot 基础。
REST API 基础。
Java record。
Controller、Service、DTO 分层概念。

暂时不需要：

Spring AI Alibaba。
ChatClient。
Tool Calling。
MCP。
RAG。
Advisor。
Memory。
Skill。
Agent Framework。
Graph Core。

这些后面会按业务问题自然引入。

5. 本章涉及的核心组件

本章只用 Spring Boot 做一个业务认知接口。

涉及代码组件：

spring-boot-starter-web
Controller
Application Service
Request DTO
Response DTO
JUnit 5
MockMvc

本章只建立概念，不实现以下能力：

Spring AI Alibaba：后续负责模型接入。
Tool Calling：后续负责安全调用后端能力。
MCP：后续负责工具服务化和跨系统复用。
RAG：后续负责检索历史活动、SOP、风控规则。
Advisor：后续负责日志、权限、RAG、风控等横切增强。
Memory：后续负责多轮追问上下文。
Skill：后续负责沉淀运营业务能力包。
Agent Framework：后续负责单 Agent 和流程型 Agent。
Graph Core：后续负责企业级流程编排、状态恢复和失败重试。

6. 先写一个最小可运行版本

本章代码位置：

text

example/stage-01-operation-agent-workbench

本章新增接口：

text

POST /api/chapter-01/evaluate

这个接口不调用模型，只做结构化认知输出。

它接收运营需求：

json

{
  "demand": "帮我分析最近 7 天新用户留存下降的原因，并给我一份下周拉活活动方案。"
}

返回四类内容：

普通 ChatBot 的问题。
ChatBot 不能完成哪些动作。
Agent 工作台应该补齐哪些能力。
下一步为什么要进入 Spring AI Alibaba。

6.1 工程目录

text

stage-01-operation-agent-workbench/
  pom.xml
  README.md
  src/
    main/
      java/com/zhixing/operationagent/
        OperationAgentWorkbenchApplication.java
        api/
          ChapterOneController.java
          OperationDemandRequest.java
          StageOneController.java
          StageOneHealthResponse.java
        application/
          ChapterOneEvaluationService.java
          StageOneArchitectureService.java
        domain/
          ChapterOneEvaluation.java
          StageOneArchitecture.java
      resources/
        application.yml
    test/
      java/com/zhixing/operationagent/
        api/
          ChapterOneControllerTest.java
          StageOneControllerTest.java
        application/
          ChapterOneEvaluationServiceTest.java

6.2 pom.xml

xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.5.0</version>
        <relativePath/>
    </parent>

    <groupId>com.zhixing</groupId>
    <artifactId>stage-01-operation-agent-workbench</artifactId>
    <version>0.1.0-SNAPSHOT</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

6.3 application.yml

yaml

server:
  port: 18081

spring:
  application:
    name: stage-01-operation-agent-workbench

6.4 启动类

java

package com.zhixing.operationagent;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class OperationAgentWorkbenchApplication {

    public static void main(String[] args) {
        SpringApplication.run(OperationAgentWorkbenchApplication.class, args);
    }
}

6.5 Request DTO

java

package com.zhixing.operationagent.api;

public record OperationDemandRequest(String demand) {
}

6.6 Response DTO

java

package com.zhixing.operationagent.domain;

import java.util.List;

public record ChapterOneEvaluation(
        String demand,
        String ordinaryChatbotConclusion,
        List<String> chatbotLimitations,
        List<String> agentWorkbenchCapabilities,
        List<String> nextLearningSteps
) {
}

6.7 Service

java

package com.zhixing.operationagent.application;

import com.zhixing.operationagent.api.OperationDemandRequest;
import com.zhixing.operationagent.domain.ChapterOneEvaluation;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class ChapterOneEvaluationService {

    public ChapterOneEvaluation evaluate(OperationDemandRequest request) {
        String demand = normalizeDemand(request);

        return new ChapterOneEvaluation(
                demand,
                "普通 ChatBot 只能生成一段看似合理的话，不能安全完成这个运营任务。",
                List.of(
                        "拿不到真实业务数据",
                        "无法判断任务类型和执行顺序",
                        "不会调用受控后端能力",
                        "不能检索历史活动、运营 SOP 和风险规则",
                        "缺少人工确认、状态记录和失败兜底",
                        "无法保存方案和创建后续任务"
                ),
                List.of(
                        "任务识别",
                        "Tool Calling",
                        "MCP 工具服务化",
                        "RAG 知识库",
                        "Advisor 与 Memory",
                        "Skill 能力包",
                        "多智能体团队",
                        "Graph Core 编排"
                ),
                List.of(
                        "先跑通第 1 章业务认知接口",
                        "下一章再接入 Spring AI Alibaba 对话入口"
                )
        );
    }

    private String normalizeDemand(OperationDemandRequest request) {
        if (request == null || request.demand() == null || request.demand().isBlank()) {
            return "分析最近 7 天新用户留存下降原因，并生成拉活活动方案";
        }

        return request.demand().trim();
    }
}

6.8 Controller

java

package com.zhixing.operationagent.api;

import com.zhixing.operationagent.application.ChapterOneEvaluationService;
import com.zhixing.operationagent.domain.ChapterOneEvaluation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value = "/api/chapter-01", produces = "application/json;charset=UTF-8")
public class ChapterOneController {

    private final ChapterOneEvaluationService evaluationService;

    public ChapterOneController(ChapterOneEvaluationService evaluationService) {
        this.evaluationService = evaluationService;
    }

    @PostMapping("/evaluate")
    public ChapterOneEvaluation evaluate(@RequestBody OperationDemandRequest request) {
        return evaluationService.evaluate(request);
    }
}

6.9 测试

java

package com.zhixing.operationagent.application;

import com.zhixing.operationagent.api.OperationDemandRequest;
import com.zhixing.operationagent.domain.ChapterOneEvaluation;
import org.junit.jupiter.api.Test;

import static org.assertj.core.api.Assertions.assertThat;

class ChapterOneEvaluationServiceTest {

    private final ChapterOneEvaluationService evaluationService = new ChapterOneEvaluationService();

    @Test
    void evaluateReturnsBusinessReasonsAndAgentCapabilities() {
        ChapterOneEvaluation evaluation = evaluationService.evaluate(
                new OperationDemandRequest("分析最近 7 天新用户留存下降原因，并生成拉活活动方案")
        );

        assertThat(evaluation.demand()).contains("新用户留存下降");
        assertThat(evaluation.ordinaryChatbotConclusion()).contains("不能安全完成");
        assertThat(evaluation.chatbotLimitations())
                .contains("拿不到真实业务数据", "无法保存方案和创建后续任务");
        assertThat(evaluation.agentWorkbenchCapabilities())
                .contains("任务识别", "Tool Calling", "RAG 知识库", "Graph Core 编排");
        assertThat(evaluation.nextLearningSteps())
                .containsExactly(
                        "先跑通第 1 章业务认知接口",
                        "下一章再接入 Spring AI Alibaba 对话入口"
                );
    }
}

7. 运行一下，看现象

进入工程目录：

powershell

Set-Location D:\codex_space\personal-docs-site\example\stage-01-operation-agent-workbench

先跑测试：

powershell

mvn.cmd test

启动服务：

powershell

mvn.cmd spring-boot:run

发送请求：

powershell

$body = @{
  demand = "帮我分析最近 7 天新用户留存下降的原因，并给我一份下周拉活活动方案。"
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "http://localhost:18081/api/chapter-01/evaluate" `
  -Method Post `
  -ContentType "application/json; charset=utf-8" `
  -Body $body

预期响应：

json

{
  "ordinaryChatbotConclusion": "普通 ChatBot 只能生成一段看似合理的话，不能安全完成这个运营任务。",
  "chatbotLimitations": [
    "拿不到真实业务数据",
    "无法判断任务类型和执行顺序",
    "不会调用受控后端能力",
    "不能检索历史活动、运营 SOP 和风险规则",
    "缺少人工确认、状态记录和失败兜底",
    "无法保存方案和创建后续任务"
  ],
  "agentWorkbenchCapabilities": [
    "任务识别",
    "Tool Calling",
    "MCP 工具服务化",
    "RAG 知识库",
    "Advisor 与 Memory",
    "Skill 能力包",
    "多智能体团队",
    "Graph Core 编排"
  ]
}

观察重点：

普通 ChatBot 的问题不是“不会写字”，而是“不能执行受控业务动作”。
本章返回的是结构化结果，方便后续前端或下一步流程读取。
响应头显式声明 UTF-8，避免中文乱码。

失败现象：

端口占用：Port 18081 was already in use。
JDK 不匹配：Maven 编译阶段提示版本不支持。
请求体不是 JSON：Spring 无法解析 OperationDemandRequest。

关键断点：

ChapterOneController#evaluate
ChapterOneEvaluationService#evaluate
ChapterOneEvaluationService#normalizeDemand

8. 代码讲解

调用链：

text

运营需求 JSON
↓
ChapterOneController#evaluate
↓
OperationDemandRequest
↓
ChapterOneEvaluationService#evaluate
↓
ChapterOneEvaluation
↓
JSON 响应

ChapterOneController 只做 HTTP 接入。

它不写判断逻辑，因为 Controller 不应该变成业务逻辑堆放处。

OperationDemandRequest 是请求模型。

现在只有一个字段 demand。后续章节会把它升级成结构化任务单。

ChapterOneEvaluationService 是应用层。

这一层负责组织“普通 ChatBot 为什么不够”和“Agent 工作台需要补什么能力”。

ChapterOneEvaluation 是响应模型。

它没有返回一段大文本，而是返回结构化字段。这样后续前端、测试、日志和流程编排都更容易处理。

9. 为什么要这样设计？

为什么本章不用 ChatClient？

因为本章要建立业务边界。模型调用是下一章的主题。

为什么不用 Tool Calling？

因为 Tool 是给模型调用后端能力用的。现在还没有模型，也没有要查询的数据接口。

为什么不用 MCP？

MCP 是工具服务化。只有当工具能力需要跨 Agent、跨系统复用时，才需要进入 MCP。

为什么不用 RAG？

RAG 解决的是“查资料再回答”。本章只证明未来为什么需要查资料。

为什么不用 Skill？

Skill 是可复用业务能力包。第一章还没有沉淀运营分析、活动策划、文案生成这些能力。

为什么不用 Agent Framework 和 Graph Core？

因为复杂流程还没出现。Graph Core 应该在分支、并行、人工确认、重试、恢复这些需求出现后再引入。

本章的正确姿势是：

text

先分清业务边界
再接模型
再接工具
再接知识库
再做 Agent 和 Graph

10. 画出流程图

text

运营提出复杂需求
↓
普通 ChatBot 生成泛泛建议
↓
运营追问数据依据、历史案例、风险和执行动作
↓
发现普通 ChatBot 不能完成任务
↓
拆出 Agent 工作台必须具备的能力
↓
用 Spring Boot 先搭建最小业务认知接口
↓
下一章接入 Spring AI Alibaba 对话入口

11. 真实项目怎么落地？

真实项目里，不要让模型直接承担所有事情。

建议边界：

Controller：接收请求、返回响应。
Application Service：编排业务流程。
Domain DTO：表达业务语义。
Tool：封装具体安全动作。
MCP Server：把通用工具服务化。
RAG：检索历史活动、运营 SOP、风控规则。
Advisor：统一处理日志、权限、RAG、风控增强。
Memory：保存多轮上下文。
Skill：沉淀可复用运营能力。
Agent：执行一类智能任务。
Graph Core：编排复杂长流程。

本章代码是教学 Demo，不是生产方案。

生产环境还需要：

请求参数校验。
统一异常处理。
接口鉴权。
日志追踪。
操作审计。
配置分环境管理。
更完整的测试。

这些后续章节会逐步补。

12. 常见坑

坑一：把“能回答”误认为“能办事”。

现象：模型能写报告，但没有真实依据。
原因：没有接入数据、工具、知识库和状态。
解决办法：把文本生成和任务执行拆开。
如何提前避免：先定义 Agent 工作台能力边界。

坑二：一上来就接模型。

现象：demo 很快能聊，但后面接 Tool、RAG、Graph 时结构混乱。
原因：没有先设计业务分层。
解决办法：先跑通 Spring Boot 骨架和业务认知接口。
如何提前避免：第一章不接模型。

坑三：让模型直接判断业务事实。

现象：模型说“渠道质量下降”，但没有数据支撑。
原因：模型没有访问真实业务指标。
解决办法：后续通过 Tool 或 MCP 查询受控后端数据。
如何提前避免：所有业务事实都要能追溯来源。

坑四：把教学 Demo 当生产方案。

现象：接口能跑，就想直接接到业务系统。
原因：忽略鉴权、校验、异常、审计和观测。
解决办法：明确 Demo、工程可用版、生产级版本的差距。
如何提前避免：每章都写工程边界。

坑五：一次引入太多概念。

现象：ChatClient、Tool、RAG、Agent、Graph 全写在一章里，能跑但讲不清。
原因：缺少问题驱动的迭代节奏。
解决办法：每章只解决一个主要问题。
如何提前避免：让下一章由上一章不足自然引出。

13. 本章小结

这一章必须掌握：

普通 ChatBot 只能生成文本，不能安全执行复杂运营任务。
Agent 工作台需要后端工具、知识库、权限、状态、流程和人工确认。
当前工程采用 api → application → domain 的最小分层。
第 1 章代码只服务业务认知，不提前实现后续能力。

需要能解释：

为什么第一章不接模型。
为什么结构化响应比一段文本更适合工程演进。
为什么后续会自然进入 Spring AI Alibaba。

暂时了解即可：

Tool、MCP、RAG、Advisor、Memory、Skill、Agent、Graph 的名字和大致职责。

下一章要解决：

text

如何让这个工作台真正调用大模型，生成第一版运营回复？

14. 课后练习

基础练习：

把请求中的需求改成：

text

帮我生成一份双 11 活动复盘报告。

观察返回结果是否仍然能解释普通 ChatBot 的限制。

改造练习：

给 ChapterOneEvaluation 增加字段：

text

riskWarnings

返回至少 3 条风险提示：

没有数据依据。
没有人工确认。
没有保存执行状态。

综合练习：

找一个你公司真实的运营任务，写出普通 ChatBot 不能完成它的 5 个原因，并标出后续应该由 Tool、MCP、RAG、Skill、Agent、Graph Core 中哪个能力解决。

第 1 章：为什么不是普通聊天机器人 ​

1. 先看业务问题 ​

2. 这一章为什么要学？ ​

3. 这一章学完能做什么？ ​

4. 前置知识 ​

5. 本章涉及的核心组件 ​

6. 先写一个最小可运行版本 ​

6.1 工程目录 ​

6.2 pom.xml ​

6.3 application.yml ​

6.4 启动类 ​

6.5 Request DTO ​

6.6 Response DTO ​

6.7 Service ​

6.8 Controller ​

6.9 测试 ​

7. 运行一下，看现象 ​

8. 代码讲解 ​

9. 为什么要这样设计？ ​

10. 画出流程图 ​

11. 真实项目怎么落地？ ​

12. 常见坑 ​

13. 本章小结 ​

14. 课后练习 ​

第 1 章：为什么不是普通聊天机器人

1. 先看业务问题

2. 这一章为什么要学？

3. 这一章学完能做什么？

4. 前置知识

5. 本章涉及的核心组件

6. 先写一个最小可运行版本

6.1 工程目录

6.2 pom.xml

6.3 application.yml

6.4 启动类

6.5 Request DTO

6.6 Response DTO

6.7 Service

6.8 Controller

6.9 测试

7. 运行一下，看现象

8. 代码讲解

9. 为什么要这样设计？

10. 画出流程图

11. 真实项目怎么落地？

12. 常见坑

13. 本章小结

14. 课后练习