diff --git a/docs/superpowers/plans/2026-06-19-agentscope-v2-migration.md b/docs/superpowers/plans/2026-06-19-agentscope-v2-migration.md index 0096448e3..8d9357897 100644 --- a/docs/superpowers/plans/2026-06-19-agentscope-v2-migration.md +++ b/docs/superpowers/plans/2026-06-19-agentscope-v2-migration.md @@ -77,11 +77,66 @@ **Interfaces:** - Produces: `docs/superpowers/specs/v2-api-findings.md`，记录以下 5 项的**确认签名**（类全名 + 方法签名 + 行为），后续 Task 须引用此处结论。 -- [ ] **Step 1: 依赖先行（Task 1.1 提前到这里做最小版本）** +> **本 Task 是 green-commit 基底**：先删掉所有依赖 v2 已删类型的源码并 stub `process()`，使 `liteflow-react-agent-core` 对 v2 可编译；再跑探针、产出 findings。此后每个 Task 都保持可编译。**原 Task 1（依赖切换）内容已并入本 Task Step 1，Task 1 取消**，后续 Task 编号不变。 -编辑 `/Users/bryan31/openSource/LiteFlow-Jdk17/pom.xml`，把 `1.0.12` 改为已发布最新 `2.0.x`（查 Maven Central 取最新 patch）。仅改版本号，先不删旧 session 包（编译会大面积失败，本 Task 只跑一个隔离探针）。 +- [ ] **Step 1: 升级版本 + 声明扩展（合并原 Task 1）** -- [ ] **Step 2: 写探针测试，逐项验证** +编辑根 `/Users/bryan31/openSource/LiteFlow-Jdk17/pom.xml`，把 `1.0.12` 改为已发布最新 `2.0.x`（查 Maven Central 取最新 patch）。 +在 `liteflow-react-agent/liteflow-react-agent-core/pom.xml` 加扩展（全部 `true`）： + +```xml +io.agentscopeagentscope-extensions-redis${agentscope.version}true +io.agentscopeagentscope-extensions-mysql${agentscope.version}true +io.agentscopeagentscope-extensions-oss${agentscope.version}true +io.agentscopeagentscope-extensions-skill-git-repository${agentscope.version}true +``` +（artifactId/版本若与 Step 6 findings 不符，回填修正。） + +- [ ] **Step 2: 删除所有依赖 v2 已删类型的源码** + +```bash +git rm liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/AgentSessionManager.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/AgentSession.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/AgentSessionFactory.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/AgentSessionFactoryRegistry.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/InMemoryAgentSessionFactory.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/LocalFileAgentSessionFactory.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/RedisAgentSessionFactory.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/MysqlAgentSessionFactory.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/NoneAgentSessionFactory.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/tool/WorkspaceFileTools.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/tool/ManagedShellCommandTool.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/SkillBoxFactory.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/SkillToolResolver.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/SkillLoadResult.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/SkillTrackingHook.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/hook/ReActLoggingHook.java \ + liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/hook/ChatUsageTrackingHook.java +``` + +- [ ] **Step 3: stub `ReActAgentComponent` 使 core 编译通过** + +删除：`buildAgent()`、`streamAgent()`、`callAgent()`、`publishAgentEvent()`、`toFlowEventType()`、`AgentSessionManagerHolder`、`skillHookKey()`、`usedSkills()`，以及对上述已删类的全部引用。 +`process()` 改为： + +```java +@Override +public final void process() { + throw new AgentInvocationException( + "ReActAgentComponent v2 migration in progress; process() is rebuilt in Task 2.3"); +} +``` + +保留：抽象方法 `model()/systemPrompt()/userPrompt()`、受保护方法签名（`tools()/skills()/enableSkills()/agentKey()/resolveConversationId()/maxIterations()/handleReply(Msg)/buildModel()/effectiveSystemPrompt()/enableShellTool()/enableWorkspaceFileTools()/hooks()/enableReActLogging()`，方法体返回 `List.of()` 或读 `agentConfig()`）、`ctx()`/`ctxKey()`。 +`ReActAgentContext`：临时移除对 `ChatUsageTrackingHook` 的依赖，`getChatUsage()` 临时返回 `null`（Task 5.1 恢复）。 +清理 import：移除所有 `io.agentscope.core.session.*`、`InMemoryMemory`、`SkillBox`；`Hook` 类型在 v2 软弃用仍可编译，若 `hooks()` 签名用到则保留 import。 + +- [ ] **Step 4: 校验 core 编译（green commit 基底）** + +Run: `mvn -pl liteflow-react-agent/liteflow-react-agent-core -am clean compile 2>&1 | tail -30` +Expected: BUILD SUCCESS（core 对 v2 可编译；功能为 stub，端到端不可运行——预期，后续 Task 重建）。 + +- [ ] **Step 5: 写探针测试，逐项验证 R1/R4/R5/R6/R7** ```java package com.yomahub.liteflow.test.agent.v2spike; @@ -121,46 +176,31 @@ class V2ApiProbe { } ``` -注：每个方法体用反射或直接调用探查目标 API（如 `HarnessAgent.builder().name("x").sysPrompt("y").model(stubModel).build()` 看默认 stateStore），用 `assertions` 或打印记录确认结果。 +每个方法体用反射或直接调用探查目标 API（如 `HarnessAgent.builder().name("x").sysPrompt("y").model(stubModel).build()` 看默认 stateStore），用断言或打印记录确认结果。 -- [ ] **Step 3: 跑探针** +- [ ] **Step 6: 跑探针** Run: `mvn -pl liteflow-testcase-el/liteflow-testcase-el-react-agent -Dtest=V2ApiProbe -DfailIfNoTests=false test 2>&1 | tail -60` -（编译会因旧 session 包失败——见 Step 4 临时处置。） +Expected: 探针方法执行并打印/断言各 API 签名（core 已在 Step 4 可编译，探针可跑）。 -- [ ] **Step 4: 临时让 core 编译通过以运行探针** +- [ ] **Step 7: 写发现笔记** -为让探针能跑，临时把 `liteflow-react-agent-core` 里所有 import 了已删 `io.agentscope.core.session.*` 的类**整文件注释/临时移除**（仅本 Task 临时手段，Task 2 会正式删除）。最省事做法：把 `agent/session/**` 与 `agent/skill/SkillBoxFactory.java`、`agent/tool/**`、`agent/hook/**` 临时移到 core 外的 `_tmp_stash/`，并临时简化 `ReActAgentComponent`（注释掉 buildAgent 里用到它们的段落），使 core 编译通过。 +`docs/superpowers/specs/v2-api-findings.md` 记录 R1/R4/R5/R6/R7 的确认签名（类全名 + 方法签名 + 默认值 + 结论）。**后续每个 Task 凡用到这些 API，须与笔记核对；若笔记与计划代码冲突，以笔记为准并回填修正计划。** 若扩展 artifactId/版本与 Step 1 不符，回填修正 core pom。 -- [ ] **Step 5: 把确认结果写入发现笔记** - -`docs/superpowers/specs/v2-api-findings.md` 记录 R1/R4/R5/R6/R7 的确认签名（类全名 + 方法签名 + 默认值 + 结论）。**后续每个 Task 凡用到这些 API，须与笔记核对；若笔记与计划代码冲突，以笔记为准并回填修正计划。** - -- [ ] **Step 6: 还原临时改动，仅保留 findings + 版本号 + 探针** - -把 `_tmp_stash/` 移回（恢复 1.0 session 包，使仓库回到"仅版本号改了、探针+findings 新增"的可编译？不——版本号已升 v2，session 包会编译失败）。处理：本 Task 结束时**保留版本号升级与探针/findings，接受 core 暂不编译**，下一个 Task（Task 1/2）正是修复编译。commit 信息注明"WIP: v2 探针，core 暂不可编译"。 - -- [ ] **Step 7: Commit** +- [ ] **Step 8: Commit（green commit：core 可编译）** ```bash -git add docs/superpowers/specs/v2-api-findings.md \ - liteflow-testcase-el/liteflow-testcase-el-react-agent/src/test/java/com/yomahub/liteflow/test/agent/v2spike/V2ApiProbe.java \ - pom.xml -git commit -m "wip(agent): v2 API 探针与发现笔记 (R1/R4/R5/R6/R7)" +git add -A +git commit -m "refactor(agent): v2 绿编译基底（删 v2-broken 源码 + stub process）+ API 探针发现笔记" ``` --- ## Phase 1 — 依赖切换 -### Task 1: 升级 agentscope 版本与扩展依赖 +### Task 1: ~~升级 agentscope 版本与扩展依赖~~（已并入 Task 0，取消） -**Files:** -- Modify: `pom.xml`（根，`agentscope.version` + `dependencyManagement`） -- Modify: `liteflow-react-agent/liteflow-react-agent-core/pom.xml`（按需加 extensions） - -**Interfaces:** -- Produces: 构建期可用 `io.agentscope.core.*`（2.0.x）与按需扩展。 +> **取消说明：** 版本升级（根 `pom.xml`）与扩展依赖声明（core pom）已在 **Task 0 Step 1** 完成。本 Task 不再单独执行；直接进入 Task 2.1。 - [ ] **Step 1: 根 pom 设定版本** @@ -542,19 +582,11 @@ protected List hooks() { return List.of(); } Run: `mvn -pl liteflow-testcase-el/liteflow-testcase-el-react-agent -Dtest=StateIsolationTest test` Expected: PASS。 -- [ ] **Step 5: 删除旧 session 包** +- [ ] **Step 5: 验证 session 包已删除（Task 0 已删）** -```bash -git rm liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/AgentSessionManager.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/AgentSession.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/AgentSessionFactory.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/AgentSessionFactoryRegistry.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/InMemoryAgentSessionFactory.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/LocalFileAgentSessionFactory.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/RedisAgentSessionFactory.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/MysqlAgentSessionFactory.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/factory/NoneAgentSessionFactory.java -``` +session 包已在 **Task 0 Step 2** 删除。本步仅验证： +Run: `ls liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/session/ 2>&1` +Expected: 目录不存在（No such file or directory）。 - [ ] **Step 6: 编译 react-agent 全模块** @@ -642,12 +674,11 @@ static void configure(HarnessAgent.Builder b, ReActAgentComponent cmp, AgentConf - [ ] **Step 4: property 新增** `WorkspaceConfig.filesystemMode`（枚举 `FilesystemMode`，默认 `LOCAL`），`@ConfigurationProperties` 自动绑定 `filesystem-mode`。 -- [ ] **Step 5: 删除自建工具类** +- [ ] **Step 5: 验证自建工具类已删除（Task 0 已删）** -```bash -git rm liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/tool/WorkspaceFileTools.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/tool/ManagedShellCommandTool.java -``` +`WorkspaceFileTools`/`ManagedShellCommandTool` 已在 **Task 0 Step 2** 删除。本步仅验证： +Run: `ls liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/tool/ 2>&1` +Expected: 目录不存在或为空。 - [ ] **Step 6: 跑测试 + 编译** — `mvn ... -Dtest=FilesystemModeTest test` → PASS；`mvn -pl liteflow-react-agent/liteflow-react-agent-core -am compile` → 通过。 @@ -678,14 +709,11 @@ git commit -m "refactor(agent): 删除自建文件/shell 工具，采用 Harness - [ ] **Step 3: 实现 `SkillRepositoryResolver`**——默认把 `skills.path` 作为 workspace skills 目录（HarnessAgent 原生扫描），可选 `.skillRepository(new ClasspathSkillRepository(...))` 等（依 findings）。`enableSkills()==false` 时 `.dynamicSkillsEnabled(false)`。`skills()` 非空 → `.skillFilter(...)`。 -- [ ] **Step 4: 删除旧 skill 类** +- [ ] **Step 4: 验证旧 skill 类已删除（Task 0 已删）** -```bash -git rm liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/SkillBoxFactory.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/SkillToolResolver.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/SkillLoadResult.java \ - liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/SkillTrackingHook.java -``` +`SkillBoxFactory`/`SkillToolResolver`/`SkillLoadResult`/`SkillTrackingHook` 已在 **Task 0 Step 2** 删除。本步仅验证： +Run: `ls liteflow-react-agent/liteflow-react-agent-core/src/main/java/com/yomahub/liteflow/agent/skill/ 2>&1` +Expected: 目录不存在或为空（`SkillRepositoryResolver` 在 Step 3 新建）。 - [ ] **Step 5: 跑测试 + 编译** → PASS / 通过。