项目简介

本项目是一个 Java 开发者系统转型 AI Agent 工程师 的完整学习路线与实战源码集合。

目标不是研究大模型算法，而是成为能够独立设计、开发、部署和商业化 AI Agent 的高级工程师。

每一天的学习都以 独立模块 形式存在，可独立运行、独立理解，最终汇聚为一个可商业化的 AI Agent 平台。

最终目标

• AI Agent 架构师
• 开发自己的 AI SaaS
• 建立自己的 AI Agent 平台
• 接企业 AI 项目
• 创业

技术栈

已引入并实际使用

文档中规划、代码尚未落地

以下技术在各模块 docs/ 中被反复引用，但当前仓库中并没有实际依赖或实现，阅读时请注意区分"教程目标"与"当前代码"：

• PostgreSQL + pgvector（向量检索目前是内存实现 InMemoryVectorStore，重启即丢）
• Redis（会话/记忆存储目前是 InMemorySessionStore）
• Spring Modulith（模块物理隔离尚未引入，所有 Day 模块共享同一 Spring 上下文）
• LangChain4j
• Docker / Kubernetes（仓库中无任何 Dockerfile、docker-compose、K8s 清单）
• Testcontainers（全仓库目前 0 个测试文件）

项目结构

Java-Agent-Study/
├── src/main/java/com/zero/ai/agentstudy/
│   ├── back/                        # 早期实验代码（API原理/流式/结构化输出 8 个 Demo）
│   ├── day01foundation/             # Day1  - AI基础 & 第一个LLM Demo
│   ├── day02llmapi/                 # Day2  - LLM API & 企业级Chat服务
│   ├── day3funcall/                 # Day3  - Function Calling & Tool Calling
│   ├── day4memory/                  # Day4  - Memory & 会话管理（8 章渐进）
│   ├── day05rag/                    # Day5  - RAG & 企业知识库
│   ├── day06workflow/               # Day6  - Workflow Engine
│   ├── day07mcp/                    # Day7  - MCP协议
│   ├── day08multiagent/             # Day8  - Multi-Agent协作
│   ├── day09browseragent/           # Day9  - Browser Agent & 浏览器自动化
│   ├── day10planningagent/          # Day10 - Planning Agent & 自主规划
│   ├── day11humanintheloop/         # Day11 - Human-in-the-loop 人工审批
│   ├── day12longrunningagent/       # Day12 - Long Running Agent 长生命周期运行时
│   ├── day13officeagent/            # Day13 - AI Office Agent 办公自动化
│   ├── day14wechatagent/            # Day14 - Enterprise AI WeChat Agent
│   ├── day15knowledgeplatform/      # Day15 - 企业知识平台（13 模块 + 14 章，全链路可跑）
│   ├── day16knowledgeagentv2/       # Day16 - 企业知识智能体 V2（演示）
│   └── AgentStudyApplication.java
├── src/main/resources/
│   ├── application.yml              # 统一配置（所有模块共享）
│   └── static/                      # 前端演示页面
├── website/                         # 占位目录（暂未使用）
├── pom.xml
└── README.md

每个 Day 模块内部结构：

dayXX/
├── controller/     # API 入口
├── service/        # 业务逻辑
├── config/         # 配置类
├── dto/            # 数据传输对象
├── entity/         # 实体
├── tool/           # Agent 工具
└── docs/           # 学习文档
    ├── README.md
    ├── ARCHITECTURE.md
    ├── TODO.md
    └── chapters/   # 逐章学习记录

较新的模块（Day11 起）普遍采用 DDD + 六边形架构，包结构演进为 domain/ → application/ → infrastructure/ → web/，并大量使用强类型 ID 与领域事件。

学习路线（30 天）

已完成（Day01 – Day14）

骨架 / 演示阶段（Day15 – Day16）

这两个模块文档先行、代码待补：教程已完整，docs/ 里描述的多数模块与 API 尚未实现。

规划中（Day17 – Day30）

快速开始

环境要求

• JDK 21+
• Maven 3.9+
• LM Studio（本地模型推理）或任意 OpenAI 兼容 API 服务

1. 克隆项目

git clone [email protected]:zeroaihub/Java-Agent-Study.git
cd Java-Agent-Study

2. 配置模型服务

编辑 src/main/resources/application.yml：

spring:
  ai:
    openai:
      base-url: http://127.0.0.1:1234   # LM Studio 或你的 API 地址
      api-key: sk-1234                   # 本地模型可随意填写
      chat:
        options:
          model: your-model-name         # 替换为你加载的模型

Day05 RAG 还需单独配置 Embedding 模型（与聊天模型不同）：

rag:
  embedding:
    base-url: http://127.0.0.1:1234
    api-key: sk-1234
    model: text-embedding-nomic-embed-text-v1.5

3. 启动项目

mvn spring-boot:run

4. 访问接口

项目启动后访问 http://localhost:8080，各模块 API 路径见下方接口速查表。

前端演示页面：

• 聊天界面：http://localhost:8080/chat.html
• 流式输出：http://localhost:8080/stream.html

接口速查表

所有模块共享同一个 Spring 上下文与 8080 端口，启动时全部接口一次性可用。

注意：Day12 与 Day14 都使用了 /api/agent 前缀（方法级子路径不同，不会冲突，但联调时需留意）。Day13、Day15、Day16 当前没有对外 HTTP 接口。

模块说明

Day01 - Foundation（AI 基础）

AI 发展史、LLM 核心概念、Java AI 开发环境搭建、使用 Spring AI ChatClient 完成第一个 LLM 对话 Demo。

Day02 - LLM API（大模型接口）

深入 Chat Completion API 协议，实现流式输出（SSE）、多轮对话、Token 计费、结构化输出，构建企业级 Chat 服务。

Day03 - Function Calling（工具调用）

实现 LLM 自主调用 Java 方法：Tool 注册中心、参数解析、执行引擎、Assistant 多轮工具调用循环。

Day04 - Memory（记忆系统）

8 个章节渐进式实现：基础对话记忆 → 滑动窗口 → Token 截断 → 摘要压缩 → 长期记忆 → 用户画像 → 记忆检索 → 完整 Memory Agent。

Day05 - RAG（检索增强生成）

从零实现 RAG 全链路：文档分块 → Embedding 向量化 → 向量存储 → 相似度检索 → Prompt 注入 → LLM 生成。

模块内存在两套并行实现，学习时请注意区分：

• 顶层教学版（day05rag/service/）：纯 Java、自带 main()，使用 HashEmbeddingClient（哈希伪向量）+ EchoLlmClient，零依赖即可跑通，用于理解原理。
• mycode 实战版（day05rag/mycode/）：Spring Bean，调用真实 /v1/embeddings 与 ChatModel，带 Top-3 截断、相似度阈值 0.2、无命中时明确"不编造"。

本模块未使用 Spring AI 的 VectorStore，向量化与向量库均为自研。

Day06 - Workflow（工作流引擎）

设计并实现 Agent Workflow 引擎：节点抽象、上下文传递、指数退避重试、耗时统计、执行日志。执行模式为顺序责任链（非 DAG），节点可返回 SUSPENDED 挂起。

Day07 - MCP（模型上下文协议）

实现 MCP Client/Server 通信协议（手写 JSON-RPC）、Tool Registry 动态注册、Workflow 与 MCP 联动。当前传输层为 InProcessTransport 进程内直连，尚未实现真实的 stdio / HTTP 跨进程通信。

Day08 - Multi-Agent（多智能体协作）

构建 Coordinator 调度器 + Planner 规划器 + 多专职 Agent（Research / Writer / Reviewer / Translator），实现共享 Memory 与协作消息传递。

Day09 - Browser Agent（浏览器智能体）

基于 Playwright 实现浏览器自动化：BrowserSession 会话管理、ContextPool 连接池、PlaywrightEngine 执行引擎、BrowserTools 工具集（以 @Tool 暴露给模型）。

Day10 - Planning Agent（规划智能体）

Agent 从「被驱动」走向「自主」的分水岭。实现完整 Planning Engine：Goal 目标建模 → LlmPlanner 动态规划 → DagScheduler 依赖调度（含环检测）→ StepExecutor 逐步执行 → ToolSelector 工具选择 → LlmReflector 反思与自我修正（CONTINUE / RETRY_STEP / REPLAN / ABORT 四分支）→ 预算护栏。

