docs: 添加 liteflow-react-agent AgentScope 2.0 迁移设计文档

基于 HarnessAgent 全家桶路线、保留并映射现有 liteflow.agent.* 配置键、一次到位接通全部增强能力的迁移设计评审稿。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-19 21:36:31 +08:00 · 2026-06-19 21:36:31 +08:00 · 6143229255
parent 0892cc6620
commit 6143229255
1 changed files with 313 additions and 0 deletions
--- a/docs/superpowers/specs/2026-06-19-agentscope-v2-migration-design.md
+++ 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<SELF>` 抽象 + 各 vendor `XxxSpec/XxxModelFactory/入口类`，`resolve(AgentConfig)` 从配置取凭据、装配 `GenerateOptions`、构造 `Model`。
+- 流式：`agent.stream(List<Msg>, StreamOptions)` → `Flux<Event>`，映射 `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/`（共享）与 `<userId>/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<AgentEvent>`，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/<conversationId>/`（每会话一目录）"改为 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/<id>/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.<name>.*`） | `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<Hook>` | 保留方法签名作兼容桥（内部 `LegacyHookDispatcher` 转 middleware），新增 `middlewares()` 返回 `List<MiddlewareBase>` 鼓励迁移；`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<AgentEvent>`。
+- `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/<conversationId>/` 不兼容；老数据无法自动迁移。**待验证** 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`