【Agent进阶专题】内核雏形

本篇实现第一版 Kernel:安装 Extension,并调度 setup、start 和 stop 生命周期。

Kernel 的内部组成

Kernel 只保存运行 Extension 所需的内容:

1
2
3
4
5
6
7
8
export class Kernel {
#extensions: Extension[] = [];
#activeExtensions: Extension[] = [];
#registry = new ExtensionRegistry();
#events = new EventBus();
#setupContext: ExtensionSetupContext;
#runtimeContext: ExtensionRuntimeContext;
#state = "created";
  • extensions 保存已安装的 Extension。
  • activeExtensions 保存已经进入启动阶段的 Extension。
  • registry 和 events 提供能力注册与事实事件。
  • 两个 Context 分别用于注册阶段和运行阶段。
  • state 状态初始值为 created。

Kernel 不保存 Workspace、Conversation、Agent 等业务状态。

状态流转

先看完整状态:

1
2
created → starting → running → stopping → stopped
└── 启动失败 ───────────→ stopped
  • created:Kernel 已创建,可以安装 Extension。
  • starting:正在执行 setup 和 start。
  • running:全部 Extension 已启动。
  • stopping:正在倒序停止 Extension。
  • stopped:资源已经清理,生命周期结束。

当前实现不支持重启同一个 Kernel 实例。进入 stopped 后,需要重新创建实例。

安装 Extension

use() 只能在 created 状态调用,每个 Extension ID 必须唯一:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
use(...extensions: Extension[]): this {
if (this.#state !== "created") {
throw new Error(`Cannot install extensions while kernel is ${this.#state}.`);
}

const ids = new Set(this.#extensions.map((extension) => extension.id));

for (const extension of extensions) {
if (ids.has(extension.id)) {
throw new Error(`Extension "${extension.id}" is already installed.`);
}
ids.add(extension.id);
}

this.#extensions.push(...extensions);
return this;
}

先检查整批 ID,再统一写入数组。只要有一个 ID 冲突,整批都不会安装。

构造上下文

Setup Context 用于 setup 阶段,只提供注册能力和监听事件能力:

1
2
3
4
5
6
7
8
this.#setupContext = {
add(name, value) {
registry.add(name, value);
},
on(event, handler) {
return events.on(event, handler);
},
};

Runtime Context 用于运行阶段,提供获取能力、监听事件和发布事件能力:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
this.#runtimeContext = {
get(name) {
return registry.get(name);
},
all(name) {
return registry.all(name);
},
on(event, handler) {
return events.on(event, handler);
},
emit(event, payload) {
return events.emit(event, payload);
},
};

两个 Context 共享同一个 Registry 和 EventBus,只是开放的操作不同。setup 阶段不能读取能力或发布事件。

启动

调用 start() 时,先检查当前状态,然后立即进入 starting:

1
2
3
4
5
if (this.#state !== "created") {
throw new Error(`Cannot start kernel while it is ${this.#state}.`);
}

this.#state = "starting";

启动分为两轮:

1
2
3
4
5
6
7
8
for (const extension of this.#extensions) {
await extension.setup(this.#setupContext);
}

for (const extension of this.#extensions) {
this.#activeExtensions.push(extension);
await extension.start?.(this.#runtimeContext);
}

第一轮完成所有注册,第二轮才开始使用能力。因此,第一个 Extension 进入 start 时,也能获取最后一个 Extension 在 setup 中注册的能力。

Extension 在调用 start 前加入 activeExtensions。如果自己的 start 失败,后续清理仍会调用它的 stop。

全部 Extension 启动完成后, Kernel 才进入 running 状态。

启动报错兜底

setup 或 start 抛错都会进入失败清理:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
} catch (error) {
const cleanupErrors = await this.#stopActiveExtensions();
this.#events.clear();
this.#registry.clear();
this.#state = "stopped";

if (cleanupErrors.length > 0) {
throw new AggregateError(
[error, ...cleanupErrors],
"Kernel failed to start and one or more extensions failed to clean up.",
);
}

throw error;
}

setup 失败时,还没有 Extension 进入 activeExtensions,只需清空已经注册的能力和事件。

start 失败时,Kernel 会倒序停止已经进入启动阶段的 Extension。清理再次失败时,原始错误和清理错误一起放进 AggregateError。

无论失败发生在哪一轮,清理结束后的状态都是 stopped。

停止

stop() 只接受 running 状态。调用后状态立刻变为 stopping:

1
2
3
4
5
6
7
if (this.#state === "stopped") return;

if (this.#state !== "running") {
throw new Error(`Cannot stop kernel while it is ${this.#state}.`);
}

this.#state = "stopping";

Extension 按启动顺序倒序停止:

1
2
3
4
5
6
7
8
9
for (const extension of [...this.#activeExtensions].reverse()) {
try {
await extension.stop?.(this.#runtimeContext);
} catch (error) {
errors.push(error);
}
}

this.#activeExtensions = [];

后启动的 Extension 往往依赖先启动的 Extension,所以先停止。单个 stop 失败不会中断其他 Extension 的清理。

最后清空 EventBus 和 Registry,并将状态改为 stopped:

1
2
3
4
const errors = await this.#stopActiveExtensions();
this.#events.clear();
this.#registry.clear();
this.#state = "stopped";

存在清理错误时,Kernel 在完成全部清理后统一抛出 AggregateError。再次调用 stop() 会直接返回,状态保持 stopped。

完整实现位于 src/kernel/kernel.ts。

到这里,Kernel 已经具备运行 Extension 的最小生命周期,下一篇开始接入具体能力。