《DeepSeek Harness Java》开篇：架构设计

作者：小傅哥
博客：https://bugstack.cn (opens new window)
视频：https://t.zsxq.com/tsEhE (opens new window)

沉淀、分享、成长，让自己和他人都能有所收获！😄

大家好，我是小傅哥。

工程实现来自于系统架构指导，系统架构来自于场景诉求。而我们（企业）的诉求，就是在各类场景（金融、信贷、交易、营销、出行、配送、履约...）增加智能体接入，但又不希望每个场景全都重复开发运行时 Agent 框架。所以 DSH Java（同类方案） 应运而生，以插件化思维，ClassLoader 热插拔加载技术，处理各类场景的智能体服务对接。

注意，Codex、Claude Code 配置 MCP、Skills 与 DSH Java Plugin 不是一类东西；插件长在进程里——与内核同 JVM，工具直接调用零序列化开销，还能注册 Hook 拦截工具调用、走事件总线与内核深度协作；MCP 连在进程外——跨语言生态广，调用走 JSON-RPC；Skills 只是喂提示词执行脚本等——约束执行体运行过程。所以插件的价值：能力不是"接进来"，而是"长进去"——性能最高、集成最深。

接下来，我们就开启 《DSH Java - DeepSeek Harness Java》 这部分项目内容的学习。在开始逐个章节的编码学习之前，我们先来整体聊一下这套工程的灵魂设计——一切能力皆工具，一切扩展皆插槽。这是贯穿全课程的一根主线，也是它和一般"把功能写死在工程里"的 AI Agent 教程最大的不同。

DSH Java 这套项目提供的配套服务，包括；web 版本、桌面版、插件开发技能「https://github.com/deepseek-harness-java (opens new window)」，以及100个实战插件开发案例。另外，配套的还有 DSH Java 官网 https://dsh-java.xiaofuge.cn/ (opens new window) —— 涵盖使用说明以及基础的配套教程，可以作为学习前的前置课程，快速上手实践，从实践中理解这是什么。

整个 DSH Java 依托于 DeepSeek Harness 马具项目，设计实现的 Java 版本。相关的 domain 领域也拆分的很细腻。这些内容，会随着后续课程的逐步讲解来介绍相关知识内容。

后续课程会先把内核立起来（骨架配置 → 契约 → LLM → ReAct 循环 → 内置工具），这个阶段工具是内核直接注册的，不绕插件；再到把插槽本身做成产品——插件加载器、生命周期、事件总线、热更新、MCP、sidecar、子代理，让外来能力走 SPI 进来；最后收官，理解了"内核长能力、扩展走插槽"，你就理解了这套工程的设计、实现和使用方式了。

学习的时候融会贯通，多一些实践。把东西玩起来，做出自己的 AI 类产品，在持续迭代这样会吸收的更好。

一、本章诉求

DSH Java 是一个以「稳定内核 + 统一插槽 + 插件化扩展」为核心的 AI Agent 运行时框架（Java 版），采用 Spring Boot DDD 多模块结构 / case / domain / infrastructure / trigger / types）。核心能力包括：ReAct 推理循环、统一工具注册（ToolRegistry，fs / shell / web / mcp / lsp / terminal 等）、Hook 拦截链、Java 插件热插拔（ClassLoader + SPI）、进程外扩展（MCP / sidecar / 子代理）等，配套 web 版本、桌面版（DSH-Java-Desktop）、插件开发技能以及插件脚手架 archetype，共 100 个实战插件开发案例。

本节要解决的诉求是：

1. 建立全局认知：理解「一切能力皆工具，一切扩展皆插槽」这条主线——内核（契约层、LLM 适配、ReAct 循环、内置工具）与插槽（ToolRegistry / Hook 链 / 端口适配）如何分工协作，以及插件 SPI 契约（AbstractHarnessPlugin / PluginContext / PluginHook）为什么是扩展的唯一入口。
2. 体验项目工程：在学习整个课程之前，最重要的是玩起来。如；启动的 Web 版本、桌面版，以及 dsh java plugin 插件能力的使用。跑通 DSH Java 初始工程（v0.1.8）的编译与启动后，初步理解 DDD 各模块的职责边界与依赖方向，为后续逐个章节学习「先把内核立起来，再把插槽做成产品」的编码实践打好地基。
3. 了解课程计划：通过 Part 00 ~ Part 12 的篇章规划（契约层 → LLM 适配 → ReAct 循环 → 工具系统 → 持久化与事件溯源 → 任务审批 → 用例编排 → 触发层与控制台 → Java 插件体系 → 进程外扩展 → 平台能力 → 收官），知道每一 Part 在整套运行时中解决什么问题、产出的组件被谁消费。
4. 搭好初始工程：整个完事后，搭建个简单的初始化工程，后续在这个工程上逐步迭代。这套东西会使用 DDD 架构设计实现，如果对 DDD 架构理解不多，可以在 https://bugstack.cn (opens new window) 编程路书里看 DDD 部分内容。

二、启动起来

• 下载工程；git clone git@gitcode.net:KnowledgePlanet/deepseek-harness-java.git - 下载后是全量代码，之后切换到 v0.1.8 分支
• 使用说明；Git 使用说明和配置 (opens new window)
• 环境信息；jdk 17、maven 3.8.x、Intellij IDEA / AI Coding
• 数据库表；deepseek-harness-java/docs/dev-ops/mysql/sql/deepseek_harness_java.sql - 测试前先导入库表，web 版本需要使用。桌面版走的是内存库（H2）

1. 体验 web

1.1 IntelliJ IDEA 启动

• 注意，本地启动 application.yml 走的是 mysql 数据库。工程里提供的 deepseek_harness_java.sql 要提前执行好，之后在 application.yml 文件中进行配置。