🎬 序章
第0章 教程导读：这本书怎么读
在翻开正文之前，先看清整张地图
0.1 这本书讲的是什么
这是一本关于 deepseek-harness-java 的实战教程——一个用 Java 17 + Spring Boot 3.3 实现的、基于 DDD 六边形架构的 Agent Harness（智能体运行时基座）。
如果你用过 Claude Code、Codex CLI 或各类 AI 编程助手，你会发现它们的核心都不是"调一次大模型 API"那么简单。真正难的是模型之外的工程：会话怎么管？工具怎么调？权限怎么控？插件怎么插？出错怎么恢复？这些"大脑之外的外壳"，就是 Harness。
🧠 LLM（大脑）
负责推理与生成文本。DeepSeek / GPT / GLM 等模型本身——本教程不讲怎么训练它。
🦾 Harness（身体与神经系统）
负责把模型的"想法"变成"行动"：工具调用、会话管理、权限审批、插件扩展、事件记录——这是本书的主角。
💡 一句话记住本项目
deepseek-harness-java 把"模型调用、工具执行、会话事件、任务审批、插件生命周期、终端与工作区"组织成一个可扩展的 Agent 运行时，并自带一个打开浏览器就能用的 Web 控制台。
0.2 为什么值得读这个项目
市面上 Agent 教程大多用 Python + LangChain 演示，而本项目有三个独特价值：
| 价值点 | 具体体现 |
|---|---|
| Java 企业级视角 | Spring Boot 3.3 + MyBatis + DDD 六边形架构，是可直接对照企业工程实践的 Agent 实现 |
| 完整的治理链路 | 权限矩阵评估 → 审批决策 → 排队 → 执行，高风险工具（Shell、写文件）默认需人工审批 |
| 真实可运行 | 不是玩具 Demo：自带 Web 控制台、插件体系（Java + Node 双模式）、MCP 集成、事件溯源回放 |
0.3 全书地图：序章 + 7 篇 16 章
本书按照"先跑起来 → 俯瞰架构 → 深入机制 → 动手扩展 → 走向生产 → 工程附录"的顺序组织，每一章都建立在前一章的基础上：
| 篇 | 章节 | 你将获得 | 建议读者 |
|---|---|---|---|
| 🚀 快速上手 | 第1章 | 十分钟内在本机跑起完整系统并发出第一次对话 | 所有人（必读） |
| 🏗️ 架构设计 | 第2-3章 | 看懂 7 个 Maven 模块的依赖方向与 27 个限界上下文的划分逻辑 | 架构师 / 想读源码的人 |
| 🧠 核心机制 | 第4-7章 | 理解 ReAct 循环、事件溯源、意图识别策略树、SSE 协议的实现细节 | 想深入原理的人 |
| 🛠️ 工具与扩展 | 第8-10章 | 会写自己的工具、Java/Node 插件，会接 MCP Server | 想二次开发的人 |
| 🛡️ 治理 | 第11章 | 掌握权限矩阵、审批链路、沙箱边界的配置与扩展 | 关注安全合规的人 |
| ⚙️ 部署与生产化 | 第12-13章 | MySQL/Docker 部署、生产检查清单、已知边界与进阶方向 | 要上线的人 |
| 🧰 工程全景 | 第14-16章 | REST 契约、控制台、数据表、测试、CI、工作流、子代理、目标、计划、技能、定时与凭据治理 | 接手维护的人 |
0.4 阅读前的准备
📋 前置知识
- 必需：Java 基础语法、Maven 构建、Spring Boot 的基本使用（会起服务、会看 yml）
- 建议：了解 DDD 基本概念（聚合、限界上下文、端口-适配器）；用过任意一种 LLM API
- 不需要：不需要懂大模型原理，不需要会 Python
💻 环境要求
- JDK 17+、Maven 3.9+（必需）
- Node.js 18+（仅第9章 Node 插件部分需要）
- MySQL 5.7+（仅第12章部署部分需要；平时用 H2 零依赖）
- 一个可用的 OpenAI 兼容模型 API Key（第1章会教你怎么配）
0.5 本书的约定
| 约定 | 含义 |
|---|---|
代码格式 | 类名、方法名、配置项、文件路径都用行内代码标记，如 ReactLoopAgent、application.yml |
| 📦 源码位置 | 每章涉及的关键类都会标注 Maven 模块与包路径，方便你对照源码 |
| 💡 一句话记忆 | 每节末尾的总结卡片，是本节最值得带走的一句话 |
| ⚠️ 注意 | 已知的坑、边界或与直觉相反的设计 |
0.6 小结与下一章预告
本章要点：Harness 是 LLM 之外的工程外壳；本书按"跑起来 → 看架构 → 懂机制 → 做扩展 → 上生产"六篇递进；前置知识只需 Java + Spring Boot 基础。
下一章：我们将真正动手——克隆代码、一次构建、选择一种方式启动，然后在浏览器里和你的 Agent 说第一句话。如果一切顺利，整个过程不会超过十分钟。