@dreanzy/dsh-skill-pack 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-skill-pack
+      name: '@dreanzy/dsh-skill-pack'

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" role="img" aria-label="Skill manager">
+  <rect x="2" y="3.5" width="20" height="17" rx="4" fill="none" stroke="#2f6fed" stroke-width="1.6" />
+  <path d="M7 8.5h6M7 12h4.5" stroke="#2f6fed" stroke-width="1.6" stroke-linecap="round" />
+  <circle cx="16.6" cy="8.5" r="2.1" fill="#2f6fed" />
+  <circle cx="15.2" cy="15.5" r="2.1" fill="none" stroke="#2f6fed" stroke-width="1.5" />
+</svg>

package/lib/effective.d.ts

@@ -0,0 +1,46 @@
+import { type Decision } from './policy.js';
+import type { PolicyState } from './store.js';
+/**
+ * 一行的求值结论。
+ *
+ * `open` 为 `null` 表示这次结论不该被信任：清单不完整时遮蔽集会被当成空集，
+ * 此时说「关」就是假话。`decidedBy` / `decidedVia` 仍保留链自己的答案，面板可以
+ * 当诊断显示，但不能当生效状态。
+ */
+export interface EffectiveRow {
+    readonly name: string;
+    readonly groupId: string | null;
+    /** 生效值；清单不完整时为 `null`。 */
+    readonly open: boolean | null;
+    /** 只按 default pack 求值的值。它与清单是否完整无关。 */
+    readonly openGlobal: boolean;
+    /** default pack 里这一项的项级记录；没有键为 `null`（跟随）。 */
+    readonly itemGlobal: boolean | null;
+    /** 工作区绑定的 pack 里这一项的项级记录；未绑定或没有键为 `null`。 */
+    readonly itemWorkspace: boolean | null;
+    /** 做出决定的 pack id；落到内置缺省时是 `default`。 */
+    readonly decidedBy: string;
+    readonly decidedVia: Decision['via'];
+}
+export interface EffectiveInput {
+    readonly policy: PolicyState;
+    /** 要算的名字，通常是清单里的全量名字。 */
+    readonly names: readonly string[];
+    readonly scope: 'global' | 'workspace';
+    /** 清单是否完整。不完整时 `open` 一律为 `null`，`hidden` 为空。 */
+    readonly complete: boolean;
+}
+export interface Effective {
+    readonly complete: boolean;
+    readonly rows: readonly EffectiveRow[];
+    /** 本轮到遮蔽的名字，已排序。清单不完整时为空：那一刻宁可不动。 */
+    readonly hidden: readonly string[];
+    isOpen(name: string): boolean;
+}
+/**
+ * 一次求值，一份答案。
+ *
+ * 求值链只在这里组装一次：装配路径要 `hidden`，面板要 `rows`，两个读者拿到的
+ * 必定是同一份结论。浏览器侧不再重算——那条链已经删掉了。
+ */
+export declare function effective(input: EffectiveInput): Effective;

package/lib/effective.js

@@ -0,0 +1,39 @@
+import { createResolver, defaultPackOf } from './policy.js';
+/**
+ * 一次求值，一份答案。
+ *
+ * 求值链只在这里组装一次：装配路径要 `hidden`，面板要 `rows`，两个读者拿到的
+ * 必定是同一份结论。浏览器侧不再重算——那条链已经删掉了。
+ */
+export function effective(input) {
+    const { policy, names, scope, complete } = input;
+    const defaultPack = defaultPackOf(policy.packs);
+    const groups = policy.groups;
+    const resolver = createResolver(scope === 'workspace'
+        ? { pack: policy.pack, packId: policy.packId, defaultPack, groups }
+        : { pack: null, defaultPack, groups });
+    const globalResolver = createResolver({ pack: null, defaultPack, groups });
+    const answers = new Map();
+    const rows = [];
+    for (const name of names) {
+        const decision = resolver.decide(name);
+        answers.set(name, decision);
+        rows.push({
+            name,
+            groupId: resolver.groupOf(name) ?? null,
+            open: complete ? decision.value : null,
+            openGlobal: globalResolver.decide(name).value,
+            itemGlobal: defaultPack.items[name] ?? null,
+            itemWorkspace: policy.pack === null ? null : (policy.pack.items[name] ?? null),
+            decidedBy: decision.packId,
+            decidedVia: decision.via,
+        });
+    }
+    const isOpen = (name) => {
+        const known = answers.get(name);
+        // 清单外的名字仍可问：链本身对任意名字都有答案。
+        return known === undefined ? resolver.decide(name).value : known.value;
+    };
+    const hidden = complete ? names.filter((name) => !isOpen(name)).sort() : [];
+    return { complete, rows, hidden, isOpen };
+}

