@dreanzy/dsh-skill-pack 0.1.0

package/lib/inventory.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 清单读取与官方判定。
+ *
+ * 只有一条硬约束：**清单不完整时不许拿它算隐藏集**。不完整意味着有些名字暂时
+ * 没读到，而「没读到」与「清单里不存在」在求值上看起来一样——用它重算会把
+ * 本来关着的项当成不需要处理而悄悄放行。宁可这一轮不动，也不要放行。
+ */
+/** `ctx.skills.snapshot()` 返回条目里本插件用到的字段。 */
+export interface SkillSummaryLike {
+    readonly name: string;
+    readonly description: string;
+    readonly path?: string;
+    readonly provider: string;
+    readonly source: string;
+    readonly invocation?: {
+        readonly modelInvocable?: boolean;
+        readonly userInvocable?: boolean;
+    };
+}
+/** 宿主 `skills` 服务在本插件用到的面。 */
+export interface SkillsFace {
+    snapshot(options: {
+        cwd?: string;
+        scope?: unknown;
+    }): Promise<{
+        skills: readonly SkillSummaryLike[];
+        complete: boolean;
+    }>;
+    get(name: string, options?: {
+        cwd?: string;
+        scope?: unknown;
+    }): Promise<{
+        readonly content?: string;
+    } | undefined>;
+    register(skill: {
+        readonly name: string;
+        readonly description: string;
+        readonly content: string;
+        readonly source: string;
+        readonly path?: string;
+        readonly invocation?: {
+            readonly modelInvocable: boolean;
+            readonly userInvocable: boolean;
+        };
+    }): () => void;
+}
+export interface Inventory {
+    readonly rows: readonly SkillSummaryLike[];
+    readonly complete: boolean;
+}
+export declare function isOfficialSkill(entry: {
+    path?: string;
+    provider?: string;
+}): boolean;

package/lib/inventory.js

@@ -0,0 +1,34 @@
+/**
+ * 清单读取与官方判定。
+ *
+ * 只有一条硬约束：**清单不完整时不许拿它算隐藏集**。不完整意味着有些名字暂时
+ * 没读到，而「没读到」与「清单里不存在」在求值上看起来一样——用它重算会把
+ * 本来关着的项当成不需要处理而悄悄放行。宁可这一轮不动，也不要放行。
+ */
+/**
+ * 清单读取只剩「调宿主 `snapshot()` 一次」这一件事。
+ *
+ * 缓存与失效搬到了 `snapshot.ts`：那里的键含 scope 身份，而且与 hooks、路由共用，
+ * 所以面板与模型看到的是同一次求值的结果。这里刻意不再留第二份缓存——两份缓存
+ * 必然分叉，早先按「cwd + 有没有 scope」建键时，不同 preset 的会话会读到彼此的清单。
+ *
+ * 读清单的调用点只剩 hooks 的 `readFresh`；`cwd` 缺省时读全局清单（`snapshot({})`），
+ * 不要用空字符串表示「全局」：`''` 会被当作一个目录去解析工程根。
+ */
+/**
+ * 官方 `@deepseek-ai` 基础设施 skill。
+ *
+ * 判定只能靠路径与 provider 白名单，不能靠 `source`：官方那批由同一个
+ * `filesystem` provider 持有，`source` 与用户自己的 custom skill 完全相同，
+ * 按 source 过滤会把用户技能一起误伤。
+ *
+ * 第二条判据覆盖「没有 path」的官方 provider（`dsh-office` 注册的 `office-*`
+ * 不填 path）。名单是白名单：名单外的第三方 provider 照常展示。
+ */
+const OFFICIAL_SCOPE = '@deepseek-ai';
+const OFFICIAL_PROVIDERS = new Set(['dsh-office']);
+export function isOfficialSkill(entry) {
+    if (entry.path !== undefined && entry.path.includes(OFFICIAL_SCOPE))
+        return true;
+    return entry.provider !== undefined && OFFICIAL_PROVIDERS.has(entry.provider);
+}

