From baf0b05e604e4b249312fcd2c4df6c219d1d6e24 Mon Sep 17 00:00:00 2001 From: slhafzjw Date: Sat, 28 Feb 2026 20:44:40 +0800 Subject: [PATCH] doc(framework): add KDoc for factory responsibilities and agent registration lifecycle --- .../partner/api/agent/factory/AgentBaseFactory.kt | 6 ++++++ .../api/agent/factory/AgentRegisterFactory.kt | 15 ++++++++++++++- .../CapabilityAnnotationValidatorFactory.kt | 9 +++++++++ .../capability/CapabilityInjectorFactory.kt | 6 ++++++ .../capability/CapabilityRegisterFactory.kt | 9 +++++++++ .../ComponentAnnotationValidatorFactory.kt | 8 ++++++++ .../component/ComponentInitHookExecutorFactory.kt | 7 ++++++- .../factory/component/ComponentInjectorFactory.kt | 10 ++++++++++ .../factory/component/ComponentRegisterFactory.kt | 8 ++++++++ .../agent/factory/config/ConfigLoaderFactory.kt | 9 ++++++--- .../context/ShutdownHookCollectorFactory.kt | 9 +++++++++ 11 files changed, 91 insertions(+), 5 deletions(-) diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentBaseFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentBaseFactory.kt index a7bc536c..fce23891 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentBaseFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentBaseFactory.kt @@ -2,6 +2,12 @@ package work.slhaf.partner.api.agent.factory import work.slhaf.partner.api.agent.factory.context.AgentRegisterContext +/** + * 所有注册链工厂的统一抽象。 + * + * 每个工厂接收同一个 [AgentRegisterContext]， + * 在其上完成单一阶段的扫描、校验、构建或注入。 + */ abstract class AgentBaseFactory { abstract fun execute(context: AgentRegisterContext) } diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentRegisterFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentRegisterFactory.kt index 5683511b..47406ae3 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentRegisterFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/AgentRegisterFactory.kt @@ -16,6 +16,20 @@ import work.slhaf.partner.api.agent.factory.exception.ExternalModulePathNotExist import java.io.File import java.net.URL +/** + * Agent 注册总入口，按固定顺序串联各 Factory。 + * + * 启动流程: + * 1. 加载配置 + * 2. 校验 Component 注解 + * 3. 注册 Component/Module + * 4. 完成 Module 注入 + * 5. 校验 Capability 注解 + * 6. 注册 Capability 代理与路由 + * 7. 注入 Capability + * 8. 执行 Init Hook + * 9. 收集 Shutdown Hook + */ object AgentRegisterFactory { private val urls: MutableList = mutableListOf() @@ -72,4 +86,3 @@ object AgentRegisterFactory { return ClasspathHelper.forPackage(packageName).toList() } } - diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityAnnotationValidatorFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityAnnotationValidatorFactory.kt index 5908b099..628d7632 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityAnnotationValidatorFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityAnnotationValidatorFactory.kt @@ -15,6 +15,15 @@ import work.slhaf.partner.api.agent.factory.context.AgentRegisterContext import work.slhaf.partner.api.agent.util.AgentUtil.isAssignableFromAnnotation import work.slhaf.partner.api.agent.util.AgentUtil.methodSignature +/** + * 校验 Capability 体系注解关系，并将扫描结果写入 `CapabilityFactoryContext`。 + * + * 当前规则: + * - `@Capability` 的 value 全局唯一。 + * - `@CapabilityMethod` 仅允许出现在 `@CapabilityCore` 类中。 + * - 每个 `@Capability` 接口方法必须在同 value 的 core 集合中存在且仅存在一个实现。 + * - `@InjectCapability` 字段仅允许位于 `@AgentComponent` 相关类中。 + */ class CapabilityAnnotationValidatorFactory : AgentBaseFactory() { override fun execute(context: AgentRegisterContext) { val reflections = context.reflections diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityInjectorFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityInjectorFactory.kt index 55ca7340..b90fc87b 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityInjectorFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityInjectorFactory.kt @@ -9,6 +9,12 @@ import work.slhaf.partner.api.agent.factory.context.AgentRegisterContext import java.lang.reflect.Field import java.lang.reflect.Modifier +/** + * 将 Capability 代理注入到 `@InjectCapability` 字段。 + * + * 注入目标来源于 `AgentContext` 的 modules 与 additionalComponents， + * 注入值来源于 `AgentContext.capabilities`。 + */ class CapabilityInjectorFactory : AgentBaseFactory() { override fun execute(context: AgentRegisterContext) { val agentContext = context.agentContext diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityRegisterFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityRegisterFactory.kt index 2caf4060..925fbfc9 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityRegisterFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/capability/CapabilityRegisterFactory.kt @@ -13,6 +13,15 @@ import java.lang.reflect.Method import java.lang.reflect.Proxy import java.util.function.Function +/** + * 基于 `CapabilityFactoryContext` 中已校验结果构建 Capability 运行时对象。 + * + * 行为: + * - 实例化所有 `@CapabilityCore`。 + * - 构建方法路由表（`value + methodSignature`）并检测重复路由。 + * - 为每个 `@Capability` 生成 JDK 动态代理，将接口调用路由到对应 core 方法。 + * - 将 capability 代理、cores 与方法映射注册到 `AgentContext`。 + */ class CapabilityRegisterFactory : AgentBaseFactory() { override fun execute(context: AgentRegisterContext) { val capabilityFactoryContext = context.capabilityFactoryContext diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentAnnotationValidatorFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentAnnotationValidatorFactory.kt index ef134499..ca7d043d 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentAnnotationValidatorFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentAnnotationValidatorFactory.kt @@ -9,6 +9,14 @@ import work.slhaf.partner.api.agent.factory.component.exception.ModuleCheckExcep import work.slhaf.partner.api.agent.factory.context.AgentRegisterContext import work.slhaf.partner.api.agent.util.AgentUtil +/** + * 校验 Component 层面的注解约束，并缓存 Init 方法扫描结果。 + * + * 当前规则: + * - `@Init` 仅能用于 `@AgentComponent` 相关类，且方法不能包含形参。 + * - `@InjectModule` 仅能用于 `@AgentComponent` 相关类，且字段类型不能是 Running 模块。 + * - 通过校验的 `@Init` 方法按声明类存入 `ComponentFactoryContext`。 + */ class ComponentAnnotationValidatorFactory : AgentBaseFactory() { override fun execute(context: AgentRegisterContext) { val reflections = context.reflections diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentInitHookExecutorFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentInitHookExecutorFactory.kt index 1cce77ab..521010da 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentInitHookExecutorFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentInitHookExecutorFactory.kt @@ -8,6 +8,12 @@ import work.slhaf.partner.api.agent.factory.context.AgentRegisterContext import work.slhaf.partner.api.agent.util.AgentUtil.methodSignature import java.lang.reflect.Method +/** + * 执行 Component 的 `@Init` 生命周期方法。 + * + * `@Init` 方法来源于 [work.slhaf.partner.api.agent.factory.context.ComponentFactoryContext]， + * 执行目标包括 modules 与 additionalComponents，按 `order` 升序执行。 + */ class ComponentInitHookExecutorFactory : AgentBaseFactory() { override fun execute(context: AgentRegisterContext) { val initMethodsByDeclaringType = context.componentFactoryContext.initMethodsByDeclaringType @@ -63,4 +69,3 @@ class ComponentInitHookExecutorFactory : AgentBaseFactory() { } } } - diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentInjectorFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentInjectorFactory.kt index 5c498861..310eb4ad 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentInjectorFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentInjectorFactory.kt @@ -8,6 +8,16 @@ import work.slhaf.partner.api.agent.factory.context.ModuleContextData import java.lang.reflect.Field import java.lang.reflect.Modifier +/** + * 处理 `@InjectModule` 依赖注入。 + * + * 注入关系: + * - `sub + standalone -> running` + * - `sub -> standalone` + * - `sub + standalone -> additionalComponent` + * + * 当注入目标无匹配实例或存在多个匹配实例时抛出异常。 + */ class ComponentInjectorFactory : AgentBaseFactory() { override fun execute(context: AgentRegisterContext) { val agentContext = context.agentContext diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentRegisterFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentRegisterFactory.kt index 172cfab8..87da252e 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentRegisterFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/component/ComponentRegisterFactory.kt @@ -16,6 +16,14 @@ import work.slhaf.partner.api.chat.pojo.Message import java.lang.reflect.Modifier import java.time.ZonedDateTime +/** + * 扫描并实例化 `@AgentComponent` 具体类，写入 [work.slhaf.partner.api.agent.factory.context.AgentContext]。 + * + * 行为: + * - 若实例是 [AbstractAgentModule]，按 Running/Sub/Standalone 构造 `ModuleContextData` 并注册到 modules。 + * - 若实现了 [ActivateModel]，必须存在对应 `modelPromptMap` 条目，随后构建 `modelInfo`。 + * - 若不是模块类型，尝试注册为 additional component（失败仅记录错误日志）。 + */ class ComponentRegisterFactory : AgentBaseFactory() { companion object { private val log = LoggerFactory.getLogger(ComponentRegisterFactory::class.java) diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/config/ConfigLoaderFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/config/ConfigLoaderFactory.kt index df0a0bf3..5f5c57de 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/config/ConfigLoaderFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/config/ConfigLoaderFactory.kt @@ -10,9 +10,13 @@ import work.slhaf.partner.api.agent.runtime.config.FileAgentConfigLoader import java.lang.reflect.Modifier /** - *

Agent启动流程 0

+ * Agent 启动阶段的配置加载工厂。 * - * 通过指定的 [AgentConfigLoader] 或默认的 [FileAgentConfigLoader] 加载配置文件。 + * 行为: + * - 使用全局 `AgentConfigLoader.INSTANCE`，为空时退回 [FileAgentConfigLoader]。 + * - 加载并写入 `modelConfigMap`、`modelPromptMap` 到 `ConfigFactoryContext`。 + * - 校验 `default` 配置与 `basic` 提示词是否存在。 + * - 反射读取配置加载器实现类（相对基类新增）的静态字段，并写入 `AgentContext.metadata`。 */ class ConfigLoaderFactory : AgentBaseFactory() { @@ -72,4 +76,3 @@ class ConfigLoaderFactory : AgentBaseFactory() { } } } - diff --git a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/context/ShutdownHookCollectorFactory.kt b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/context/ShutdownHookCollectorFactory.kt index 1ecbbe3d..b8a4229e 100644 --- a/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/context/ShutdownHookCollectorFactory.kt +++ b/Partner-Framework/src/main/java/work/slhaf/partner/api/agent/factory/context/ShutdownHookCollectorFactory.kt @@ -6,6 +6,15 @@ import work.slhaf.partner.api.agent.factory.component.annotation.AgentComponent import work.slhaf.partner.api.agent.factory.component.exception.ModuleCheckException import work.slhaf.partner.api.agent.util.AgentUtil +/** + * 校验并收集 `@Shutdown` 方法。 + * + * 当前规则: + * - `@Shutdown` 仅允许位于 `@AgentComponent` 相关类或 `@CapabilityCore` 相关类。 + * - `@Shutdown` 方法不能包含形参。 + * + * 收集通过后，统一调用 `AgentContext.addShutdownHook` 注册。 + */ class ShutdownHookCollectorFactory : AgentBaseFactory() { override fun execute(context: AgentRegisterContext) { val reflections = context.reflections