@aalis/core 0.1.0

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":""}

package/dist/semver-mini.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 轻量级 semver range 校验
+ *
+ * 仅支持 Aalis 插件市场常用的 range 形态，足够用于 manifest.engines.aalis 校验：
+ *   - 精确：`1.2.3`
+ *   - 比较器：`>=1.2.3` / `>1.2.3` / `<=1.2.3` / `<1.2.3` / `=1.2.3`
+ *   - caret：`^1.2.3`（允许 1.x.x，不允许 2.0.0）
+ *   - tilde：`~1.2.3`（允许 1.2.x，不允许 1.3.0）
+ *   - 多个比较器以空格连接，需全部满足：`>=1.2.0 <2.0.0`
+ *   - `*` / 空字符串：任意版本
+ *
+ * 不支持：`||` 或运算、prerelease 标签的精细比较（统一忽略 prerelease）。
+ * 这些限制对 manifest 校验场景是可接受的。
+ */
+/**
+ * 判断 version 是否落在 range 范围内。
+ * range 中的多个比较器以空白分隔，需全部满足（AND 关系）。
+ */
+export declare function satisfies(version: string, range: string | undefined): boolean;
+//# sourceMappingURL=semver-mini.d.ts.map

package/dist/semver-mini.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver-mini.d.ts","sourceRoot":"","sources":["../src/semver-mini.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2DH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAU7E"}

package/dist/semver-mini.js

@@ -0,0 +1,94 @@
+/**
+ * 轻量级 semver range 校验
+ *
+ * 仅支持 Aalis 插件市场常用的 range 形态，足够用于 manifest.engines.aalis 校验：
+ *   - 精确：`1.2.3`
+ *   - 比较器：`>=1.2.3` / `>1.2.3` / `<=1.2.3` / `<1.2.3` / `=1.2.3`
+ *   - caret：`^1.2.3`（允许 1.x.x，不允许 2.0.0）
+ *   - tilde：`~1.2.3`（允许 1.2.x，不允许 1.3.0）
+ *   - 多个比较器以空格连接，需全部满足：`>=1.2.0 <2.0.0`
+ *   - `*` / 空字符串：任意版本
+ *
+ * 不支持：`||` 或运算、prerelease 标签的精细比较（统一忽略 prerelease）。
+ * 这些限制对 manifest 校验场景是可接受的。
+ */
+/** 解析 `major.minor.patch[-prerelease]` 为 [maj, min, pat]，prerelease 忽略。 */
+function parseVersion(v) {
+    const trimmed = v.trim().replace(/^v/, '');
+    const m = trimmed.match(/^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/);
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/** 比较两个版本：返回负数 / 0 / 正数。 */
+function cmp(a, b) {
+    for (let i = 0; i < 3; i++) {
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    }
+    return 0;
+}
+/** 判断单个比较器是否满足版本。 */
+function checkComparator(version, comp) {
+    comp = comp.trim();
+    if (!comp || comp === '*' || comp === 'x')
+        return true;
+    // caret ^x.y.z: >=x.y.z <(x+1).0.0（x>0），或 >=0.y.z <0.(y+1).0（x=0,y>0），或 >=0.0.z <0.0.(z+1)（x=y=0）
+    if (comp.startsWith('^')) {
+        const base = parseVersion(comp.slice(1));
+        if (!base)
+            return false;
+        if (cmp(version, base) < 0)
+            return false;
+        const [maj, min] = base;
+        if (maj > 0)
+            return version[0] === maj;
+        if (min > 0)
+            return version[0] === 0 && version[1] === min;
+        return version[0] === 0 && version[1] === 0 && version[2] === base[2];
+    }
+    // tilde ~x.y.z: >=x.y.z <x.(y+1).0
+    if (comp.startsWith('~')) {
+        const base = parseVersion(comp.slice(1));
+        if (!base)
+            return false;
+        if (cmp(version, base) < 0)
+            return false;
+        return version[0] === base[0] && version[1] === base[1];
+    }
+    // 比较运算符
+    const opMatch = comp.match(/^(>=|<=|>|<|=)?\s*(.+)$/);
+    if (!opMatch)
+        return false;
+    const op = opMatch[1] || '=';
+    const target = parseVersion(opMatch[2]);
+    if (!target)
+        return false;
+    const c = cmp(version, target);
+    switch (op) {
+        case '>=': return c >= 0;
+        case '<=': return c <= 0;
+        case '>': return c > 0;
+        case '<': return c < 0;
+        case '=': return c === 0;
+        default: return false;
+    }
+}
+/**
+ * 判断 version 是否落在 range 范围内。
+ * range 中的多个比较器以空白分隔，需全部满足（AND 关系）。
+ */
+export function satisfies(version, range) {
+    if (!range || !range.trim())
+        return true;
+    const v = parseVersion(version);
+    if (!v)
+        return false;
+    // 简化：不支持 `||`，命中任意 `||` 直接放行（避免误拒），并发出隐式 warning 由调用方处理
+    if (range.includes('||')) {
+        return range.split('||').some(part => satisfies(version, part));
+    }
+    const comparators = range.split(/\s+/).filter(Boolean);
+    return comparators.every(c => checkComparator(v, c));
+}
+//# sourceMappingURL=semver-mini.js.map

package/dist/semver-mini.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semver-mini.js","sourceRoot":"","sources":["../src/semver-mini.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,2EAA2E;AAC3E,SAAS,YAAY,CAAC,CAAS;IAC7B,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC3C,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC5D,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpD,CAAC;AAED,4BAA4B;AAC5B,SAAS,GAAG,CAAC,CAA2B,EAAE,CAA2B;IACnE,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,qBAAqB;AACrB,SAAS,eAAe,CAAC,OAAiC,EAAE,IAAY;IACtE,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IACnB,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAEvD,kGAAkG;IAClG,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACzC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;QACxB,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;QACvC,IAAI,GAAG,GAAG,CAAC;YAAE,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;QAC3D,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,mCAAmC;IACnC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,IAAI,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACzC,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED,QAAQ;IACR,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACtD,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;IAC7B,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,EAAE,EAAE,CAAC;QACX,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACzB,KAAK,GAAG,CAAC,CAAE,OAAO,CAAC,GAAI,CAAC,CAAC;QACzB,KAAK,GAAG,CAAC,CAAE,OAAO,CAAC,GAAI,CAAC,CAAC;QACzB,KAAK,GAAG,CAAC,CAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAC1B,OAAO,CAAC,CAAG,OAAO,KAAK,CAAC;IAC1B,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,OAAe,EAAE,KAAyB;IAClE,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAChC,IAAI,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACrB,wDAAwD;IACxD,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,WAAW,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvD,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/service-helpers.d.ts

@@ -0,0 +1,34 @@
+import type { EventBus } from './events.js';
+import type { Logger } from './logger.js';
+import type { ServiceContainer } from './service.js';
+/**
+ * provide() 的 dev-mode 校验集合：
+ *   1. entryId 必须以 ctxId 为前缀（否则 plugin 卸载时清理不到）
+ *   2. 声明的 capabilities 必须能在 instance 上探测到对应方法
+ *   3. 同一上下文重复 provide 同一服务名静默失效（容器路由按 contextId）
+ *   4. priority 应使用 ServicePriority enum 而非裸数字
+ *
+ * 参数 explicitEntryId 区分"调用方有意覆盖 entryId"vs"使用 ctxId 默认值"——
+ * 前者才触发 entryId 前缀检查与抑制重复 provide warn（有意拆粒度的语义）。
+ *
+ * 失败模式：
+ *   - capabilities 不匹配 → throw（写错的代码不该跑起来）
+ *   - 其它 → warn（提示但不阻断）
+ */
+export declare function validateProvide(args: {
+    ctxId: string;
+    name: string;
+    instance: unknown;
+    capabilities: readonly string[];
+    entryId: string;
+    explicitEntryId: boolean;
+    priority?: number;
+    services: ServiceContainer;
+    logger: Logger;
+}): void;
+/**
+ * 异步发射 service:registered 事件，捕获并 warn 任何监听器抛错。
+ * 抽出为函数主要让 provide() 主体看起来更短。
+ */
+export declare function emitServiceRegistered(events: EventBus, logger: Logger, name: string, capabilities: readonly string[]): void;
+//# sourceMappingURL=service-helpers.d.ts.map

package/dist/service-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-helpers.d.ts","sourceRoot":"","sources":["../src/service-helpers.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIrD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,IAAI,CAyCP;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,MAAM,EAAE,GAC9B,IAAI,CAIN"}

package/dist/service-helpers.js

@@ -0,0 +1,68 @@
+// ============================================================
+// service-helpers.ts — Context 的服务子系统辅助
+//
+// 从 context.ts 拆出来的纯函数，消除 Context 类自身对"如何包装/校验服务"的细节
+// 知识，留下 Context 作为编排者：路由参数 → 调 helper → 登记 disposable。
+//
+// 这里不持有任何状态，所有副作用（注册/警告/事件）都通过参数传入的 services/
+// logger/events 反映出去。便于单元测试（mock 即可）。
+// ============================================================
+import { probeCapability } from './types/capabilities.js';
+import { ServicePriority } from './types/service.js';
+/**
+ * provide() 的 dev-mode 校验集合：
+ *   1. entryId 必须以 ctxId 为前缀（否则 plugin 卸载时清理不到）
+ *   2. 声明的 capabilities 必须能在 instance 上探测到对应方法
+ *   3. 同一上下文重复 provide 同一服务名静默失效（容器路由按 contextId）
+ *   4. priority 应使用 ServicePriority enum 而非裸数字
+ *
+ * 参数 explicitEntryId 区分"调用方有意覆盖 entryId"vs"使用 ctxId 默认值"——
+ * 前者才触发 entryId 前缀检查与抑制重复 provide warn（有意拆粒度的语义）。
+ *
+ * 失败模式：
+ *   - capabilities 不匹配 → throw（写错的代码不该跑起来）
+ *   - 其它 → warn（提示但不阻断）
+ */
+export function validateProvide(args) {
+    const { ctxId, name, instance, capabilities, entryId, explicitEntryId, priority, services, logger } = args;
+    if (explicitEntryId && entryId !== ctxId && !entryId.startsWith(`${ctxId}/`)) {
+        logger.warn(`服务 "${name}" 的 entryId "${entryId}" 不以 "${ctxId}/" 为前缀。` +
+            `违反约定后 plugin 卸载时可能遗漏清理。` +
+            `推荐格式：\`\${ctx.id}/\${子粒度标识}\`。`);
+    }
+    const failures = [];
+    for (const cap of capabilities) {
+        const result = probeCapability(name, cap, instance);
+        if (typeof result === 'string')
+            failures.push(`  - [${cap}] ${result}`);
+    }
+    if (failures.length > 0) {
+        throw new Error(`服务 "${name}" 声明的能力与实例实现不符（provide 拒绝注册）:\n${failures.join('\n')}`);
+    }
+    if (!explicitEntryId && services.hasByContext(name, ctxId)) {
+        logger.warn(`服务 "${name}" 已被当前上下文 "${ctxId}" provide 过一次。容器允许多 entry，` +
+            `但下游按 contextId 路由时仅能命中首个，后续注册将静默失效。` +
+            `如需多实例（如多套 API key），请在插件 module 上声明 reusable=true，` +
+            `然后在 config 中用 "<name>:<suffix>" 形式注册多份。` +
+            `若是有意拆出多个子粒度 entry（如 per-model LLM），请传入 options.entryId。`);
+    }
+    if (priority !== undefined) {
+        const standard = Object.values(ServicePriority);
+        if (!standard.includes(priority)) {
+            // 裸数字作为细粒度预留滩位是合理设计（如 priority=10 在 Backend 与 Override 之间插入），
+            // 不强制使用 enum。但保留 debug 日志，方便排查「谁是默认胜者」问题。
+            logger.debug(`服务 "${name}" 使用裸数字 priority=${priority}（非 ServicePriority enum：Backend=0/Override=50/System=200）。` +
+                `这是允许的，但插件作者须自行记载该数值含义以便下游推断胜者。`);
+        }
+    }
+}
+/**
+ * 异步发射 service:registered 事件，捕获并 warn 任何监听器抛错。
+ * 抽出为函数主要让 provide() 主体看起来更短。
+ */
+export function emitServiceRegistered(events, logger, name, capabilities) {
+    events.emit('service:registered', name, [...capabilities]).catch(err => {
+        logger.warn(`服务注册事件发射失败 [${name}]:`, err);
+    });
+}
+//# sourceMappingURL=service-helpers.js.map

package/dist/service-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-helpers.js","sourceRoot":"","sources":["../src/service-helpers.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,wCAAwC;AACxC,EAAE;AACF,qDAAqD;AACrD,uDAAuD;AACvD,EAAE;AACF,8CAA8C;AAC9C,sCAAsC;AACtC,+DAA+D;AAK/D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,IAU/B;IACC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAE3G,IAAI,eAAe,IAAI,OAAO,KAAK,KAAK,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;QAC7E,MAAM,CAAC,IAAI,CACT,OAAO,IAAI,gBAAgB,OAAO,SAAS,KAAK,SAAS;YACvD,yBAAyB;YACzB,gCAAgC,CACnC,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QACpD,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,QAAQ,CAAC,IAAI,CAAC,QAAQ,GAAG,KAAK,MAAM,EAAE,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,kCAAkC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtF,CAAC;IAED,IAAI,CAAC,eAAe,IAAI,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,CAAC,IAAI,CACT,OAAO,IAAI,cAAc,KAAK,4BAA4B;YACxD,qCAAqC;YACrC,mDAAmD;YACnD,yCAAyC;YACzC,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,eAAe,CAAa,CAAC;QAC5D,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,8DAA8D;YAC9D,0CAA0C;YAC1C,MAAM,CAAC,KAAK,CACV,OAAO,IAAI,oBAAoB,QAAQ,4DAA4D;gBACjG,gCAAgC,CACnC,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAgB,EAChB,MAAc,EACd,IAAY,EACZ,YAA+B;IAE/B,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE,IAAI,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;QACrE,MAAM,CAAC,IAAI,CAAC,eAAe,IAAI,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/service.d.ts

@@ -0,0 +1,145 @@
+import { type NormalizedDependency, normalizeDependency, type ServiceEntry, ServicePriority, type ServicePriorityValue } from './types/service.js';
+export type { NormalizedDependency, ServiceEntry, ServicePriorityValue };
+export { normalizeDependency, ServicePriority };
+/**
+ * 服务容器 —— 支持同名多实现 + 能力匹配
+ *
+ * 设计要点：
+ * - 同一个服务名可以有多个提供者（不同能力集）
+ * - 获取服务时可指定所需能力, 容器会匹配满足所有能力的最高优先级提供者
+ * - 每个注册都关联 contextId, 以便在插件卸载时批量清理
+ */
+export declare class ServiceContainer {
+    private entries;
+    /** 服务偏好：service name → preferred contextId（preferred 永远胜过 priority） */
+    private preferences;
+    /**
+     * 注册一个服务实例
+     *
+     * @returns 刚插入的 ServiceEntry，调用方可以该引用调用 {@link unregisterEntry} 精确删除这一条。
+     */
+    register(name: string, instance: unknown, capabilities?: string[], priority?: number, contextId?: string, label?: string): ServiceEntry;
+    /**
+     * 按解析顺序返回某服务的所有 entry：
+     *
+     *   1. 用户偏好的 entry（如有，且仍存在）
+     *   2. 其余 entry，按 priority 降序 + 注册顺序
+     *
+     * 这是 get/getEntries/getAll 的共同基础——保证「偏好 > 优先级 > 注册顺序」语义在所有读路径一致。
+     */
+    private resolveEntries;
+    /**
+     * 获取一个满足能力要求的服务实例
+     */
+    get<T>(name: string, requiredCapabilities?: readonly string[]): T | undefined;
+    /**
+     * 检查某个服务是否存在（并且满足指定能力）
+     */
+    has(name: string, requiredCapabilities?: readonly string[]): boolean;
+    /**
+     * 检查指定 contextId 是否注册了某个服务。
+     *
+     * "拥有" 语义：同时匹配 `contextId === ownerId` 和 per-entry 拆粒度的
+     * `contextId` 以 `ownerId + '/'` 为前缀的子 entry（如 `@aalis/plugin-ollama:main/llama3`）。
+     */
+    hasByContext(name: string, contextId: string): boolean;
+    /**
+     * 获取某个服务的所有能力列表（合并所有提供者）
+     */
+    getCapabilities(name: string): string[];
+    /**
+     * 按 entry 引用精确删除某个提供者（推荐）
+     *
+     * 避免 "同一 contextId 多次 register" 场景下按 contextId 删除会命中错误条目的 footgun。
+     * @returns 是否成功删除
+     */
+    unregisterEntry(name: string, entry: ServiceEntry): boolean;
+    /**
+     * 按 contextId 移除该上下文拥有的所有服务 entry，返回被移除的服务名列表。
+     *
+     * "拥有" 同 hasByContext：包括 `contextId === id` 和以 `id + '/'` 为前缀的 per-entry 子 entry。
+     * 这是插件 unload 时清理多 entry 注册（per-model LLM / per-root storage / …）的路径。
+     */
+    unregisterByContext(contextId: string): string[];
+    /**
+     * 列出所有已注册的服务名
+     */
+    getServiceNames(): string[];
+    /**
+     * 获取某个服务的所有 entry（给 API 暴露用）
+     *
+     * 返回顺序遵循「偏好 > 优先级 > 注册顺序」。
+     */
+    getEntries(name: string): ServiceEntry[];
+    /**
+     * 获取某个服务的所有实例（带提供者信息）
+     *
+     * 可选 requiredCapabilities 过滤：只返回满足所有所需能力的提供者。
+     * 返回顺序遵循「偏好 > 优先级 > 注册顺序」。
+     */
+    getAll<T>(name: string, requiredCapabilities?: readonly string[]): Array<{
+        instance: T;
+        contextId: string;
+        capabilities: string[];
+        label?: string;
+    }>;
+    /**
+     * 设置某服务的偏好 provider（按 contextId）
+     *
+     * 语义：偏好 > 优先级 > 注册顺序。即偏好 entry 总会被 `get()` 第一个返回，
+     * 哪怕它的 priority 数值低于 router 等其他 entry。
+     *
+     * @returns true 表示偏好已记录（即使目标 entry 当下尚未注册也会接受——一旦注册即生效）
+     * @internal 公开 API 走 `ctx.preferService()`（额外 emit service:preference-changed
+     *   触发 whenService 重挂）；本方法仅供 Context 内部转发，插件勿直接调用。
+     */
+    prefer(name: string, contextId: string): boolean;
+    /**
+     * 清除某服务的偏好（恢复 priority + 注册顺序解析）
+     * @internal 公开 API 走 `ctx.unpreferService()`；本方法仅供 Context 内部转发。
+     */
+    unprefer(name: string): boolean;
+    /**
+     * 读取某服务当前的偏好 contextId（无偏好返回 undefined）
+     * @internal 公开 API 走 `ctx.getPreferredService()`；本方法仅供 Context 内部转发。
+     */
+    getPreferred(name: string): string | undefined;
+    /**
+     * 创建作用域子容器
+     *
+     * 子容器读取时先查本地，miss 则 fallback 到父容器；
+     * 写入（register）仅影响子容器自身。
+     *
+     * 适用于沙盒/会话隔离场景：每个沙盒拥有独立的服务覆盖，
+     * 同时继承全局公共服务（如 authority、commands）。
+     *
+     * @example
+     * const scoped = container.createScope();
+     * scoped.register('agent', sandboxAgent); // 仅沙盒可见
+     * scoped.get('authority'); // fallback 到父容器
+     */
+    createScope(): ScopedServiceContainer;
+}
+/**
+ * 作用域服务容器 —— ServiceContainer 的子容器
+ *
+ * - get / has / getEntries / getServiceNames: 先查本地，miss 则 fallback 到父容器
+ * - register / unregisterEntry: 仅操作本地，不影响父容器
+ * - 支持多层嵌套: ScopedServiceContainer.createScope() 返回更深层的子容器
+ */
+export declare class ScopedServiceContainer extends ServiceContainer {
+    readonly parent: ServiceContainer;
+    constructor(parent: ServiceContainer);
+    get<T>(name: string, requiredCapabilities?: readonly string[]): T | undefined;
+    has(name: string, requiredCapabilities?: readonly string[]): boolean;
+    getCapabilities(name: string): string[];
+    getServiceNames(): string[];
+    getEntries(name: string): ServiceEntry[];
+    getAll<T>(name: string, requiredCapabilities?: readonly string[]): Array<{
+        instance: T;
+        contextId: string;
+        capabilities: string[];
+        label?: string;
+    }>;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

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

package/dist/service.js

@@ -0,0 +1,279 @@
+import { normalizeDependency, ServicePriority, } from './types/service.js';
+// 类型与纯辅助 re-export，保留同名旧导入路径
+export { normalizeDependency, ServicePriority };
+/**
+ * 服务容器 —— 支持同名多实现 + 能力匹配
+ *
+ * 设计要点：
+ * - 同一个服务名可以有多个提供者（不同能力集）
+ * - 获取服务时可指定所需能力, 容器会匹配满足所有能力的最高优先级提供者
+ * - 每个注册都关联 contextId, 以便在插件卸载时批量清理
+ */
+export class ServiceContainer {
+    entries = new Map();
+    /** 服务偏好：service name → preferred contextId（preferred 永远胜过 priority） */
+    preferences = new Map();
+    /**
+     * 注册一个服务实例
+     *
+     * @returns 刚插入的 ServiceEntry，调用方可以该引用调用 {@link unregisterEntry} 精确删除这一条。
+     */
+    register(name, instance, capabilities = [], priority = 0, contextId = 'root', label) {
+        let list = this.entries.get(name);
+        if (!list) {
+            list = [];
+            this.entries.set(name, list);
+        }
+        const entry = {
+            instance,
+            capabilities: new Set(capabilities),
+            priority,
+            contextId,
+            label,
+        };
+        list.push(entry);
+        // 按优先级降序排列（稳定排序：同优先级先注册者在前）
+        list.sort((a, b) => b.priority - a.priority);
+        return entry;
+    }
+    /**
+     * 按解析顺序返回某服务的所有 entry：
+     *
+     *   1. 用户偏好的 entry（如有，且仍存在）
+     *   2. 其余 entry，按 priority 降序 + 注册顺序
+     *
+     * 这是 get/getEntries/getAll 的共同基础——保证「偏好 > 优先级 > 注册顺序」语义在所有读路径一致。
+     */
+    resolveEntries(name) {
+        const list = this.entries.get(name);
+        if (!list || list.length === 0)
+            return [];
+        const preferredCtxId = this.preferences.get(name);
+        if (!preferredCtxId)
+            return list;
+        const preferred = list.find(e => e.contextId === preferredCtxId);
+        if (!preferred)
+            return list;
+        return [preferred, ...list.filter(e => e !== preferred)];
+    }
+    /**
+     * 获取一个满足能力要求的服务实例
+     */
+    get(name, requiredCapabilities) {
+        const list = this.resolveEntries(name);
+        if (list.length === 0)
+            return undefined;
+        for (const entry of list) {
+            if (requiredCapabilities && requiredCapabilities.length > 0) {
+                const satisfied = requiredCapabilities.every(c => entry.capabilities.has(c));
+                if (!satisfied)
+                    continue;
+            }
+            return entry.instance;
+        }
+        return undefined;
+    }
+    /**
+     * 检查某个服务是否存在（并且满足指定能力）
+     */
+    has(name, requiredCapabilities) {
+        return this.get(name, requiredCapabilities) !== undefined;
+    }
+    /**
+     * 检查指定 contextId 是否注册了某个服务。
+     *
+     * "拥有" 语义：同时匹配 `contextId === ownerId` 和 per-entry 拆粒度的
+     * `contextId` 以 `ownerId + '/'` 为前缀的子 entry（如 `@aalis/plugin-ollama:main/llama3`）。
+     */
+    hasByContext(name, contextId) {
+        const list = this.entries.get(name);
+        if (!list)
+            return false;
+        const prefix = `${contextId}/`;
+        return list.some(e => e.contextId === contextId || e.contextId.startsWith(prefix));
+    }
+    /**
+     * 获取某个服务的所有能力列表（合并所有提供者）
+     */
+    getCapabilities(name) {
+        const list = this.entries.get(name);
+        if (!list)
+            return [];
+        const caps = new Set();
+        for (const entry of list) {
+            for (const c of entry.capabilities)
+                caps.add(c);
+        }
+        return [...caps];
+    }
+    /**
+     * 按 entry 引用精确删除某个提供者（推荐）
+     *
+     * 避免 "同一 contextId 多次 register" 场景下按 contextId 删除会命中错误条目的 footgun。
+     * @returns 是否成功删除
+     */
+    unregisterEntry(name, entry) {
+        const list = this.entries.get(name);
+        if (!list)
+            return false;
+        const idx = list.indexOf(entry);
+        if (idx < 0)
+            return false;
+        list.splice(idx, 1);
+        if (list.length === 0)
+            this.entries.delete(name);
+        return true;
+    }
+    /**
+     * 按 contextId 移除该上下文拥有的所有服务 entry，返回被移除的服务名列表。
+     *
+     * "拥有" 同 hasByContext：包括 `contextId === id` 和以 `id + '/'` 为前缀的 per-entry 子 entry。
+     * 这是插件 unload 时清理多 entry 注册（per-model LLM / per-root storage / …）的路径。
+     */
+    unregisterByContext(contextId) {
+        const removed = [];
+        const prefix = `${contextId}/`;
+        for (const [name, list] of this.entries) {
+            const before = list.length;
+            const filtered = list.filter(e => e.contextId !== contextId && !e.contextId.startsWith(prefix));
+            if (filtered.length < before) {
+                removed.push(name);
+            }
+            if (filtered.length === 0) {
+                this.entries.delete(name);
+            }
+            else {
+                this.entries.set(name, filtered);
+            }
+        }
+        return removed;
+    }
+    /**
+     * 列出所有已注册的服务名
+     */
+    getServiceNames() {
+        return [...this.entries.keys()];
+    }
+    /**
+     * 获取某个服务的所有 entry（给 API 暴露用）
+     *
+     * 返回顺序遵循「偏好 > 优先级 > 注册顺序」。
+     */
+    getEntries(name) {
+        return this.resolveEntries(name);
+    }
+    /**
+     * 获取某个服务的所有实例（带提供者信息）
+     *
+     * 可选 requiredCapabilities 过滤：只返回满足所有所需能力的提供者。
+     * 返回顺序遵循「偏好 > 优先级 > 注册顺序」。
+     */
+    getAll(name, requiredCapabilities) {
+        const list = this.resolveEntries(name);
+        if (list.length === 0)
+            return [];
+        const result = [];
+        for (const entry of list) {
+            if (requiredCapabilities && requiredCapabilities.length > 0) {
+                const satisfied = requiredCapabilities.every(c => entry.capabilities.has(c));
+                if (!satisfied)
+                    continue;
+            }
+            result.push({
+                instance: entry.instance,
+                contextId: entry.contextId,
+                capabilities: [...entry.capabilities],
+                label: entry.label,
+            });
+        }
+        return result;
+    }
+    /**
+     * 设置某服务的偏好 provider（按 contextId）
+     *
+     * 语义：偏好 > 优先级 > 注册顺序。即偏好 entry 总会被 `get()` 第一个返回，
+     * 哪怕它的 priority 数值低于 router 等其他 entry。
+     *
+     * @returns true 表示偏好已记录（即使目标 entry 当下尚未注册也会接受——一旦注册即生效）
+     * @internal 公开 API 走 `ctx.preferService()`（额外 emit service:preference-changed
+     *   触发 whenService 重挂）；本方法仅供 Context 内部转发，插件勿直接调用。
+     */
+    prefer(name, contextId) {
+        this.preferences.set(name, contextId);
+        return true;
+    }
+    /**
+     * 清除某服务的偏好（恢复 priority + 注册顺序解析）
+     * @internal 公开 API 走 `ctx.unpreferService()`；本方法仅供 Context 内部转发。
+     */
+    unprefer(name) {
+        return this.preferences.delete(name);
+    }
+    /**
+     * 读取某服务当前的偏好 contextId（无偏好返回 undefined）
+     * @internal 公开 API 走 `ctx.getPreferredService()`；本方法仅供 Context 内部转发。
+     */
+    getPreferred(name) {
+        return this.preferences.get(name);
+    }
+    /**
+     * 创建作用域子容器
+     *
+     * 子容器读取时先查本地，miss 则 fallback 到父容器；
+     * 写入（register）仅影响子容器自身。
+     *
+     * 适用于沙盒/会话隔离场景：每个沙盒拥有独立的服务覆盖，
+     * 同时继承全局公共服务（如 authority、commands）。
+     *
+     * @example
+     * const scoped = container.createScope();
+     * scoped.register('agent', sandboxAgent); // 仅沙盒可见
+     * scoped.get('authority'); // fallback 到父容器
+     */
+    createScope() {
+        return new ScopedServiceContainer(this);
+    }
+}
+/**
+ * 作用域服务容器 —— ServiceContainer 的子容器
+ *
+ * - get / has / getEntries / getServiceNames: 先查本地，miss 则 fallback 到父容器
+ * - register / unregisterEntry: 仅操作本地，不影响父容器
+ * - 支持多层嵌套: ScopedServiceContainer.createScope() 返回更深层的子容器
+ */
+export class ScopedServiceContainer extends ServiceContainer {
+    parent;
+    constructor(parent) {
+        super();
+        this.parent = parent;
+    }
+    get(name, requiredCapabilities) {
+        const local = super.get(name, requiredCapabilities);
+        if (local !== undefined)
+            return local;
+        return this.parent.get(name, requiredCapabilities);
+    }
+    has(name, requiredCapabilities) {
+        return super.has(name, requiredCapabilities) || this.parent.has(name, requiredCapabilities);
+    }
+    getCapabilities(name) {
+        const local = super.getCapabilities(name);
+        const parent = this.parent.getCapabilities(name);
+        return [...new Set([...local, ...parent])];
+    }
+    getServiceNames() {
+        return [...new Set([...super.getServiceNames(), ...this.parent.getServiceNames()])];
+    }
+    getEntries(name) {
+        const local = super.getEntries(name);
+        const parent = this.parent.getEntries(name);
+        // 本地条目优先（在前），父容器条目在后
+        return [...local, ...parent];
+    }
+    getAll(name, requiredCapabilities) {
+        const local = super.getAll(name, requiredCapabilities);
+        const parent = this.parent.getAll(name, requiredCapabilities);
+        return [...local, ...parent];
+    }
+}
+//# sourceMappingURL=service.js.map