package/lib/hooks.d.ts

@@ -0,0 +1,32 @@
+import { type ScopeSnapshot } from './snapshot.js';
+/** 宿主 ctx 的最小面：订阅、纳管、取服务、记日志。 */
+export interface PluginContext {
+    on(event: string, listener: (payload: unknown) => unknown): () => void;
+    effect(callback: () => unknown): unknown;
+    get(name: string): unknown;
+    logger: {
+        info(message: string): void;
+        warn(message: string): void;
+    };
+}
+/**
+ * 装好监听器并返回重新落地的入口。
+ *
+ * 只订阅三个事件：`agent/created`、`agent/disposed`、`skills/change`。
+ * 不挂 `agent/pre-step` 或 `system-prompt/assemble`——`agent/created` 是 serial
+ * 派发，必然早于该 Agent 的首次装配，不需要接管装配瀑布。
+ *
+ * 策略不冻结：每次重新落地都重读两层文件，所以保存的效果落在下一个回合边界。
+ */
+export interface HooksOptions {
+    /** 注入一份共享快照；缺省按本包的真实读取自建。测试用它绕开文件系统。 */
+    readonly snapshot?: ScopeSnapshot;
+}
+export declare function installHooks(ctx: PluginContext, options?: HooksOptions): {
+    reapply: () => Promise<void>;
+    bootstrap: () => Promise<void>;
+    stopAll: () => void;
+    stuck: () => readonly string[];
+    /** 与落地共用的那份求值缓存。路由要用同一份，否则面板与模型看到的会分叉。 */
+    snapshot: ScopeSnapshot;
+};

package/lib/hooks.js