package/lib/policy.d.ts

@@ -0,0 +1,85 @@
+import { type Bindings, type GroupRegistry, type Pack, type PackBook, type ParseResult, type UiState } from './types.js';
+/**
+ * 工作区键归一：同一目录的不同写法必须落到同一个键。
+ *
+ * 反斜杠转正斜杠、剥除尾部斜杠、Windows 下转小写；盘符根目录保留尾斜杠。
+ * 这份实现是**唯一一份**：绑定表的键（store）、求值缓存的键（snapshot），
+ * 以及任何按 cwd 找绑定的调用点都调它。复制一份必然分叉，表现是「绑定了却不生效」。
+ */
+export declare function normalizeCwd(cwd: string | null): string | null;
+/** `packs.json` 的解析结果：pack 名册与 `ui` 段同住一个文件。 */
+export interface ParsedPacks {
+    readonly book: PackBook;
+    readonly ui: UiState;
+}
+/**
+ * 解析 `packs.json`。
+ *
+ * `default` 缺席时补一个空 pack：它是求值链的终点，不能不存在。补的行为留一条
+ * warning，因为正常写入路径永远会写出 `default`，缺席意味着文件被外部改坏。
+ */
+export declare function parsePacks(text: string | undefined): ParseResult<ParsedPacks>;
+/** 解析 `workspaces.json`。绑定键与 `extra` 都在读取时归一，缺失即空表。 */
+export declare function parseBindings(text: string | undefined): ParseResult<Bindings>;
+/**
+ * 解析组定义。
+ *
+ * 成员搬进 `assignments`（项为主键），查询「这一项属于哪个组」是 O(1)；
+ * 反查「这一组有哪些项」扫一遍即可，几百项的量级不值得维护两份索引。
+ * 指向未知分组的条目保留不删：组被临时删除再建回来时语义自动恢复。
+ */
+export declare function parseGroups(text: string | undefined): ParseResult<GroupRegistry>;
+/**
+ * 序列化 `packs.json`。
+ *
+ * 键排序 + 两空格 + 结尾换行是硬要求：同一份策略必须序列化成同一串字节，
+ * 否则每次保存都产生一次无意义的 git 差异。`ui` 段总是写全，`default` 总是在。
+ */
+export declare function serializePacks(packs: Readonly<Record<string, Pack>>, ui: UiState): string;
+/** 序列化 `workspaces.json`：绑定键排序，`extra` 保持用户添加顺序。 */
+export declare function serializeBindings(bindings: Bindings): string;
+export declare function serializeGroups(registry: GroupRegistry): string;
+/** 取名册里的 default。解析保证它存在，这里只是给类型收窄一个出口。 */
+export declare function defaultPackOf(book: PackBook): Pack;
+/** 一次求值的结论：值、做出决定的 pack，以及落在 pack 的哪一级。 */
+export interface Decision {
+    readonly value: boolean;
+    /** 做出决定的 pack id；取内置缺省时是 `default`。 */
+    readonly packId: string;
+    /** `builtin` 表示两层都没有记录，取缺省值 `true`。 */
+    readonly via: 'item' | 'group' | 'builtin';
+}
+/** 求值上下文：工作区绑定的 pack、default pack 与组归属。 */
+export interface ResolverInput {
+    /** 工作区绑定的 pack；未绑定、绑定悬空或绑定到 `default` 时为 `null`。 */
+    readonly pack: Pack | null;
+    /** `pack` 的 id；`pack` 为 `null` 时忽略。 */
+    readonly packId?: string;
+    /** 求值链的终点：`packs.json` 里的 `default`。 */
+    readonly defaultPack: Pack;
+    /**
+     * 组定义与归属。只有仍存在于 `groups` 里的 id 才参与组级求值：指向已删分组的
+     * 残留归属若照旧去 `pack.groups` 取值，一个早已不存在的组还能靠遗留开关
+     * 决定 skill 可不可见，而面板上它显示为「未分组」。
+     */
+    readonly groups: GroupRegistry;
+}
+export interface Resolver {
+    /** 某一项此刻是否开着。 */
+    isOpen(name: string): boolean;
+    /** 某一项的分组 id，未分组时 `undefined`。 */
+    groupOf(name: string): string | undefined;
+    /** 某一项的决定来源；都没有记录时返回内置缺省。 */
+    decide(name: string): Decision;
+}
+/**
+ * 建一个求值器，链序是：
+ *
+ * ```
+ * pack.items[项] ?? pack.groups[组] ?? default.items[项] ?? default.groups[组] ?? true
+ * ```
+ *
+ * 用 `!== undefined` 而不是 `||`：`false` 是「明令关」，必须原样保留。
+ * 绑定悬空时调用方传 `pack: null`，求值自然退回 `default`。
+ */
+export declare function createResolver(input: ResolverInput): Resolver;

package/lib/policy.js

@@ -0,0 +1,386 @@
+import { DEFAULT_PACK_ID, DEFAULT_PACK_NAME, EMPTY_BINDINGS, EMPTY_GROUPS, EMPTY_PACK, EMPTY_UI, } from './types.js';
+/** 单个域的名字上限，只为防止文件被写成无界清单。 */
+const MAX_NAMES = 2000;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function sortMap(map) {
+    const out = {};
+    for (const key of Object.keys(map).sort()) {
+        const value = map[key];
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+/**
+ * 解析一张「名字 → 布尔」表。
+ *
+ * **不校验名字形状**：表里记录的是用户的决定，不是当前清单的投影；
+ * 名字暂时不存在（还没装、已卸载）时仍要保留，否则卸载再装回来决定就没了。
+ */
+function parseMap(raw, label, warnings) {
+    const out = {};
+    if (raw === undefined)
+        return out;
+    if (!isRecord(raw)) {
+        warnings.push(`${label} 不是对象，已忽略`);
+        return out;
+    }
+    const names = Object.keys(raw).sort();
+    if (names.length > MAX_NAMES) {
+        warnings.push(`${label} 超过 ${MAX_NAMES} 项，已只保留前 ${MAX_NAMES} 项`);
+        names.length = MAX_NAMES;
+    }
+    for (const name of names) {
+        const value = raw[name];
+        if (typeof value !== 'boolean') {
+            warnings.push(`${label}.${name} 不是布尔值，已忽略`);
+            continue;
+        }
+        out[name] = value;
+    }
+    return out;
+}
+function readJson(text, warnings) {
+    if (text === undefined || text.trim() === '')
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (error) {
+        warnings.push(`文件不是合法 JSON，已按空策略处理：${String(error)}`);
+        return null;
+    }
+    if (!isRecord(raw)) {
+        warnings.push('文件顶层不是对象，已按空策略处理');
+        return null;
+    }
+    return raw;
+}
+/**
+ * 工作区键归一：同一目录的不同写法必须落到同一个键。
+ *
+ * 反斜杠转正斜杠、剥除尾部斜杠、Windows 下转小写；盘符根目录保留尾斜杠。
+ * 这份实现是**唯一一份**：绑定表的键（store）、求值缓存的键（snapshot），
+ * 以及任何按 cwd 找绑定的调用点都调它。复制一份必然分叉，表现是「绑定了却不生效」。
+ */
+export function normalizeCwd(cwd) {
+    if (cwd === null)
+        return null;
+    const trimmed = cwd.trim();
+    if (trimmed === '')
+        return null;
+    let unified = trimmed.replace(/\\/gu, '/');
+    if (process.platform === 'win32')
+        unified = unified.toLowerCase();
+    if (unified.length > 1) {
+        const stripped = unified.replace(/\/+$/u, '');
+        if (stripped === '')
+            return '/';
+        // `C:/` 去掉尾斜杠会变成 `C:`，那不是一个目录。
+        return /^[a-z]:$/iu.test(stripped) ? stripped + '/' : stripped;
+    }
+    return unified;
+}
+function parseUi(raw, warnings) {
+    if (raw === undefined)
+        return { ...EMPTY_UI };
+    if (!isRecord(raw)) {
+        warnings.push('ui 不是对象，已用缺省值');
+        return { ...EMPTY_UI };
+    }
+    // chip 缺省开着：文件里没写这个键时，用户期待入口在。
+    // 未知键（例如已废弃的 `showSidebarEntry`）原样忽略，不报警告。
+    return {
+        showOfficialSkills: typeof raw['showOfficialSkills'] === 'boolean' ? raw['showOfficialSkills'] : false,
+        showChip: typeof raw['showChip'] === 'boolean' ? raw['showChip'] : true,
+        defaultTab: raw['defaultTab'] === 'packs' || raw['defaultTab'] === 'workspace' ? raw['defaultTab'] : 'groups',
+    };
+}
+function parsePack(id, raw, warnings) {
+    if (!isRecord(raw)) {
+        warnings.push(`packs.${id} 不是对象，已按空 pack 处理`);
+        return { name: id, items: {}, groups: {} };
+    }
+    const nameRaw = raw['name'];
+    const name = typeof nameRaw === 'string' && nameRaw.trim() !== '' ? nameRaw : id;
+    if (name !== nameRaw)
+        warnings.push(`packs.${id}.name 缺失或不是非空字符串，已用 id 代替`);
+    return {
+        name,
+        items: parseMap(raw['items'], `packs.${id}.items`, warnings),
+        groups: parseMap(raw['groups'], `packs.${id}.groups`, warnings),
+    };
+}
+/**
+ * 解析 `packs.json`。
+ *
+ * `default` 缺席时补一个空 pack：它是求值链的终点，不能不存在。补的行为留一条
+ * warning，因为正常写入路径永远会写出 `default`，缺席意味着文件被外部改坏。
+ */
+export function parsePacks(text) {
+    const warnings = [];
+    const raw = readJson(text, warnings);
+    const ui = parseUi(raw?.['ui'], warnings);
+    const packs = {};
+    if (raw !== null) {
+        const rawPacks = raw['packs'];
+        if (rawPacks !== undefined) {
+            if (!isRecord(rawPacks)) {
+                warnings.push('packs 不是对象，已忽略');
+            }
+            else {
+                const ids = Object.keys(rawPacks).sort();
+                if (ids.length > MAX_NAMES) {
+                    warnings.push(`packs 超过 ${MAX_NAMES} 个，已只保留前 ${MAX_NAMES} 个`);
+                    ids.length = MAX_NAMES;
+                }
+                for (const id of ids) {
+                    if (id === '') {
+                        warnings.push('packs 里有空 id 的条目，已忽略');
+                        continue;
+                    }
+                    const pack = parsePack(id, rawPacks[id], warnings);
+                    // 内置 pack 的显示名固定「默认」：文件里可能是旧名（default 等），读侧一并归一。
+                    packs[id] = id === DEFAULT_PACK_ID ? { ...pack, name: DEFAULT_PACK_NAME } : pack;
+                }
+            }
+        }
+    }
+    if (packs[DEFAULT_PACK_ID] === undefined) {
+        if (raw !== null)
+            warnings.push('packs 缺少 default，已补一个空 pack');
+        packs[DEFAULT_PACK_ID] = EMPTY_PACK;
+    }
+    return { value: { book: { packs }, ui }, warnings };
+}
+/** 解析 `workspaces.json`。绑定键与 `extra` 都在读取时归一，缺失即空表。 */
+export function parseBindings(text) {
+    const warnings = [];
+    const raw = readJson(text, warnings);
+    if (raw === null)
+        return { value: EMPTY_BINDINGS, warnings };
+    const bindings = {};
+    const rawBindings = raw['bindings'];
+    if (rawBindings !== undefined) {
+        if (!isRecord(rawBindings)) {
+            warnings.push('bindings 不是对象，已忽略');
+        }
+        else {
+            const keys = Object.keys(rawBindings).sort();
+            if (keys.length > MAX_NAMES) {
+                warnings.push(`bindings 超过 ${MAX_NAMES} 项，已只保留前 ${MAX_NAMES} 项`);
+                keys.length = MAX_NAMES;
+            }
+            for (const key of keys) {
+                const value = rawBindings[key];
+                if (typeof value !== 'string' || value === '') {
+                    warnings.push(`bindings.${key} 不是 pack id，已忽略`);
+                    continue;
+                }
+                const normalized = normalizeCwd(key);
+                if (normalized === null) {
+                    warnings.push('bindings 里有空路径，已忽略');
+                    continue;
+                }
+                bindings[normalized] = value;
+            }
+        }
+    }
+    const extra = [];
+    const rawExtra = raw['extra'];
+    if (rawExtra !== undefined) {
+        if (!Array.isArray(rawExtra)) {
+            warnings.push('extra 不是数组，已忽略');
+        }
+        else {
+            let capped = false;
+            for (const entry of rawExtra) {
+                if (typeof entry !== 'string') {
+                    warnings.push('extra 里有非字符串元素，已忽略');
+                    continue;
+                }
+                if (extra.length >= MAX_NAMES) {
+                    if (!capped) {
+                        warnings.push(`extra 超过 ${MAX_NAMES} 项，已只保留前 ${MAX_NAMES} 项`);
+                        capped = true;
+                    }
+                    continue;
+                }
+                const normalized = normalizeCwd(entry);
+                if (normalized === null)
+                    continue;
+                if (!extra.includes(normalized))
+                    extra.push(normalized);
+            }
+        }
+    }
+    return { value: { bindings, extra }, warnings };
+}
+/**
+ * 解析组定义。
+ *
+ * 成员搬进 `assignments`（项为主键），查询「这一项属于哪个组」是 O(1)；
+ * 反查「这一组有哪些项」扫一遍即可，几百项的量级不值得维护两份索引。
+ * 指向未知分组的条目保留不删：组被临时删除再建回来时语义自动恢复。
+ */
+export function parseGroups(text) {
+    const warnings = [];
+    const raw = readJson(text, warnings);
+    if (raw === null)
+        return { value: EMPTY_GROUPS, warnings };
+    const groups = [];
+    const seen = new Set();
+    const rawGroups = raw['groups'];
+    if (rawGroups !== undefined) {
+        if (!Array.isArray(rawGroups)) {
+            warnings.push('groups 不是数组，已忽略');
+        }
+        else {
+            if (rawGroups.length > MAX_NAMES) {
+                warnings.push(`groups 超过 ${MAX_NAMES} 个，已只保留前 ${MAX_NAMES} 个`);
+                rawGroups.length = MAX_NAMES;
+            }
+            for (const entry of rawGroups) {
+                if (!isRecord(entry)) {
+                    warnings.push('groups 里有非对象元素，已忽略');
+                    continue;
+                }
+                const id = entry['id'];
+                const name = entry['name'];
+                if (typeof id !== 'string' || id === '' || typeof name !== 'string' || name === '') {
+                    warnings.push('groups 里有缺少 id 或 name 的元素，已忽略');
+                    continue;
+                }
+                if (seen.has(id)) {
+                    warnings.push(`分组 id 重复（${id}），已忽略后来者`);
+                    continue;
+                }
+                seen.add(id);
+                groups.push({ id, name });
+            }
+        }
+    }
+    const assignments = {};
+    const rawAssignments = raw['assignments'];
+    if (rawAssignments !== undefined) {
+        if (!isRecord(rawAssignments)) {
+            warnings.push('assignments 不是对象，已忽略');
+        }
+        else {
+            const names = Object.keys(rawAssignments).sort();
+            if (names.length > MAX_NAMES) {
+                warnings.push(`assignments 超过 ${MAX_NAMES} 项，已只保留前 ${MAX_NAMES} 项`);
+                names.length = MAX_NAMES;
+            }
+            for (const name of names) {
+                const groupId = rawAssignments[name];
+                if (typeof groupId !== 'string' || groupId === '') {
+                    warnings.push(`assignments.${name} 不是分组 id，已忽略`);
+                    continue;
+                }
+                assignments[name] = groupId;
+            }
+        }
+    }
+    return { value: { groups, assignments }, warnings };
+}
+function serializeRecord(entries) {
+    return `${JSON.stringify(entries, null, 2)}\n`;
+}
+/**
+ * 序列化 `packs.json`。
+ *
+ * 键排序 + 两空格 + 结尾换行是硬要求：同一份策略必须序列化成同一串字节，
+ * 否则每次保存都产生一次无意义的 git 差异。`ui` 段总是写全，`default` 总是在。
+ */
+export function serializePacks(packs, ui) {
+    const out = { version: 1, ui: { ...ui } };
+    const packEntries = {};
+    for (const id of Object.keys(packs).sort()) {
+        const pack = packs[id];
+        if (pack === undefined)
+            continue;
+        const entry = { name: id === DEFAULT_PACK_ID ? DEFAULT_PACK_NAME : pack.name };
+        if (Object.keys(pack.items).length > 0)
+            entry['items'] = sortMap(pack.items);
+        if (Object.keys(pack.groups).length > 0)
+            entry['groups'] = sortMap(pack.groups);
+        packEntries[id] = entry;
+    }
+    out['packs'] = packEntries;
+    return serializeRecord(out);
+}
+/** 序列化 `workspaces.json`：绑定键排序，`extra` 保持用户添加顺序。 */
+export function serializeBindings(bindings) {
+    const out = {};
+    for (const key of Object.keys(bindings.bindings).sort()) {
+        const packId = bindings.bindings[key];
+        if (packId !== undefined)
+            out[key] = packId;
+    }
+    return serializeRecord({ version: 1, bindings: out, extra: [...bindings.extra] });
+}
+export function serializeGroups(registry) {
+    const groups = [...registry.groups].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    const assignments = {};
+    for (const name of Object.keys(registry.assignments).sort()) {
+        const groupId = registry.assignments[name];
+        if (groupId !== undefined)
+            assignments[name] = groupId;
+    }
+    return serializeRecord({ version: 1, groups, assignments });
+}
+/** 取名册里的 default。解析保证它存在，这里只是给类型收窄一个出口。 */
+export function defaultPackOf(book) {
+    return book.packs[DEFAULT_PACK_ID] ?? EMPTY_PACK;
+}
+/**
+ * 建一个求值器，链序是：
+ *
+ * ```
+ * pack.items[项] ?? pack.groups[组] ?? default.items[项] ?? default.groups[组] ?? true
+ * ```
+ *
+ * 用 `!== undefined` 而不是 `||`：`false` 是「明令关」，必须原样保留。
+ * 绑定悬空时调用方传 `pack: null`，求值自然退回 `default`。
+ */
+export function createResolver(input) {
+    const { pack, defaultPack, groups } = input;
+    const packId = pack === null ? DEFAULT_PACK_ID : (input.packId ?? DEFAULT_PACK_ID);
+    const groupOf = (name) => {
+        const groupId = groups.assignments[name];
+        if (groupId === undefined || groupId === '')
+            return undefined;
+        for (const group of groups.groups) {
+            if (group.id === groupId)
+                return groupId;
+        }
+        return undefined;
+    };
+    const decide = (name) => {
+        const groupId = groupOf(name);
+        if (pack !== null) {
+            const own = pack.items[name];
+            if (own !== undefined)
+                return { value: own, packId, via: 'item' };
+            if (groupId !== undefined) {
+                const byGroup = pack.groups[groupId];
+                if (byGroup !== undefined)
+                    return { value: byGroup, packId, via: 'group' };
+            }
+        }
+        const top = defaultPack.items[name];
+        if (top !== undefined)
+            return { value: top, packId: DEFAULT_PACK_ID, via: 'item' };
+        if (groupId !== undefined) {
+            const byGroup = defaultPack.groups[groupId];
+            if (byGroup !== undefined)
+                return { value: byGroup, packId: DEFAULT_PACK_ID, via: 'group' };
+        }
+        return { value: true, packId: DEFAULT_PACK_ID, via: 'builtin' };
+    };
+    return { isOpen: (name) => decide(name).value, groupOf, decide };
+}

package/lib/reconcile.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 每个主体的装配记账。
+ *
+ * 三个不变式住在这里：同一个 key 的上一轮落地没完就不开始下一轮；新一轮先释放
+ * 上一轮的资源；落地失败退回「没有资源」，而不是留下半份。调用方只提供「这一轮怎么
+ * 算、怎么落地」，并自己决定计划没变时就别调进来。
+ */
+export type Dispose = () => void;
+export interface Reconciler {
+    /**
+     * 重算并落地。返回 true 表示这一轮的资源已生效（或本来就不需要资源）。
+     * 失败时返回 false：上一轮已被释放，此刻这个主体没有资源。
+     */
+    apply(key: string, build: () => Dispose | null): Promise<boolean>;
+    /** 释放并忘记这个 key 的资源（主体销毁时用）。 */
+    release(key: string): void;
+}
+export declare function createReconciler(warn: (message: string) => void): Reconciler;

package/lib/reconcile.js

@@ -0,0 +1,60 @@
+export function createReconciler(warn) {
+    const disposers = new Map();
+    /** 每个 key 的串联队列：上一轮没完成时，新一轮排在它后面。 */
+    const queues = new Map();
+    /** 每个 key 的世代号：释放或新一轮开始都会加一，用来丢弃过期结果。 */
+    const epochs = new Map();
+    const drop = (key) => {
+        const dispose = disposers.get(key);
+        if (dispose === undefined)
+            return;
+        disposers.delete(key);
+        try {
+            dispose();
+        }
+        catch (error) {
+            warn('释放上一个装配失败（' + key + '）：' + String(error));
+        }
+    };
+    const release = (key) => {
+        epochs.set(key, (epochs.get(key) ?? 0) + 1);
+        drop(key);
+    };
+    const apply = (key, build) => {
+        const previous = queues.get(key) ?? Promise.resolve(true);
+        const epoch = (epochs.get(key) ?? 0) + 1;
+        epochs.set(key, epoch);
+        const task = previous.then(async () => {
+            // 排队期间被 release（主体销毁）或被更新的一次顶掉：这一轮不落地，也不动资源。
+            if (epochs.get(key) !== epoch)
+                return false;
+            drop(key);
+            let dispose;
+            try {
+                dispose = build();
+            }
+            catch (error) {
+                warn('装配失败（' + key + '）：' + String(error));
+                return false;
+            }
+            // 落地期间被 release 或又被要求重算：这一份资源不该留下。
+            if (epochs.get(key) !== epoch) {
+                if (dispose !== null) {
+                    try {
+                        dispose();
+                    }
+                    catch {
+                        // 已过期，释放失败也无处可去。
+                    }
+                }
+                return false;
+            }
+            if (dispose !== null)
+                disposers.set(key, dispose);
+            return true;
+        });
+        queues.set(key, task);
+        return task;
+    };
+    return { apply, release };
+}