[Roadmap] ARGI Extensions 独立扩展架构与实现重设计 #30

当前架构决策：Workflow 独立执行，Graph 抽离为 Loop

用户已确认：Workflow 通过定义创建并独立执行，不依赖 Graph/Loop；非 Workflow Agent 同样独立执行。原 Graph 抽离为独立能力并命名为 Loop，通用身份、预算、运行管理和共享契约不因抽离而成为 Loop 专属。

• Workflow 定义、解析、执行与 Workflow Agent：#197。
• Loop 独立能力与命名/依赖迁移：[Architecture][CR-15] 将 Graph 抽离为独立 Loop 能力并完成命名与依赖迁移 argi#198 。
• Loop 保留图执行语义；它与 Workflow 循环步骤、LoopAgent 和 ReAct 内部循环必须区分。公共类、包、坐标及数据字段按映射迁移，不做无差别替换。
• 可选桥接由 Loop 集成侧依赖中立 Agent 契约；Workflow 不以 Loop 为默认后端。破坏性变更仍逐项论证，历史数据遵守 #182。

本节替代早期“Graph 承载 Workflow”或“Graph 名称整体保留”的架构假设；历史路径和类名仍作为问题证据。

设计约束：以收益决定变更，破坏性变更需逐项论证

用户明确：技术独立是目标，改动幅度和破坏性不是目标。合理的现有概念、API、模块和实现可以保留；不能因为来自上游就要求删除、重命名或重写。新 API 包装旧引擎若只是表面换名不能证明技术独立，但也不以“零旧代码”作为验收指标。

每项破坏性变更在实施前必须完成以下决策记录：

• 具体问题：现状如何影响职责、正确性、扩展性、依赖隔离或使用体验，附代码/用例/测试证据。
• 方案比较：至少比较保留现状或兼容演进与破坏性调整，说明为何较小改动不足以解决问题。
• 收益与成本：列出预期收益、受影响 API/消费者/配置/数据/观测、迁移工作量及回归风险；只有收益足以覆盖成本才采用破坏性方案。
• 迁移与验证：明确目标版本、旧→新映射、升级步骤、必要的兼容期限或不兼容理由、回滚条件及有意义的行为验收。
• 评审结论：记录采用、保留或推迟及理由；未形成结论前不实施对应破坏性调整。

不为追求与上游形式不同而修改成熟设计，不机械加前缀、迁包、拆模块或替换行业通用术语。技术独立通过自主架构决策、清晰契约、可控依赖和独立演进能力评估；重写仅用于解决已证实且值得付出迁移成本的问题。

本节是后续明确的约束；若下文历史规划含有无条件重写、删除旧路径或仅因上游来源而替换的表述，按本节执行并在设计阶段修订。

范围调整：以可自主演进的架构和实现为目标

用户进一步明确：本系列应进行大幅重设计，摆脱原仓库架构、API 与实现路径的约束。仅替换品牌、包名或为旧类型增加包装不算完成。允许破坏性变更、删除旧 API、重组模块与重写实现；具体方案由目标架构决定。

新增架构主线：agentic-ai-java/argi#186

执行要求：CR-01 提供基线与领域输入；CR-11 定义独立目标架构并拆分能力重写任务；CR-02 确定数据导出/转换/不支持策略；CR-03 至 CR-09 按新架构重新确定各自职责和实施范围，不再以最小改名为目标；CR-10 验证新体系可独立消费并收口旧实现退场。数据契约设计可提前推进，实际替换需等待目标架构确定。

原有条目是现状证据和候选问题，不构成必须沿用的架构约束。旧 API 兼容层不作为默认要求；过渡方案必须明确删除条件。已有代码的来源、版权及历史事实如实保留，不以大改宣称严格 clean-room 独立实现。

原始审查与任务清单（按上述新目标执行）

背景与目标

承接已合并的品牌迁移 #4，对 Extensions 的包名、类名、模块和配置/观测标识进行 Clear Room 设计梳理：从扩展能力及适配目标重新定义职责，再确定命名，避免无差别替换 Alibaba、Spring AI、Nacos 或 ARMS 等合理名称。

这里的 Clear Room 指按当前需求重新设计，不宣称既有迁移代码是独立 clean-room 实现。Core 的统一术语和边界设计将在关联 issue 中跟踪。

迁移来源与对照要求

用户确认的原始仓库：

• Core：https://github.com/alibaba/spring-ai-alibaba
• Extensions：https://github.com/spring-ai-alibaba/spring-ai-extensions

实施前记录实际迁移基点（commit/tag）；上游当前 main 不能直接视为迁移时版本。对照表需区分“上游继承的命名”“本项目迁移后引入的不一致”“应保留的第三方产品/协议名称”，记录原始与当前路径、职责及目标设计。当前审查结论来自本地工程，尚未完成基于迁移基点的逐文件上游比对；不得将候选问题直接认定为上游缺陷。

已核实的基线与问题

审查提交：495414b76a37aca4d7c1022d973a8e5b9a7e92e6。

包名前缀、主要 Maven artifact 与配置前缀已使用 io.github.agentic.ai、argi-*、argi.*。后续重点是语义一致性和残留标识，而非重新品牌迁移。

以上为代码审查发现与候选方向；未认定所有现有名称都必须变更。

交付步骤

