From 3c9ace8e5657029ce2aa734fb1f1e87d28477911 Mon Sep 17 00:00:00 2001
From: slhafzjw <slhafzjw@slhaf.work>
Date: Sat, 21 Feb 2026 16:19:00 +0800
Subject: [PATCH] refactor(framework): rename `CapabilityHolder` to
 `AgentComponent` across factory and module hooks

---
 .../CapabilityHolder.java => AgentComponent.java}        | 4 ++--
 .../agent/factory/capability/CapabilityCheckFactory.java | 9 +++++----
 .../factory/capability/CapabilityRegisterFactory.java    | 3 ++-
 .../factory/capability/annotation/InjectCapability.java  | 4 +++-
 .../api/agent/factory/module/abstracts/AgentModule.kt    | 4 ++--
 .../api/agent/factory/module/annotation/Init.java        | 5 +++++
 .../agent/factory/module/annotation/InjectModule.java    | 5 +++++
 7 files changed, 24 insertions(+), 10 deletions(-)
 rename Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/{capability/annotation/CapabilityHolder.java => AgentComponent.java} (50%)

diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/annotation/CapabilityHolder.java b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentComponent.java
similarity index 50%
rename from Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/annotation/CapabilityHolder.java
rename to Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentComponent.java
index 4ed0f477..54a9db14 100644
--- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/annotation/CapabilityHolder.java
+++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentComponent.java
@@ -1,9 +1,9 @@
-package work.slhaf.partner.api.agent.factory.capability.annotation;
+package work.slhaf.partner.api.agent.factory;
 
 import java.lang.annotation.*;
 
 @Inherited
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
-public @interface CapabilityHolder {
+public @interface AgentComponent {
 }
diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityCheckFactory.java b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityCheckFactory.java
index 9b205b4a..ead1480a 100644
--- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityCheckFactory.java
+++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityCheckFactory.java
@@ -3,6 +3,7 @@ package work.slhaf.partner.api.agent.factory.capability;
 import cn.hutool.core.util.ClassUtil;
 import org.reflections.Reflections;
 import work.slhaf.partner.api.agent.factory.AgentBaseFactory;
+import work.slhaf.partner.api.agent.factory.AgentComponent;
 import work.slhaf.partner.api.agent.factory.capability.annotation.*;
 import work.slhaf.partner.api.agent.factory.capability.exception.*;
 import work.slhaf.partner.api.agent.factory.context.AgentRegisterContext;
@@ -40,7 +41,7 @@ import static work.slhaf.partner.api.agent.util.AgentUtil.methodSignature;
  *     </li>
  *     <li>
  *         <p>{@link CapabilityCheckFactory#checkInjectCapability()}</p>
- *         检查 {@link InjectCapability} 注解是否只用在 {@link CapabilityHolder} 所标识类的字段上。{@link AgentRunningModule} 与 {@link AgentSubModule} 已经被 {@link CapabilityHolder} 标注
+ *         检查 {@link InjectCapability} 注解是否只用在 {@link AgentComponent} 所标识类的字段上。{@link AgentRunningModule} 与 {@link AgentSubModule} 已经被 {@link AgentComponent} 标注
  *     </li>
  * </ol>
  *
@@ -92,13 +93,13 @@ public class CapabilityCheckFactory extends AgentBaseFactory {
     }
 
     /**
-     * 检查<code>@InjectCapability</code>注解是否只用在<code>@CapabilityHolder</code>所标识类的字段上
+     * 检查<code>@InjectCapability</code>注解是否只用在<code>@AgentComponent</code>所标识类的字段上
      */
     private void checkInjectCapability() {
         reflections.getFieldsAnnotatedWith(InjectCapability.class).forEach(field -> {
             Class<?> declaringClass = field.getDeclaringClass();
-            if (!isAssignableFromAnnotation(declaringClass, CapabilityHolder.class)) {
-                throw new UnMatchedCapabilityException("InjectCapability 注解只能用于 CapabilityHolder 注解所在类，检查该类是否使用了@CapabilityHolder注解或者受其标注的注解或父类: " + declaringClass);
+            if (!isAssignableFromAnnotation(declaringClass, AgentComponent.class)) {
+                throw new UnMatchedCapabilityException("InjectCapability 注解只能用于 AgentComponent 注解所在类，检查该类是否使用了@CapabilityHolder注解或者受其标注的注解或父类: " + declaringClass);
             }
         });
     }
diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityRegisterFactory.java b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityRegisterFactory.java
index fd674f03..cfbed1fe 100644
--- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityRegisterFactory.java
+++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityRegisterFactory.java
@@ -3,6 +3,7 @@ package work.slhaf.partner.api.agent.factory.capability;
 import cn.hutool.core.util.ClassUtil;
 import org.reflections.Reflections;
 import work.slhaf.partner.api.agent.factory.AgentBaseFactory;
+import work.slhaf.partner.api.agent.factory.AgentComponent;
 import work.slhaf.partner.api.agent.factory.capability.annotation.*;
 import work.slhaf.partner.api.agent.factory.capability.exception.CapabilityCoreInstancesCreateFailedException;
 import work.slhaf.partner.api.agent.factory.capability.exception.CapabilityFactoryExecuteFailedException;
@@ -86,7 +87,7 @@ public class CapabilityRegisterFactory extends AgentBaseFactory {
     }
 
     private void setCapabilityHolderInstances() {
-        Set<Class<?>> collect = reflections.getTypesAnnotatedWith(CapabilityHolder.class).stream()
+        Set<Class<?>> collect = reflections.getTypesAnnotatedWith(AgentComponent.class).stream()
                 .filter(ClassUtil::isNormalClass)
                 .filter(clazz -> !capabilityHolderInstances.containsKey(clazz))
                 .collect(Collectors.toSet());
diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/annotation/InjectCapability.java b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/annotation/InjectCapability.java
index 51bf991d..2a565863 100644
--- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/annotation/InjectCapability.java
+++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/annotation/InjectCapability.java
@@ -1,12 +1,14 @@
 package work.slhaf.partner.api.agent.factory.capability.annotation;
 
+import work.slhaf.partner.api.agent.factory.AgentComponent;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * 用于注入`Capability`
+ * 用于注入`Capability`,适用于{@link AgentComponent} 实例
  */
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/abstracts/AgentModule.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/abstracts/AgentModule.kt
index daa7dddb..d631d6b6 100644
--- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/abstracts/AgentModule.kt
+++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/abstracts/AgentModule.kt
@@ -2,7 +2,7 @@ package work.slhaf.partner.api.agent.factory.module.abstracts
 
 import org.slf4j.Logger
 import org.slf4j.LoggerFactory
-import work.slhaf.partner.api.agent.factory.capability.annotation.CapabilityHolder
+import work.slhaf.partner.api.agent.factory.AgentComponent
 import work.slhaf.partner.api.agent.factory.module.annotation.Init
 import work.slhaf.partner.api.agent.runtime.config.AgentConfigManager
 import work.slhaf.partner.api.agent.runtime.interaction.flow.entity.RunningFlowContext
@@ -14,7 +14,7 @@ import work.slhaf.partner.api.chat.pojo.Message
 /**
  * 模块基类
  */
-@CapabilityHolder
+@AgentComponent
 sealed class AbstractAgentModule {
 
     var moduleName: String = javaClass.simpleName
diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/annotation/Init.java b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/annotation/Init.java
index b7c936a0..a7a1ce70 100644
--- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/annotation/Init.java
+++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/annotation/Init.java
@@ -1,10 +1,15 @@
 package work.slhaf.partner.api.agent.factory.module.annotation;
 
+import work.slhaf.partner.api.agent.factory.AgentComponent;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * 初始化 Hook，适用于{@link AgentComponent} 实例
+ */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.METHOD)
 public @interface Init {
diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/annotation/InjectModule.java b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/annotation/InjectModule.java
index 42754970..cd99cf4e 100644
--- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/annotation/InjectModule.java
+++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/module/annotation/InjectModule.java
@@ -1,10 +1,15 @@
 package work.slhaf.partner.api.agent.factory.module.annotation;
 
+import work.slhaf.partner.api.agent.factory.AgentComponent;
+
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ * 模块注入 Hook，适用于{@link AgentComponent} 实例
+ */
 @Target(ElementType.FIELD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface InjectModule {