mirror of https://gitee.com/dromara/liteFlow
docs(react-agent): 修复 guide v2 findings（臆造类名/缺注记/措辞）
- Important-1: 删除不存在的 HookMiddlewareAdapter 引用，改为 ReActAgent.builder().hooks(...) 直接桥接（§1.5.x 与 §3 注释两处） - Important-2: §6.1/§6.2 开头各加 2.0(RC3) 变化注记框， 指出单根 workspace + AgentSessionManager 已删使原 1.0 描述失效 - Minor-3: §1.5.4 线程模型扩写，ChatUsage 与 SkillTracking 均经 reactor Context (Flux.deferContextual) 透传 - Minor-4: BackCompatSmokeTest 描述由"严格镜像 §2.3"弱化为 "基于 §2.3"（实际额外覆写 enableReActLogging） Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
everywhere.z
parent
8380280bb1
commit
bccf1426e8
|
|
@ -118,9 +118,9 @@
|
|||
- `ChatUsageTrackingHook` → `ChatUsageMiddleware`（在 `onModelCall` 后读 message usage 累加，**`ctx().getChatUsage()` API 保留**）；
|
||||
- `SkillTrackingHook` → `SkillTrackingMiddleware`（在 `onActing` 监听 `load_skill_through_path` 工具调用，记录 `usedSkills()`）。
|
||||
|
||||
业务侧 `hooks()` 返回 `List<Hook>` 的写法**保留兼容**（内部经 `HookMiddlewareAdapter` 转 middleware），但方法标 `@Deprecated(forRemoval)`；**推荐改用 `middlewares()` 返回 `List<MiddlewareBase>`**。1.0 的 `Hook`（`io.agentscope.core.hook.Hook`）在 v2 软弃用但仍可编译运行。
|
||||
业务侧 `hooks()` 返回 `List<Hook>` 的写法**保留兼容**（经 `ReActAgent.builder().hooks(...)` 直接桥接，`builder` 内部把 1.0 `Hook` 软适配为 v2 middleware；v2 `Hook` 软弃用但仍可编译运行），但方法标 `@Deprecated(forRemoval)`；**推荐新代码用 `middlewares()` 返回 `List<MiddlewareBase>`**。1.0 的 `Hook`（`io.agentscope.core.hook.Hook`）在 v2 软弃用但仍可编译运行。
|
||||
|
||||
**`ctx().getChatUsage()` 的线程模型**：真实 vendor 模型下，`onModelCall` 在 `boundedElastic` 调度线程上被调用（不在 `process()` 的 HTTP 线程上）。ChatUsage 累加器走 **reactor `Context` 向上游传播**（`process()` 在订阅前 `contextWrite` 把累加器塞进 Context），保证任意调度线程上的 middleware 都能读到；同时保留 ThreadLocal 回退使无 reactor Context 的单元测试继续可用。1.0 的单线程 ThreadLocal 假设在 v2 不成立——若你自定义 middleware 累加 token，请走同样的 reactor Context 方案。
|
||||
**`ctx().getChatUsage()` 的线程模型**：真实 vendor 模型下，`onModelCall` 在 `boundedElastic` 调度线程上被调用（不在 `process()` 的 HTTP 线程上）。累计 per-invocation 状态的 middleware（`ChatUsageMiddleware` 累加 token、`SkillTrackingMiddleware` 记录 `usedSkills()`）均经 **reactor `Context` 向上游透传**（`Flux.deferContextual`，`process()` 在订阅前 `contextWrite` 把累加器/状态塞进 Context），保证任意调度线程上的 middleware 都能读到，跨 `boundedElastic` 线程安全；同时保留 ThreadLocal 回退使无 reactor Context 的单元测试继续可用。1.0 的单线程 ThreadLocal 假设在 v2 不成立——若你自定义 middleware 累加 token 或其它 per-invocation 状态，请走同样的 reactor Context 方案。
|
||||
|
||||
**流式**：`agent.stream(...)` → `agent.streamEvents(...)`（`Flux<AgentEvent>`，28 个类型化事件）。`AgentEventBridge` 把 v2 事件映射到 LiteFlow 对外 4 类 `FlowEvent` type（**type 字符串不变**，保下游兼容）：`agent.reasoning` / `agent.tool_result` / `agent.summary` / `agent.result`，并可选透传 HITL 事件。没有注册 `ExecuteOption.eventListener(...)` 时仍走阻塞 `call()` 路径。详见 [§ 2.6 流式输出](#26-流式输出)。
|
||||
|
||||
|
|
@ -138,7 +138,7 @@
|
|||
- 自定义 `hooks()` 返回 `List<Hook>`——保留兼容但标 `@Deprecated`，建议迁 `middlewares()`；
|
||||
- 依赖 workspace“每会话一目录”物理布局（自定义工具按 `<conversationId>/` 约定读写文件）——RC3 单根布局下需调整路径约定。
|
||||
|
||||
> **源码兼容回归测试**：`liteflow-testcase-el/liteflow-testcase-el-react-agent/src/test/java/com/yomahub/liteflow/test/agent/v2/BackCompatSmokeTest.java` 把“业务子类核心用法零改动可编译运行”做成回归用例——一个严格镜像 [§ 2.3](#23-编写-agent-组件) 范式的 `ReActAgentComponent` 子类（`model()` 返回 mock `ModelSpec` 产出 `CannedReplyModel`，避免真实凭据），最简 chain `THEN(agent)`，`execute2Resp` 执行，断言 success + `responseData` 非空。每次升级 agentscope 版本都应保证此测试绿。
|
||||
> **源码兼容回归测试**：`liteflow-testcase-el/liteflow-testcase-el-react-agent/src/test/java/com/yomahub/liteflow/test/agent/v2/BackCompatSmokeTest.java` 把“业务子类核心用法零改动可编译运行”做成回归用例——一个基于 [§ 2.3](#23-编写-agent-组件) 范式的 `ReActAgentComponent` 子类（在 § 2.3 示例基础上额外覆写 `enableReActLogging()` 等开关以演示能力声明，`model()` 返回 mock `ModelSpec` 产出 `CannedReplyModel`，避免真实凭据），最简 chain `THEN(agent)`，`execute2Resp` 执行，断言 success + `responseData` 非空。每次升级 agentscope 版本都应保证此测试绿。
|
||||
|
||||
### 1.5.6 进一步阅读
|
||||
|
||||
|
|
@ -369,7 +369,7 @@ if (response.isSuccess()) {
|
|||
`ReActAgentComponent#process()` 是 `final`。框架在其中统一完成配置读取、conversation 解析、`agentKey` 解析、Session 获取、加锁、Agent 懒构建、调用、回复处理和 memory 保存。业务侧通过覆写受保护方法定制行为。
|
||||
|
||||
> **2.0(RC3) 变化**：`process()` 内部已重写——不再手动 Session 获取/加锁/懒构建/memory 保存，改为构建无状态 `ReActAgent` 单例 + `RuntimeContext(userId=conversationId, sessionId=agentKey)` + `agent.call(...)`，由 v2 管 load/save/串行。受保护方法签名（下表）**保持不变**，仅以下几项语义微调：
|
||||
> - `hooks()`：1.0 注册 agentscope `Hook`；RC3 标 `@Deprecated(forRemoval)`，内部经 `HookMiddlewareAdapter` 转 v2 `MiddlewareBase`。**推荐改用 `middlewares()` 返回 `List<MiddlewareBase>`**。
|
||||
> - `hooks()`：1.0 注册 agentscope `Hook`；RC3 标 `@Deprecated(forRemoval)`，经 `ReActAgent.builder().hooks(...)` 直接桥接（v2 `Hook` 软弃用但仍可编译运行）。**推荐新代码用 `middlewares()` 返回 `List<MiddlewareBase>`**。
|
||||
> - `enableShellTool()` / `enableWorkspaceFileTools()`：签名保留，语义改为“是否在 `ReActAgent` 上启用对应工具组”（与 1.0 行为等价，shell 仍与 `shell.mode` 取逻辑与）。
|
||||
> - `enableReActLogging()`：改为控制 `LoggingMiddleware` 是否安装（开关仍是 `logging.react-enabled`）。
|
||||
>
|
||||
|
|
@ -839,6 +839,8 @@ public class EncryptedFileSessionFactory implements AgentSessionFactory {
|
|||
|
||||
### 6.1 Workspace 目录结构
|
||||
|
||||
> **2.0(RC3) 变化：** 下方“每个 conversation 一个 `<conversationId>/` 子目录”的布局是 **1.0 行为**，RC3-core 下已不适用——workspace 改为 `workspace.root` 单根 + conversationId 作为 v2 `userId` 维度命名（不再为每会话建独立子目录）。原描述保留作历史参考，详见 [§ 1.5](#15-从-10-升级到-agentscope-20rc3)。
|
||||
|
||||
每个 conversation 都会在 `liteflow.agent.workspace.root` 下获得一个独立子目录：
|
||||
|
||||
```text
|
||||
|
|
@ -852,6 +854,8 @@ public class EncryptedFileSessionFactory implements AgentSessionFactory {
|
|||
|
||||
### 6.2 Workspace 配置
|
||||
|
||||
> **2.0(RC3) 变化：** 下表中 `cleanup-on-session-expire` / `cleanup-on-jvm-shutdown` 绑定的是 1.0 已删除的 `AgentSessionManager.close()` / 空闲 AgentSession 过期语义，RC3-core 下随单根 workspace 一起**失效**；这两个键的清理语义将随 GA HarnessAgent 落地，详见 [§ 1.5](#15-从-10-升级到-agentscope-20rc3)。原描述保留作历史参考。
|
||||
|
||||
| 配置项 | 默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `root` | 无 | 必填，workspace 根目录 |
|
||||
|
|
|
|||
Loading…
Reference in New Issue