【Agent进阶专题】能力注册与事件总线

本篇实现 Kernel 使用的两个基础组件:管理能力的 ExtensionRegistry,以及发布事实的 EventBus。

两种协作方式

Extension 之间有两种协作方式:

  • 需要调用并取得结果时,通过 Registry 获取能力后直接调用。
  • 状态已经发生,需要通知其他 Extension 时,通过 EventBus 发布事件。

控制流程不走事件总线。事件监听器没有返回业务结果,也不负责审批、回滚和调用顺序。

ExtensionRegistry

Registry 使用字符串名称保存能力,同一个名称可以注册一个或多个值:

1
2
3
4
5
6
7
8
9
10
11
12
13
export class ExtensionRegistry {
#values = new Map<string, unknown[]>();

add<T>(name: string, value: T): void {
const values = this.#values.get(name);

if (values) {
values.push(value);
} else {
this.#values.set(name, [value]);
}
}
}

名称只是带命名空间的字符串,例如 workspace 或 model.providers。

读取分为 get() 和 all():

1
2
3
4
5
6
7
8
9
10
11
12
13
get<T>(name: string): T {
const values = this.all<T>(name);

if (values.length !== 1) {
throw new Error(`"${name}" needs exactly one value, found ${values.length}.`);
}

return values[0] as T;
}

all<T>(name: string): T[] {
return [...(this.#values.get(name) ?? [])] as T[];
}

get() 要求结果恰好一个。没有注册或注册了多个值都会报错,适合 Workspace、Agent 这类单一能力。

all() 返回同名能力的全部实现,适合 model.providers 这类扩展点,返回值是新数组。
调用方不应该直接修改 Registry 内部数据,而应该通过能力本身提供的方法进行操作。

停止 Runtime 时调用 clear() 清空所有能力:

1
2
3
clear(): void {
this.#values.clear();
}

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

EventBus

EventBus 使用事件名称保存一组监听器:

1
2
3
4
5
6
export type EventHandler<T> = (payload: T) => void | Promise<void>;
export type Unsubscribe = () => void;

export class EventBus {
#listeners = new Map<string, Set<EventHandler<any>>>();
}

监听器可以同步执行,也可以返回 Promise。使用 Set 保存,可以避免同一个函数重复注册到同一事件。

on() 完成订阅,并返回取消函数:

1
2
3
4
5
6
7
8
9
10
on<T>(event: string, handler: EventHandler<T>): Unsubscribe {
const listeners = this.#listeners.get(event) ?? new Set();
listeners.add(handler);
this.#listeners.set(event, listeners);

return () => {
listeners.delete(handler);
if (listeners.size === 0) this.#listeners.delete(event);
};
}

最后一个监听器取消后,事件名称也会从 Map 中删除。

emit() 按注册顺序逐个等待监听器:

1
2
3
4
5
6
7
8
9
10
11
12
13
async emit<T>(event: string, payload: T): Promise<unknown[]> {
const errors: unknown[] = [];

for (const listener of this.#listeners.get(event) ?? []) {
try {
await listener(payload);
} catch (error) {
errors.push(error);
}
}

return errors;
}

一个监听器失败不会打断后面的监听器。错误不会直接从 emit() 抛出,而是收集后返回,由发布方决定如何处理。

Runtime 停止时,clear() 会移除全部监听器。完整实现位于 src/kernel/events.ts。

Registry 和 EventBus 到这里就完成了。下一篇把它们装进 Kernel,处理 Extension 的安装、启动和停止。