Day11 - Human-in-the-loop（人机协同）

给「自动执行」链路装上安全阀门，是一层横切能力：任何节点都可在执行前/执行中挂起，交人类决策后恢复。

核心是 ApprovalStateMachine（EnumMap 转移表驱动）+ 可插拔 RiskPolicy，配套：

• InterruptManager / ResumeEngine —— 中断与精确恢复
• CheckpointManager —— 执行现场快照、可回滚可续跑
• multilevelapproval/ —— 多级会签、超时策略
• feedbackengine/ —— 人类决策沉淀为可学习数据（FewShot）
• erpdemo/ —— 「批量删除测试订单」实战场景，演示拦截不可逆操作

Day12 - Long Running Agent（长生命周期 Agent）

把「一次性 ChatBot」升级为有状态、可恢复、可调度、可观测的运行时。借鉴操作系统进程管理与工作流引擎范式：

AgentStateMachine（生命周期状态机）+ 任务队列 + 重试策略 + 事件总线 + Checkpoint 崩溃恢复 + DeadLetterQueue + 定时调度 + 指标监控。附带「GitHub Trending 每日巡检」完整示例。

Day13 - AI Office Agent（办公自动化）

把前 12 天的技术原语拼装成能产生业务价值的产品：输入一句自然语言，输出可交付的 Word / Excel / PPT / PDF / 邮件 / 会议纪要。

设计亮点是 Document IR（文档中间表示）：

• DocumentIR + sealed interface Block（Heading / Paragraph / List / Table / Chart / Image / PageBreak）—— 内容与格式彻底解耦
• 一份 IR 由 WordRenderer（POI）、ExcelRenderer（POI）、PptRenderer（XSLF）、PdfRenderer（PDFBox）分别投影
• LLM 侧用 ChatClient.entity(DocumentIR.class) 一步产出结构化文档树
• 出站端口化：ModelPort / MailSender / FileStorage / CalendarPort / TemplateEngine / TaskRepository

Day14 - Enterprise AI WeChat Agent（企业微信智能体）

给 Agent 装上「企业 IM 入口」，只用企业微信官方 API / 群机器人 Webhook，不碰个人微信 hook。规模最大的模块（90 个文件，11 个子包），工程严格度最高：

• wechatcore —— 消息领域模型、渠道端口 MessageChannel、IdempotencyStore
• wechatsession —— 会话管理 + 状态机 + 过期调度
• wechatrouter —— 责任链路由（命令 → 多模态 → Chat → Echo，按 order 排序）
• wechatcommand —— 命令系统（/help、/reset、/whoami）
• wechatnotify —— 通知中心（企微 / 邮件 / Webhook 三种出站）
• wechatworkflow —— 长流程编排，支持步骤挂起与 approve 续跑
• wechatapi —— 入站适配器，HMAC-SHA256 验签 + eventId 幂等去重
• 终极场景 MeetingSummaryOrchestrator：企微消息 → 规划 → 生成纪要 → 上传归档 → 存知识库 → 人工审批 → 发通知

已知占位：真实企微 AES 加解密回调未实现（仅通用 HMAC 验签）；ChatHandler 为 TODO，尚未接入 LLM。

Day15 - Enterprise AI Knowledge Platform（企业知识平台）

把 Day05 的「玩具 RAG」升级为多租户、可商业化 SaaS 的企业知识平台。

当前进度：第 1~14 章全部完成，13 个业务模块全部实现，并配了 11 个零依赖可运行的 Demo。
完整链路可离线跑通：上传 → 解析 → 切分 → 向量化 → 双索引入库 → 权限收敛 → 混合召回 → 精排 → 去冗余 → 结果。

第 4 章 Demo 会用 POI/PDFBox 先生成真实的 docx/xlsx/pptx/pdf 再解析回来，完整闭环；
第 13 章 Demo 会跑通「入库 → 权限隔离 → 删除同步 → 更新不同步」四个关键场景。

