DeepSeek Harness Java 实战笔记|导读:从工具调用到完整运行时
上一篇:无(系列导读) · 下一篇:模型、Agent 与最小循环
Java 后端的调用关系大多能提前画出来。Controller 调 Service,Service 查库或调接口,失败了进异常分支。Agent 的执行路径由模型输出决定。读到的文件不同,后续可能是搜索目录、运行测试,也可能是向用户询问缺失信息。
DeepSeek Harness Java 用 Spring Boot 实现 Agent 运行时。模型选择工具,Java 负责执行、权限检查、会话记录和页面通知。理解这套工程,需要看各个模块的职责、各自的领域设计边界,以及模型、工具和会话之间的调用关系。
最小实现只有一个循环。用户消息进来,模型提出工具请求,Java 执行后把结果送回。历史消息增多,需要管理上下文预算;工具能修改文件,需要审批和隔离;进程退出以后,还需要从存储恢复会话。插件提供额外工具,多 Agent 编排则处理任务分派和结果交接。
图中模型返回的是动作请求;文件和外部服务由工具访问。会话保存执行记录,后续请求从中取得历史,页面则接收运行时发出的通知。
目录
| 篇目 | 涉及的设计与实现 | 读完应该能解释的问题 |
|---|---|---|
| 01 · 模型、Agent 与最小循环 | 可运行的 Java 测试程序,实现模型请求和文件工具调用 | 为什么一轮任务要调两次模型,ReAct 和 Harness 分别指什么 |
| 02 · 模型协议与适配器 | 消息类型、流片段、工具 schema、渠道选择 | DeepSeek 和 OpenAI 哪些概念相通,哪些字段与接口不能照搬 |
| 03 · 会话、上下文与客户端 | 事件日志、消息投影、压缩、SSE | 为什么历史落库了模型还会忘,刷新浏览器和恢复执行差在哪 |
| 04 · 工具执行、审批与沙箱 | 并发、超时、审批、环境隔离 | 谁决定动作能不能做,超时以后能否重试,为什么要保留调用 ID |
| 05 · 插件、MCP 与 Skill | 能力发现、按需加载、资源生命周期 | 何时写 Java 插件,何时接 MCP,操作手册又该放在哪 |
| 06 · 任务与多 Agent 编排 | 任务记录、依赖、交接、取消与重试 | 多个角色怎么合作,计划何时交给模型,哪些约束仍由代码检查 |
| 07 · 验证、部署与工程复盘 | 评估用例、构建、部署、故障定位 | 怎样证明任务做对了,单实例能用以后,离多人长期使用还差什么 |
第一篇的 Java 测试程序可以直接运行,只有模型 HTTP 调用、文件工具和一份内存历史。后续的会话日志、执行器和插件,都能在这个测试程序里找到它们要替换或扩展的位置。
骨架进度
| 章节 | 这一版解决的问题 | 完整代码目录 |
|---|---|---|
| 01 | 模型请求读文件,Java 回填结果并续步 | lab/chapters/01 |
| 02 | 拆开循环、协议转换与工具,检查字段和参数分片 | lab/chapters/02 |
| 03 | 日志恢复、消息投影、成组裁剪与客户端状态 | lab/chapters/03 |
| 04 | 读写注册、审批拒绝、并发、期限与有序回填 | lab/chapters/04 |
| 05 | 插件 JAR、失败回滚、Skill 和 MCP 接入 | lab/chapters/05 |
| 06 | 两项读取、依赖交接、编号核对和报告写入 | lab/chapters/06 |
| 07 | 本地 HTTP SSE 服务、会话复用和结果验收 | lab/chapters/07 |
各阶段目录可以独立编译。正文拆项目中的关键实现,章末保留这一阶段的完整文件、运行命令和本地检查,便于对照代码中的状态变化。
Java 部分用到接口、集合、异常和少量并发。陌生术语旁有批注,关键源码附调用位置和分支说明。本地测试文件在 第 01 篇的本地测试。
常用词对照
| 词 | 在这套代码里怎么理解 |
|---|---|
| 模型 | 接收上下文,产出文字或工具请求的服务 |
| Agent | 围着一个目标反复调用模型、执行工具的程序 |
| Harness | 管理 Agent 执行过程的运行环境,包括上下文、工具、权限、状态和执行反馈 |
| Tool Calling | 模型用结构化数据提出工具请求,宿主执行后回传结果 |
| Turn | 一次用户输入驱动的整轮处理 |
| Step | Turn 内的一次模型调用及随后处理,具体划分见第 01 篇 |
| Token | 模型处理文本的计量单位,与字数、字符数没有固定一一对应关系 |
| Context | 本次推理请求中发送给模型的信息 |
| Schema | 描述参数长相的规则,例如 path 是必填字符串 |
| 事件与投影 | 记录发生过什么,从中派生当前需要的视图 |
| 幂等 | 同一项业务操作重复提交,最终效果仍能保持一致 |
| DAG | 有向无环图,用依赖关系表示哪些步骤先做、哪些可以并行 |
本机已经跑过完整项目的 Java 17 构建、H2 单实例读文件和 App 冒烟测试。原工程全量测试里三个远端 A2A 用例返回 404,记录留在第 07 篇。七份本地骨架另有固定响应检查,覆盖协议字段、日志恢复、写入拒绝、插件清理和任务失败;真实模型的规划质量、跨节点接管仍需另外验证。
上一篇:无(系列导读) · 下一篇:模型、Agent 与最小循环
更多推荐

所有评论(0)