diff --git a/doc/architecture/register-chain.md b/doc/architecture/register-chain.md
index e1caa608..b0284155 100644
--- a/doc/architecture/register-chain.md
+++ b/doc/architecture/register-chain.md
@@ -1,13 +1,13 @@
# Agent 注册链
-本文说明 `AgentRegisterFactory.launch(packageName)` 内部的注册链。注册链的职责是基于应用包与外部模块目录扫描结果，完成组件、模块、Capability、生命周期方法和关闭方法的注册。
+本文说明 `AgentRegisterFactory.launch(registerContext)` 内部的注册链。注册链的职责是基于启动层已经构建好的 `AgentRegisterContext`，完成组件、模块、Capability、生命周期方法和关闭方法的注册。
`AgentRegisterContext` 是注册链上下文。它持有 `Reflections` 扫描器，以及供各阶段读写的 `ComponentFactoryContext`、`CapabilityFactoryContext` 和全局 `AgentContext`。
```mermaid
flowchart TD
- A["AgentRegisterFactory.launch(packageName)"] --> B["packageNameToURL(packageName)"]
- B --> C["创建 AgentRegisterContext"]
+ A["AgentApp.launch()"] --> B["构建最终 AgentRegisterContext"]
+ B --> C["AgentRegisterFactory.launch(registerContext)"]
subgraph CTX["AgentRegisterContext"]
direction TB
diff --git a/doc/architecture/startup.md b/doc/architecture/startup.md
index b208edd7..e892d3ba 100644
--- a/doc/architecture/startup.md
+++ b/doc/architecture/startup.md
@@ -2,54 +2,131 @@
本文说明 `Agent.newAgent(appClass).launch()` 的外层启动顺序。
-`Agent.launch()` 负责拉起基础单例、注册配置参与者、注册 Gateway、安装关闭钩子、添加外部模块目录，并启动注册工厂。组件扫描、模块实例化和能力注册的细节见 [注册链](register-chain.md)。
+`AgentApp.launch()` 负责拉起基础单例、构建扫描上下文、执行启动前扩展、注册配置参与者、注册 Gateway、安装关闭钩子，并把最终 `AgentRegisterContext` 交给注册工厂。组件扫描、模块实例化和能力注册的细节见 [注册链](register-chain.md)。
+
+## 启动前扩展：AgentBootstrap
+
+`Agent.AgentBootstrap` 是启动前扩展点。它会在正式组件注册链执行前被扫描、实例化并执行 `boot()`。
+
+Bootstrap 实现类需要继承 `Agent.AgentBootstrap`，并提供 `Agent.AgentApp` 构造器：
+
+```java
+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`。
+
+## 外层启动顺序
```mermaid
flowchart TD
A["Agent.newAgent(appClass).launch()"] --> B["加载基础单例
ConfigCenter / StateCenter"]
- B --> C["注册 ExceptionReporter"]
+ B --> C["准备基础扫描范围"]
- C --> D
-
- subgraph D["注册 Configurable"]
+ subgraph C["基础扫描范围"]
direction TB
- D1["LogAdviceProvider.register()"]
- D2["ModelRuntimeRegistry.register()"]
- D3["AgentGatewayRegistry.register()"]
- D4["应用传入的 Configurable.register()"]
+ C1["application package"]
+ C2["外部模块目录
resources/module/*.jar"]
end
- D --> E["注册 AgentGatewayRegistration"]
+ C --> D["构建 bootstrap AgentRegisterContext"]
+ D --> E["扫描 AgentBootstrap"]
+ E --> F["实例化并执行 bootstrap()"]
- E --> F
+ F --> G["Bootstrap 扩展 AgentApp"]
- subgraph F["注册关闭钩子"]
+ subgraph G["Bootstrap 可扩展内容"]
direction TB
- F1["preShutdown
AgentGatewayRegistry.close()"]
- F2["preShutdown hooks"]
- F3["postShutdown
StateCenter.save()"]
- F4["postShutdown
TraceSinkRegistry.close()"]
- F5["postShutdown
ConfigCenter.close()"]
- F6["postShutdown hooks"]
- F1 --> F2
- F3 --> F4 --> F5 --> F6
+ G1["GatewayRegistration"]
+ G2["Configurable"]
+ G3["ExceptionReporter"]
+ G4["pre/post shutdown hook"]
+ G5["scan package / scan dir"]
end
- F --> G["添加外部模块扫描目录
resources/module"]
- G --> H["启动注册工厂
AgentRegisterFactory.launch(application package)"]
+ G --> H["重建最终 AgentRegisterContext"]
- H --> I
+ H --> I["注册 ExceptionReporter"]
- subgraph I["初始化配置系统"]
+ I --> J
+
+ subgraph J["注册 Configurable"]
direction TB
- I1["ConfigCenter.initAll()
初始化已注册的 Configurable"]
- I2["触发各 Configurable.init(config, json)"]
- I3["ConfigCenter.start()
启动配置监听"]
- I1 --> I2 --> I3
+ J1["LogAdviceProvider.register()"]
+ J2["ModelRuntimeRegistry.register()"]
+ J3["AgentGatewayRegistry.register()"]
+ J4["Bootstrap / 应用声明的 Configurable.register()"]
end
- I --> K["Agent 启动完成"]
+ J --> K["注册 AgentGatewayRegistration"]
+
+ K --> L
+
+ subgraph L["注册关闭钩子"]
+ direction TB
+ L1["preShutdown
AgentGatewayRegistry.close()"]
+ L2["Bootstrap / 应用声明的 preShutdown hooks"]
+ L3["postShutdown
StateCenter.save()"]
+ L4["postShutdown
TraceSinkRegistry.close()"]
+ L5["postShutdown
ConfigCenter.close()"]
+ L6["Bootstrap / 应用声明的 postShutdown hooks"]
+ L1 --> L2
+ L3 --> L4 --> L5 --> L6
+ end
+
+ L --> M["启动注册工厂
AgentRegisterFactory.launch(registerContext)"]
+
+ M --> N
+
+ subgraph N["初始化配置系统"]
+ direction TB
+ N1["ConfigCenter.initAll()
初始化已注册的 Configurable"]
+ N2["触发各 Configurable.init(config, json)"]
+ N3["ConfigCenter.start()
启动配置监听"]
+ 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` 执行。