尚未产出：API.md / DATABASE.md / DEPLOY.md / TESTING.md / adr/ / ROADMAP.md / TODO.md。
生产化替换清单见 第 14 章第六节（10 条，优先级：租户来源 → 持久化与索引 → 真实 Embedding + minScore）。

Day16 - Enterprise Knowledge Agent V2（企业知识智能体 V2）

在 Day15 之上补齐企业 RAG 的 10 个致命短板：Knowledge Routing、Query Rewrite、Hybrid Search、Reranker、权限前置、Citation / Grounding / Verification、Knowledge Gap、版本、Evaluation、Observability。

当前进度：以独立可运行的 ChapterNNDemo 演示类为主，覆盖

• hybrid/ —— HybridRetriever 用 RRF 融合（k=60）合并多路召回
• grounding/ —— 引用抽取 + 接地判定 + 置信度（用词项重合度替代 NLI 模型）
• acl/ security/ tenant/ —— AccessPolicy、TenantGuard、PiiRedactor、PromptInjectionGuard（防注入 + PII 脱敏）
• eval/ —— Evaluator + HitRate / AnswerRelevancy 指标
• metering/ observability/ perf/ —— 配额护栏、Trace 采集、并行检索与租户隔离缓存

docs/ 是本模块最完整的部分（README / ARCHITECTURE / API / DATABASE / DEPLOY / EVALUATION / SECURITY + 20 章）。

当前实现状态说明

这一节是为了让阅读代码的人准确分辨"教程目标"与"当前代码"，避免被文档误导。

1. 共享上下文：17 个模块不是 Maven 多模块工程，而是同一工程下按包名划分，共享一份 application.yml 与 8080 端口。
2. 存储均为内存实现：向量库（InMemoryVectorStore）、会话（InMemorySessionStore）、审批仓储、知识库全部是 Map 实现，进程重启即丢失。
3. 零测试：仓库中尚无 src/test，但 pom.xml 已引入 spring-boot-starter-test。
4. 存在 Mock / 占位实现：EchoLlmClient、HashEmbeddingClient、MockLlmClient、TrendingStubClient、MockMessageChannel、InProcessTransport、HashingEmbeddingProvider，以及 Day16 用「词项重合度」替代 NLI 模型。这些是为「零依赖跑通」刻意设计的，不是生产实现。
5. 概念存在重复实现：状态机三处独立实现（Day11 ApprovalStateMachine、Day12 AgentStateMachine、Day06 / Day14 的 WorkflowState）；工作流引擎三套（Day06 / Day10 / Day14）；Embedding 三套。尚未抽取公共抽象。
6. 命名风格不统一：day3funcall（缺 0）与 day05rag、day11humanintheloop 混用。
7. 待清理项：website/ 仅为占位空目录；src/main/resources/tempfile_*.mermaid 为误提交的临时文件。

学习文档

每个模块的 docs/ 目录下包含完整学习文档：

• README.md — 完整教程（5000+ 字），可脱离聊天记录独立学习
• ARCHITECTURE.md — 系统架构图、流程图、模块说明、设计决策
• TODO.md — 必做练习 / 进阶挑战 / 企业级挑战
• chapters/ — 逐章节 Markdown 学习记录
• Day14 额外提供 API.md / DATABASE.md / DEPLOY.md / TESTING.md / ROADMAP.md / CHANGELOG.md / ADR/（架构决策记录）
• Day16 额外提供 EVALUATION.md / SECURITY.md

设计理念

• Java First — 所有核心实现均为 Java / Spring Boot，Python 仅辅助阅读
• 企业级 — 不是玩具 Demo，而是面向生产环境的工程实践
• 渐进式 — 每天一个独立模块，由浅入深，前后衔接
• 可运行 — 所有代码均可独立编译运行，即学即用
• 文档完备 — 每个模块都配自包含教程，可脱离聊天记录独立学习
• 商业化导向 — 最终目标是构建可落地的 AI Agent 平台

适合人群

• 有 Java / Spring Boot 经验，想转型 AI Agent 方向的开发者
• 想系统学习 AI Agent 工程化落地的后端工程师
• 对 AI Agent 架构设计感兴趣的技术负责人
• 希望构建自己 AI SaaS / Agent 平台的创业者

许可证

MIT License