• 输出全量命名清单：Java FQCN、artifact、配置键、自动配置类/Bean、SPI/反射/资源、观测属性、缓存键/数据格式；逐项写明保留或目标名、原因、消费者与风险。
• 与 Core 统一术语和依赖边界；维持 Extensions 按需集成定位，不将厂商 SDK 引回 Core。
• 将自有产品标识、第三方产品/协议、历史数据标识、来源/版权记录分类；为扫描门禁建立带理由的例外表。
• 优先评审 MCP 注册命名、观测职责与品牌值，再处理配置类、memory 包和契约模块边界；按能力拆分可独立验证的实施任务。
• 对每个公共改名明确破坏性替换或限期兼容策略和发布版本；同步 BOM、Starter、AutoConfiguration.imports、配置元数据、README、examples、website。
• 若迁移数据键或序列化类型，提供旧格式 fixture、迁移/拒绝策略及回滚约束；配置和观测变化提供旧→新映射。

验收标准

• 上述发现均有设计结论，所有变更可追溯到领域职责，未机械添加 Argi 或删除厂商标识。
• 自动配置上下文测试覆盖启用/禁用、Bean 装配、属性绑定和 imports；必要时验证 SPI/反射加载。
• 核查观测输出的 framework、span/metric 名与属性，给出受影响 dashboard/告警迁移说明。
• 修改的 MCP、memory、prompt 等能力完成对应行为回归；依赖外部服务的测试明确实际执行环境与结果。
• reactor/BOM/Starter 构建及独立消费者示例通过，跨仓改动有明确跟踪链接。
• 命名扫描对历史自有标识防回归；Nacos、ARMS、Spring AI、真实厂商 SDK 坐标及来源记录可按职责保留。

不重复实施已合并品牌迁移；不把已有 A2A SDK 升级 #25、MCP 行为修复 #24 或其他运行时功能任务混入本命名改造。

本 issue 是设计与实施跟踪单，当前未修改源码或运行构建；目标命名和兼容策略需在设计阶段确定。

关联 Core 设计：agentic-ai-java/argi#180

子任务与执行顺序

本 issue 保留为总览，实施与验收在以下子任务跟踪。勾选代表子任务验收完成，建单不代表实施完成。

• [Clear Room][CR-05] 统一 MCP 注册职责与 registry、registrar、registration 命名 #31 — [Clear Room][CR-05] 统一 MCP 注册职责与 registry、registrar、registration 命名
• [Clear Room][CR-06] 分清通用工具观测与 ARMS 适配并统一框架标识 #32 — [Clear Room][CR-06] 分清通用工具观测与 ARMS 适配并统一框架标识
• [Clear Room][CR-07] 明确 Nacos Prompt 配置类命名并校验装配兼容 #33 — [Clear Room][CR-07] 明确 Nacos Prompt 配置类命名并校验装配兼容
• [Clear Room][CR-08] 统一聊天记忆契约与存储适配的包层级 #34 — [Clear Room][CR-08] 统一聊天记忆契约与存储适配的包层级
• [Clear Room][CR-09] 评估并明确 Document 与 Rerank 契约模块边界 #35 — [Clear Room][CR-09] 评估并明确 Document 与 Rerank 契约模块边界

执行顺序：CR-01 统一基线与决策 → CR-02 明确数据迁移契约 → CR-03/04/08 实施涉及公共类型或数据的调整；CR-05/06/07/09 在 CR-01 完成后可分别推进。CR-10 最终汇总两仓发布验收。相同文件或公共 API 的调整顺序合并。

共享前置：https://github.com/agentic-ai-java/argi/issues/181；数据迁移：https://github.com/agentic-ai-java/argi/issues/182；发布收口：https://github.com/agentic-ai-java/argi/issues/185。

当前代码优化任务

• [BUG][OPT-01] MCP 服务精确查询与删除不应依赖向量 Top-1 检索 #36 — [BUG][OPT-01] MCP 服务精确查询与删除不应依赖向量 Top-1 检索
• [BUG][OPT-02] MCP 刷新应避免先删后查及单服务缺失中断整轮 #37 — [BUG][OPT-02] MCP 刷新应避免先删后查及单服务缺失中断整轮
• [Design][CR-02/OPT-05] 明确 checkpoint 协议、类型解耦与历史数据迁移契约 argi#182 — OPT-05：checkpoint 协议与 Java 类型解耦（复用 CR-02）。

跨仓存储归属任务：https://github.com/agentic-ai-java/argi/issues/190。

顺序：优先 MCP 正确性与后台资源策略；再推进状态/数据契约、存储边界与工具内部重构。局部正确性修复不等待整体架构重写。

第二轮代码优化：Studio 与动态 Prompt

• [Design][OPT-10] 明确动态 Prompt 引用契约并修复旧引用不更新 #38 — [Design][OPT-10] 明确动态 Prompt 引用契约并修复旧引用不更新
• [Design][OPT-11] 定义 Nacos Prompt 批次更新校验与发布边界 #39 — [Design][OPT-11] 定义 Nacos Prompt 批次更新校验与发布边界
• [Enhancement][OPT-13] 调整动态 Prompt 日志以避免默认输出正文和变量 #40 — [Enhancement][OPT-13] 调整动态 Prompt 日志以避免默认输出正文和变量

先处理错误传输和会话一致性；Prompt 引用与批次契约协调推进；性能任务先测量再决定是否修改协议。

框架边界关联

通用运行契约：agentic-ai-java/argi#200

声明式能力包及 Nacos 公开扩展迁移：agentic-ai-java/argi#202

统一定义与版本发布：agentic-ai-java/argi#199

上述任务在 Core 统一契约，Extensions 适配实现与发布需跟随，不在本总览重复建同目标任务。