@aalis/core 0.1.0

package/dist/context.js

@@ -0,0 +1,521 @@
+import { ScopedConfigManager } from './config.js';
+import { DisposableChain } from './disposable-chain.js';
+import { emitServiceRegistered, validateProvide } from './service-helpers.js';
+/**
+ * 上下文 (Context)
+ *
+ * 每个插件获得一个子 Context。所有通过子 Context 注册的副作用
+ * (事件监听、服务注册、工具注册) 在 dispose 时自动清理。
+ *
+ * 采用 fork / inject / provide / middleware 等术语，
+ * 但 Aalis 在此之上引入若干差异化机制：
+ * - **能力声明框架**：`provide` 时声明 `capabilities`，编译期类型字面量收敛 +
+ *   dev 期 `probeCapability` 运行时校验声明与实现是否一致
+ * - **多提供者 + 能力匹配**：`getService` / `getAllServices` 支持按能力过滤，
+ *   服务可以并存多个实现
+ * - **`ScopedServiceContainer` + `ScopedConfigManager`**：`createScope()` 创建
+ *   读取 fallback、写入隔离的子作用域，用于会话/沙盒
+ * - **`whenService(name, cb)`**：服务就绪即触发的延迟订阅，回调可返回 cleanup
+ *   纳入 dispose 链
+ */
+export class Context {
+    id;
+    logger;
+    config;
+    hooks;
+    /**
+     * 开发模式开关——由 App 注入，子 Context 通过 fork/createScope 继承。
+     *
+     * - `true`（默认）：`provide` 时按声明的能力跑探测器，暴露"声明与实现不符"
+     * - `false`（生产）：跳过探测，节省热路径开销
+     *
+     * core 不读 `process.env`——是否 dev 由宿主决定。
+     */
+    devMode;
+    _events;
+    _services;
+    _disposables;
+    _children = new Set();
+    _parent;
+    _disposed = false;
+    constructor(options) {
+        this.id = options.id;
+        this._events = options.events;
+        this._services = options.services;
+        this.hooks = options.hooks;
+        this.logger = options.logger;
+        this.config = options.config;
+        this._parent = options.parent;
+        this.devMode = options.devMode ?? options.parent?.devMode ?? true;
+        this._disposables = new DisposableChain(this.logger);
+    }
+    // ---- 子系统访问（供高级插件检查/包装用） ----
+    /**
+     * 底层服务容器实例。
+     *
+     * ⚠️ **@internal** —— 仅供 host 级巡视代码（如 plugin-activation 检查 provides
+     * 完整性）使用。
+     *
+     * **插件请勿直接使用**：
+     * - 枚举某服务的所有 entry（含 contextId / capabilities / priority）：
+     *   → 用公开 API `ctx.getServiceEntries(name)`
+     * - 获取服务实例：用 `ctx.getService()` / `ctx.getAllServices()`
+     * - 注册服务：用 `ctx.provide()`（会自动登记到 _disposables 链）
+     */
+    get serviceContainer() {
+        return this._services;
+    }
+    /**
+     * 创建子上下文（通常为每个插件创建一个）
+     */
+    fork(id) {
+        const child = new Context({
+            id,
+            events: this._events,
+            services: this._services,
+            hooks: this.hooks,
+            logger: this.logger.child(id),
+            config: this.config,
+            parent: this,
+            devMode: this.devMode,
+        });
+        this._children.add(child);
+        return child;
+    }
+    /**
+     * 创建隔离作用域的子上下文
+     *
+     * 与 fork() 的区别：fork() 共享同一个 ServiceContainer / ConfigManager；
+     * createScope() 同时创建：
+     * - **ScopedServiceContainer**（子容器）：读 fallback、写不影响父级
+     * - **ScopedConfigManager**（cleanup-7 新增）：同样 fallback + overlay 语义
+     *
+     * 适用于沙盒/会话隔离场景：
+     * - 沙盒内 `ctx.provide('agent', sandboxAgent)` 不会污染全局
+     * - 沙盒内 `ctx.getService('authority')` 仍能 fallback 到全局服务
+     * - 沙盒内 `ctx.config.set('logLevel', 'debug')` 仅作用于沙盒
+     * - 沙盒内 `ctx.config.setPluginConfig('llm.openai', { ... })` 给当前沙盒一份
+     *   临时 LLM 配置，dispose 后随作用域消失（写只进 overlay，save() 为内存
+     *   模式 no-op，磁盘不被污染）
+     *
+     * @example
+     * const sandbox = ctx.createScope('sandbox-group-123');
+     * sandbox.provide('agent', myCustomAgent); // 仅此作用域可见
+     * sandbox.config.setPluginConfig('llm.openai', { temperature: 0.1 }); // 临时配置
+     * sandbox.getService('authority'); // fallback 到父级全局服务
+     */
+    createScope(id) {
+        const scopedServices = this._services.createScope();
+        const scopedConfig = new ScopedConfigManager(this.config);
+        const child = new Context({
+            id,
+            events: this._events,
+            services: scopedServices,
+            hooks: this.hooks,
+            logger: this.logger.child(id),
+            config: scopedConfig,
+            parent: this,
+            devMode: this.devMode,
+        });
+        this._children.add(child);
+        return child;
+    }
+    // ---- 事件 ----
+    on(event, handler) {
+        const off = this._events.on(event, handler);
+        return this.trackDisposable(off);
+    }
+    once(event, handler) {
+        const off = this._events.once(event, handler);
+        return this.trackDisposable(off);
+    }
+    /**
+     * 把一个底层退订原语登记到 disposable 链，并返回**自移除**的退订函数：
+     * 调用方手动退订时，闭包不再滞留 _disposables（否则它持有 handler 引用直到
+     * ctx.dispose——审计 HIGH #2 的同类泄漏，统一所有注册 API 的退订语义）。
+     */
+    trackDisposable(off) {
+        const dispose = () => {
+            this._disposables.remove(dispose);
+            off();
+        };
+        this._disposables.push(dispose);
+        return dispose;
+    }
+    emit(event, ...args) {
+        return this._events.emit(event, ...args);
+    }
+    // ---- 服务 (IoC + 能力声明) ----
+    /**
+     * 注册服务，返回 dispose 函数用于精确卸载该服务
+     *
+     * `capabilities` 参数按服务名获得强类型约束：
+     * - 已注册服务名（如 `'llm'`, `'memory'`）→ 仅允许对应 union 中的字面量
+     * - 未注册服务名 → 退回 `string`，保留动态扩展空间
+     *
+     * @example
+     * ctx.provide('llm', service, { capabilities: ['chat', 'tool_calling'] });
+     * //                                            ^^^^^^  ^^^^^^^^^^^^^^
+     * //                                            类型安全，拼错 'tool_call' 会编译报错
+     *
+     * `entryId` 选项：覆盖默认 contextId（默认 = `this.id`）。用于一个 plugin 实例
+     * 需要按某种语义子粒度拆出多个 entry 的场景（典型：per-model LLM、per-path storage）。
+     * 约定：`entryId` 必须以 `this.id` 为前缀（以 `/` 分隔），以保证 plugin 卸载时
+     * `unregisterByContext(this.id)` 如需清理仍可多次调用；dispose 函数并不依赖这个约定，
+     * 但 dev 模式下会验证以避免 "entryId 与拥有者 plugin 脱联" 的 footgun。
+     */
+    provide(name, instance, options) {
+        const caps = (options?.capabilities ?? []);
+        const entryId = options?.entryId ?? this.id;
+        if (this.devMode) {
+            validateProvide({
+                ctxId: this.id,
+                name,
+                instance,
+                capabilities: caps,
+                entryId,
+                explicitEntryId: options?.entryId !== undefined,
+                priority: options?.priority,
+                services: this._services,
+                logger: this.logger,
+            });
+        }
+        const entry = this._services.register(name, instance, caps, options?.priority ?? 0, entryId, options?.label);
+        const dispose = () => {
+            // 自移除：调用方手动 dispose 后，闭包不再滞留 _disposables（否则它持有
+            // entry 引用，instance 无法 GC，多实例热替换场景累积僵尸——审计 HIGH #2）。
+            // ctx.dispose 经 DisposableChain.dispose 调用本函数时 remove 返回 false，无害。
+            this._disposables.remove(dispose);
+            const removed = this._services.unregisterEntry(name, entry);
+            if (removed) {
+                this._events.emit('service:unregistered', name).catch(err => {
+                    this.logger.warn(`emit service:unregistered 失败 (${name}): ${err}`);
+                });
+            }
+        };
+        this._disposables.push(dispose);
+        emitServiceRegistered(this._events, this.logger, name, caps);
+        this.logger.debug(`服务已注册: ${name}${caps.length ? ` [${caps.join(', ')}]` : ''}`);
+        return dispose;
+    }
+    getService(name, requiredCapabilities) {
+        return this._services.get(name, requiredCapabilities);
+    }
+    /**
+     * 检查服务是否可用
+     */
+    hasService(name, requiredCapabilities) {
+        return this._services.has(name, requiredCapabilities);
+    }
+    /**
+     * 获取服务的能力列表
+     */
+    getServiceCapabilities(name) {
+        return this._services.getCapabilities(name);
+    }
+    /**
+     * 列出所有已注册的服务名
+     */
+    getServiceNames() {
+        return this._services.getServiceNames();
+    }
+    getAllServices(name, requiredCapabilities) {
+        return this._services.getAll(name, requiredCapabilities);
+    }
+    /**
+     * 设置某服务的偏好 provider（按 contextId）
+     *
+     * 语义：「偏好 > 优先级 > 注册顺序」。偏好者总是 `getService(name)` 的第一返回值，
+     * 即使其 priority 数值低于 router 等其他 entry。
+     *
+     * 注：偏好可以提前于 entry 注册前设置——一旦目标 contextId 注册即刻生效。
+     * @returns 始终返回 true（偏好已记录）
+     */
+    preferService(name, contextId) {
+        const ok = this._services.prefer(name, contextId);
+        if (ok) {
+            this.logger.debug(`服务偏好已设置: ${name} -> ${contextId}`);
+            this._events.emit('service:preference-changed', name).catch(err => {
+                this.logger.warn(`emit service:preference-changed 失败 (${name}): ${err}`);
+            });
+        }
+        return ok;
+    }
+    /**
+     * 清除某服务的偏好（恢复 priority + 注册顺序解析）
+     */
+    unpreferService(name) {
+        const ok = this._services.unprefer(name);
+        if (ok) {
+            this.logger.debug(`服务偏好已清除: ${name}`);
+            this._events.emit('service:preference-changed', name).catch(err => {
+                this.logger.warn(`emit service:preference-changed 失败 (${name}): ${err}`);
+            });
+        }
+        return ok;
+    }
+    /**
+     * 读取某服务当前的偏好 contextId（无偏好返回 undefined）
+     */
+    getPreferredService(name) {
+        return this._services.getPreferred(name);
+    }
+    /**
+     * 获取某服务的全部 entry（含 priority），按「偏好 > 优先级 > 注册顺序」排序。
+     *
+     * 主要给管控类消费者（如 WebUI / CLI status 视图）枚举展示用。
+     * 业务消费者应优先使用 `getService` / `getAllServices`。
+     */
+    getServiceEntries(name) {
+        return this._services.getEntries(name);
+    }
+    // biome-ignore lint/suspicious/noConfusingVoidType: cb 可隐式返回 void 或显式返回 cleanup
+    whenService(name, cb) {
+        let cleanup;
+        let disposed = false;
+        /** 当前已挂载的胜者实例；undefined = 未挂载 */
+        let attached;
+        const runCleanup = () => {
+            if (!cleanup)
+                return;
+            try {
+                cleanup();
+            }
+            catch (err) {
+                this.logger.warn(`whenService('${name}') cleanup 抛错（已忽略）:`, err);
+            }
+            cleanup = undefined;
+        };
+        /**
+         * 对齐到容器当前胜者（核心不变量：attached === getService(name)）：
+         * - 胜者未变（如败者 entry 上下线、同胜者重复事件）→ 不动，避免无谓 bounce
+         * - 胜者变了 → 先 cleanup 再用新实例重挂
+         * - 没有胜者了 → 只 cleanup 脱挂
+         * 不读事件 payload、只看容器当前态，天然对事件乱序/合并免疫。
+         */
+        const sync = () => {
+            if (disposed)
+                return;
+            const winner = this._services.get(name);
+            if (winner === attached)
+                return;
+            runCleanup();
+            attached = winner;
+            if (winner === undefined)
+                return;
+            const ret = cb(winner);
+            // cb 执行期间可能同步触发了本 whenService 的 dispose（如 cb 内部链式
+            // 卸载）。此时不能把新 cleanup 挂上去——dispose 已跑过 runCleanup 且
+            // disposed=true，挂上的 cleanup 将永不执行（泄漏）。直接立即执行掉。
+            if (disposed) {
+                if (typeof ret === 'function') {
+                    try {
+                        ret();
+                    }
+                    catch (err) {
+                        this.logger.warn(`whenService('${name}') cleanup 抛错（dispose 期间，已忽略）:`, err);
+                    }
+                }
+                return;
+            }
+            if (typeof ret === 'function')
+                cleanup = ret;
+        };
+        // 持续订阅 provider 上下线 + 偏好切换（不退订），ctx.dispose 时由 disposable 链清理。
+        const offReg = this.on('service:registered', (svcName) => {
+            if (svcName === name)
+                sync();
+        });
+        const offUnreg = this.on('service:unregistered', (svcName) => {
+            if (svcName === name)
+                sync();
+        });
+        const offPref = this.on('service:preference-changed', (svcName) => {
+            if (svcName === name)
+                sync();
+        });
+        // 立即检查：若已就绪则首挂。
+        sync();
+        const dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            this._disposables.remove(dispose); // 自移除，不滞留闭包（对称 provide）
+            offReg();
+            offUnreg();
+            offPref();
+            runCleanup();
+            attached = undefined;
+        };
+        this._disposables.push(dispose);
+        return dispose;
+    }
+    // ---- 中间件/钩子 ----
+    /**
+     * 注册命名生命周期事件 handler（中间件管道）
+     *
+     * 同一钩子键内的多个 handler 按 **注册顺序** 执行洋葱模型 (next 语义)，
+     * 不再使用数字优先级。相位间的次序由调度方（如 plugin-gateway 的入站
+     * 多相位调度）显式表达。
+     *
+     * @example
+     * // 在消息发送给 LLM 前添加额外指令
+     * ctx.middleware('agent:llm:before', async (data, next) => {
+     *   data.messages.unshift({ role: 'system', content: '额外指令...' });
+     *   await next();
+     * });
+     *
+     * // 命令命中后中断后续处理
+     * ctx.middleware('inbound:command', async (data, next) => {
+     *   if (handled(data.message)) return; // 不调用 next = 中断
+     *   await next();
+     * });
+     */
+    middleware(hook, fn) {
+        return this.trackDisposable(this.hooks.register(hook, fn, this.id));
+    }
+    // ---- 生命周期 ----
+    get disposed() {
+        return this._disposed;
+    }
+    /**
+     * 在当前 Context 内动态加载一个插件 module 作为"沙盒插件"。
+     *
+     * 与 `App.plugin(...)` / `PluginManager.register(...)` 的区别：
+     * - 不进入全局 `PluginManager`（不参与依赖追踪、softReload）
+     * - 创建一个 fork/createScope 子上下文，调用 `module.apply(child, config)`
+     * - 返回 dispose：调用即销毁该子上下文，对应子上下文里所有副作用一并清理
+     * - 父 ctx dispose 时也会级联销毁
+     *
+     * 典型场景：
+     * - 会话级动态工具/中间件
+     * - 沙盒（`createScope`）内挂载临时 mini 插件
+     * - 单元测试里组装最小可运行单元
+     *
+     * @param module 任意符合 `{ name, apply(ctx, config) }` 的对象
+     * @param config 传给 apply 的配置（默认 `{}`）
+     * @param options.scoped 是否使用 `createScope`（服务/配置隔离），默认 false 用 `fork`
+     * @returns dispose 函数；返回的 Promise 在 apply 完成后 resolve
+     *
+     * @example
+     * const off = await ctx.useModule({
+     *   name: 'temp-mw',
+     *   apply(c) {
+     *     c.middleware('agent:input:before', async (data, next) => {
+     *       data.message.content += ' [临时标记]';
+     *       await next();
+     *     });
+     *   }
+     * });
+     * // ...
+     * off(); // 卸载临时中间件
+     */
+    async useModule(module, config = {}, options) {
+        if (this._disposed) {
+            throw new Error(`Context "${this.id}" 已 dispose，无法 useModule`);
+        }
+        const childId = `${this.id}#${module.name}`;
+        const child = options?.scoped ? this.createScope(childId) : this.fork(childId);
+        try {
+            await module.apply(child, config);
+        }
+        catch (err) {
+            child.dispose();
+            throw err;
+        }
+        return () => child.dispose();
+    }
+    /**
+     * 注册一个在本 Context dispose 时执行的清理回调。
+     *
+     * 插件清理副作用的**唯一正确 API**：
+     * - 直接挂在 `_disposables` 链上，保证逆序执行
+     * - 在 `ctx.dispose()` 的任何路径上都会触发（app 停机 / bounce / unload /
+     *   updatePluginConfig / softReload 级联 evict）
+     * - 沙盒 / fork 子上下文同样适用
+     *
+     * ⚠． 不要用 `ctx.on('app:stopping', ...)` 做资源清理——那只在 app 全局停机
+     *    时触发一次，**不会**在插件 bounce / hot reload 时触发，会造成旧连接、
+     *    旧定时器泄漏。全局停机不需要特别处理——`onDispose` 也会被触发。
+     *
+     * @example
+     * const conn = await connectExternal();
+     * ctx.onDispose(() => conn.close());
+     *
+     * @returns 取消该清理回调的函数（在 dispose 前调用可阻止执行）
+     */
+    onDispose(fn) {
+        const wrapped = () => {
+            try {
+                const ret = fn();
+                if (ret && typeof ret.then === 'function') {
+                    ret.catch(err => {
+                        this.logger.debug('onDispose 异步清理抛错（已忽略）:', err);
+                    });
+                }
+            }
+            catch (err) {
+                this.logger.debug('onDispose 清理抛错（已忽略）:', err);
+            }
+        };
+        this._disposables.push(wrapped);
+        return () => this._disposables.remove(wrapped);
+    }
+    /** @internal 当前 disposable 链长度（诊断 / 测试用：检测 provide/whenService 的闭包是否如期自移除）。 */
+    get disposableCount() {
+        return this._disposables.size;
+    }
+    /**
+     * 销毁此上下文，清理所有副作用
+     */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        // 先销毁子上下文（复制避免迭代中修改 Set）
+        const children = [...this._children];
+        for (const child of children) {
+            child.dispose();
+        }
+        this._children.clear();
+        // 记录此上下文注册的服务名，以便 dispose 后发射事件
+        const removedServices = this._services.unregisterByContext(this.id);
+        // 逆序执行清理（unregisterByContext 已整体移除服务，provide 的 dispose 会安全跳过）
+        this._disposables.dispose();
+        // 发射服务注销事件，让 App 的自动恢复监听器能响应
+        for (const svc of removedServices) {
+            this._events.emit('service:unregistered', svc).catch(err => {
+                this.logger.warn(`emit service:unregistered 失败 (${svc}): ${err}`);
+            });
+        }
+        // 清理该上下文注册的钩子
+        this.hooks.unregisterByContext(this.id);
+        // 服务自清理协议：任何服务实例若实现 `unregisterByPlugin(contextId)`，
+        // dispose 时统一通知它清理本上下文相关的注册项（如 plugin-tools 的
+        // ToolService、plugin-commands 的 CommandService）。
+        // core 不再硬编码任何具体服务名。
+        // 遍历该服务名下的**所有** entry 而非只通知胜者——败者实例（低优先级
+        // 并存 provider）也可能持有本上下文注册的条目。同名多 entry 可能指向
+        // 同一实例（per-model 拆粒度），按实例去重避免重复通知。
+        for (const name of this._services.getServiceNames()) {
+            const seen = new Set();
+            for (const entry of this._services.getEntries(name)) {
+                if (seen.has(entry.instance))
+                    continue;
+                seen.add(entry.instance);
+                const svc = entry.instance;
+                try {
+                    svc?.unregisterByPlugin?.(this.id);
+                }
+                catch (err) {
+                    this.logger.warn(`服务 "${name}" 的 unregisterByPlugin 抛错:`, err);
+                }
+            }
+        }
+        // 从父上下文中移除
+        if (this._parent) {
+            this._parent._children.delete(this);
+        }
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/disposable-chain.d.ts

