Partner/doc/architecture/startup.md

Agent 启动流程

本文说明 Agent.newAgent(appClass).launch() 的外层启动顺序。

AgentApp.launch() 负责拉起基础单例、构建扫描上下文、执行启动前扩展、注册配置参与者、注册 Gateway、安装关闭钩子，并把最终 AgentRegisterContext 交给注册工厂。组件扫描、模块实例化和能力注册的细节见 注册链。

启动前扩展：AgentBootstrap

Agent.AgentBootstrap 是启动前扩展点。它会在正式组件注册链执行前被扫描、实例化并执行 boot()。

Bootstrap 实现类需要继承 Agent.AgentBootstrap，并提供 Agent.AgentApp 构造器：

public final class PartnerAgentBootstrap extends Agent.AgentBootstrap {

    public PartnerAgentBootstrap(Agent.AgentApp agentApp) {
        super(agentApp);
    }

    @Override
    protected void bootstrap() {
        addGatewayRegistration(WebSocketGatewayRegistration.INSTANCE);
        addConfigurable(new VectorClientRegistry());
    }
}

Bootstrap 可用于声明启动前基础设施扩展：

• addGatewayRegistration(...)
• addConfigurable(...)
• addExceptionReporter(...)
• addPreShutdownHook(...)
• addPostShutdownHook(...)
• addScanPackage(...)
• addScanDir(...)

Bootstrap 按 order() 升序执行，默认 order() 为 0。

外层启动顺序

flowchart TD
    A["Agent.newAgent(appClass).launch()"] --> B["加载基础单例<br/>ConfigCenter / StateCenter"]

    B --> C["准备基础扫描范围"]

    subgraph C["基础扫描范围"]
        direction TB
        C1["application package"]
        C2["外部模块目录<br/>resources/module/*.jar"]
    end

    C --> D["构建 bootstrap AgentRegisterContext"]
    D --> E["扫描 AgentBootstrap"]
    E --> F["实例化并执行 bootstrap()"]

    F --> G["Bootstrap 扩展 AgentApp"]

    subgraph G["Bootstrap 可扩展内容"]
        direction TB
        G1["GatewayRegistration"]
        G2["Configurable"]
        G3["ExceptionReporter"]
        G4["pre/post shutdown hook"]
        G5["scan package / scan dir"]
    end

    G --> H["重建最终 AgentRegisterContext"]

    H --> I["注册 ExceptionReporter"]

    I --> J

    subgraph J["注册 Configurable"]
        direction TB
        J1["LogAdviceProvider.register()"]
        J2["ModelRuntimeRegistry.register()"]
        J3["AgentGatewayRegistry.register()"]
        J4["Bootstrap / 应用声明的 Configurable.register()"]
    end

    J --> K["注册 AgentGatewayRegistration"]

    K --> L

    subgraph L["注册关闭钩子"]
        direction TB
        L1["preShutdown<br/>AgentGatewayRegistry.close()"]
        L2["Bootstrap / 应用声明的 preShutdown hooks"]
        L3["postShutdown<br/>StateCenter.save()"]
        L4["postShutdown<br/>TraceSinkRegistry.close()"]
        L5["postShutdown<br/>ConfigCenter.close()"]
        L6["Bootstrap / 应用声明的 postShutdown hooks"]
        L1 --> L2
        L3 --> L4 --> L5 --> L6
    end

    L --> M["启动注册工厂<br/>AgentRegisterFactory.launch(registerContext)"]

    M --> N

    subgraph N["初始化配置系统"]
        direction TB
        N1["ConfigCenter.initAll()<br/>初始化已注册的 Configurable"]
        N2["触发各 Configurable.init(config, json)"]
        N3["ConfigCenter.start()<br/>启动配置监听"]
        N1 --> N2 --> N3
    end

    N --> O["Agent 启动完成"]

扫描上下文

AgentApp 现在负责维护扫描输入并构建 AgentRegisterContext。

默认扫描输入包括：

• applicationClass.getPackageName() 对应的 classpath package URL
• ConfigCenter.INSTANCE.getPaths().getResourcesDir().resolve("module") 下的 *.jar

启动时会构建两次扫描上下文：

1. bootstrap context：用于发现 AgentBootstrap。
2. final register context：在 AgentBootstrap.boot() 可能追加 scan package / scan dir 后重建，用于后续 AgentRegisterFactory.launch(registerContext)。

AgentRegisterFactory 现在只负责执行注册链。它接收已经构建好的 AgentRegisterContext，不再是主启动链路里扫描上下文的拥有者。旧的 launch(packageName) 仍可作为兼容入口使用。

Gateway 启动时机

Gateway 的实际 launch() 不在 AgentGatewayRegistration.register() 中直接发生。Gateway registration 只把可用通道注册到 AgentGatewayRegistry；真正的通道创建、启动和默认响应通道设置发生在 ConfigCenter.initAll() 阶段，由 AgentGatewayRegistry.init() 根据 gateway.json 执行。