doc(framework): add KDoc for factory responsibilities and agent registration lifecycle

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)
 }

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<URL> = mutableListOf()
 
@@ -72,4 +86,3 @@ object AgentRegisterFactory {
         return ClasspathHelper.forPackage(packageName).toList()
     }
 }
-

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

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

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

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

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() {
         }
     }
 }
-

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

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)

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
 
 /**
- * <h2>Agent启动流程 0</h2>
+ * Agent 启动阶段的配置加载工厂。
  *
- * 通过指定的 [AgentConfigLoader] 或默认的 [FileAgentConfigLoader] 加载配置文件。
+ * 行为:
+ * - 使用全局 `AgentConfigLoader.INSTANCE`，为空时退回 [FileAgentConfigLoader]。
+ * - 加载并写入 `modelConfigMap`、`modelPromptMap` 到 `ConfigFactoryContext`。
+ * - 校验 `default` 配置与 `basic` 提示词是否存在。
+ * - 反射读取配置加载器实现类（相对基类新增）的静态字段，并写入 `AgentContext.metadata`。
  */
 class ConfigLoaderFactory : AgentBaseFactory() {
 
@@ -72,4 +76,3 @@ class ConfigLoaderFactory : AgentBaseFactory() {
             }
     }
 }
-

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