mirror of https://gitee.com/dromara/liteFlow
docs: 修订迁移计划 Task 0 为绿编译基底，Task 1 并入取消
按 pre-flight 决策：Task 0 先删 v2-broken 源码 + stub process 使 core 对 v2 可编译， 保证此后每次提交可编译、reviewer 可跑编译/测试；Tasks 2.3/3.2/4.1 的删除步骤改为验证。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
everywhere.z
parent
8954412e93
commit
e3220a4977
|
|
@ -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`，把 `<agentscope.version>1.0.12</agentscope.version>` 改为已发布最新 `2.0.x`（查 Maven Central 取最新 patch）。仅改版本号，先不删旧 session 包（编译会大面积失败，本 Task 只跑一个隔离探针）。
|
||||
- [ ] **Step 1: 升级版本 + 声明扩展（合并原 Task 1）**
|
||||
|
||||
- [ ] **Step 2: 写探针测试，逐项验证**
|
||||
编辑根 `/Users/bryan31/openSource/LiteFlow-Jdk17/pom.xml`，把 `<agentscope.version>1.0.12</agentscope.version>` 改为已发布最新 `2.0.x`（查 Maven Central 取最新 patch）。
|
||||
在 `liteflow-react-agent/liteflow-react-agent-core/pom.xml` 加扩展（全部 `<optional>true</optional>`）：
|
||||
|
||||
```xml
|
||||
<dependency><groupId>io.agentscope</groupId><artifactId>agentscope-extensions-redis</artifactId><version>${agentscope.version}</version><optional>true</optional></dependency>
|
||||
<dependency><groupId>io.agentscope</groupId><artifactId>agentscope-extensions-mysql</artifactId><version>${agentscope.version}</version><optional>true</optional></dependency>
|
||||
<dependency><groupId>io.agentscope</groupId><artifactId>agentscope-extensions-oss</artifactId><version>${agentscope.version}</version><optional>true</optional></dependency>
|
||||
<dependency><groupId>io.agentscope</groupId><artifactId>agentscope-extensions-skill-git-repository</artifactId><version>${agentscope.version}</version><optional>true</optional></dependency>
|
||||
```
|
||||
（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<Hook> 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 / 通过。
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue