mirror of
https://gitee.com/dromara/liteFlow.git
synced 2026-06-10 03:07:32 +08:00
docs(agent): update react-agent guide to dual-key (conversationId + agentKey) model
Reflect the session management refactor from single sessionId to (conversationId, agentKey) dual-key: update all hook signatures to parameterless style with ctx(), add curl/wget to shell whitelist, and remove obsolete SlotAttachmentTest. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
everywhere.z
@@ -7,11 +7,11 @@
|
||||
- 引入对应模型平台模块，并完成 `liteflow.agent.*` 配置；
|
||||
- 编写一个继承 `ReActAgentComponent` 的 Agent 组件；
|
||||
- 在 EL 中组合 Agent、普通节点、条件路由和并行节点；
|
||||
- 正确理解 Session、memory、workspace、内置文件工具和 Shell 工具的边界。
|
||||
- 正确理解 conversation、agentKey、memory、workspace、内置文件工具和 Shell 工具的边界。
|
||||
|
||||
> 当前仓库根版本：`2.15.3.2`。
|
||||
> 当前仓库根版本：`2.16.0`。
|
||||
>
|
||||
> 当前源码中 `liteflow-react-agent` 子模块的 `maven.compiler.source` / `target` 为 `17`，根 `compile-17+` profile 会在 JDK 17 及以上激活该模块。实际运行时还需要满足 agentscope-java 及具体模型 SDK 的运行要求。
|
||||
> 当前源码中 `liteflow-react-agent` 聚合模块的 `maven.compiler.source` / `target` 为 `17`，根 `compile-17+` profile 会在 JDK 17 及以上激活该模块。实际运行时还需要满足 agentscope-java 及具体模型 SDK 的运行要求。
|
||||
|
||||
---
|
||||
|
||||
@@ -21,8 +21,8 @@
|
||||
|
||||
| 模块 | 作用 |
|
||||
| --- | --- |
|
||||
| `liteflow-react-agent-core` | `ReActAgentComponent`、`ModelSpec` 基础设施、Session 管理、memory 持久化、workspace 文件工具、受管 Shell 工具 |
|
||||
| `liteflow-react-agent-openai` | OpenAI 官方 API + OpenAI 兼容协议，内置 DeepSeek、Kimi、GLM、MiniMax 便捷入口 |
|
||||
| `liteflow-react-agent-core` | `ReActAgentComponent`、`ModelSpec` 基础设施、conversation / agentKey 会话管理、memory 持久化、workspace 文件工具、受管 Shell 工具 |
|
||||
| `liteflow-react-agent-openai` | OpenAI 官方 API + OpenAI 兼容协议，内置 DeepSeek、Kimi、GLM、Minimax 便捷入口 |
|
||||
| `liteflow-react-agent-anthropic` | Anthropic Claude 模型入口 |
|
||||
| `liteflow-react-agent-gemini` | Google Gemini 模型入口 |
|
||||
| `liteflow-react-agent-dashscope` | 阿里云 DashScope / Qwen 模型入口 |
|
||||
@@ -45,7 +45,7 @@
|
||||
</dependency>
|
||||
```
|
||||
|
||||
如果一条应用里要同时使用多个模型平台，可以同时引入多个平台模块。
|
||||
如果一个应用里要同时使用多个模型平台，可以同时引入多个平台模块。
|
||||
|
||||
### 2.2 配置 LiteFlow 与 Agent
|
||||
|
||||
@@ -58,6 +58,7 @@ liteflow.agent.workspace.root=/var/lib/liteflow/agent-workspaces
|
||||
liteflow.agent.shell.mode=disabled
|
||||
|
||||
liteflow.agent.openai-compatible.deepseek.api-key=${DEEPSEEK_API_KEY}
|
||||
# DeepSeek.of(...) 已内置默认 baseUrl；如需覆盖再配置下一行。
|
||||
liteflow.agent.openai-compatible.deepseek.base-url=https://api.deepseek.com/v1
|
||||
```
|
||||
|
||||
@@ -69,17 +70,18 @@ AgentConfigException: liteflow.agent.workspace.root is required
|
||||
|
||||
### 2.3 编写 Agent 组件
|
||||
|
||||
Agent 组件继承 `ReActAgentComponent`，至少实现三个方法：
|
||||
Agent 组件继承 `ReActAgentComponent`，至少实现三个无参方法：
|
||||
|
||||
- `model(ctx)`：返回一个 `ModelSpec<?>`，声明使用哪个平台、哪个模型及可选高级参数；
|
||||
- `systemPrompt(ctx)`：创建 Agent 时使用的系统提示词；
|
||||
- `userPrompt(ctx)`：每次调用时发送给 Agent 的用户消息。
|
||||
- `model()`：返回一个 `ModelSpec<?>`，声明使用哪个平台、哪个模型及可选高级参数；
|
||||
- `systemPrompt()`：创建 Agent 时使用的系统提示词；
|
||||
- `userPrompt()`：每次调用时发送给 Agent 的用户消息。
|
||||
|
||||
当前源码已把执行上下文改为通过 `ctx()` 动态获取，而不是把 `ReActAgentContext` 作为参数传入各个 hook。`ctx()` 只能在 `process()` 生命周期内调用，包括 `systemPrompt()`、`userPrompt()`、自定义工具回调、Hook 回调和 `handleReply()`。
|
||||
|
||||
```java
|
||||
package demo.agent;
|
||||
|
||||
import com.yomahub.liteflow.agent.component.ReActAgentComponent;
|
||||
import com.yomahub.liteflow.agent.component.ReActAgentContext;
|
||||
import com.yomahub.liteflow.agent.model.ModelSpec;
|
||||
import com.yomahub.liteflow.agent.openai.DeepSeek;
|
||||
import org.springframework.stereotype.Component;
|
||||
@@ -88,18 +90,19 @@ import org.springframework.stereotype.Component;
|
||||
public class DeepSeekAgentCmp extends ReActAgentComponent {
|
||||
|
||||
@Override
|
||||
protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
protected ModelSpec<?> model() {
|
||||
return DeepSeek.of("deepseek-chat");
|
||||
}
|
||||
|
||||
@Override
|
||||
protected String systemPrompt(ReActAgentContext ctx) {
|
||||
protected String systemPrompt() {
|
||||
return "你是一名简洁的中文助理，回答严格控制在两句话以内。";
|
||||
}
|
||||
|
||||
@Override
|
||||
protected String userPrompt(ReActAgentContext ctx) {
|
||||
return String.valueOf(ctx.getSlot().getChainReqData(ctx.getSlot().getChainId()));
|
||||
protected String userPrompt() {
|
||||
Object req = getSlot().getChainReqData(getSlot().getChainId());
|
||||
return req == null ? "" : req.toString();
|
||||
}
|
||||
|
||||
@Override
|
||||
@@ -110,6 +113,8 @@ public class DeepSeekAgentCmp extends ReActAgentComponent {
|
||||
}
|
||||
```
|
||||
|
||||
如果自定义工具、Hook 或 Model 会被缓存并跨多次 invocation 复用，不要在这些对象中保存某次调用的 `ReActAgentContext` 引用；应保存组件实例，并在运行时通过组件内部类或组件暴露的公开方法间接调用受保护的 `ctx()`，获取当次上下文。
|
||||
|
||||
### 2.4 在 EL 中编排
|
||||
|
||||
Agent 节点和普通 `NodeComponent` 一样使用：
|
||||
@@ -133,19 +138,19 @@ if (response.isSuccess()) {
|
||||
}
|
||||
```
|
||||
|
||||
默认情况下，Agent 回复会通过 `reply.getTextContent()` 写入 `slot.responseData`。如果后续节点希望从指定位置读取回复，可以覆写 `handleReply(reply, ctx)`，或者像测试用例中的 `RecordReplyCmp` 一样把 `responseData` 转存到节点输出。
|
||||
默认情况下，Agent 回复会通过 `reply.getTextContent()` 写入 `slot.responseData`。如果后续节点希望从指定位置读取回复，可以覆写 `handleReply(reply)`，或者像测试用例中的 `RecordReplyCmp` 一样把 `responseData` 转存到节点输出。
|
||||
|
||||
### 2.3 下游节点如何拿到 Agent 的执行结果
|
||||
### 2.5 下游节点如何拿到 Agent 的执行结果
|
||||
|
||||
ReAct Agent 节点执行完后，结果传递给下一个节点有两种方式：
|
||||
ReAct Agent 节点执行完后，结果传递给下一个节点有两种方式。
|
||||
|
||||
**方式 1：默认走 `slot.responseData`（最简单）**
|
||||
|
||||
`ReActAgentComponent#handleReply()` 默认实现：
|
||||
|
||||
```java
|
||||
protected void handleReply(Msg reply, ReActAgentContext ctx) {
|
||||
ctx.getSlot().setResponseData(reply == null ? null : reply.getTextContent());
|
||||
protected void handleReply(Msg reply) {
|
||||
ctx().getSlot().setResponseData(reply == null ? null : reply.getTextContent());
|
||||
}
|
||||
```
|
||||
|
||||
@@ -166,53 +171,55 @@ public class RecordReplyCmp extends NodeComponent {
|
||||
|
||||
**方式 2：覆写 `handleReply` 写入自定义位置**
|
||||
|
||||
需要做结构化处理、写到 ContextBean、或者一个链路里有**多个 Agent 节点**时，必须覆写 `handleReply`，否则后一个 Agent 的 `responseData` 会覆盖前一个：
|
||||
需要做结构化处理、写到 ContextBean，或者一条链路里有多个 Agent 节点时，建议覆写 `handleReply`，否则后一个 Agent 的 `responseData` 会覆盖前一个：
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected void handleReply(Msg reply, ReActAgentContext ctx) {
|
||||
protected void handleReply(Msg reply) {
|
||||
String text = reply == null ? null : reply.getTextContent();
|
||||
// 选择 1：写入自定义 ContextBean
|
||||
ctx.getSlot().getContextBean(MyAgentCtx.class).setReply(getNodeId(), text);
|
||||
ctx().getSlot().getContextBean(MyAgentCtx.class).setReply(getNodeId(), text);
|
||||
// 选择 2：以 nodeId 为 key 存到 slot 输出，避免相互覆盖
|
||||
ctx.getSlot().setOutput(getNodeId(), text);
|
||||
ctx().getSlot().setOutput(getNodeId(), text);
|
||||
}
|
||||
```
|
||||
|
||||
下游节点对应使用 `slot.getContextBean(MyAgentCtx.class)` 或 `slot.getOutput(nodeId)` 读取。
|
||||
|
||||
> **多 Agent 节点共存的注意事项**：默认 `responseData` 是 slot 级别的单一字段，后写覆盖先写。链路中存在多个 ReAct Agent 时，请务必覆写 `handleReply` 用 `setOutput(nodeId, ...)` 或自定义 ContextBean 区分各 Agent 的输出。
|
||||
> **多 Agent 节点共存的注意事项**：默认 `responseData` 是 slot 级别的单一字段，后写覆盖先写。链路中存在多个 ReAct Agent 时，请覆写 `handleReply` 用 `setOutput(nodeId, ...)` 或自定义 ContextBean 区分各 Agent 的输出。
|
||||
|
||||
---
|
||||
|
||||
## 3. ReActAgentComponent 扩展点
|
||||
|
||||
`ReActAgentComponent#process()` 是 `final`。框架在其中统一完成配置读取、Session 获取、加锁、Agent 懒构建、调用、回复处理和 memory 保存。业务侧通过覆写受保护方法定制行为。
|
||||
`ReActAgentComponent#process()` 是 `final`。框架在其中统一完成配置读取、conversation 解析、`agentKey` 解析、Session 获取、加锁、Agent 懒构建、调用、回复处理和 memory 保存。业务侧通过覆写受保护方法定制行为。
|
||||
|
||||
| 方法 | 是否必须 | 默认行为 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `model(ctx)` | 是 | 无 | 返回 `ModelSpec<?>`，由框架从 `AgentConfig` 解析凭据并构造 agentscope `Model` |
|
||||
| `systemPrompt(ctx)` | 是 | 无 | 返回系统提示词，同一 Session 首次构建 Agent 时调用 |
|
||||
| `userPrompt(ctx)` | 是 | 无 | 返回本轮用户消息，每次 `process()` 都调用 |
|
||||
| `tools(ctx)` | 否 | 空列表 | 注册自定义 `@Tool` 对象 |
|
||||
| `resolveSessionId(slot)` | 否 | `NanoIdSessionIdGenerator.generate()`，格式 `YYYYMMDD_NanoId(12)` | 决定本次调用使用哪个 Session；默认每次调用生成新 ID（单轮无状态） |
|
||||
| `model()` | 是 | 无 | 返回 `ModelSpec<?>`，由框架从 `AgentConfig` 解析凭据并构造 agentscope `Model` |
|
||||
| `systemPrompt()` | 是 | 无 | 返回系统提示词，同一 `(conversationId, agentKey)` 首次构建 Agent 时调用 |
|
||||
| `userPrompt()` | 是 | 无 | 返回本轮用户消息，每次 `process()` 都调用 |
|
||||
| `tools()` | 否 | 空列表 | 注册自定义 `@Tool` 对象 |
|
||||
| `resolveConversationId()` | 否 | 先复用 `slot.conversationId`，再读 `chainReqData` Map 中的 `conversationId`，最后调用 `ConversationIdGenerator.generate()` | 决定本次调用所属业务会话；同一条 chain 内首个 Agent 写回 slot 后，后续 Agent 默认复用 |
|
||||
| `agentKey()` | 否 | 当前 `nodeId`，为空时为 `default` | 在同一 conversation 中区分不同 Agent 实例和记忆；默认不同节点互相隔离 |
|
||||
| `maxIterations()` | 否 | `-1` | 返回正数时覆盖全局 `defaults.max-iterations` |
|
||||
| `enableShellTool()` | 否 | `true` | 是否注册内置受管 Shell 工具 |
|
||||
| `enableShellTool()` | 否 | `true` | 是否注册内置受管 Shell 工具；配置为 `DISABLED` 时即使返回 `true` 也不会注册 |
|
||||
| `enableWorkspaceFileTools()` | 否 | `true` | 是否注册内置 workspace 文件工具 |
|
||||
| `hooks(ctx)` | 否 | 空列表 | 注册 agentscope `Hook` |
|
||||
| `hooks()` | 否 | 空列表 | 注册 agentscope `Hook` |
|
||||
| `enableReActLogging()` | 否 | 读 `liteflow.agent.logging.react-enabled`（默认 `true`） | 是否注册内置 `ReActLoggingHook`，将 reason / act / error 事件写到日志 |
|
||||
| `handleReply(reply, ctx)` | 否 | 写入 `slot.responseData` | 自定义回复处理逻辑 |
|
||||
| `buildModel(ctx)` | 否 | 委派 `model(ctx).resolve(agentConfig())` | 逃生舱：完全自行构造 agentscope `Model` |
|
||||
| `handleReply(reply)` | 否 | 写入 `slot.responseData` | 自定义回复处理逻辑 |
|
||||
| `buildModel()` | 否 | 委派 `model().resolve(agentConfig())` | 逃生舱：完全自行构造 agentscope `Model` |
|
||||
|
||||
`ReActAgentContext` 提供三项执行上下文：
|
||||
`ReActAgentContext` 可通过组件的 `ctx()` 方法取得，提供四项执行上下文：
|
||||
|
||||
| 方法 | 说明 |
|
||||
| --- | --- |
|
||||
| `getSlot()` | 当前 LiteFlow `Slot` |
|
||||
| `getSessionId()` | 安全化后的 Session ID |
|
||||
| `getWorkspaceDir()` | 当前 Session 对应的 workspace 目录 |
|
||||
| `getConversationId()` | 安全化后的 conversation ID，决定 workspace 子目录 |
|
||||
| `getAgentKey()` | 安全化后的 Agent key，默认来自 `nodeId` |
|
||||
| `getWorkspaceDir()` | 当前 conversation 对应的 workspace 目录 |
|
||||
|
||||
注意：`systemPrompt(ctx)` 只在同一 `sessionId` 下首次构建 Agent 时调用；后续调用会复用同一个 Agent 实例和 memory。动态输入应放在 `userPrompt(ctx)` 中。
|
||||
注意：`systemPrompt()` 只在同一 `(conversationId, agentKey)` 下首次构建 Agent 时调用；后续调用会复用同一个 Agent 实例和 memory。动态输入应放在 `userPrompt()` 中，并通过 `ctx()` 或 `getSlot()` 读取当次 invocation 的数据。
|
||||
|
||||
---
|
||||
|
||||
@@ -220,7 +227,7 @@ protected void handleReply(Msg reply, ReActAgentContext ctx) {
|
||||
|
||||
### 4.1 核心设计
|
||||
|
||||
`ModelSpec<SELF>` 是所有平台模型描述符的基类。子类按"哪个平台 + 哪个模型 + 可选高级参数"三段式给出，框架负责从 `AgentConfig` 解析凭据并构造 agentscope `Model`。
|
||||
`ModelSpec<SELF>` 是所有平台模型描述符的基类。子类按“哪个平台 + 哪个模型 + 可选高级参数”三段式给出，框架负责从 `AgentConfig` 解析凭据并构造 agentscope `Model`。
|
||||
|
||||
基类提供的共性参数（所有平台共享）：
|
||||
|
||||
@@ -232,26 +239,26 @@ protected void handleReply(Msg reply, ReActAgentContext ctx) {
|
||||
| `maxTokens(int)` | `Integer` | 最大输出 token |
|
||||
| `seed(long)` | `Long` | 随机种子 |
|
||||
| `stream(boolean)` | `Boolean` | 是否流式 |
|
||||
| `cacheControl(boolean)` | `Boolean` | 缓存控制 |
|
||||
| `cacheControl(boolean)` | `Boolean` | 缓存控制；当前 OpenAI 与 DashScope 内置解析会下发该参数 |
|
||||
|
||||
所有参数均为可选，未设置时传 `null`，agentscope 使用服务端默认值。
|
||||
所有参数均为可选，未设置时不写入 `GenerateOptions` 或模型 Builder，agentscope 使用服务端或 SDK 默认值。
|
||||
|
||||
### 4.2 平台入口一览
|
||||
|
||||
每个平台模块提供一个不可变入口类，通过静态 `of(modelName)` 方法返回平台对应的 `Spec` 子类。Spec 子类在基类共性参数之上暴露平台个性参数。
|
||||
每个平台模块提供一个不可变入口类，通过静态 `of(modelName)` 或 `custom(configKey, modelName)` 方法返回平台对应的 `Spec` 子类。Spec 子类在基类共性参数之上暴露平台个性参数。
|
||||
|
||||
| 模块 | 入口类 | Spec 子类 | 个性参数 |
|
||||
| --- | --- | --- | --- |
|
||||
| `liteflow-react-agent-openai` | `OpenAI` | `OpenAISpec` | `reasoningEffort`, `frequencyPenalty`, `presencePenalty` |
|
||||
| `liteflow-react-agent-openai` | `DeepSeek` | `OpenAICompatibleSpec` | 继承 `OpenAISpec` 全部参数 |
|
||||
| `liteflow-react-agent-openai` | `DeepSeek` | `OpenAICompatibleSpec` | 继承 `OpenAISpec` 全部参数，内置默认 `baseUrl` |
|
||||
| `liteflow-react-agent-openai` | `Kimi` | `OpenAICompatibleSpec` | 同上 |
|
||||
| `liteflow-react-agent-openai` | `GLM` | `OpenAICompatibleSpec` | 同上 |
|
||||
| `liteflow-react-agent-openai` | `Minimax` | `OpenAICompatibleSpec` | 同上 |
|
||||
| `liteflow-react-agent-openai` | `OpenAICompatible` | `OpenAICompatibleSpec` | 自定义 `configKey`，用于任意 OpenAI 兼容厂商 |
|
||||
| `liteflow-react-agent-anthropic` | `Anthropic` | `AnthropicSpec` | `thinking(budget, enabled)` |
|
||||
| `liteflow-react-agent-openai` | `OpenAICompatible` | `OpenAICompatibleSpec` | 自定义 `configKey`，用于任意 OpenAI 兼容厂商；无默认 `baseUrl` |
|
||||
| `liteflow-react-agent-anthropic` | `Anthropic` | `AnthropicSpec` | `thinking(t -> t.budget(...).enabled(...))`；当前内置解析下发 `budget` |
|
||||
| `liteflow-react-agent-anthropic` | `AnthropicCompatible` | `AnthropicSpec` | 自定义 `configKey`，用于 Anthropic 兼容网关 |
|
||||
| `liteflow-react-agent-gemini` | `Gemini` | `GeminiSpec` | `thinking(level, budget)` |
|
||||
| `liteflow-react-agent-dashscope` | `DashScope` | `DashScopeSpec` | `thinking(budget)` |
|
||||
| `liteflow-react-agent-gemini` | `Gemini` | `GeminiSpec` | `thinking(t -> t.level(...).budget(...))` |
|
||||
| `liteflow-react-agent-dashscope` | `DashScope` | `DashScopeSpec` | `thinking(t -> t.budget(...))`，设置 budget 时会启用 thinking |
|
||||
|
||||
### 4.3 使用示例
|
||||
|
||||
@@ -259,7 +266,7 @@ protected void handleReply(Msg reply, ReActAgentContext ctx) {
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
protected ModelSpec<?> model() {
|
||||
return OpenAI.of("gpt-4o")
|
||||
.temperature(0.7)
|
||||
.maxTokens(1000)
|
||||
@@ -273,31 +280,31 @@ protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
protected ModelSpec<?> model() {
|
||||
return DeepSeek.of("deepseek-chat")
|
||||
.temperature(0.5);
|
||||
}
|
||||
```
|
||||
|
||||
凭据来源：`liteflow.agent.openai-compatible.deepseek.api-key` / `base-url`。
|
||||
凭据来源：`liteflow.agent.openai-compatible.deepseek.api-key`，`base-url` 可选；未配置时使用 `DeepSeek` 入口内置的默认地址。
|
||||
|
||||
**自定义 OpenAI 兼容厂商：**
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
protected ModelSpec<?> model() {
|
||||
return OpenAICompatible.custom("myvendor", "my-model")
|
||||
.temperature(0.7);
|
||||
}
|
||||
```
|
||||
|
||||
凭据来源：`liteflow.agent.openai-compatible.myvendor.api-key` / `base-url`。
|
||||
凭据来源：`liteflow.agent.openai-compatible.myvendor.api-key` / `base-url`。自定义厂商没有内置默认地址，通常需要配置 `base-url`。
|
||||
|
||||
**Anthropic Claude：**
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
protected ModelSpec<?> model() {
|
||||
return Anthropic.of("claude-sonnet-4-5")
|
||||
.temperature(0.5)
|
||||
.thinking(t -> t.budget(2000).enabled(true));
|
||||
@@ -310,7 +317,7 @@ protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
protected ModelSpec<?> model() {
|
||||
return AnthropicCompatible.custom("gateway", "claude-haiku");
|
||||
}
|
||||
```
|
||||
@@ -321,7 +328,7 @@ protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
protected ModelSpec<?> model() {
|
||||
return Gemini.of("gemini-2.5-flash")
|
||||
.thinking(t -> t.level("high").budget(1024));
|
||||
}
|
||||
@@ -333,7 +340,7 @@ protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
protected ModelSpec<?> model() {
|
||||
return DashScope.of("qwen-plus")
|
||||
.thinking(t -> t.budget(2048));
|
||||
}
|
||||
@@ -349,7 +356,7 @@ protected ModelSpec<?> model(ReActAgentContext ctx) {
|
||||
| --- | --- |
|
||||
| `apiKey` | API Key |
|
||||
| `baseUrl` | 可选，自定义网关或兼容端点 |
|
||||
| `extra` | 可选，业务自定义键值 |
|
||||
| `extra` | 可选，业务自定义键值；当前内置 ProviderSpec 尚未读取 |
|
||||
|
||||
YAML 示例：
|
||||
|
||||
@@ -386,15 +393,15 @@ liteflow:
|
||||
框架内建两种凭据解析策略，通过 `CredentialResolver` 实现：
|
||||
|
||||
- **头等平台**（`OpenAI` / `Anthropic` / `Gemini` / `DashScope`）：从 `AgentConfig` 的单一 `PlatformCredential` 字段读取（如 `cfg.getOpenai()`）。缺失时抛出 `AgentConfigException`，提示 `liteflow.agent.<platform>.api-key`。
|
||||
- **兼容平台**（`DeepSeek` / `Kimi` / `GLM` / `Minimax` / `OpenAICompatible.custom`）：从 `AgentConfig` 的 `Map<String, PlatformCredential>` 中按 `configKey` 读取。缺失时抛出提示 `liteflow.agent.<type>.<configKey>.api-key`。
|
||||
- **兼容平台**（`DeepSeek` / `Kimi` / `GLM` / `Minimax` / `OpenAICompatible.custom` / `AnthropicCompatible.custom`）：从 `AgentConfig` 的 `Map<String, PlatformCredential>` 中按 `configKey` 读取。缺失时抛出提示 `liteflow.agent.<type>.<configKey>.api-key`。
|
||||
|
||||
### 4.6 逃生舱：buildModel(ctx)
|
||||
### 4.6 逃生舱：buildModel()
|
||||
|
||||
如果 `ModelSpec` 无法满足需求（例如需要传入 agentscope 原生的高级参数），可以直接覆写 `buildModel(ctx)`，完全自行构造 agentscope `Model`：
|
||||
如果 `ModelSpec` 无法满足需求（例如需要传入 agentscope 原生的高级参数），可以直接覆写 `buildModel()`，完全自行构造 agentscope `Model`：
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected Model buildModel(ReActAgentContext ctx) {
|
||||
protected Model buildModel() {
|
||||
return OpenAIChatModel.builder()
|
||||
.apiKey(agentConfig().getOpenai().getApiKey())
|
||||
.modelName("gpt-4o")
|
||||
@@ -406,46 +413,104 @@ protected Model buildModel(ReActAgentContext ctx) {
|
||||
}
|
||||
```
|
||||
|
||||
覆写 `buildModel(ctx)` 后，`model(ctx)` 不再被 `process()` 调用，但仍建议实现以保持 API 一致性。
|
||||
覆写 `buildModel()` 后，默认实现中的 `model().resolve(agentConfig())` 不会被调用；但因为 `model()` 仍是抽象方法，子类仍需实现它。
|
||||
|
||||
---
|
||||
|
||||
## 5. Session 与 memory
|
||||
## 5. Conversation、agentKey 与 memory
|
||||
|
||||
### 5.1 Session 负责什么
|
||||
### 5.1 两层标识分别负责什么
|
||||
|
||||
每次执行 Agent 组件时，框架会通过 `AgentSessionManager.acquire(sessionId)` 获取一个 `AgentSession`。同一个 Session 会复用：
|
||||
当前源码不是单一 `sessionId` 模型，而是把会话拆成两层：
|
||||
|
||||
- `conversationId`：业务 / 对话维度，整条 chain 内一致，决定 workspace 子目录；
|
||||
- `agentKey`：组件维度，默认是 `nodeId`，用于在同一段 conversation 中区分不同 Agent 的 `ReActAgent` 实例和记忆。
|
||||
|
||||
每次执行 Agent 组件时，框架会通过 `AgentSessionManager.acquire(conversationId, agentKey)` 获取一个 `AgentSession`。同一个 `(conversationId, agentKey)` 会复用：
|
||||
|
||||
- 同一个 `ReActAgent` 实例；
|
||||
- 同一个 Agent memory；
|
||||
- 同一个 workspace 子目录；
|
||||
- 同一把 `ReentrantLock`。
|
||||
- 同一把 `ReentrantLock`；
|
||||
- 同一个持久化 key，格式为安全化后的 `conversationId + "__" + agentKey`。
|
||||
|
||||
因此，同一个 `sessionId` 下的调用会串行执行，避免多线程同时修改同一份 memory。不同 `sessionId` 可以并行执行。
|
||||
同一个 `conversationId` 下的不同 `agentKey` 默认拥有独立 Agent 和独立 memory，但共享同一个 workspace 子目录，便于多个 Agent 通过文件协作。
|
||||
|
||||
### 5.2 Session ID 从哪里来
|
||||
因此，同一个 `(conversationId, agentKey)` 下的调用会串行执行，避免多线程同时修改同一份 memory。不同 `agentKey` 可以并行执行，但如果共享 workspace，需要由业务自行避免写同名文件造成冲突。
|
||||
|
||||
### 5.2 conversationId 从哪里来
|
||||
|
||||
默认实现是：
|
||||
|
||||
```java
|
||||
protected String resolveSessionId(Slot slot) {
|
||||
return NanoIdSessionIdGenerator.generate();
|
||||
protected String resolveConversationId() {
|
||||
Slot slot = getSlot();
|
||||
String existing = slot.getConversationId();
|
||||
if (existing != null && !existing.isEmpty()) {
|
||||
return existing;
|
||||
}
|
||||
Object req = slot.getChainReqData(slot.getChainId());
|
||||
if (req instanceof Map<?, ?> map) {
|
||||
Object v = map.get(CONVERSATION_ID_REQUEST_KEY);
|
||||
if (v != null) {
|
||||
String s = v.toString();
|
||||
if (!s.isEmpty()) {
|
||||
return s;
|
||||
}
|
||||
}
|
||||
}
|
||||
return ConversationIdGenerator.generate();
|
||||
}
|
||||
```
|
||||
|
||||
`NanoIdSessionIdGenerator.generate()` 返回 `YYYYMMDD_<12 位 NanoId>` 形式的字符串（例如 `20260430_3F7K9PQRSTUV`），每次调用都会生成一个全新的 ID。这意味着默认情况下"一次调用一个会话"，会话之间互不共享 memory 与 workspace。如果要实现多轮对话，必须覆写为业务会话 ID：
|
||||
`ConversationIdGenerator.generate()` 返回 `YYYYMMDD_<12 位 NanoId>` 形式的字符串（例如 `20260430_3F7K9PQRSTUV`）。首个 Agent 解析出 conversationId 后会写回 `slot.setConversationId(cid)`，同一条 chain 中后续 Agent 会默认复用它。
|
||||
|
||||
也可以在调用链路时显式传入 conversationId：
|
||||
|
||||
```java
|
||||
LiteflowResponse response = flowExecutor.execute2Resp(
|
||||
"deepseekChain",
|
||||
request,
|
||||
ExecuteOption.of().conversationId("chat-user-1-conv-1"));
|
||||
```
|
||||
|
||||
或者让框架先生成一个 conversationId，再从响应中取回供下一轮复用：
|
||||
|
||||
```java
|
||||
LiteflowResponse first = flowExecutor.execute2Resp(
|
||||
"deepseekChain",
|
||||
request,
|
||||
ExecuteOption.of().autoConversationId());
|
||||
String cid = first.getConversationId();
|
||||
```
|
||||
|
||||
如果要按业务请求对象实现多轮对话，也可以覆写：
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected String resolveSessionId(Slot slot) {
|
||||
ChatRequest req = slot.getChainReqData(slot.getChainId());
|
||||
protected String resolveConversationId() {
|
||||
ChatRequest req = getSlot().getChainReqData(getSlot().getChainId());
|
||||
return "chat-" + req.getUserId() + "-" + req.getConversationId();
|
||||
}
|
||||
```
|
||||
|
||||
Session ID 只允许直接使用 `[a-zA-Z0-9_-]+`。其他字符会被 URL 编码，并把 `%` 替换为 `_`，从而安全地用作目录名。空值会变成 `_`。
|
||||
`conversationId` 与 `agentKey` 只允许直接使用 `[a-zA-Z0-9_-]+`。其他字符会被 URL 编码，并把 `%` 替换为 `_`，从而安全地用作目录名或缓存 key。空值会变成 `_`。
|
||||
|
||||
### 5.3 JVM 热 Session 配置
|
||||
### 5.3 agentKey 从哪里来
|
||||
|
||||
默认实现是当前节点的 `nodeId`：
|
||||
|
||||
```java
|
||||
protected String agentKey() {
|
||||
String nodeId = getNodeId();
|
||||
return (nodeId == null || nodeId.isEmpty()) ? "default" : nodeId;
|
||||
}
|
||||
```
|
||||
|
||||
这意味着同一段 conversation 中，`mathAgent` 和 `summaryAgent` 默认有各自独立的 Agent 记忆；但它们共享 `workspace.root/<conversationId>/` 目录。
|
||||
|
||||
如果确实希望多个节点共享同一个 Agent 记忆，可以让它们返回同一个 `agentKey()`；如果希望同一个节点的不同执行完全隔离，可以把 `requestId` 或业务标识拼入 `agentKey()`。
|
||||
|
||||
### 5.4 JVM 热 Session 配置
|
||||
|
||||
`liteflow.agent.session.*` 控制当前 JVM 中热 Session 的缓存时间和数量：
|
||||
|
||||
@@ -453,21 +518,21 @@ Session ID 只允许直接使用 `[a-zA-Z0-9_-]+`。其他字符会被 URL 编
|
||||
| --- | --- | --- |
|
||||
| `idle-timeout` | `30m` | Session 空闲多久后可被清理 |
|
||||
| `cleanup-interval` | `1m` | 后台清理线程检查间隔，最低 20ms |
|
||||
| `max-sessions` | `10000` | 当前 JVM 中最多保留多少个热 Session |
|
||||
| `max-sessions` | `10000` | 当前 JVM 中最多保留多少个热 Session，按 `(conversationId, agentKey)` 计数 |
|
||||
|
||||
清理线程名为 `liteflow-agent-session-cleaner`。它只会清理已经超过 `idle-timeout` 且当前没有被加锁的 Session。
|
||||
|
||||
当 Session 数量超过 `max-sessions` 时，会按 `lastActive` 淘汰最旧的 JVM 内缓存。这个淘汰只移除热 Agent 实例，不删除 workspace，也不删除 Redis、MySQL 或文件中的持久化记忆。
|
||||
|
||||
### 5.4 memory 持久化模式
|
||||
### 5.5 memory 持久化模式
|
||||
|
||||
`liteflow.agent.session.memory.*` 控制 Agent memory 保存在哪里。它和热 Session 缓存是两件事：热缓存决定当前 JVM 里保留多久，memory 持久化决定重启或重新加载后能否恢复对话历史。
|
||||
|
||||
| 模式 | 含义 | 适用场景 |
|
||||
| --- | --- | --- |
|
||||
| `JVM` | 默认值，使用 AgentScope 的 JVM 内 Session | 单进程内多轮对话，进程退出后可丢失 |
|
||||
| `NONE` | 不加载也不保存持久化 Session | 不需要持久化；如需严格无状态，配合唯一 `sessionId` 使用 |
|
||||
| `LOCAL_FILE` | 保存到 `workspace.root/.agent-session/<sessionId>/` | 本地文件持久化、开发测试、小规模部署 |
|
||||
| `JVM` | 默认值，使用 AgentScope 的 JVM 内 Session；进程退出后丢失 | 单进程内多轮对话 |
|
||||
| `NONE` | 不加载也不保存持久化 Session；热缓存中的同一 `(conversationId, agentKey)` 仍会复用到过期或淘汰 | 不需要持久化；如需严格无状态，配合每次唯一的 conversationId 或 agentKey 使用 |
|
||||
| `LOCAL_FILE` | 保存到 `workspace.root/.agent-session/` 下，由 AgentScope 文件 Session 管理 | 本地文件持久化、开发测试、小规模部署 |
|
||||
| `REDIS` | 使用用户提供的 Redis 客户端 Bean | 多实例共享短期会话 |
|
||||
| `MYSQL` | 使用用户提供的 `DataSource` Bean | 需要数据库持久化和运维治理 |
|
||||
|
||||
@@ -517,7 +582,7 @@ LiteFlow 不创建 JDBC 连接池，`DataSource` 也需要由业务应用提供
|
||||
|
||||
### 6.1 Workspace 目录结构
|
||||
|
||||
每个 Session 都会在 `liteflow.agent.workspace.root` 下获得一个独立子目录：
|
||||
每个 conversation 都会在 `liteflow.agent.workspace.root` 下获得一个独立子目录：
|
||||
|
||||
```text
|
||||
/var/lib/liteflow/agent-workspaces/
|
||||
@@ -526,7 +591,7 @@ LiteFlow 不创建 JDBC 连接池，`DataSource` 也需要由业务应用提供
|
||||
└── .agent-session/
|
||||
```
|
||||
|
||||
`<sessionId>/` 是 Agent 工具读写文件的目录；`.agent-session/` 只在 `session.memory.mode=LOCAL_FILE` 时创建，用于保存 AgentScope 的记忆文件。
|
||||
`<conversationId>/` 是同一段 conversation 中多个 Agent 共享的工具读写目录；`.agent-session/` 只在 `session.memory.mode=LOCAL_FILE` 时创建，用于保存 AgentScope 的记忆文件。
|
||||
|
||||
### 6.2 Workspace 配置
|
||||
|
||||
@@ -534,9 +599,9 @@ LiteFlow 不创建 JDBC 连接池，`DataSource` 也需要由业务应用提供
|
||||
| --- | --- | --- |
|
||||
| `root` | 无 | 必填，workspace 根目录 |
|
||||
| `auto-create` | `true` | 根目录不存在时是否自动创建 |
|
||||
| `cleanup-on-session-expire` | `true` | 空闲 Session 过期清理时是否删除对应 workspace 子目录 |
|
||||
| `cleanup-on-jvm-shutdown` | `false` | `AgentSessionManager.close()` 时是否删除当前存活 Session 的 workspace |
|
||||
| `max-file-bytes` | `10485760` | `read_file` 单次最多读取的字节数 |
|
||||
| `cleanup-on-session-expire` | `true` | 空闲 Session 过期清理时，若该 conversation 下没有其他存活 AgentSession，是否删除对应 workspace 子目录 |
|
||||
| `cleanup-on-jvm-shutdown` | `false` | `AgentSessionManager.close()` 时是否删除当前存活 Session 对应的 workspace |
|
||||
| `max-file-bytes` | `10485760` | `read_file` 单次最多读取的字节数；超出时截断读取 |
|
||||
| `max-list-size` | `1000` | `list_files` 单次最多返回的条目数 |
|
||||
|
||||
如果 Agent 生成的文件需要长期保留，例如报告、草稿、审计材料，应把 `cleanup-on-session-expire` 设为 `false`，并由业务侧做归档。
|
||||
@@ -547,7 +612,7 @@ LiteFlow 不创建 JDBC 连接池，`DataSource` 也需要由业务应用提供
|
||||
|
||||
| 工具名 | 行为 |
|
||||
| --- | --- |
|
||||
| `read_file` | 读取当前 Session workspace 内的文本文件，超过 `max-file-bytes` 时截断 |
|
||||
| `read_file` | 读取当前 conversation workspace 内的文本文件，超过 `max-file-bytes` 时截断 |
|
||||
| `write_file` | 覆盖写入文本文件，并自动创建父目录 |
|
||||
| `list_files` | 列出目录内容，最多返回 `max-list-size` 条 |
|
||||
| `delete_file` | 删除文件 |
|
||||
@@ -567,12 +632,12 @@ protected boolean enableWorkspaceFileTools() {
|
||||
|
||||
`enableShellTool()` 默认为 `true`。如果配置中的 `liteflow.agent.shell.mode` 不是 `DISABLED`，框架会注册 `ManagedShellCommandTool`，工具名为 `execute_shell_command`。
|
||||
|
||||
Shell 工具在当前 Session workspace 下执行命令，使用空白符切分参数，并通过首 token 做白名单或黑名单判断。配置项如下：
|
||||
Shell 工具在当前 conversation workspace 下执行命令。当前实现会按空白符切分命令字符串，用 `ProcessBuilder` 直接执行 token 列表，并通过首 token 做白名单或黑名单判断；不会通过系统 shell 解释管道、重定向、变量展开等语法。配置项如下：
|
||||
|
||||
| 配置项 | 默认值 |
|
||||
| --- | --- |
|
||||
| `mode` | `WHITELIST` |
|
||||
| `whitelist` | `ls, find, tree, stat, file, basename, dirname, pwd, which, cat, head, tail, grep, sed, awk, wc, sort, uniq, cut, tr, diff, echo, printf, expr, date, whoami, hostname, uname, env, df, du, ps, md5sum, sha256sum, jq, python3, node` |
|
||||
| `whitelist` | `ls, find, tree, stat, file, basename, dirname, pwd, which, cat, head, tail, grep, sed, awk, wc, sort, uniq, cut, tr, diff, echo, printf, expr, date, whoami, hostname, uname, env, df, du, ps, md5sum, sha256sum, jq, curl, wget, python3, node` |
|
||||
| `blacklist` | `rm, sudo, shutdown, mkfs, dd` |
|
||||
| `timeout` | `30s` |
|
||||
| `max-output-bytes` | `1048576` |
|
||||
@@ -585,19 +650,17 @@ liteflow.agent.shell.mode=disabled
|
||||
|
||||
确实需要 Shell 时，优先使用 `WHITELIST`，并把白名单收窄到业务需要的命令。
|
||||
|
||||
---
|
||||
### 6.5 ReAct 事件日志
|
||||
|
||||
## 6.5 ReAct 事件日志
|
||||
|
||||
框架内置 `ReActLoggingHook`，把 agent 的 `reason` / `act` / `error` 事件写入 SLF4J，便于在终端直接观察 ReAct 推理过程：
|
||||
框架内置 `ReActLoggingHook`，把 agent 的 `reason` / `act` / `error` 事件写入 SLF4J，便于在终端直接观察 ReAct 推理过程。日志中的方括号 ID 为 `conversationId:agentKey`。
|
||||
|
||||
| 事件 | 日志格式 |
|
||||
| --- | --- |
|
||||
| `PreReasoningEvent` | `[agent:reason][sid] >>> model=... messages=N` |
|
||||
| `PostReasoningEvent` | `[agent:reason][sid] <<< text=... toolCalls=[...]` |
|
||||
| `PreActingEvent` | `[agent:act][sid] >>> tool=... input=...` |
|
||||
| `PostActingEvent` | `[agent:act][sid] <<< tool=... result=...` |
|
||||
| `ErrorEvent` | `[agent:error][sid] ...` |
|
||||
| `PreReasoningEvent` | `[agent:reason][conversationId:agentKey] >>> model=... messages=N` |
|
||||
| `PostReasoningEvent` | `[agent:reason][conversationId:agentKey] <<< text=... toolCalls=[...]` |
|
||||
| `PreActingEvent` | `[agent:act][conversationId:agentKey] >>> tool=... input=...` |
|
||||
| `PostActingEvent` | `[agent:act][conversationId:agentKey] <<< tool=... result=...` |
|
||||
| `ErrorEvent` | `[agent:error][conversationId:agentKey] ...` |
|
||||
|
||||
- 全局开关：`liteflow.agent.logging.react-enabled`（默认 `true`）。
|
||||
- 单组件开关：覆写 `enableReActLogging()` 强制返回 `true` / `false`。
|
||||
@@ -633,11 +696,13 @@ public class OrderTool {
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected List<Object> tools(ReActAgentContext ctx) {
|
||||
protected List<Object> tools() {
|
||||
return List.of(new OrderTool());
|
||||
}
|
||||
```
|
||||
|
||||
如果工具需要访问当前 `Slot`、workspace 或 conversation 信息，不要在构造工具时捕获 `ctx()` 的返回值；可以把工具写成组件内部类，或由组件提供一个公开代理方法，在工具方法执行时再间接调用受保护的 `ctx()`。
|
||||
|
||||
### 7.2 用 IF 做路由
|
||||
|
||||
```xml
|
||||
@@ -664,28 +729,44 @@ protected List<Object> tools(ReActAgentContext ctx) {
|
||||
</chain>
|
||||
```
|
||||
|
||||
如果两个 Agent 组件返回同一个 `sessionId`，它们会因为同一把 Session 锁而串行执行。要真正并行，确保不同组件使用不同 Session ID，例如在 `resolveSessionId` 中拼入节点 ID：
|
||||
默认情况下，同一条 chain 内的多个 Agent 会共享同一个 `conversationId`，但因为默认 `agentKey()` 是各自的 `nodeId`，所以 `deepseekAgent` 与 `dashscopeAgent` 会使用不同的 `AgentSession`、不同的锁和不同的 memory，可以并行执行；它们共享同一个 workspace 子目录。
|
||||
|
||||
如果多个 Agent 覆写为相同的 `agentKey()`，它们会因为同一把 Session 锁而串行执行。要真正隔离并行，请确保 `(conversationId, agentKey)` 组合不同；如需文件层面也隔离，则同时让它们使用不同的 `conversationId` 或在共享 workspace 内写入不同子目录。
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected String resolveSessionId(Slot slot) {
|
||||
return getNodeId() + "-" + slot.getRequestId();
|
||||
protected String agentKey() {
|
||||
return getNodeId() + "-" + getSlot().getRequestId();
|
||||
}
|
||||
```
|
||||
|
||||
### 7.4 多轮对话
|
||||
|
||||
多轮对话的关键是让同一业务会话返回同一个 `sessionId`：
|
||||
多轮对话的关键是让多次调用使用同一个 `conversationId`，同时需要让同一个 Agent 节点保持同一个 `agentKey`（默认 nodeId 已满足）：
|
||||
|
||||
```java
|
||||
LiteflowResponse first = flowExecutor.execute2Resp(
|
||||
"deepseekChain",
|
||||
firstRequest,
|
||||
ExecuteOption.of().conversationId("chat-user-1-conv-1"));
|
||||
|
||||
LiteflowResponse second = flowExecutor.execute2Resp(
|
||||
"deepseekChain",
|
||||
secondRequest,
|
||||
ExecuteOption.of().conversationId("chat-user-1-conv-1"));
|
||||
```
|
||||
|
||||
或者在组件中按业务对象覆写：
|
||||
|
||||
```java
|
||||
@Override
|
||||
protected String resolveSessionId(Slot slot) {
|
||||
ChatRequest req = slot.getChainReqData(slot.getChainId());
|
||||
protected String resolveConversationId() {
|
||||
ChatRequest req = getSlot().getChainReqData(getSlot().getChainId());
|
||||
return "chat-" + req.getUserId() + "-" + req.getConversationId();
|
||||
}
|
||||
```
|
||||
|
||||
只要多次执行传入相同的业务会话 ID，Agent 就会在同一个 Session 下复用 memory。是否能跨 JVM 重启恢复，取决于 `liteflow.agent.session.memory.mode`。
|
||||
只要多次执行解析出的 `(conversationId, agentKey)` 相同，Agent 就会复用同一份 memory。是否能跨 JVM 重启恢复，取决于 `liteflow.agent.session.memory.mode`。
|
||||
|
||||
---
|
||||
|
||||
@@ -753,10 +834,11 @@ liteflow.agent.anthropic-compatible.gateway.base-url=https://anthropic-gateway.e
|
||||
|
||||
1. 生产环境默认关闭 Shell：`liteflow.agent.shell.mode=disabled`。
|
||||
2. `workspace.root` 使用专门目录，不要和业务源码、日志、密钥目录混放。
|
||||
3. 不要直接把用户输入原样作为 Session ID。建议使用业务 ID 拼接、哈希或映射。
|
||||
3. 不要直接把用户输入原样作为 `conversationId` 或 `agentKey`。建议使用业务 ID 拼接、哈希或映射。
|
||||
4. API Key 使用环境变量、配置中心或密钥管理系统，不要写入代码仓库。
|
||||
5. 根据业务体量设置 `max-file-bytes`、`max-output-bytes`、`timeout` 和 `max-sessions`，避免 Agent 调用消耗不可控。
|
||||
6. 选择 `REDIS` 或 `MYSQL` 记忆模式时，连接 Bean 由业务应用提供，权限和网络访问也应由业务应用控制。
|
||||
7. 多个 Agent 共享同一个 conversation workspace 时，建议约定各自的文件名前缀或子目录，避免并行写冲突。
|
||||
|
||||
---
|
||||
|
||||
@@ -768,13 +850,14 @@ liteflow.agent.anthropic-compatible.gateway.base-url=https://anthropic-gateway.e
|
||||
| `cannot create workspace root` | 根目录不可写，或父目录权限不足 | 换到应用可写目录，或提前创建并授权 |
|
||||
| `workspace root does not exist` | `auto-create=false` 且目录不存在 | 提前创建目录，或开启 `auto-create` |
|
||||
| `Missing API key: please configure liteflow.agent.openai.api-key` | 对应平台凭据未配置 | 配置对应平台的 `api-key` |
|
||||
| 多轮对话没有记忆 | 默认 Session ID 由 `NanoIdSessionIdGenerator` 每次随机生成 | 覆写 `resolveSessionId`，返回稳定的业务会话 ID |
|
||||
| 多轮对话没有记忆 | 每次调用使用了不同 `conversationId`，或 `agentKey()` 被拼入了一次性值 | 传入稳定的 `ExecuteOption.conversationId(...)`，或覆写 `resolveConversationId()` 返回稳定业务会话 ID；同时保持同一 Agent 的 `agentKey` 稳定 |
|
||||
| 同一条 chain 中多个 Agent 没有共享文件 | 它们解析到了不同 `conversationId` | 让首个 Agent 写回的 `slot.conversationId` 被后续 Agent 复用，或显式传入同一个 `ExecuteOption.conversationId(...)` |
|
||||
| 重启后没有历史记忆 | `session.memory.mode=JVM` 或 `NONE` | 改为 `LOCAL_FILE`、`REDIS` 或 `MYSQL` |
|
||||
| Redis 模式启动失败 | 未配置 Bean 名，或 Bean 类型与 `client-type` 不匹配 | 检查 `bean-name`、`client-type` 和 classpath 依赖 |
|
||||
| MySQL 模式启动失败 | 未配置 `DataSource` Bean，或 Bean 类型错误 | 配置正确的 `data-source-bean-name` |
|
||||
| Shell 返回 `command 'xxx' not allowed by whitelist` | 白名单模式下命令未放行 | 加入白名单，或继续保持禁用 |
|
||||
| `path escapes workspace` | 文件工具收到绝对路径或越界路径 | 使用相对路径，并限制在当前 workspace 内 |
|
||||
| `WHEN` 中多个 Agent 看起来没有并行 | 多个组件共用了同一个 Session ID | 让不同 Agent 返回不同 `sessionId` |
|
||||
| `WHEN` 中多个 Agent 看起来没有并行 | 多个组件解析到了相同 `(conversationId, agentKey)`，共用了同一把锁；或下游等待最慢分支 | 确保需要并行的 Agent 使用不同 `agentKey()`；如还要隔离文件，则使用不同 conversation 或子目录 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -36,6 +36,8 @@ public class ShellConfig {
|
||||
"date", "whoami", "hostname", "uname", "env", "df", "du", "ps",
|
||||
// 哈希与数据格式
|
||||
"md5sum", "sha256sum", "jq",
|
||||
// 网络请求
|
||||
"curl", "wget",
|
||||
// 脚本解释器
|
||||
"python3", "node");
|
||||
|
||||
|
||||
@@ -1,59 +0,0 @@
|
||||
package com.yomahub.liteflow.test.slot;
|
||||
|
||||
import com.yomahub.liteflow.slot.Slot;
|
||||
import org.junit.jupiter.api.Test;
|
||||
|
||||
import static org.junit.jupiter.api.Assertions.assertEquals;
|
||||
import static org.junit.jupiter.api.Assertions.assertFalse;
|
||||
import static org.junit.jupiter.api.Assertions.assertNull;
|
||||
import static org.junit.jupiter.api.Assertions.assertThrows;
|
||||
import static org.junit.jupiter.api.Assertions.assertTrue;
|
||||
|
||||
public class SlotAttachmentTest {
|
||||
|
||||
@Test
|
||||
public void setAndGetAttachment_roundTrip() {
|
||||
Slot slot = new Slot();
|
||||
slot.setAttachment("foo", "bar");
|
||||
String v = slot.getAttachment("foo");
|
||||
assertEquals("bar", v);
|
||||
}
|
||||
|
||||
@Test
|
||||
public void getAttachment_missingKey_returnsNull() {
|
||||
Slot slot = new Slot();
|
||||
Object v = slot.getAttachment("absent");
|
||||
assertNull(v);
|
||||
}
|
||||
|
||||
@Test
|
||||
public void hasAttachment_reportsPresence() {
|
||||
Slot slot = new Slot();
|
||||
assertFalse(slot.hasAttachment("k"));
|
||||
slot.setAttachment("k", 1);
|
||||
assertTrue(slot.hasAttachment("k"));
|
||||
}
|
||||
|
||||
@Test
|
||||
public void removeAttachment_clearsValue() {
|
||||
Slot slot = new Slot();
|
||||
slot.setAttachment("k", 1);
|
||||
slot.removeAttachment("k");
|
||||
assertFalse(slot.hasAttachment("k"));
|
||||
assertNull(slot.getAttachment("k"));
|
||||
}
|
||||
|
||||
@Test
|
||||
public void setAttachment_nullValue_throws() {
|
||||
Slot slot = new Slot();
|
||||
assertThrows(RuntimeException.class, () -> slot.setAttachment("k", null));
|
||||
}
|
||||
|
||||
@Test
|
||||
public void getAttachment_genericTypeInference() {
|
||||
Slot slot = new Slot();
|
||||
slot.setAttachment("num", 42);
|
||||
Integer n = slot.getAttachment("num");
|
||||
assertEquals(42, n);
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user