@@ -0,0 +1,31 @@
+import type { Logger } from './logger.js';
+/**
+ * 一次性清理器链
+ *
+ * 用途：Context 及其他需要累积「注册 → 卸载」副作用的场景，提供：
+ * - `push(fn)` 追加清理函数
+ * - `remove(fn)` 精确移除单个清理函数（不执行）
+ * - `dispose()` 逆序调用所有清理函数并清空；期间任一抛错不影响其他
+ *
+ * 相比散落的 `this._disposables: (() => void)[]`，集中管理能避免
+ * 「忘记 push / 忘记清空 / 错误处理不一致」等低级 bug。
+ */
+export declare class DisposableChain {
+    private readonly logger?;
+    private _items;
+    private _disposed;
+    constructor(logger?: Logger | undefined);
+    /** 追加一个清理函数。dispose 后追加会立刻执行。 */
+    push(fn: () => void): void;
+    /** 精确移除单个 disposable（不执行）。用于缓冲项"取消"场景。 */
+    remove(fn: () => void): boolean;
+    get disposed(): boolean;
+    /** 当前登记的清理函数数量（诊断 / 测试用：可检测闭包是否如期自移除）。 */
+    get size(): number;
+    /**
+     * 逆序执行所有清理函数并清空。重复调用无效果。
+     * 单个函数抛错被 swallow（可选择通过 logger 记录 debug）。
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=disposable-chain.d.ts.map

package/dist/disposable-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposable-chain.d.ts","sourceRoot":"","sources":["../src/disposable-chain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;;;;;;;GAUG;AACH,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;IAHpC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,SAAS,CAAS;gBAEG,MAAM,CAAC,EAAE,MAAM,YAAA;IAE5C,iCAAiC;IACjC,IAAI,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI;IAY1B,0CAA0C;IAC1C,MAAM,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO;IAO/B,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,0CAA0C;IAC1C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,OAAO,IAAI,IAAI;CAYhB"}

package/dist/disposable-chain.js

@@ -0,0 +1,66 @@
+/**
+ * 一次性清理器链
+ *
+ * 用途：Context 及其他需要累积「注册 → 卸载」副作用的场景，提供：
+ * - `push(fn)` 追加清理函数
+ * - `remove(fn)` 精确移除单个清理函数（不执行）
+ * - `dispose()` 逆序调用所有清理函数并清空；期间任一抛错不影响其他
+ *
+ * 相比散落的 `this._disposables: (() => void)[]`，集中管理能避免
+ * 「忘记 push / 忘记清空 / 错误处理不一致」等低级 bug。
+ */
+export class DisposableChain {
+    logger;
+    _items = [];
+    _disposed = false;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /** 追加一个清理函数。dispose 后追加会立刻执行。 */
+    push(fn) {
+        if (this._disposed) {
+            try {
+                fn();
+            }
+            catch (err) {
+                this.logger?.warn(`DisposableChain: post-dispose 执行失败: ${err}`);
+            }
+            return;
+        }
+        this._items.push(fn);
+    }
+    /** 精确移除单个 disposable（不执行）。用于缓冲项"取消"场景。 */
+    remove(fn) {
+        const idx = this._items.indexOf(fn);
+        if (idx < 0)
+            return false;
+        this._items.splice(idx, 1);
+        return true;
+    }
+    get disposed() {
+        return this._disposed;
+    }
+    /** 当前登记的清理函数数量（诊断 / 测试用：可检测闭包是否如期自移除）。 */
+    get size() {
+        return this._items.length;
+    }
+    /**
+     * 逆序执行所有清理函数并清空。重复调用无效果。
+     * 单个函数抛错被 swallow（可选择通过 logger 记录 debug）。
+     */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        for (let i = this._items.length - 1; i >= 0; i--) {
+            try {
+                this._items[i]();
+            }
+            catch (err) {
+                this.logger?.debug('DisposableChain: dispose 抛出，已忽略:', err);
+            }
+        }
+        this._items = [];
+    }
+}
+//# sourceMappingURL=disposable-chain.js.map

package/dist/disposable-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disposable-chain.js","sourceRoot":"","sources":["../src/disposable-chain.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAe;IAIG;IAHrB,MAAM,GAAmB,EAAE,CAAC;IAC5B,SAAS,GAAG,KAAK,CAAC;IAE1B,YAA6B,MAAe;QAAf,WAAM,GAAN,MAAM,CAAS;IAAG,CAAC;IAEhD,iCAAiC;IACjC,IAAI,CAAC,EAAc;QACjB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,CAAC;gBACH,EAAE,EAAE,CAAC;YACP,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,uCAAuC,GAAG,EAAE,CAAC,CAAC;YAClE,CAAC;YACD,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;IAED,0CAA0C;IAC1C,MAAM,CAAC,EAAc;QACnB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,0CAA0C;IAC1C,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACjD,IAAI,CAAC;gBACH,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACnB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,kCAAkC,EAAE,GAAG,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC;IACnB,CAAC;CACF"}