qinghuan
返回三条项目主线

机制参考 · 按需阅读 / 读工具执行循环

Lynxe（原 JManus）

跟着 Java 代码读懂“想一步、做一步、再看结果”

适合补执行引擎机制：模型如何提出工具调用，工具结果如何回到下一轮，何时并行、何时等待人。建议只抽取一个小业务，不照搬全部浏览器和办公工具。

进阶核对 2026-09-29

先固定版本和学习范围

JDK 17 · Spring Boot 3.5.6 · Spring AI 1.1.2 · 手写 ReAct 执行循环

打开本轮固定源码 · 项目仓库

提交 27ead6adaf501b87333f04844f539bf278c2448a

仓库许可证标识：Apache-2.0（读取该 SHA 的 LICENSE）。本页介绍所读版本，未保证未来版本保持相同行为。

开始前要会

  • Java CompletableFuture 与并发
  • 读得懂工具调用和任务状态
环境、模型费用和额外服务
  • JDK 17+；源码构建需要 Maven。
  • 自备 DashScope 或其他兼容模型的 Key/额度，真实模型调用可能付费。
  • 默认 h2 profile 使用文件数据库；MySQL/PostgreSQL 是可选配置，不是全部必需。
  • 浏览器工具另有 Playwright 浏览器运行环境；MCP 工具取决于配置的外部服务。
  • README Docker 示例 v4.7.0 与本次源码 pom4.10.12 不同，学习时固定 commit，不混用不同版本说明。

已经在源码中读到

一次任务大致怎样走

  1. 选择模板和工具
  2. 建立计划与上下文
  3. 模型选择下一步
  4. 执行工具并收集结果
  5. 继续 / 等待人工 / 达到上限

执行循环在源码中可见

BaseAgent、ReActAgent、DynamicAgent 分别管理轮次、思考 / 动作和工具执行。普通工具可并行，人工表单等路径有串行处理。

执行记录与恢复是两件事

执行记录通过 JPA 保存，但人工执行快照仍使用内存 Map；记录能查不等于进程重启后可继续。

需要自己补齐或验证

这些能力不能直接写成“已实现”

  • 不要把 pom 中未使用的 Spring AI Alibaba 属性当实际运行依赖；这条主链是手写循环。
  • 默认跳过测试；README 的旧 Docker 标签也不等于本轮固定源码版本。
  • 人工输入等待不等于业务动作已获得持久、可追溯的批准。

建议改造 · 不是原仓库成绩

把原项目变成自己的项目

按顺序完成最小闭环，再增加难度。只把真正实现并测过的部分写进简历；如果声明支持恢复或并发，就补对应的故障实验。

01

抽取一个三工具业务

两个只读工具加一个模拟工单写入工具；明确每个工具的执行权限。

怎样验收

  • 画出完整调用链和哪些决定属于模型。
02

约束并行与重复写入

只允许独立只读工具并行；写工具用业务幂等键和批准记录。

怎样验收

  • 同一写工具重复回调不多建工单；并发与失败有确定结果。
03

比较两种执行方式

相同任务比较固定流程与自由工具循环。

怎样验收

  • 记录成功率、工具次数和成本；解释何时不需要更自由的 Agent。

按这个顺序读源码

每读一步，画一条调用关系，写下输入、状态变化和失败出口。无需先把整个仓库读完。

  1. 第 1 步 · 确定实际依赖pom.xmlpom.xml
  2. 第 2 步 · 创建 AgentDynamicToolPlanExecutor.javasrc/main/java/com/alibaba/cloud/ai/lynxe/runtime/executor/DynamicToolPlanExecutor.java
  3. 第 3 步 · 执行上限BaseAgent.javasrc/main/java/com/alibaba/cloud/ai/lynxe/agent/BaseAgent.java
  4. 第 4 步 · 工具调用DynamicAgent.javasrc/main/java/com/alibaba/cloud/ai/lynxe/agent/DynamicAgent.java
  5. 第 5 步 · 恢复状态在哪里ExecutionSnapshotService.javasrc/main/java/com/alibaba/cloud/ai/lynxe/runtime/service/ExecutionSnapshotService.java

准备好回答这些追问

先用自己的实现和实验回答，再对照源码。只背术语，很难解释异常情况。

  1. 为什么把工具放在 selectedToolKeys 中，还需要服务端授权与参数校验？
  2. maxSteps 耗尽该算成功吗？给用户的状态和内部失败原因怎样对应？
  3. CompletableFuture.allOf 或并行工具中一个失败，其他工具怎么办？
  4. 为什么执行记录落库仍不等于 exactly-once 或 crash recovery？
  5. 人工批准的对象应是自然语言计划，还是具体工具参数？批准后参数改变怎么办？
  6. 上下文压缩为什么可能丢掉工具结果？如何保留必须追溯的事实？

本轮实际验证范围

  • 已固定提交并审阅源码；未构建、运行测试、启动工具或调用模型。

源码链接是阅读证据；改造建议是待完成任务。二者都不等于完整系统运行证明。