@@ -0,0 +1,403 @@
+import {} from './inventory.js';
+import { createReconciler } from './reconcile.js';
+import { createScopeSnapshot, fingerprintOf } from './snapshot.js';
+import { loadState } from './store.js';
+function asAgentLike(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const record = value;
+    const session = record['session'];
+    if (typeof session !== 'object' || session === null)
+        return null;
+    const sessionRecord = session;
+    if (typeof record['id'] !== 'string' || typeof sessionRecord['id'] !== 'string')
+        return null;
+    const header = sessionRecord['header'];
+    const cwd = typeof header === 'object' && header !== null ? header['cwd'] : undefined;
+    return {
+        id: record['id'],
+        ctx: record['ctx'],
+        session: {
+            id: sessionRecord['id'],
+            ...(typeof cwd === 'string' ? { header: { cwd } } : {}),
+        },
+        raw: value,
+    };
+}
+function cwdOf(agent) {
+    const cwd = agent.session.header?.cwd;
+    return typeof cwd === 'string' && cwd !== '' ? cwd : null;
+}
+/**
+ * 取该 Agent 作用域的 skills 实例。
+ *
+ * **必须由 `agent.ctx.get('skills')` 取**：`register()` 用 `scopeOf(this.ctx)`
+ * 决定落到哪一层，只有这个实例代表的才是该 Agent 的层。
+ */
+function scopedSkills(agent) {
+    const get = agent.ctx?.get;
+    if (typeof get !== 'function')
+        return null;
+    try {
+        const service = get.call(agent.ctx, 'skills');
+        if (typeof service !== 'object' || service === null)
+            return null;
+        return service;
+    }
+    catch {
+        return null;
+    }
+}
+async function prepareShadows(skills, rows, hidden, cwd, scope) {
+    const byName = new Map(rows.map((row) => [row.name, row]));
+    /**
+     * **先取全部定义，再统一注册。**
+     *
+     * `skills.register()` 会无条件让注册表的 revision +1 并清掉收集缓存，而
+     * `skills.get()` 的缓存正按 revision 做键。所以「取一个 → 注册一个」会让
+     * 每次 `get()` 都必然缓存未命中、触发一次完整枚举：一百来个隐藏项实测要
+     * 三秒以上，而这段代码跑在 `agent/created` 里、被宿主串行 await——用户看到的
+     * 就是「点新会话要等很久」。
+     *
+     * 分段之后只有第一次 `get()` 可能全量，其余命中缓存；注册本身是微秒级。
+     */
+    const prepared = [];
+    for (const name of hidden) {
+        const row = byName.get(name);
+        if (row === undefined)
+            continue;
+        let content = '';
+        try {
+            const definition = await skills.get(name, { cwd, scope });
+            if (definition !== undefined && typeof definition.content === 'string')
+                content = definition.content;
+        }
+        catch {
+            // 读不到正文只影响手动调用的内容，不影响遮蔽本身。
+        }
+        prepared.push({ row, content });
+    }
+    return prepared;
+}
+/**
+ * 同步注册一份遮蔽。
+ *
+ * 放进 reconcile 的 `build` 里调用：那一刻上一轮已经释放；这一半失败也退回无资源，
+ * 不会留下半份。
+ */
+function registerShadows(ctx, skills, drafts) {
+    const disposers = [];
+    for (const { row, content } of drafts) {
+        try {
+            disposers.push(skills.register({
+                name: row.name,
+                description: row.description,
+                content,
+                source: row.source,
+                ...(row.path === undefined ? {} : { path: row.path }),
+                invocation: { modelInvocable: false, userInvocable: true },
+            }));
+        }
+        catch (error) {
+            ctx.logger.warn(`dsh-skill-pack: 注册遮蔽副本失败（${row.name}）：${String(error)}`);
+        }
+    }
+    if (disposers.length === 0)
+        return null;
+    return () => {
+        for (const dispose of disposers) {
+            try {
+                dispose();
+            }
+            catch {
+                // 释放失败只影响内存，下一次落地会重建。
+            }
+        }
+    };
+}
+/**
+ * 复验：判据是 `invocation.modelInvocable !== false`，不是「名字还在不在」。
+ * 遮蔽只改 invocation 标记，名字永远在清单里。
+ */
+async function verifyShadows(ctx, skills, hidden, cwd, scope) {
+    let stuck = [];
+    try {
+        const after = await skills.snapshot({ cwd, scope });
+        if (after.complete) {
+            const visible = new Set();
+            for (const row of after.skills) {
+                if (row.invocation?.modelInvocable !== false)
+                    visible.add(row.name);
+            }
+            stuck = hidden.filter((name) => visible.has(name));
+            if (stuck.length > 0) {
+                ctx.logger.warn(`dsh-skill-pack: 以下 skill 关不掉（同层已被别的插件注册）：${stuck.join(', ')}`);
+            }
+        }
+    }
+    catch {
+        // 复验失败不影响已落地的遮蔽，只是这条会话的「关不掉」名单未知。
+    }
+    return stuck;
+}
+export function installHooks(ctx, options) {
+    const states = new Map();
+    /**
+     * 每个 agent 一份装配记账：先释放上一轮、串行、失败退回无资源，三件事都在这里。
+     * key 用 agent id，一个 agent 只有一份遮蔽。
+     */
+    const shadows = createReconciler((message) => {
+        ctx.logger.warn(`dsh-skill-pack: ${message}`);
+    });
+    /**
+     * scope 对象 → agent 的索引。
+     *
+     * 快照的键是「cwd + scope 身份」，而读清单必须用该 agent 自己的 skills 实例
+     * （`register()` 用 `scopeOf(ctx)` 决定落到哪一层）。刷新时只拿得到 scope 对象，
+     * 所以在这里反查回 agent。
+     */
+    const agentByScope = new WeakMap();
+    const rootSkills = () => {
+        try {
+            const service = ctx.get('skills');
+            return typeof service === 'object' && service !== null ? service : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    /**
+     * 读一份**未缓存**的清单。
+     *
+     * 刻意不复用 `inventory.ts` 的 `readInventory`：它的缓存键不含 scope 身份，会让
+     * 不同 preset 的会话读到彼此的清单。缓存统一由 `ScopeSnapshot` 负责。
+     */
+    const readFresh = async (cwd, scope) => {
+        const agent = typeof scope === 'object' && scope !== null ? agentByScope.get(scope) : undefined;
+        const skills = agent === undefined ? rootSkills() : scopedSkills(agent);
+        if (skills === null)
+            throw new Error('取不到 skills 服务，无法读取清单');
+        const request = {};
+        if (cwd !== null && cwd !== '')
+            request.cwd = cwd;
+        if (scope !== undefined)
+            request.scope = scope;
+        const result = await skills.snapshot(request);
+        return { rows: result.skills, complete: result.complete };
+    };
+    const snapshot = options?.snapshot ??
+        createScopeSnapshot({
+            loadPolicy: (cwd) => loadState(cwd),
+            readInventory: readFresh,
+            fingerprint: fingerprintOf,
+        });
+    /**
+     * 本插件正在落地时的计数。
+     *
+     * 遮蔽是 `skills.register()`，而它会触发 `skills/change`；本监听器又监听
+     * `skills/change`。没有这个守卫，一次落地会自我复制成注册风暴，表现为
+     * 新建会话卡顿数秒、且首条消息的 skill 目录整体消失（快照 revisions 抖动）。
+     * 用计数而非布尔：落地期间可能嵌套一次真正的外部变化。
+     */
+    let applying = 0;
+    /** 落地期间到达的清单变化。直接丢掉会让遮蔽停在上一个版本，所以记下来补跑。 */
+    let dirty = false;
+    async function guarded(operation) {
+        applying += 1;
+        try {
+            await operation();
+        }
+        finally {
+            applying -= 1;
+            if (applying === 0 && dirty) {
+                dirty = false;
+                void onChange().catch((error) => {
+                    ctx.logger.warn(`dsh-skill-pack: 补跑清单变化失败：${String(error)}`);
+                });
+            }
+        }
+    }
+    const applyOne = async (state) => {
+        const cwd = cwdOf(state.agent);
+        if (cwd === null)
+            return;
+        const skills = scopedSkills(state.agent);
+        if (skills === null) {
+            ctx.logger.warn(`dsh-skill-pack: 取不到 agent 作用域的 skills 服务（agent=${state.agent.id}）`);
+            return;
+        }
+        // 求值按 cwd + scope 共享：同一会话的多次落地（created、清单变更、保存、
+        // 插件重载）只在策略或清单真的变了之后才重新读盘。
+        // 清单始终是全量的（含官方技能）：官方技能只是面板默认不展示，一旦用户把它们
+        // 放出来并关掉，「显示官方技能」开关再关回去，那条决定仍然有效。
+        //
+        // 绑定表的键是规范化后的 cwd；归一在 `loadState` 内部完成，用的是
+        // `policy.ts` 的 `normalizeCwd` 唯一实现。这里刻意保留原始 cwd 给清单读取：
+        // 宿主按原写法解析工程根，改写大小写会让工程 skill 找不到。
+        const view = await snapshot.refresh(cwd, state.agent.raw);
+        for (const warning of view.warnings)
+            ctx.logger.warn(`dsh-skill-pack: ${warning}`);
+        if (!view.complete) {
+            ctx.logger.warn(`dsh-skill-pack: skill 清单不完整，本轮不改变遮蔽（agent=${state.agent.id}）`);
+            return;
+        }
+        const hidden = view.hidden;
+        // 计划没变就跳过：这条判断留在调用方，reconcile 只管落地。
+        const key = hidden.join(',');
+        if (key === state.key)
+            return;
+        // 读正文不碰注册表，可以在这里并发；注册必须排进 reconcile 的队列，
+        // 这样「先释放上一轮、再施加这一轮」才成立。
+        const drafts = await prepareShadows(skills, view.rows, hidden, cwd, state.agent.raw);
+        const landed = await shadows.apply(state.agent.id, () => registerShadows(ctx, skills, drafts));
+        if (!landed) {
+            // 上一轮已被释放、这一轮没有资源：不推进 key，下一个事件会重试。
+            state.stuck = [];
+            return;
+        }
+        state.key = key;
+        state.stuck =
+            drafts.length === 0 ? [] : await verifyShadows(ctx, skills, hidden, cwd, state.agent.raw);
+    };
+    const onCreated = async (payload) => {
+        // 这个事件的监听器抛错会让会话创建失败（仓库红线），所以整条路径吞掉降级。
+        try {
+            const agent = asAgentLike(payload?.agent);
+            if (agent === null) {
+                ctx.logger.warn('dsh-skill-pack: agent/created 负载形状不符，跳过');
+                return;
+            }
+            if (cwdOf(agent) === null) {
+                ctx.logger.warn(`dsh-skill-pack: agent/created 缺少 cwd，跳过（agent=${agent.id}）`);
+                return;
+            }
+            // 宿主可能对同一个 agent id 再发一次 created（会话恢复、重连）。
+            // 覆盖前必须释放旧遮蔽，否则注册表里留下没人能释放的第二份副本。
+            shadows.release(agent.id);
+            const state = { agent, key: '', stuck: [] };
+            states.set(agent.id, state);
+            if (typeof agent.raw === 'object' && agent.raw !== null)
+                agentByScope.set(agent.raw, agent);
+            await guarded(async () => {
+                await applyOne(state);
+            });
+        }
+        catch (error) {
+            ctx.logger.warn(`dsh-skill-pack: agent/created 落地失败，本会话按空策略运行：${String(error)}`);
+        }
+    };
+    const onDisposed = (payload) => {
+        const agent = asAgentLike(payload?.agent);
+        if (agent === null)
+            return;
+        const state = states.get(agent.id);
+        if (state === undefined)
+            return;
+        // 释放并忘记这个主体的资源；还排在队列里的那一轮会自己作废。
+        shadows.release(agent.id);
+        states.delete(agent.id);
+        // 这一格已经没有消费者；不清理会让缓存按开过的会话数单调增长。
+        // 同目录还有活会话时会被一并打掉，代价是它们下一轮重读一次。
+        const cwd = cwdOf(agent);
+        if (cwd !== null)
+            snapshot.invalidate(cwd);
+    };
+    async function onChange() {
+        if (applying > 0) {
+            // 自己注册遮蔽触发的 skills/change 会走这里；外部变化也走这里，不能丢。
+            dirty = true;
+            return;
+        }
+        // 清单变化不改三份策略文件，指纹挡不住；不主动打掉就会一直读到旧清单。
+        snapshot.invalidate();
+        await guarded(async () => {
+            // 并发而不是串行：不同 agent 落在各自的 scope 上，互不依赖；同键的刷新由
+            // `ScopeSnapshot` 单飞合并，所以并发不会把一次变更放大成 N 次读盘。
+            await Promise.all([...states.values()].map(async (state) => {
+                try {
+                    await applyOne(state);
+                }
+                catch (error) {
+                    ctx.logger.warn(`dsh-skill-pack: 清单变化后重新落地失败（agent=${state.agent.id}）：${String(error)}`);
+                }
+            }));
+        });
+    }
+    const offCreated = ctx.on('agent/created', onCreated);
+    // 事件名必须带斜杠，与宿主 emit 的字符串逐字一致；写成点号不会报错，也永远不会被调用。
+    const offSkills = ctx.on('skills/change', onChange);
+    const offDisposed = ctx.on('agent/disposed', onDisposed);
+    /**
+     * 策略保存不触碰 skill 注册表，因此不会发出 `skills/change`。
+     * 保存成功后由路由显式调用这里，否则同一会话里改策略要等新会话才生效。
+     */
+    const reapply = async () => {
+        // 策略刚被写盘：onChange 里的显式失效不靠 mtime 精度。同毫秒内的两次写在
+        // Windows 上可能得到同一个时间戳，靠指纹会漏掉第二次。
+        await onChange();
+    };
+    const stopAll = () => {
+        for (const off of [offCreated, offSkills, offDisposed]) {
+            try {
+                off();
+            }
+            catch {
+                // 退订失败不影响后续释放。
+            }
+        }
+        for (const id of states.keys())
+            shadows.release(id);
+        states.clear();
+        snapshot.invalidate();
+    };
+    ctx.effect(() => stopAll);
+    /**
+     * 插件重载后补一次落地。
+     *
+     * `states` 是进程内表，插件一重载就清空；而那些**已经存在**的会话不会再收到
+     * `agent/created`，于是一直以为自己没有被遮蔽——直到用户重开会话，表现就是
+     * 「策略改了，手上这个会话还是能看到被关掉的 skill」。
+     * 这里主动枚举一次 live Agent，把表补回来。
+     */
+    const bootstrap = async () => {
+        let list = [];
+        try {
+            const agents = ctx.get('agents');
+            const raw = typeof agents?.list === 'function' ? agents.list.call(agents) : [];
+            list = Array.isArray(raw) ? raw : [];
+        }
+        catch {
+            return;
+        }
+        for (const raw of list) {
+            const agent = asAgentLike({ agent: raw });
+            if (agent === null || states.has(agent.id) || cwdOf(agent) === null)
+                continue;
+            const state = { agent, key: '', stuck: [] };
+            states.set(agent.id, state);
+            if (typeof agent.raw === 'object' && agent.raw !== null)
+                agentByScope.set(agent.raw, agent);
+            try {
+                await guarded(async () => {
+                    await applyOne(state);
+                });
+            }
+            catch (error) {
+                ctx.logger.warn(`dsh-skill-pack: 补落地失败（agent=${agent.id}）：${String(error)}`);
+            }
+        }
+    };
+    return {
+        reapply,
+        bootstrap,
+        stopAll,
+        snapshot,
+        stuck: () => {
+            const out = new Set();
+            for (const state of states.values())
+                for (const name of state.stuck)
+                    out.add(name);
+            return [...out].sort();
+        },
+    };
+}

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+/** 插件名，同时是 bundle patch 的 entry id。 */
+export declare const name = "dsh-skill-pack";
+/**
+ * 硬依赖只有 `skills`：清单读取与遮蔽注册都取不到替代。
+ *
+ * 刻意不注入 `tools`（不管 MCP）、不注入 `agents`（用自己维护的会话表就够了）、
+ * 不注入 `connection`（无连接服务的 profile 也必须能装配；路由阶段再可选嵌套注入）。
+ */
+export declare const inject: readonly ["skills"];
+export declare function apply(ctx: unknown): void;

package/lib/index.js

@@ -0,0 +1,109 @@
+import { installHooks } from './hooks.js';
+import { handleApply, handleGlobal, handleWorkspace, } from './routes.js';
+/** 插件名，同时是 bundle patch 的 entry id。 */
+export const name = 'dsh-skill-pack';
+/**
+ * 硬依赖只有 `skills`：清单读取与遮蔽注册都取不到替代。
+ *
+ * 刻意不注入 `tools`（不管 MCP）、不注入 `agents`（用自己维护的会话表就够了）、
+ * 不注入 `connection`（无连接服务的 profile 也必须能装配；路由阶段再可选嵌套注入）。
+ */
+export const inject = ['skills'];
+/** 路由路径。宿主按完整 pathname 匹配，`/api` 前缀不能省。 */
+const ROUTES = {
+    global: '/api/skill-pack/global',
+    workspace: '/api/skill-pack/workspace',
+    apply: '/api/skill-pack/apply',
+};
+function toResponse(envelope) {
+    // HTTP 状态恒为 200：前端只认信封里的 `code`，非 2xx 会让它丢掉 body。
+    return Response.json(envelope, { headers: { 'cache-control': 'no-store' } });
+}
+function wrap(handler) {
+    return async (request) => {
+        let body = null;
+        try {
+            const parsed = await request.json();
+            body = typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+                ? parsed
+                : null;
+        }
+        catch {
+            // 空体合法：全局读取不需要任何入参。
+        }
+        try {
+            return toResponse(await handler(body));
+        }
+        catch (error) {
+            return toResponse({
+                ok: false,
+                error: { code: 'internal', message: `路由处理失败：${String(error)}` },
+            });
+        }
+    };
+}
+function readFetchFace(ctx) {
+    const connection = ctx.get('connection');
+    if (typeof connection !== 'object' || connection === null)
+        return null;
+    const fetchFace = connection['fetch'];
+    if (typeof fetchFace !== 'object' || fetchFace === null)
+        return null;
+    const register = fetchFace['register'];
+    if (typeof register !== 'function')
+        return null;
+    return { register: (spec) => register.call(fetchFace, spec) };
+}
+export function apply(ctx) {
+    const context = ctx;
+    const hooks = installHooks(context);
+    // 重载后补一次落地：已有会话不会再收到 agent/created，不补的话它们会一直
+    // 保持「没有遮蔽」，直到用户重开会话。失败只降级，不影响插件加载。
+    void hooks.bootstrap().catch((error) => {
+        context.logger.warn(`${name}: 重载后补落地失败：${String(error)}`);
+    });
+    context.inject(['connection'], () => {
+        const face = readFetchFace(context);
+        if (face === null) {
+            context.logger.warn(`${name}: connection 服务在册但没有 fetch.register，路由未注册（策略仍生效）`);
+            return;
+        }
+        const routeCtx = { get: (key) => context.get(key), logger: context.logger };
+        // 与 hooks 共用同一份快照：面板上的隐藏集必须就是会话里生效的那一份。
+        const deps = { snapshot: hooks.snapshot, reapply: hooks.reapply, stuck: hooks.stuck };
+        const disposers = [];
+        const register = (path, handler) => {
+            try {
+                disposers.push(face.register({ path, methods: ['POST'], requestBody: 'buffered', fetch: wrap(handler) }));
+            }
+            catch (error) {
+                context.logger.warn(`${name}: 注册路由失败（${path}）：${String(error)}`);
+            }
+        };
+        register(ROUTES.global, (body) => {
+            // 面板会带当前会话：全局面板的行集合因此与会话一致，而不是「恰好排第一的那个」。
+            const sessionId = body !== null && typeof body['sessionId'] === 'string' && body['sessionId'] !== ''
+                ? body['sessionId']
+                : undefined;
+            return handleGlobal(routeCtx, deps, sessionId);
+        });
+        register(ROUTES.workspace, (body) => handleWorkspace(routeCtx, body, deps));
+        register(ROUTES.apply, (body) => handleApply(routeCtx, body, deps));
+        context.effect(() => () => {
+            for (const dispose of disposers) {
+                try {
+                    const result = dispose();
+                    if (result !== null && typeof result === 'object' && 'catch' in result) {
+                        void result.catch(() => {
+                            // 释放失败只影响这次卸载，没有可回滚的状态。
+                        });
+                    }
+                }
+                catch {
+                    // 同上。
+                }
+            }
+        });
+    });
+    context.logger.info(`${name}: applied`);
+}