From 6143229255bcee5cb06ba99460c996abab029060 Mon Sep 17 00:00:00 2001 From: "everywhere.z" Date: Fri, 19 Jun 2026 21:36:31 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=20liteflow-react-age?= =?UTF-8?q?nt=20AgentScope=202.0=20=E8=BF=81=E7=A7=BB=E8=AE=BE=E8=AE=A1?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 基于 HarnessAgent 全家桶路线、保留并映射现有 liteflow.agent.* 配置键、 一次到位接通全部增强能力的迁移设计评审稿。 Co-Authored-By: Claude Fable 5 --- ...26-06-19-agentscope-v2-migration-design.md | 313 ++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-19-agentscope-v2-migration-design.md diff --git a/docs/superpowers/specs/2026-06-19-agentscope-v2-migration-design.md b/docs/superpowers/specs/2026-06-19-agentscope-v2-migration-design.md new file mode 100644 index 000000000..677a7a0a9 --- /dev/null +++ b/docs/superpowers/specs/2026-06-19-agentscope-v2-migration-design.md @@ -0,0 +1,313 @@ +# liteflow-react-agent · AgentScope 2.0 迁移设计 + +- 状态：已通过设计评审，待出实施计划 +- 日期：2026-06-19 +- 基线：`agentscope 1.0.12` → 目标 `agentscope 2.0.x` +- 路线决策：**基于 HarnessAgent 全家桶 + 一次到位启用全部增强能力 + 保留并映射现有 `liteflow.agent.*` 配置键** + +## 1. 背景与动机 + +`liteflow-react-agent` 模块当前依赖 AgentScope 1.0.12。AgentScope 2.0 带来大量原生能力，其中**会话/持久化、workspace、文件与 shell 工具、skill 仓库**恰好与 liteflow 当前在 `react-agent-core` 中手写的实现高度重合。本迁移的目标是用 v2 原生能力替换这些手写层，同时保住业务侧继承 `ReActAgentComponent` 的核心用法与现有配置键。 + +### 1.1 现状关键事实（迁移前） + +- 引擎入口：`ReActAgentComponent`（抽象，继承 `NodeComponent`），`process()` 为 `final`，内部手动完成配置读取、`(conversationId, agentKey)` 解析、Session 获取加锁、agent 懒构建、调用、回复处理、memory 保存。 +- 会话层（**全部建在 v2 已删除的类型上**）： + - `AgentSessionManager`：依赖 `io.agentscope.core.session.SessionManager` 与 `Session`（v2 已删）。 + - `AgentSessionFactory` SPI + `AgentSessionFactoryRegistry` + 5 个 factory（`InMemory/LocalFile/Redis/Mysql/None`），返回 `Session`，并 import `InMemorySession/JsonSession/RedisSession/MysqlSession`（v2 均已删）。 + - `AgentSession`：持有 `conversationId/agentKey/cacheKey/workspaceDir/ReentrantLock` 与缓存的 agent。 +- 标识模型：`(conversationId, agentKey)` 两级。`conversationId` 决定 workspace 目录（同 chain 内多个 agent 共享），`agentKey`（默认 `nodeId`）区分不同 agent 的实例与记忆。持久化 key 为 `safe(conversationId) + "__" + safe(agentKey)`。 +- 配置（`liteflow.agent.*`，定义在 liteflow-core 的 `property/agent` 包）：`AgentConfig` 聚合 `workspace/session/shell/defaults/logging/skills` + 4 个头等平台凭据（openai/anthropic/gemini/dashscope）+ 2 个兼容平台 Map。`MemoryStorageMode` 枚举：`NONE/JVM/LOCAL_FILE/REDIS/MYSQL`。 +- Hook（依赖 v2 已 `@Deprecated(forRemoval)` 的 `io.agentscope.core.hook.*`）：`ReActLoggingHook`、`ChatUsageTrackingHook`（跨 reasoning step 累加 token，经 `ctx.getChatUsage()` 暴露）、`SkillTrackingHook`。 +- 工具（使用 v2 仍有效的 `@Tool/@ToolParam`）：`WorkspaceFileTools`（read/write/list/delete + 路径防穿越 + 大小上限）、`ManagedShellCommandTool`（白/黑名单/disabled/超时/输出截断 + 拒绝管道与命令链）。 +- Skill：`SkillBoxFactory` + `SkillToolResolver`，依赖 `SkillBox`（v2 已 `@Deprecated`）。 +- 模型层：`ModelSpec` 抽象 + 各 vendor `XxxSpec/XxxModelFactory/入口类`，`resolve(AgentConfig)` 从配置取凭据、装配 `GenerateOptions`、构造 `Model`。 +- 流式：`agent.stream(List, StreamOptions)` → `Flux`，映射 `EventType.REASONING/TOOL_RESULT/SUMMARY/AGENT_RESULT` 到 `FlowEvent`。 +- 工作区清理：`workspace.cleanup-on-session-expire` / `cleanup-on-jvm-shutdown` 删除整个会话目录。 + +### 1.2 v2 关键能力（迁移目标） + +- `HarnessAgent`：`ReActAgent` 的薄包装，能力（workspace 注入/compaction/subagent/sandbox/Plan Mode）**挂到** ReAct 循环关键时刻，不改循环；用户 middleware 跑在内置 middleware **之前**。 +- 三个共享对象：`RuntimeContext(userId, sessionId, extras)`（不持久化）、workspace、`AgentStateStore`。 +- Agent 完全无状态：单实例并发服务多个 `(userId, sessionId)`；同 session 串行、异 session 并行；call 入口自动 load、出口自动 save。 +- `AgentStateStore`：`InMemory/JsonFile/Redis/MySQL/OSS`，按 `(userId, sessionId)` 分桶；分布式 store 下跨进程/跨机器自动恢复。 +- 文件系统三模式：`LocalFilesystemSpec`（默认，host shell）/ `DockerFilesystemSpec` 等沙箱（隔离执行 + 跨 call 恢复）/ `RemoteFilesystemSpec(store)`（多副本共享 KV，无 shell）。内置工具 `read_file/write_file/edit_file/grep_files/glob_files/list_files` + `execute`。 +- 多租户：`IsolationScope.USER` 按 `userId` 分桶 workspace 文件。 +- Skill：`.skillRepository(Git/Nacos/MySQL/Classpath/自定义)` + workspace `skills/`（共享）与 `/skills/`（隔离）；可选 self-learning loop。 +- Middleware：`MiddlewareBase`，5 stage（洋葱型 `onAgent/onReasoning/onActing/onModelCall` + 管道型 `onSystemPrompt`）。 +- Permission：`PermissionEngine` 在每次工具调用前裁决（允许/审批/拒绝），模式 `DEFAULT/ACCEPT_EDITS/EXPLORE/BYPASS/DONT_ASK`，HITL 决策回流 `UserConfirmResultEvent`。 +- Model：`ModelRegistry` 解析 `"provider:model"` 字符串并自动读 env key；`maxRetries`/`fallbackModel`/`stopOnReject`；`ModelConfig`/`CompactionConfig`/`MemoryConfig` 可指定独立轻量模型。 +- 事件：`streamEvents()` → `Flux`，28 个类型化事件（含 HITL）。 +- 其它：Plan Mode（只读调查阶段 + HITL 门控）、TaskList（`TodoTools` + `TaskReminderMiddleware`）、per-session `interrupt`、context compaction、大工具结果外存。 + +### 1.3 断裂面确认 + +- **硬断裂（不改编译失败）**：整个 `session` 包（Manager/SPI/Registry/5 factory，均 import v2 已删的 `io.agentscope.core.session.*`）；`buildAgent()` 中 `.memory(new InMemoryMemory())`（`.memory(Memory)` 已删）。 +- **软弃用（2.0.x 仍可编译运行，`@Deprecated(forRemoval)`）**：`Hook` 三实现、`SkillBoxFactory`、`stream()`+`EventType`、`Msg.builder()`（role 严格校验，推荐 `UserMessage`）。 +- **0 影响纯增益**：Middleware / Permission / Compaction / Plan Mode / TaskList / interrupt / 28 事件等。 + +## 2. 目标与非目标 + +### 目标 +1. 底层从 `ReActAgent`(1.0) 切到 `HarnessAgent`(2.0)，会话/持久化/workspace/skill/工具全部用 v2 原生。 +2. 业务侧继承 `ReActAgentComponent` 的核心用法（`model()/systemPrompt()/userPrompt()` 等）尽量源码兼容。 +3. 老 `liteflow.agent.*` 配置键**保留并映射**到 v2 概念，老用户改配置即可升级。 +4. 一次性接通 HarnessAgent 的 compaction / plan-mode / subagent / sandbox / self-learning skill / per-session interrupt 等增强能力（配置驱动，默认或可选启用）。 + +### 非目标 +- 不做 1.x→2.x 无感二进制兼容（session 层硬断裂不可避免，做一次性协调性 breaking release）。 +- 不重写 `liteflow-core` 编排引擎；agent 仍是 `NodeComponent`。 +- 不引入新脚本/规则源；只迁 react-agent 模块。 + +## 3. 总体架构：模块改造地图 + +| 现有（1.0） | 处置 | v2 替代 | +|---|---|---| +| `AgentSessionManager`（LRU/lock/清理线程/目录） | 删除 | `HarnessAgent`（单例无状态）+ `AgentStateStore` 自动 load/save + per-session 串行门 | +| `AgentSession` | 删除 | `RuntimeContext(userId, sessionId)` | +| `AgentSessionFactory` SPI + Registry + 5 factory | 删除，能力收口进 `AgentStateStoreResolver` | `InMemory/JsonFile/Redis/MySQL/OSS AgentStateStore` | +| `ReActAgentComponent.process()`（手动 lock/save/load） | 重写、大幅瘦身 | `agent.call(msgs, runtimeContext)`，由 v2 管 load/save/串行 | +| `.memory(new InMemoryMemory())` | 删除（API 已删） | `.stateStore(...)` | +| `WorkspaceFileTools` | 删除 | HarnessAgent 内置文件工具 | +| `ManagedShellCommandTool` | 删除 | HarnessAgent `execute` + `PermissionEngine` | +| `SkillBoxFactory` + `SkillToolResolver` + `SkillTrackingHook` | 删除/重写 | `.skillRepository(...)` + workspace `skills/` + `DynamicSkillMiddleware` | +| `ReActLoggingHook` / `ChatUsageTrackingHook` | 重写为 middleware | `MiddlewareBase`（5 stage） | +| `stream()` + `EventType` 四类桥接 | 重写 | `streamEvents()` + `AgentEvent`（28 类） | +| `ModelSpec` + 各 vendor Spec/Factory/入口类 | 保留，实现微调 | `resolve()` 返回 `Model` 喂 `.model(...)` | +| `ReActAgentContext`（ctx） | 保留并扩展 | 增加 `getRuntimeContext()`；`getChatUsage()` 由 middleware 支撑 | +| `AgentConfig` 及 property 包（liteflow-core） | 保留键，语义重映射 | 见 §7 | + +**新增类型**：`AgentStateStoreResolver`（mode→store 映射）、`PermissionConfigMapper`（shell.*→PermissionRule）、`AgentEventBridge`（AgentEvent→FlowEvent）、`HarnessAgentFactory`（构建并缓存单例 agent）、LoggingMiddleware / ChatUsageMiddleware / SkillTrackingMiddleware、各能力配置包装类。 + +## 4. 核心：会话与状态层重设计 + +### 4.1 标识映射 + +``` +liteflow 现有 → v2 RuntimeContext / HarnessAgent +conversationId → userId (workspace 文件命名空间：同 conversation 的多个 agentKey 共享文件) +agentKey (默认 nodeId) → sessionId (独立 AgentState / 记忆) +nodeId → agent.name() (每个 ReActAgentComponent 子类一个 HarnessAgent 实例) +``` + +与 v2 的 `IsolationScope.USER` 文件分桶 + `(userId,sessionId)` 状态分桶语义同构，保住"同 conversation 共享 workspace、不同 agentKey 隔离记忆"。 + +### 4.2 缓存模型变化 + +- 旧：为每个 `(conversationId, agentKey)` 缓存独立 `ReActAgent` + `ReentrantLock`，JVM 内 LRU/超时清理。 +- 新：每个 `ReActAgentComponent` 子类构建**一个无状态 `HarnessAgent` 单例**（按子类 Class 缓存），所有调用复用同一实例，靠 `RuntimeContext` 路由。串行/并行/隔离由 v2 保证。 +- `maxSessions`/`idleTimeout`/`cleanupInterval`/LRU 逻辑整体删除。配置键保留但 `@Deprecated`。 + +### 4.3 process() 重写骨架 + +```java +@Override +public final void process() { + AgentConfig cfg = agentConfig(); + HarnessAgent agent = HarnessAgentFactory.getOrCreate(this, cfg); // 单例 + + String cid = resolveConversationId(); // 保留现有解析逻辑 + slot.setConversationId(cid); + String akey = agentKey(); + RuntimeContext rc = RuntimeContext.builder() + .userId(cid).sessionId(akey).build(); + + ReActAgentContext ctx = new ReActAgentContext(slot, cid, akey, workspaceRoot(cfg, cid)); + slot.setAttachment(ctxKey(), ctx); + try { + Msg reply = callAgent(agent, new UserMessage(userPrompt()), rc, slot); + handleReply(reply); + } finally { + slot.removeAttachment(ctxKey()); + } + // 不再手动 load/save —— v2 在 call() 入口/出口自动处理 +} +``` + +- `callAgent()`：无 FlowEvent 监听时 `agent.call(msgs, rc).block()`；有时走 `streamEvents()` 桥接（§10）。 +- workspace 目录：从"`root//`（每会话一目录）"改为 HarnessAgent 的"`root`（单根）+ `userId=conversationId` 内部分桶"。物理布局变，隔离语义保留。 + +### 4.4 AgentStateStore 映射（`AgentStateStoreResolver`） + +| `MemoryStorageMode`（老键，保留） | v2 `AgentStateStore` | 依赖 | +|---|---|---| +| `NONE` | NoOp/不落盘 store（见 R1） | — | +| `JVM`（默认） | `InMemoryAgentStateStore`（共享实例，堆内累积，重启丢） | core | +| `LOCAL_FILE` | `JsonFileAgentStateStore(root/.agent-state)` | core | +| `REDIS` | `RedisAgentStateStore`（Jedis/Lettuce/Redisson，按现有 `redis.beanName/clientType` 反射取 bean） | `agentscope-extensions-redis` | +| `MYSQL` | `MysqlAgentStateStore`（按现有 `mysql.dataSourceBeanName/databaseName/tableName`） | `agentscope-extensions-mysql` | +| `OSS`（新增可选） | `OssAgentStateStore` | `agentscope-extensions-oss` | + +- `loadOnFirstUse`/`saveAfterCall`/`saveOnError`：v2 每次 call 自动 load+save，三键降级为提示性（`saveOnError=false` 需在异常路径包一层），建议 `@Deprecated` 并文档说明被 v2 行为取代。 + +## 5. Workspace / 文件系统 / 工具 + +### 5.1 文件系统模式（新增 `filesystem.mode`，默认 LOCAL） + +| `filesystem.mode`（新键） | v2 `FilesystemSpec` | shell | 说明 | +|---|---|---|---| +| `LOCAL`（默认） | `LocalFilesystemSpec` | host `sh -c` | 单机/可信，替代现有 ManagedShellCommandTool | +| `SANDBOX_DOCKER`/`SANDBOX_K8S`/`SANDBOX_E2B`/`SANDBOX_AGENTRUN` | `DockerFilesystemSpec` 等 | 沙箱内 | 隔离执行、跨 call 恢复、可选快照 | +| `REMOTE` | `RemoteFilesystemSpec(store)` | 无 | 多副本共享 KV（配合 `distributedStore`） | + +- 选 `SANDBOX_*` 或 `REMOTE` 时，v2 强制要求分布式 store（否则 `build()` 抛异常）。`AgentStateStoreResolver` 在此场景自动要求 REDIS/OSS，配置缺失时给清晰报错。 + +### 5.2 自建工具删除 → 内置 + 权限 + +- 删 `WorkspaceFileTools`、`ManagedShellCommandTool`，由 HarnessAgent 内置文件工具 + `execute` 接管。 +- `enableShellTool()` / `enableWorkspaceFileTools()` 语义改为"是否在 HarnessAgent 上启用对应工具组"（HarnessAgent 有 `disable*` 开关）。 +- `ShellConfig` → `PermissionEngine`（`PermissionConfigMapper`）： + - `shell.mode=DISABLED` → 不启用 `execute` + - `WHITELIST` → `PermissionRule` 允许集合 + - `BLACKLIST` → `PermissionRule` 拒绝集合 + - `timeout`/`maxOutputBytes` → sandbox/工具执行配置 +- `workspace.maxFileBytes`/`maxListSize` → 文件工具/`toolResultEviction` 配置。 + +### 5.3 workspace 语义变化（需文档化） + +HarnessAgent workspace 持久累积（`MEMORY.md` 累积、`agents//sessions/` 只增、`plans/` 跨 call 保留）。`cleanup-on-session-expire`/`cleanup-on-jvm-shutdown` 保留键，语义从"删整个会话目录"变为"按 userId 清理 HarnessAgent 用户桶"。老数据无法自动迁移，需文档说明。 + +## 6. Skill 迁移 + +- 删 `SkillBoxFactory`/`SkillToolResolver`/`SkillTrackingHook`。 +- `skills.path` → 默认走 workspace `skills/`（HarnessAgent 原生，无需注册）；或额外 `.skillRepository(Classpath/Git/Nacos/MySQL/...)`。 +- `skills()`（allow-list）→ v2 `.skillFilter(SkillFilter)`。 +- `enableSkills()` → 控制 `DynamicSkillMiddleware` 是否安装（`Builder.dynamicSkillsEnabled(...)`）。 +- self-learning skill loop：HarnessAgent 自带（agent 起草 → review gate → 后台 curator 清理），由配置开关启用，无需 liteflow 写代码。 +- `usedSkills()` 跟踪：改由 skill-tracking middleware 提供。 + +## 7. 配置层映射（保留老键） + +| 老键（保留） | v2 去向 | 备注 | +|---|---|---| +| `workspace.root` | `HarnessAgent.workspace(Path)` | 必填不变 | +| `workspace.autoCreate`/`cleanup-*`/`maxFileBytes`/`maxListSize` | workspace/filesystem 配置 | 保留 | +| `openai/anthropic/gemini/dashscope.*`（含 `-compatible..*`） | `ModelSpec` 凭据 → `.model(Model)` | 完全保留 | +| `session.memory.mode = NONE/JVM/LOCAL_FILE/REDIS/MYSQL` | `AgentStateStoreResolver` → `.stateStore(...)` | 保留，+可选 `OSS` | +| `session.memory.redis.*`/`mysql.*`/`localFile.*` | 对应 store 构造参数 | 保留 | +| `session.memory.loadOnFirstUse/saveAfterCall/saveOnError` | 提示性 / `@Deprecated` | v2 自动 load/save | +| `session.maxSessions/idleTimeout/cleanupInterval` | `@Deprecated`（启动告警） | v2 无实例缓存 | +| `shell.mode/whitelist/blacklist/timeout/maxOutputBytes` | `PermissionEngine` + filesystem 执行配置 | 保留键，语义重映射 | +| `skills.enabled/path/strict` | `.skillRepository(...)` + workspace `skills/` | 保留 | +| `logging.react-enabled` | logging middleware 开关 | 保留 | +| `defaults.max-iterations` | `.maxIters(...)`/`reactConfig` | 保留 | +| **新增** `filesystem.mode` | `FilesystemSpec` 选择 | 默认 LOCAL | +| **新增** `compaction.*` | `CompactionConfig`（可指定轻量模型） | 默认开启 | +| **新增** `planMode.enabled`/`taskList.enabled` | `.enablePlanMode()`/`.enableTaskList(true)` | 默认关闭，可选 | +| **新增** `subagent.*`/`sandbox.*` | subagent 声明 / sandbox 后端 | 默认关闭，可选 | +| **新增** `model.fallback`/`model.maxRetries` | `ModelConfig` | 可选 | + +## 8. Hook → Middleware（保留 `ctx.getChatUsage()`） + +| 现有 Hook | → Middleware（stage） | +|---|---| +| `ReActLoggingHook` | `LoggingMiddleware`（`onReasoning`/`onActing`，reason/act/error 日志） | +| `ChatUsageTrackingHook`（跨 reasoning step 累加 token） | `ChatUsageMiddleware`（`onModelCall` 后读 message usage 累加）—— 保留 `ctx.getChatUsage()` API | +| `SkillTrackingHook` | `SkillTrackingMiddleware` | +| 业务侧 `hooks()` 返回 `List` | 保留方法签名作兼容桥（内部 `LegacyHookDispatcher` 转 middleware），新增 `middlewares()` 返回 `List` 鼓励迁移；`hooks()` 标 `@Deprecated(forRemoval)`，给一个版本缓冲 | + +liteflow 自有 middleware 经 `.middlewares(...)` 注册，跑在 HarnessAgent 内置 middleware 之前。 + +## 9. 模型层（保留 `ModelSpec`） + +- `ModelSpec`/各 `XxxSpec`/`XxxModelFactory`/入口类保留——config 驱动凭据 + vendor 个性参数是 liteflow 的价值，不与 v2 重复。 +- `resolve()` 仍返回 `io.agentscope.core.model.Model`，喂 `HarnessAgent.builder().model(...)`。 +- 可选增强：`model.fallback`/`maxRetries` 走 v2 `ModelConfig`；compaction/memory 独立轻量模型走 `CompactionConfig.model(...)`/`MemoryConfig.model(...)`。 +- 各 vendor `XxxChatModel.builder()` 若 v2 签名/包路径有变动，实现期按 javadoc 微调；`ModelSpec` 抽象不动。 + +## 10. 流式事件：`stream()` → `streamEvents()` + +- 有 FlowEvent 监听时 `agent.streamEvents(List.of(userMsg), rc)` → `Flux`。 +- `AgentEventBridge` 映射到现有 4 类 `FlowEvent` type（对外 type 字符串不变，保下游兼容）： + +| v2 `AgentEvent` | 现有 `FlowEvent` type | +|---|---| +| `TextBlockDeltaEvent`（reasoning 增量） | `agent.reasoning` | +| 工具相关事件 | `agent.tool_result` | +| summary 相关 | `agent.summary` | +| 最终 `AgentResultEvent` | `agent.result` | +| HITL `RequireUserConfirmEvent` 等（新增） | 新增 `agent.hitl.*` type（可选透传） | + +- 已知 gap（文档化）：`HarnessAgent.streamEvents()` 暂不转发子 agent 事件；启用 subagent 后若需子 agent 事件流，临时回退 `stream()`（2.0.x 可用），等 v2 通道落地再切。 + +## 11. 新增能力接入（配置驱动，一次到位） + +| 能力 | 接入点 | 默认 | +|---|---|---| +| 上下文压缩 compaction | `.compaction(CompactionConfig)`（可独立轻量模型） | 开 | +| 大工具结果外存 toolResultEviction | `.toolResultEviction(...)` | 开 | +| 两层长期记忆 MEMORY.md | `.memory(MemoryConfig)`（HarnessAgent 默认开） | 开 | +| Plan Mode | `.enablePlanMode()`，受 `planMode.enabled` | 关（可选） | +| TaskList（todo_write） | `.enableTaskList(true)`，受 `taskList.enabled` | 关（可选） | +| Subagent | `.subagent(...)` + workspace `subagents/`，受 `subagent.*` | 关（可选） | +| Sandbox 执行 | `filesystem.mode=SANDBOX_*` | 关（默认 LOCAL） | +| Self-learning skill | HarnessAgent 内置，受 skill 配置开关 | 关（可选） | +| Per-session interrupt | 暴露 `interrupt(conversationId, agentKey)` 工具方法，映射 `agent.interrupt(userId,sessionId)` | 按需 | + +## 12. 对外 API 兼容性（业务子类） + +**保持不变（源码兼容）**：`model()`/`systemPrompt()`/`userPrompt()`/`tools()`/`skills()`/`enableSkills()`/`resolveConversationId()`/`agentKey()`/`maxIterations()`/`handleReply(Msg)`/`buildModel()`/`ctx()`/`getSlot()`。 + +**签名保留但语义可能微调**：`enableShellTool()`/`enableWorkspaceFileTools()`（→ HarnessAgent 工具组开关）、`enableReActLogging()`。 + +**新增**：`middlewares()`（推荐替代 `hooks()`）、`permissionContext()`、`runtimeContext()`。 + +**弃用**：`hooks()`（`@Deprecated(forRemoval)`，内部桥接，给缓冲）。 + +结论：绝大多数现有业务组件源码零改动即可在 v2 编译运行；仅自定义了 `hooks()` 或依赖被删自建工具类的少数代码需调整。 + +## 13. 破坏性变更清单 + +**编译期硬断裂（必须改）** +- 整个 `session` 包删除（依赖 v2 已删类型）。 +- `buildAgent()`：`ReActAgent`→`HarnessAgent`，`.memory(InMemoryMemory)`→`.stateStore(...)`，去掉手写 lock/save/load。 +- `WorkspaceFileTools`/`ManagedShellCommandTool` 删除（import 它们的业务代码需改）。 +- `Msg.builder().textContent().build()` → `new UserMessage(...)`。 +- 三个 Hook 类改 middleware；`import ...hook.*` 的业务代码迁 `middlewares()`。 +- `SkillBoxFactory`/`SkillToolResolver`/`SkillTrackingHook` 删除/重写。 + +**配置层**：老键保留映射；`session.maxSessions/idleTimeout/cleanupInterval` 与 `loadOnFirstUse/saveAfterCall/saveOnError` 标 `@Deprecated`（启动告警）；workspace 清理语义变化需文档。 + +**运行期行为变化**：workspace 从"每会话目录"→"单根+用户桶+持久累积"；agent 实例从"每(conv,key)缓存"→"单例无状态"；LRU 清理不再发生。 + +## 14. 实施阶段（每阶段可独立编译/测试） + +1. 依赖切换：`agentscope.version`→2.0.x；core pom 按需加 redis/mysql/oss/skill-git 等 extension。确认 Java 21 运行时不变。 +2. 状态层：建 `AgentStateStoreResolver`，删 session 包，重写 `process()` 与 `HarnessAgentFactory`（单例 agent + RuntimeContext）。先跑通 NONE/JVM/LOCAL_FILE。 +3. 工具/权限：删自建工具，接 HarnessAgent 文件工具 + `execute` + `PermissionConfigMapper`。 +4. Skill：`SkillBoxFactory`→`skillRepository` + workspace skills + skill tracking middleware。 +5. Middleware：三个 Hook→middleware，保 `ctx.getChatUsage()`；`hooks()` 桥接 + `middlewares()`。 +6. 流式：`AgentEventBridge`，`stream()`→`streamEvents()`。 +7. 新能力：compaction/memory/plan-mode/tasklist/subagent/sandbox/interrupt 配置接入。 +8. 配置映射收口 + `@Deprecated` 告警 + 迁移文档（更新 `docs/liteflow-react-agent-guide.md`）。 +9. 测试（§15）。 + +## 15. 测试策略 + +- 测试统一放 `liteflow-testcase-el/` 子模块（遵守仓库规范），新增 `liteflow-testcase-react-agent` 或复用既有 agent 测试模块。 +- 关键用例： + - `(conversationId, agentKey)` 隔离与共享：同 conversation 不同 agentKey 记忆隔离、workspace 文件共享。 + - 5 种 `MemoryStorageMode`→store 映射（REDIS/MYSQL 用 testcontainer 或 mock bean）。 + - 文件工具/`execute` + Permission 白黑名单/禁用。 + - 流式 4 类 FlowEvent + HITL 透传。 + - compaction 长对话触发、plan-mode 门控、subagent 委派、interrupt 恢复。 + - 业务子类源码兼容（guide 里 DeepSeek 示例组件，预期零改动编译运行）。 + - 不改 `skipTests` 红线。 + +## 16. 风险与待验证项 + +- **R1（NONE 语义）**：HarnessAgent 默认 `JsonFileAgentStateStore`（持久），`MemoryStorageMode.NONE` 需显式注入"不落盘"store。待实现期确认 v2 是否提供 NoOp store，否则 liteflow 自写薄实现。**待验证**。 +- **R2（workspace 布局）**：HarnessAgent 单根 + 用户桶，与现有 `root//` 不兼容；老数据无法自动迁移。**待验证** IsolationScope=USER 时 `conversationId` 含特殊字符的命名安全。 +- **R3（subagent 事件 gap）**：`streamEvents()` 暂不转发子 agent 事件。**待验证** v2 后续修复点。 +- **R4（vendor model API）**：各 `XxxChatModel.builder()` 在 v2 的签名/包路径可能微调。**待实现期按 javadoc 核对**。 +- **R5（ChatUsage API）**：v2 message 上 `ChatUsage` 的取值点（middleware `onModelCall` 阶段）需核对，确保 `ctx.getChatUsage()` 累计语义不变。**待验证**。 +- **R6（Permission 与现有 ShellConfig 能力差）**：v2 Permission 按工具调用裁决，与 ManagedShellCommandTool 的"命令级白黑名单"粒度不同；可能需自定义 PermissionRule 做命令级校验以保等价。**待实现期评估**。 +- **R7（Java 版本）**：v2 运行时仍需 Java 21+，react-agent 已满足；确认 v2 无更高要求。**待验证**。 + +## 17. 参考文档 + +- AgentScope 2.0 迁移指南：https://java.agentscope.io/v2/zh/docs/change-log.html +- Harness 架构：https://java.agentscope.io/v2/en/docs/harness/architecture.html +- Workspace / Filesystem / Skill：https://java.agentscope.io/v2/en/docs/harness/{workspace,filesystem,skill}.html +- Agent 构建块：https://java.agentscope.io/v2/zh/docs/building-blocks/agent.html +- liteflow-react-agent 现有指南：`docs/liteflow-react-agent-guide.md`