@aalis/core 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -0
- package/dist/app.d.ts +166 -0
- package/dist/app.d.ts.map +1 -0
- package/dist/app.js +348 -0
- package/dist/app.js.map +1 -0
- package/dist/config.d.ts +174 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +377 -0
- package/dist/config.js.map +1 -0
- package/dist/constants.d.ts +31 -0
- package/dist/constants.d.ts.map +1 -0
- package/dist/constants.js +36 -0
- package/dist/constants.js.map +1 -0
- package/dist/context.d.ts +328 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +521 -0
- package/dist/context.js.map +1 -0
- package/dist/disposable-chain.d.ts +31 -0
- package/dist/disposable-chain.d.ts.map +1 -0
- package/dist/disposable-chain.js +66 -0
- package/dist/disposable-chain.js.map +1 -0
- package/dist/events.d.ts +64 -0
- package/dist/events.d.ts.map +1 -0
- package/dist/events.js +145 -0
- package/dist/events.js.map +1 -0
- package/dist/hooks.d.ts +49 -0
- package/dist/hooks.d.ts.map +1 -0
- package/dist/hooks.js +102 -0
- package/dist/hooks.js.map +1 -0
- package/dist/i18n.d.ts +6 -0
- package/dist/i18n.d.ts.map +1 -0
- package/dist/i18n.js +26 -0
- package/dist/i18n.js.map +1 -0
- package/dist/identity.d.ts +26 -0
- package/dist/identity.d.ts.map +1 -0
- package/dist/identity.js +36 -0
- package/dist/identity.js.map +1 -0
- package/dist/index.d.ts +17 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +29 -0
- package/dist/index.js.map +1 -0
- package/dist/init.d.ts +20 -0
- package/dist/init.d.ts.map +1 -0
- package/dist/init.js +455 -0
- package/dist/init.js.map +1 -0
- package/dist/llm-router.d.ts.map +1 -0
- package/dist/llm-router.js +123 -0
- package/dist/llm-router.js.map +1 -0
- package/dist/logger.d.ts +76 -0
- package/dist/logger.d.ts.map +1 -0
- package/dist/logger.js +187 -0
- package/dist/logger.js.map +1 -0
- package/dist/marketplace-bootstrap.d.ts +54 -0
- package/dist/marketplace-bootstrap.d.ts.map +1 -0
- package/dist/marketplace-bootstrap.js +132 -0
- package/dist/marketplace-bootstrap.js.map +1 -0
- package/dist/mixin-registry.d.ts +34 -0
- package/dist/mixin-registry.d.ts.map +1 -0
- package/dist/mixin-registry.js +60 -0
- package/dist/mixin-registry.js.map +1 -0
- package/dist/model-ref.d.ts +22 -0
- package/dist/model-ref.d.ts.map +1 -0
- package/dist/model-ref.js +46 -0
- package/dist/model-ref.js.map +1 -0
- package/dist/pending-buffer.d.ts +46 -0
- package/dist/pending-buffer.d.ts.map +1 -0
- package/dist/pending-buffer.js +131 -0
- package/dist/pending-buffer.js.map +1 -0
- package/dist/platform-registry.d.ts +40 -0
- package/dist/platform-registry.d.ts.map +1 -0
- package/dist/platform-registry.js +64 -0
- package/dist/platform-registry.js.map +1 -0
- package/dist/plugin-activation.d.ts +43 -0
- package/dist/plugin-activation.d.ts.map +1 -0
- package/dist/plugin-activation.js +172 -0
- package/dist/plugin-activation.js.map +1 -0
- package/dist/plugin-topology.d.ts +40 -0
- package/dist/plugin-topology.d.ts.map +1 -0
- package/dist/plugin-topology.js +126 -0
- package/dist/plugin-topology.js.map +1 -0
- package/dist/plugin.d.ts +184 -0
- package/dist/plugin.d.ts.map +1 -0
- package/dist/plugin.js +549 -0
- package/dist/plugin.js.map +1 -0
- package/dist/providers.d.ts +85 -0
- package/dist/providers.d.ts.map +1 -0
- package/dist/providers.js +2 -0
- package/dist/providers.js.map +1 -0
- package/dist/semver-mini.d.ts +20 -0
- package/dist/semver-mini.d.ts.map +1 -0
- package/dist/semver-mini.js +94 -0
- package/dist/semver-mini.js.map +1 -0
- package/dist/service-helpers.d.ts +34 -0
- package/dist/service-helpers.d.ts.map +1 -0
- package/dist/service-helpers.js +68 -0
- package/dist/service-helpers.js.map +1 -0
- package/dist/service.d.ts +145 -0
- package/dist/service.d.ts.map +1 -0
- package/dist/service.js +279 -0
- package/dist/service.js.map +1 -0
- package/dist/types/agent.d.ts +51 -0
- package/dist/types/agent.d.ts.map +1 -0
- package/dist/types/agent.js +3 -0
- package/dist/types/agent.js.map +1 -0
- package/dist/types/app.d.ts +74 -0
- package/dist/types/app.d.ts.map +1 -0
- package/dist/types/app.js +3 -0
- package/dist/types/app.js.map +1 -0
- package/dist/types/archive.d.ts +59 -0
- package/dist/types/archive.d.ts.map +1 -0
- package/dist/types/archive.js +16 -0
- package/dist/types/archive.js.map +1 -0
- package/dist/types/authority.d.ts +63 -0
- package/dist/types/authority.d.ts.map +1 -0
- package/dist/types/authority.js +3 -0
- package/dist/types/authority.js.map +1 -0
- package/dist/types/capabilities.d.ts +53 -0
- package/dist/types/capabilities.d.ts.map +1 -0
- package/dist/types/capabilities.js +87 -0
- package/dist/types/capabilities.js.map +1 -0
- package/dist/types/cli.d.ts +14 -0
- package/dist/types/cli.d.ts.map +1 -0
- package/dist/types/cli.js +3 -0
- package/dist/types/cli.js.map +1 -0
- package/dist/types/commands.d.ts +98 -0
- package/dist/types/commands.d.ts.map +1 -0
- package/dist/types/commands.js +3 -0
- package/dist/types/commands.js.map +1 -0
- package/dist/types/core.d.ts +117 -0
- package/dist/types/core.d.ts.map +1 -0
- package/dist/types/core.js +6 -0
- package/dist/types/core.js.map +1 -0
- package/dist/types/disposable-service.d.ts +31 -0
- package/dist/types/disposable-service.d.ts.map +1 -0
- package/dist/types/disposable-service.js +3 -0
- package/dist/types/disposable-service.js.map +1 -0
- package/dist/types/embedding.d.ts +7 -0
- package/dist/types/embedding.d.ts.map +1 -0
- package/dist/types/embedding.js +3 -0
- package/dist/types/embedding.js.map +1 -0
- package/dist/types/flow-control.d.ts +51 -0
- package/dist/types/flow-control.d.ts.map +1 -0
- package/dist/types/flow-control.js +12 -0
- package/dist/types/flow-control.js.map +1 -0
- package/dist/types/gateway.d.ts +24 -0
- package/dist/types/gateway.d.ts.map +1 -0
- package/dist/types/gateway.js +15 -0
- package/dist/types/gateway.js.map +1 -0
- package/dist/types/hooks.d.ts +3 -0
- package/dist/types/hooks.d.ts.map +1 -0
- package/dist/types/hooks.js +18 -0
- package/dist/types/hooks.js.map +1 -0
- package/dist/types/image-recognition.d.ts +123 -0
- package/dist/types/image-recognition.d.ts.map +1 -0
- package/dist/types/image-recognition.js +31 -0
- package/dist/types/image-recognition.js.map +1 -0
- package/dist/types/index.d.ts +8 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/types/index.js +17 -0
- package/dist/types/index.js.map +1 -0
- package/dist/types/llm.d.ts +146 -0
- package/dist/types/llm.d.ts.map +1 -0
- package/dist/types/llm.js +27 -0
- package/dist/types/llm.js.map +1 -0
- package/dist/types/memory.d.ts +62 -0
- package/dist/types/memory.d.ts.map +1 -0
- package/dist/types/memory.js +22 -0
- package/dist/types/memory.js.map +1 -0
- package/dist/types/persona.d.ts +45 -0
- package/dist/types/persona.d.ts.map +1 -0
- package/dist/types/persona.js +3 -0
- package/dist/types/persona.js.map +1 -0
- package/dist/types/platform.d.ts +126 -0
- package/dist/types/platform.d.ts.map +1 -0
- package/dist/types/platform.js +5 -0
- package/dist/types/platform.js.map +1 -0
- package/dist/types/plugin.d.ts +84 -0
- package/dist/types/plugin.d.ts.map +1 -0
- package/dist/types/plugin.js +24 -0
- package/dist/types/plugin.js.map +1 -0
- package/dist/types/service.d.ts +43 -0
- package/dist/types/service.d.ts.map +1 -0
- package/dist/types/service.js +38 -0
- package/dist/types/service.js.map +1 -0
- package/dist/types/services.d.ts +17 -0
- package/dist/types/services.d.ts.map +1 -0
- package/dist/types/services.js +41 -0
- package/dist/types/services.js.map +1 -0
- package/dist/types/session.d.ts +153 -0
- package/dist/types/session.d.ts.map +1 -0
- package/dist/types/session.js +19 -0
- package/dist/types/session.js.map +1 -0
- package/dist/types/storage.d.ts +100 -0
- package/dist/types/storage.d.ts.map +1 -0
- package/dist/types/storage.js +29 -0
- package/dist/types/storage.js.map +1 -0
- package/dist/types/tools.d.ts +39 -0
- package/dist/types/tools.d.ts.map +1 -0
- package/dist/types/tools.js +3 -0
- package/dist/types/tools.js.map +1 -0
- package/dist/types/trigger-policy.d.ts +16 -0
- package/dist/types/trigger-policy.d.ts.map +1 -0
- package/dist/types/trigger-policy.js +6 -0
- package/dist/types/trigger-policy.js.map +1 -0
- package/dist/types/vectorstore.d.ts +23 -0
- package/dist/types/vectorstore.d.ts.map +1 -0
- package/dist/types/vectorstore.js +3 -0
- package/dist/types/vectorstore.js.map +1 -0
- package/dist/types/web-search.d.ts +88 -0
- package/dist/types/web-search.d.ts.map +1 -0
- package/dist/types/web-search.js +23 -0
- package/dist/types/web-search.js.map +1 -0
- package/dist/types/webui.d.ts +137 -0
- package/dist/types/webui.d.ts.map +1 -0
- package/dist/types/webui.js +3 -0
- package/dist/types/webui.js.map +1 -0
- package/package.json +22 -0
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
import { type ConfigManager } from './config.js';
|
|
2
|
+
import type { EventBus } from './events.js';
|
|
3
|
+
import type { HookRegistry } from './hooks.js';
|
|
4
|
+
import type { Logger } from './logger.js';
|
|
5
|
+
import type { ServiceContainer } from './service.js';
|
|
6
|
+
import type { AalisEvents, CapabilityList, HookContextMap, MiddlewareFn, ServiceTypeMap } from './types/index.js';
|
|
7
|
+
type EventHandler<Args extends unknown[]> = (...args: Args) => void | Promise<void>;
|
|
8
|
+
/**
|
|
9
|
+
* 上下文 (Context)
|
|
10
|
+
*
|
|
11
|
+
* 每个插件获得一个子 Context。所有通过子 Context 注册的副作用
|
|
12
|
+
* (事件监听、服务注册、工具注册) 在 dispose 时自动清理。
|
|
13
|
+
*
|
|
14
|
+
* 采用 fork / inject / provide / middleware 等术语,
|
|
15
|
+
* 但 Aalis 在此之上引入若干差异化机制:
|
|
16
|
+
* - **能力声明框架**:`provide` 时声明 `capabilities`,编译期类型字面量收敛 +
|
|
17
|
+
* dev 期 `probeCapability` 运行时校验声明与实现是否一致
|
|
18
|
+
* - **多提供者 + 能力匹配**:`getService` / `getAllServices` 支持按能力过滤,
|
|
19
|
+
* 服务可以并存多个实现
|
|
20
|
+
* - **`ScopedServiceContainer` + `ScopedConfigManager`**:`createScope()` 创建
|
|
21
|
+
* 读取 fallback、写入隔离的子作用域,用于会话/沙盒
|
|
22
|
+
* - **`whenService(name, cb)`**:服务就绪即触发的延迟订阅,回调可返回 cleanup
|
|
23
|
+
* 纳入 dispose 链
|
|
24
|
+
*/
|
|
25
|
+
export declare class Context {
|
|
26
|
+
readonly id: string;
|
|
27
|
+
readonly logger: Logger;
|
|
28
|
+
readonly config: ConfigManager;
|
|
29
|
+
readonly hooks: HookRegistry;
|
|
30
|
+
/**
|
|
31
|
+
* 开发模式开关——由 App 注入,子 Context 通过 fork/createScope 继承。
|
|
32
|
+
*
|
|
33
|
+
* - `true`(默认):`provide` 时按声明的能力跑探测器,暴露"声明与实现不符"
|
|
34
|
+
* - `false`(生产):跳过探测,节省热路径开销
|
|
35
|
+
*
|
|
36
|
+
* core 不读 `process.env`——是否 dev 由宿主决定。
|
|
37
|
+
*/
|
|
38
|
+
readonly devMode: boolean;
|
|
39
|
+
private _events;
|
|
40
|
+
private _services;
|
|
41
|
+
private _disposables;
|
|
42
|
+
private _children;
|
|
43
|
+
private _parent?;
|
|
44
|
+
private _disposed;
|
|
45
|
+
constructor(options: {
|
|
46
|
+
id: string;
|
|
47
|
+
events: EventBus;
|
|
48
|
+
services: ServiceContainer;
|
|
49
|
+
hooks: HookRegistry;
|
|
50
|
+
logger: Logger;
|
|
51
|
+
config: ConfigManager;
|
|
52
|
+
parent?: Context;
|
|
53
|
+
devMode?: boolean;
|
|
54
|
+
});
|
|
55
|
+
/**
|
|
56
|
+
* 底层服务容器实例。
|
|
57
|
+
*
|
|
58
|
+
* ⚠️ **@internal** —— 仅供 host 级巡视代码(如 plugin-activation 检查 provides
|
|
59
|
+
* 完整性)使用。
|
|
60
|
+
*
|
|
61
|
+
* **插件请勿直接使用**:
|
|
62
|
+
* - 枚举某服务的所有 entry(含 contextId / capabilities / priority):
|
|
63
|
+
* → 用公开 API `ctx.getServiceEntries(name)`
|
|
64
|
+
* - 获取服务实例:用 `ctx.getService()` / `ctx.getAllServices()`
|
|
65
|
+
* - 注册服务:用 `ctx.provide()`(会自动登记到 _disposables 链)
|
|
66
|
+
*/
|
|
67
|
+
get serviceContainer(): ServiceContainer;
|
|
68
|
+
/**
|
|
69
|
+
* 创建子上下文(通常为每个插件创建一个)
|
|
70
|
+
*/
|
|
71
|
+
fork(id: string): Context;
|
|
72
|
+
/**
|
|
73
|
+
* 创建隔离作用域的子上下文
|
|
74
|
+
*
|
|
75
|
+
* 与 fork() 的区别:fork() 共享同一个 ServiceContainer / ConfigManager;
|
|
76
|
+
* createScope() 同时创建:
|
|
77
|
+
* - **ScopedServiceContainer**(子容器):读 fallback、写不影响父级
|
|
78
|
+
* - **ScopedConfigManager**(cleanup-7 新增):同样 fallback + overlay 语义
|
|
79
|
+
*
|
|
80
|
+
* 适用于沙盒/会话隔离场景:
|
|
81
|
+
* - 沙盒内 `ctx.provide('agent', sandboxAgent)` 不会污染全局
|
|
82
|
+
* - 沙盒内 `ctx.getService('authority')` 仍能 fallback 到全局服务
|
|
83
|
+
* - 沙盒内 `ctx.config.set('logLevel', 'debug')` 仅作用于沙盒
|
|
84
|
+
* - 沙盒内 `ctx.config.setPluginConfig('llm.openai', { ... })` 给当前沙盒一份
|
|
85
|
+
* 临时 LLM 配置,dispose 后随作用域消失(写只进 overlay,save() 为内存
|
|
86
|
+
* 模式 no-op,磁盘不被污染)
|
|
87
|
+
*
|
|
88
|
+
* @example
|
|
89
|
+
* const sandbox = ctx.createScope('sandbox-group-123');
|
|
90
|
+
* sandbox.provide('agent', myCustomAgent); // 仅此作用域可见
|
|
91
|
+
* sandbox.config.setPluginConfig('llm.openai', { temperature: 0.1 }); // 临时配置
|
|
92
|
+
* sandbox.getService('authority'); // fallback 到父级全局服务
|
|
93
|
+
*/
|
|
94
|
+
createScope(id: string): Context;
|
|
95
|
+
on<E extends string & keyof AalisEvents>(event: E, handler: EventHandler<AalisEvents[E]>): () => void;
|
|
96
|
+
once<E extends string & keyof AalisEvents>(event: E, handler: EventHandler<AalisEvents[E]>): () => void;
|
|
97
|
+
/**
|
|
98
|
+
* 把一个底层退订原语登记到 disposable 链,并返回**自移除**的退订函数:
|
|
99
|
+
* 调用方手动退订时,闭包不再滞留 _disposables(否则它持有 handler 引用直到
|
|
100
|
+
* ctx.dispose——审计 HIGH #2 的同类泄漏,统一所有注册 API 的退订语义)。
|
|
101
|
+
*/
|
|
102
|
+
private trackDisposable;
|
|
103
|
+
emit<E extends string & keyof AalisEvents>(event: E, ...args: AalisEvents[E]): Promise<void>;
|
|
104
|
+
/**
|
|
105
|
+
* 注册服务,返回 dispose 函数用于精确卸载该服务
|
|
106
|
+
*
|
|
107
|
+
* `capabilities` 参数按服务名获得强类型约束:
|
|
108
|
+
* - 已注册服务名(如 `'llm'`, `'memory'`)→ 仅允许对应 union 中的字面量
|
|
109
|
+
* - 未注册服务名 → 退回 `string`,保留动态扩展空间
|
|
110
|
+
*
|
|
111
|
+
* @example
|
|
112
|
+
* ctx.provide('llm', service, { capabilities: ['chat', 'tool_calling'] });
|
|
113
|
+
* // ^^^^^^ ^^^^^^^^^^^^^^
|
|
114
|
+
* // 类型安全,拼错 'tool_call' 会编译报错
|
|
115
|
+
*
|
|
116
|
+
* `entryId` 选项:覆盖默认 contextId(默认 = `this.id`)。用于一个 plugin 实例
|
|
117
|
+
* 需要按某种语义子粒度拆出多个 entry 的场景(典型:per-model LLM、per-path storage)。
|
|
118
|
+
* 约定:`entryId` 必须以 `this.id` 为前缀(以 `/` 分隔),以保证 plugin 卸载时
|
|
119
|
+
* `unregisterByContext(this.id)` 如需清理仍可多次调用;dispose 函数并不依赖这个约定,
|
|
120
|
+
* 但 dev 模式下会验证以避免 "entryId 与拥有者 plugin 脱联" 的 footgun。
|
|
121
|
+
*/
|
|
122
|
+
provide<TName extends string>(name: TName, instance: unknown, options?: {
|
|
123
|
+
capabilities?: CapabilityList<TName>;
|
|
124
|
+
priority?: number;
|
|
125
|
+
label?: string;
|
|
126
|
+
entryId?: string;
|
|
127
|
+
}): () => void;
|
|
128
|
+
/**
|
|
129
|
+
* 按名字 + 能力过滤拿服务当前最佳提供者。
|
|
130
|
+
*
|
|
131
|
+
* 返回的是**当时点的裸实例**,调用后 provider 发生换跳不会跟随。
|
|
132
|
+
* 需要跟随切换的场景请听 `service:registered` / `service:unregistered`
|
|
133
|
+
* 事件重新拉取;常规场景推荐在函数作用域内即取即用,不要长期存入类字段。
|
|
134
|
+
*
|
|
135
|
+
* `requiredCapabilities` 按服务名获得强类型约束(同 `provide()`)。
|
|
136
|
+
* 如果当前没有任何匹配的 entry,返回 `undefined`(保留 null-check 语义)。
|
|
137
|
+
*
|
|
138
|
+
* 重载行为:
|
|
139
|
+
* - 传入字面量服务名(如 `'memory'`)→ 命中 `ServiceTypeMap` 自动推断为 `MemoryService | undefined`;
|
|
140
|
+
* - 传入字符串变量或未登记服务名 → 退回 `<T = unknown>`,调用方需自行 narrow,
|
|
141
|
+
* 仍可显式传 `<T>` 兼容旧写法。
|
|
142
|
+
*/
|
|
143
|
+
getService<TName extends keyof ServiceTypeMap>(name: TName, requiredCapabilities?: CapabilityList<TName>): ServiceTypeMap[TName] | undefined;
|
|
144
|
+
getService<T = unknown>(name: string, requiredCapabilities?: readonly string[]): T | undefined;
|
|
145
|
+
/**
|
|
146
|
+
* 检查服务是否可用
|
|
147
|
+
*/
|
|
148
|
+
hasService<TName extends string>(name: TName, requiredCapabilities?: CapabilityList<TName>): boolean;
|
|
149
|
+
/**
|
|
150
|
+
* 获取服务的能力列表
|
|
151
|
+
*/
|
|
152
|
+
getServiceCapabilities(name: string): string[];
|
|
153
|
+
/**
|
|
154
|
+
* 列出所有已注册的服务名
|
|
155
|
+
*/
|
|
156
|
+
getServiceNames(): string[];
|
|
157
|
+
/**
|
|
158
|
+
* 获取某个服务的所有实例(带提供者信息)
|
|
159
|
+
*
|
|
160
|
+
* 可选 requiredCapabilities 过滤:只返回满足所有所需能力的提供者。
|
|
161
|
+
*
|
|
162
|
+
* @example
|
|
163
|
+
* // 获取所有支持 vision 的 LLM
|
|
164
|
+
* const visionLLMs = ctx.getAllServices('llm', ['vision']);
|
|
165
|
+
*
|
|
166
|
+
* // 获取所有 LLM 并聚合模型列表
|
|
167
|
+
* const allLLMs = ctx.getAllServices('llm');
|
|
168
|
+
*/
|
|
169
|
+
getAllServices<TName extends keyof ServiceTypeMap>(name: TName, requiredCapabilities?: CapabilityList<TName>): Array<{
|
|
170
|
+
instance: ServiceTypeMap[TName];
|
|
171
|
+
contextId: string;
|
|
172
|
+
capabilities: string[];
|
|
173
|
+
label?: string;
|
|
174
|
+
}>;
|
|
175
|
+
getAllServices<T = unknown>(name: string, requiredCapabilities?: readonly string[]): Array<{
|
|
176
|
+
instance: T;
|
|
177
|
+
contextId: string;
|
|
178
|
+
capabilities: string[];
|
|
179
|
+
label?: string;
|
|
180
|
+
}>;
|
|
181
|
+
/**
|
|
182
|
+
* 设置某服务的偏好 provider(按 contextId)
|
|
183
|
+
*
|
|
184
|
+
* 语义:「偏好 > 优先级 > 注册顺序」。偏好者总是 `getService(name)` 的第一返回值,
|
|
185
|
+
* 即使其 priority 数值低于 router 等其他 entry。
|
|
186
|
+
*
|
|
187
|
+
* 注:偏好可以提前于 entry 注册前设置——一旦目标 contextId 注册即刻生效。
|
|
188
|
+
* @returns 始终返回 true(偏好已记录)
|
|
189
|
+
*/
|
|
190
|
+
preferService(name: string, contextId: string): boolean;
|
|
191
|
+
/**
|
|
192
|
+
* 清除某服务的偏好(恢复 priority + 注册顺序解析)
|
|
193
|
+
*/
|
|
194
|
+
unpreferService(name: string): boolean;
|
|
195
|
+
/**
|
|
196
|
+
* 读取某服务当前的偏好 contextId(无偏好返回 undefined)
|
|
197
|
+
*/
|
|
198
|
+
getPreferredService(name: string): string | undefined;
|
|
199
|
+
/**
|
|
200
|
+
* 获取某服务的全部 entry(含 priority),按「偏好 > 优先级 > 注册顺序」排序。
|
|
201
|
+
*
|
|
202
|
+
* 主要给管控类消费者(如 WebUI / CLI status 视图)枚举展示用。
|
|
203
|
+
* 业务消费者应优先使用 `getService` / `getAllServices`。
|
|
204
|
+
*/
|
|
205
|
+
getServiceEntries(name: string): ReadonlyArray<{
|
|
206
|
+
instance: unknown;
|
|
207
|
+
contextId: string;
|
|
208
|
+
capabilities: ReadonlySet<string>;
|
|
209
|
+
priority: number;
|
|
210
|
+
label?: string;
|
|
211
|
+
}>;
|
|
212
|
+
/**
|
|
213
|
+
* 持续订阅一个服务:每当 provider 上线就调一次 `cb(svc)`,下线则自动执行
|
|
214
|
+
* 上一次 cb 返回的 cleanup。
|
|
215
|
+
*
|
|
216
|
+
* 适用场景:把"向某个 hub 服务注册副作用"封装成一行;当 hub 服务被 bounce
|
|
217
|
+
* 或换提供者时,下游注册会自动重挂——无需作者自己监听 service:registered。
|
|
218
|
+
*
|
|
219
|
+
* 语义细则:
|
|
220
|
+
* - 调用时若服务已就绪,立即触发首次 `cb`。
|
|
221
|
+
* - provider 重新 provide(unregister → register)会先调上次 cleanup、
|
|
222
|
+
* 再用新 svc 调一次 cb;保证不持有失效引用。
|
|
223
|
+
* - `cb` 可返回 cleanup 函数;返回的 dispose 与 `ctx.dispose()` 都会调它。
|
|
224
|
+
* - 返回的 dispose 函数 idempotent,可手动调(多次安全)。
|
|
225
|
+
* - 同名 provider 仅取 `getService(name)` 的胜者,多 entry 并存场景按容器优先级。
|
|
226
|
+
* **胜者不变则不动**:败者 entry 上下线不会触发重挂;胜者换人(含
|
|
227
|
+
* `preferService` 偏好切换、胜者注销后由次优顶上)才 cleanup + 重挂。
|
|
228
|
+
*
|
|
229
|
+
* @example 注册到 hub 服务:
|
|
230
|
+
* ctx.whenService('tools', svc => svc.register(myTool, ctx.id));
|
|
231
|
+
*
|
|
232
|
+
* @example 监听 provider 切换:
|
|
233
|
+
* ctx.whenService('llm', llm => {
|
|
234
|
+
* const handle = llm.onModelChange(updateUI);
|
|
235
|
+
* return () => handle.dispose();
|
|
236
|
+
* });
|
|
237
|
+
*/
|
|
238
|
+
whenService<TName extends keyof ServiceTypeMap>(name: TName, cb: (svc: ServiceTypeMap[TName]) => void | (() => void)): () => void;
|
|
239
|
+
whenService<T = unknown>(name: string, cb: (svc: T) => void | (() => void)): () => void;
|
|
240
|
+
/**
|
|
241
|
+
* 注册命名生命周期事件 handler(中间件管道)
|
|
242
|
+
*
|
|
243
|
+
* 同一钩子键内的多个 handler 按 **注册顺序** 执行洋葱模型 (next 语义),
|
|
244
|
+
* 不再使用数字优先级。相位间的次序由调度方(如 plugin-gateway 的入站
|
|
245
|
+
* 多相位调度)显式表达。
|
|
246
|
+
*
|
|
247
|
+
* @example
|
|
248
|
+
* // 在消息发送给 LLM 前添加额外指令
|
|
249
|
+
* ctx.middleware('agent:llm:before', async (data, next) => {
|
|
250
|
+
* data.messages.unshift({ role: 'system', content: '额外指令...' });
|
|
251
|
+
* await next();
|
|
252
|
+
* });
|
|
253
|
+
*
|
|
254
|
+
* // 命令命中后中断后续处理
|
|
255
|
+
* ctx.middleware('inbound:command', async (data, next) => {
|
|
256
|
+
* if (handled(data.message)) return; // 不调用 next = 中断
|
|
257
|
+
* await next();
|
|
258
|
+
* });
|
|
259
|
+
*/
|
|
260
|
+
middleware<K extends string & keyof HookContextMap>(hook: K, fn: MiddlewareFn<HookContextMap[K]>): () => void;
|
|
261
|
+
get disposed(): boolean;
|
|
262
|
+
/**
|
|
263
|
+
* 在当前 Context 内动态加载一个插件 module 作为"沙盒插件"。
|
|
264
|
+
*
|
|
265
|
+
* 与 `App.plugin(...)` / `PluginManager.register(...)` 的区别:
|
|
266
|
+
* - 不进入全局 `PluginManager`(不参与依赖追踪、softReload)
|
|
267
|
+
* - 创建一个 fork/createScope 子上下文,调用 `module.apply(child, config)`
|
|
268
|
+
* - 返回 dispose:调用即销毁该子上下文,对应子上下文里所有副作用一并清理
|
|
269
|
+
* - 父 ctx dispose 时也会级联销毁
|
|
270
|
+
*
|
|
271
|
+
* 典型场景:
|
|
272
|
+
* - 会话级动态工具/中间件
|
|
273
|
+
* - 沙盒(`createScope`)内挂载临时 mini 插件
|
|
274
|
+
* - 单元测试里组装最小可运行单元
|
|
275
|
+
*
|
|
276
|
+
* @param module 任意符合 `{ name, apply(ctx, config) }` 的对象
|
|
277
|
+
* @param config 传给 apply 的配置(默认 `{}`)
|
|
278
|
+
* @param options.scoped 是否使用 `createScope`(服务/配置隔离),默认 false 用 `fork`
|
|
279
|
+
* @returns dispose 函数;返回的 Promise 在 apply 完成后 resolve
|
|
280
|
+
*
|
|
281
|
+
* @example
|
|
282
|
+
* const off = await ctx.useModule({
|
|
283
|
+
* name: 'temp-mw',
|
|
284
|
+
* apply(c) {
|
|
285
|
+
* c.middleware('agent:input:before', async (data, next) => {
|
|
286
|
+
* data.message.content += ' [临时标记]';
|
|
287
|
+
* await next();
|
|
288
|
+
* });
|
|
289
|
+
* }
|
|
290
|
+
* });
|
|
291
|
+
* // ...
|
|
292
|
+
* off(); // 卸载临时中间件
|
|
293
|
+
*/
|
|
294
|
+
useModule(module: {
|
|
295
|
+
name: string;
|
|
296
|
+
apply(ctx: Context, config: Record<string, unknown>): void | Promise<void>;
|
|
297
|
+
}, config?: Record<string, unknown>, options?: {
|
|
298
|
+
scoped?: boolean;
|
|
299
|
+
}): Promise<() => void>;
|
|
300
|
+
/**
|
|
301
|
+
* 注册一个在本 Context dispose 时执行的清理回调。
|
|
302
|
+
*
|
|
303
|
+
* 插件清理副作用的**唯一正确 API**:
|
|
304
|
+
* - 直接挂在 `_disposables` 链上,保证逆序执行
|
|
305
|
+
* - 在 `ctx.dispose()` 的任何路径上都会触发(app 停机 / bounce / unload /
|
|
306
|
+
* updatePluginConfig / softReload 级联 evict)
|
|
307
|
+
* - 沙盒 / fork 子上下文同样适用
|
|
308
|
+
*
|
|
309
|
+
* ⚠. 不要用 `ctx.on('app:stopping', ...)` 做资源清理——那只在 app 全局停机
|
|
310
|
+
* 时触发一次,**不会**在插件 bounce / hot reload 时触发,会造成旧连接、
|
|
311
|
+
* 旧定时器泄漏。全局停机不需要特别处理——`onDispose` 也会被触发。
|
|
312
|
+
*
|
|
313
|
+
* @example
|
|
314
|
+
* const conn = await connectExternal();
|
|
315
|
+
* ctx.onDispose(() => conn.close());
|
|
316
|
+
*
|
|
317
|
+
* @returns 取消该清理回调的函数(在 dispose 前调用可阻止执行)
|
|
318
|
+
*/
|
|
319
|
+
onDispose(fn: () => void | Promise<void>): () => void;
|
|
320
|
+
/** @internal 当前 disposable 链长度(诊断 / 测试用:检测 provide/whenService 的闭包是否如期自移除)。 */
|
|
321
|
+
get disposableCount(): number;
|
|
322
|
+
/**
|
|
323
|
+
* 销毁此上下文,清理所有副作用
|
|
324
|
+
*/
|
|
325
|
+
dispose(): void;
|
|
326
|
+
}
|
|
327
|
+
export {};
|
|
328
|
+
//# sourceMappingURL=context.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}
|