@wenaixi/dsh-superpower 7.0.0 → 7.1.0

package/lib/document.js

@@ -0,0 +1,268 @@
+/**
+ * @wenaixi/dsh-superpower — SkillDocument 深度模块
+ *
+ * 封装单个技能文档的读取、BOM/CRLF 归一化、YAML frontmatter 解析、
+ * 规范字段与调用策略校验，以及向 SkillCandidate 和 SkillDefinition 的契约映射。
+ *
+ * 核心原则：
+ * - Depth: 将大量文件 I/O、边界扫描、YAML 解析与类型收敛封装在紧凑的小接口后；
+ * - Locality: 所有 frontmatter 规则与校验逻辑内聚于此；
+ * - Test Surface: 对外暴露规范接口，成为运行时与验证脚本的共同测试表面。
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { parse } from 'yaml';
+import { isSkillName } from '@deepseek-ai/dsh-skill';
+// ---------------------------------------------------------------------------
+// 内部纯工具函数（封装在模块内部，不泄漏给外部调用方）
+// ---------------------------------------------------------------------------
+function stringField(data, key) {
+    const v = data[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+function optionalString(data, key) {
+    const v = data[key];
+    return typeof v === 'string' && v.length > 0 ? { [key]: v } : {};
+}
+function frontmatterBoolean(data, key) {
+    if (!Object.hasOwn(data, key))
+        return undefined;
+    const v = data[key];
+    if (typeof v === 'boolean')
+        return v;
+    if (v === 1 || v === '1')
+        return true;
+    if (v === 0 || v === '0')
+        return false;
+    if (typeof v === 'string') {
+        switch (v.toLowerCase()) {
+            case 'true':
+            case 'yes':
+            case 'on':
+                return true;
+            case 'false':
+            case 'no':
+            case 'off':
+                return false;
+        }
+    }
+    throw new TypeError(`frontmatter field "${key}" must be a boolean`);
+}
+function rejectLegacyKey(data, legacy, canonical) {
+    if (Object.hasOwn(data, legacy)) {
+        throw new Error(`frontmatter field "${legacy}" is unsupported; use "${canonical}"`);
+    }
+}
+function parseInvocationPolicy(data) {
+    rejectLegacyKey(data, 'disableModelInvocation', 'disable-model-invocation');
+    rejectLegacyKey(data, 'modelInvocable', 'disable-model-invocation');
+    rejectLegacyKey(data, 'userInvocable', 'user-invocable');
+    const disableModelInvocation = frontmatterBoolean(data, 'disable-model-invocation');
+    const userInvocable = frontmatterBoolean(data, 'user-invocable');
+    return {
+        modelInvocable: disableModelInvocation !== true,
+        userInvocable: userInvocable !== false,
+    };
+}
+function findClosingFrontmatter(raw, start) {
+    let lineStart = start;
+    while (lineStart <= raw.length) {
+        const nl = raw.indexOf('\n', lineStart);
+        const lineEnd = nl < 0 ? raw.length : nl;
+        if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
+            return { start: lineStart, bodyStart: nl < 0 ? raw.length : nl + 1 };
+        }
+        if (nl < 0)
+            return undefined;
+        lineStart = nl + 1;
+    }
+    return undefined;
+}
+function extractFrontmatter(raw) {
+    // 去除 Windows 编辑器易带的 UTF-8 BOM 头
+    let content = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    const firstNl = content.indexOf('\n');
+    if (firstNl < 0 || content.slice(0, firstNl).replace(/\r$/, '') !== '---') {
+        throw new Error('missing opening frontmatter delimiter "---"');
+    }
+    const start = firstNl + 1;
+    const closing = findClosingFrontmatter(content, start);
+    if (!closing) {
+        throw new Error('missing closing frontmatter delimiter "---"');
+    }
+    const parsed = parse(content.slice(start, closing.start));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('frontmatter must be a YAML object mapping');
+    }
+    return {
+        data: parsed,
+        body: content.slice(closing.bodyStart),
+    };
+}
+// ---------------------------------------------------------------------------
+// SkillDocument 深度模块
+// ---------------------------------------------------------------------------
+export class SkillDocument {
+    path;
+    name;
+    description;
+    whenToUse;
+    invocation;
+    metadata;
+    body;
+    rawFrontmatterData;
+    constructor(filePath, extracted) {
+        this.path = filePath;
+        this.rawFrontmatterData = extracted.data;
+        this.body = extracted.body;
+        const skillName = stringField(extracted.data, 'name');
+        if (!skillName) {
+            throw new Error(`skill at "${filePath}" is missing required frontmatter field "name"`);
+        }
+        if (!isSkillName(skillName)) {
+            throw new Error(`invalid skill name "${skillName}" at "${filePath}" (must be kebab-case)`);
+        }
+        this.name = skillName;
+        const desc = stringField(extracted.data, 'description');
+        if (!desc) {
+            throw new Error(`skill "${skillName}" at "${filePath}" is missing required frontmatter field "description"`);
+        }
+        this.description = desc;
+        this.whenToUse = stringField(extracted.data, 'whenToUse');
+        this.invocation = parseInvocationPolicy(extracted.data);
+        const meta = extracted.data['metadata'];
+        if (typeof meta === 'object' && meta !== null && !Array.isArray(meta)) {
+            this.metadata = meta;
+        }
+    }
+    /**
+     * 从指定文件路径异步解析 SkillDocument。
+     */
+    static async fromFile(filePath, signal) {
+        signal?.throwIfAborted();
+        const raw = await readFile(filePath, {
+            encoding: 'utf8',
+            signal,
+        });
+        signal?.throwIfAborted();
+        const extracted = extractFrontmatter(raw);
+        return new SkillDocument(filePath, extracted);
+    }
+    /**
+     * 从内存中的原始 markdown 字符串直接解析（用于测试或动态构建）。
+     */
+    static fromString(raw, filePath = 'SKILL.md') {
+        const extracted = extractFrontmatter(raw);
+        return new SkillDocument(filePath, extracted);
+    }
+    /**
+     * 执行 SkillDocument 核心边界契约规范自检（接口即测试表面）。
+     */
+    static async selfTest() {
+        const results = [];
+        const runCheck = async (name, fn) => {
+            try {
+                await fn();
+                results.push({ name, ok: true });
+            }
+            catch (err) {
+                results.push({ name, ok: false, error: err?.message ?? String(err) });
+            }
+        };
+        await runCheck('BOM 剥离', () => {
+            const d = SkillDocument.fromString('\uFEFF---\nname: bom-test\ndescription: d\n---\nbody');
+            if (d.name !== 'bom-test')
+                throw new Error('BOM 未剥离: ' + JSON.stringify(d.name));
+        });
+        await runCheck('CRLF 归一', () => {
+            const d = SkillDocument.fromString('---\r\nname: crlf-test\r\ndescription: d\r\n---\r\nbody');
+            if (d.body.trim() !== 'body')
+                throw new Error('CRLF 归一失败: ' + JSON.stringify(d.body));
+        });
+        await runCheck('kebab 校验', () => {
+            let threw = null;
+            try {
+                SkillDocument.fromString('---\nname: Not_Kebab\ndescription: d\n---\n');
+            }
+            catch (e) {
+                threw = e;
+            }
+            if (!threw || !/kebab/.test(String(threw?.message)))
+                throw new Error('未抛 kebab 错误: ' + String(threw));
+        });
+        await runCheck('缺 name 报错', () => {
+            let threw = null;
+            try {
+                SkillDocument.fromString('---\ndescription: d\n---\n');
+            }
+            catch (e) {
+                threw = e;
+            }
+            if (!threw || !/name/.test(String(threw?.message)))
+                throw new Error('未抛缺 name 错误: ' + String(threw));
+        });
+        await runCheck('缺 description 报错', () => {
+            let threw = null;
+            try {
+                SkillDocument.fromString('---\nname: x-test\n---\n');
+            }
+            catch (e) {
+                threw = e;
+            }
+            if (!threw || !/description/.test(String(threw?.message)))
+                throw new Error('未抛缺 description 错误: ' + String(threw));
+        });
+        await runCheck('abort 中止', async () => {
+            const ctrl = new AbortController();
+            ctrl.abort();
+            let threw = null;
+            try {
+                await SkillDocument.fromFile('non-existent-whatever.md', ctrl.signal);
+            }
+            catch (e) {
+                threw = e;
+            }
+            if (!threw || threw.name !== 'AbortError')
+                throw new Error('未抛 AbortError: ' + (threw?.name ?? '无'));
+        });
+        return results;
+    }
+    /**
+     * 映射为 DSH SkillCandidate 契约对象。
+     */
+    toCandidate(providerName, rank) {
+        const dir = dirname(this.path);
+        return {
+            name: this.name,
+            description: this.description,
+            ...(this.whenToUse ? { whenToUse: this.whenToUse } : {}),
+            invocation: this.invocation,
+            source: 'bundled',
+            provider: providerName,
+            rank,
+            locator: { path: this.path, directory: dir },
+            resourceBase: { kind: 'directory', path: dir },
+            path: this.path,
+            ...(this.metadata ? { metadata: this.metadata } : {}),
+        };
+    }
+    /**
+     * 映射为 DSH SkillDefinition 契约对象。
+     */
+    toDefinition(providerName) {
+        const dir = dirname(this.path);
+        return {
+            name: this.name,
+            description: this.description,
+            ...(this.whenToUse ? { whenToUse: this.whenToUse } : {}),
+            invocation: this.invocation,
+            source: 'bundled',
+            provider: providerName,
+            resourceBase: { kind: 'directory', path: dir },
+            path: this.path,
+            ...(this.metadata ? { metadata: this.metadata } : {}),
+            content: this.body.trim(),
+        };
+    }
+}
+//# sourceMappingURL=document.js.map

package/lib/document.js.map

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

package/lib/superpowers.d.ts

@@ -7,6 +7,10 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
+import { SkillCatalog } from './catalog.js';
+import { SkillDocument } from './document.js';
+export { SkillCatalog, type SpecificationReport } from './catalog.js';
+export { SkillDocument, type SpecificationTestResult } from './document.js';
 export declare const Config: Schema<Schemastery.ObjectS<{
     /** 注册到 ctx.skills 的 provider 名称，默认为 superpowers；不可为保留名 runtime */
     providerName: Schema<string, string>;
@@ -40,6 +44,8 @@ declare const _default: {
         skillDir: Schema<string, string>;
     }>>;
     apply: typeof apply;
+    SkillDocument: typeof SkillDocument;
+    SkillCatalog: typeof SkillCatalog;
 };
 export default _default;
 //# sourceMappingURL=superpowers.d.ts.map

package/lib/superpowers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"superpowers.d.ts","sourceRoot":"","sources":["../src/superpowers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AASlD,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAM7C,eAAO,MAAM,MAAM;IACjB,kEAAkE;;IAElE,8CAA8C;;;IAF9C,kEAAkE;;IAElE,8CAA8C;;GAEF,CAAA;AAE9C,MAAM,WAAW,MAAM;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAMD,eAAO,MAAM,IAAI,gBAAgB,CAAA;AACjC,eAAO,MAAM,MAAM,qBAAsB,CAAA;AA4RzC,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAqBxD;;;;;QAjUC,kEAAkE;;QAElE,8CAA8C;;;QAF9C,kEAAkE;;QAElE,8CAA8C;;;;;AAiUhD,wBAA8C"}
+{"version":3,"file":"superpowers.d.ts","sourceRoot":"","sources":["../src/superpowers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQlD,OAAO,MAAM,MAAM,0BAA0B,CAAA;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAG7C,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAA;AAM3E,eAAO,MAAM,MAAM;IACjB,kEAAkE;;IAElE,8CAA8C;;;IAF9C,kEAAkE;;IAElE,8CAA8C;;GAEF,CAAA;AAE9C,MAAM,WAAW,MAAM;IACrB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAMD,eAAO,MAAM,IAAI,gBAAgB,CAAA;AACjC,eAAO,MAAM,MAAM,qBAAsB,CAAA;AA6DzC,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CA0BxD;;;;;QAvGC,kEAAkE;;QAElE,8CAA8C;;;QAF9C,kEAAkE;;QAElE,8CAA8C;;;;;;;AAuGhD,wBAA2E"}

package/lib/superpowers.js

@@ -5,12 +5,14 @@
  * 通过 ctx.skills.registerProvider 注入全局层，rank 10 使本插件技能优先级最高：
  * 小于 dsh-skill-filesystem 的项目/用户根（100–500）与官方 bundled（600）。
  */
-import { readdir, readFile, stat } from 'node:fs/promises';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parse } from 'yaml';
-import { isSkillName } from '@deepseek-ai/dsh-skill';
 import Schema from '@deepseek-ai/schemastery';
+import { SkillCatalog } from './catalog.js';
+import { SkillDocument } from './document.js';
+// 具名导出深度模块，为验证治理与测试表面提供统一深度接口
+export { SkillCatalog } from './catalog.js';
+export { SkillDocument } from './document.js';
 // ---------------------------------------------------------------------------
 // Config — 默认值写在 schema 里；可选字段用可选属性声明
 // ---------------------------------------------------------------------------
@@ -26,7 +28,7 @@ export const Config = Schema.object({
 export const name = 'superpowers';
 export const inject = ['skills'];
 // ---------------------------------------------------------------------------
-// 工具函数
+// 常量与校验
 // ---------------------------------------------------------------------------
 // 本插件技能优先级最高：rank 值越小优先级越高（官方注册表升序裁决），
 // 10 低于 filesystem 项目/用户根(100–500) 与官方 bundled(600)。
@@ -37,92 +39,6 @@ function assertNotRuntimeProvider(providerName) {
         throw new Error(`[superpowers] providerName "${RUNTIME_PROVIDER}" 为保留名，不可用`);
     }
 }
-function stringField(data, key) {
-    const v = data[key];
-    return typeof v === 'string' && v.length > 0 ? v : undefined;
-}
-function optionalString(data, key) {
-    const v = data[key];
-    return typeof v === 'string' && v.length > 0 ? { [key]: v } : {};
-}
-function frontmatterBoolean(data, key) {
-    if (!Object.hasOwn(data, key))
-        return undefined;
-    const v = data[key];
-    if (typeof v === 'boolean')
-        return v;
-    if (v === 1 || v === '1')
-        return true;
-    if (v === 0 || v === '0')
-        return false;
-    if (typeof v === 'string') {
-        switch (v.toLowerCase()) {
-            case 'true':
-            case 'yes':
-            case 'on':
-                return true;
-            case 'false':
-            case 'no':
-            case 'off':
-                return false;
-        }
-    }
-    throw new TypeError(`frontmatter field "${key}" must be a boolean`);
-}
-function rejectLegacyKey(data, legacy, canonical) {
-    if (Object.hasOwn(data, legacy)) {
-        throw new Error(`frontmatter field "${legacy}" is unsupported; use "${canonical}"`);
-    }
-}
-function parseInvocationPolicy(data) {
-    rejectLegacyKey(data, 'disableModelInvocation', 'disable-model-invocation');
-    rejectLegacyKey(data, 'modelInvocable', 'disable-model-invocation');
-    rejectLegacyKey(data, 'userInvocable', 'user-invocable');
-    const disableModelInvocation = frontmatterBoolean(data, 'disable-model-invocation');
-    const userInvocable = frontmatterBoolean(data, 'user-invocable');
-    return {
-        modelInvocable: disableModelInvocation !== true,
-        userInvocable: userInvocable !== false,
-    };
-}
-function optionalMetadata(data) {
-    const v = data['metadata'];
-    if (typeof v === 'object' && v !== null && !Array.isArray(v))
-        return { metadata: v };
-    return {};
-}
-function findClosingFrontmatter(raw, start) {
-    let lineStart = start;
-    while (lineStart <= raw.length) {
-        const nl = raw.indexOf('\n', lineStart);
-        const lineEnd = nl < 0 ? raw.length : nl;
-        if (raw.slice(lineStart, lineEnd).replace(/\r$/, '') === '---') {
-            return { start: lineStart, bodyStart: nl < 0 ? raw.length : nl + 1 };
-        }
-        if (nl < 0)
-            return undefined;
-        lineStart = nl + 1;
-    }
-    return undefined;
-}
-function parseFrontmatter(raw) {
-    // 去 BOM：Windows 编辑器易带 \uFEFF，导致首行非 --- 而被静默跳过
-    if (raw.charCodeAt(0) === 0xfeff)
-        raw = raw.slice(1);
-    const firstNl = raw.indexOf('\n');
-    if (firstNl < 0)
-        return undefined;
-    if (raw.slice(0, firstNl).replace(/\r$/, '') !== '---')
-        return undefined;
-    const start = firstNl + 1;
-    const closing = findClosingFrontmatter(raw, start);
-    if (!closing)
-        return undefined;
-    const parsed = parse(raw.slice(start, closing.start));
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
-        return undefined;
-    return { data: parsed, body: raw.slice(closing.bodyStart) };
-}
 function resolveDefaultSkillDir(configSkillDir) {
     if (configSkillDir)
         return resolve(configSkillDir);
@@ -132,175 +48,32 @@ function resolveDefaultSkillDir(configSkillDir) {
     return resolve(dirname(here), '..', 'skills');
 }
 // ---------------------------------------------------------------------------
-// Provider
+// Provider 实现 — 纯调度与生命周期治理，具体编目、快照与文档解析委托给 SkillCatalog 深度模块
 // ---------------------------------------------------------------------------
 class SuperpowersProvider {
     name;
-    skillDir;
+    catalog;
     ctx;
     constructor(ctx, _control, config) {
         assertNotRuntimeProvider(config.providerName);
         this.ctx = ctx;
         this.name = config.providerName;
-        this.skillDir = resolveDefaultSkillDir(config.skillDir);
+        const skillDir = resolveDefaultSkillDir(config.skillDir);
+        this.catalog = new SkillCatalog(skillDir);
     }
     async list(options) {
-        options.signal?.throwIfAborted();
-        const candidates = [];
-        const seen = new Set();
-        let entries;
-        try {
-            entries = await readdir(this.skillDir, { withFileTypes: true, signal: options.signal });
-        }
-        catch (err) {
-            const code = err?.code;
-            if (code === 'ENOENT' || code === 'ENOTDIR') {
-                this.ctx.logger.warn(`[superpowers] skillDir not found: ${this.skillDir}`);
-                return [];
-            }
-            throw err;
-        }
-        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-            options.signal?.throwIfAborted();
-            if (!entry.isDirectory())
-                continue;
-            if (entry.name.startsWith('.'))
-                continue;
-            const skillPath = join(this.skillDir, entry.name, 'SKILL.md');
-            try {
-                await stat(skillPath);
-            }
-            catch (err) {
-                const code = err?.code;
-                this.ctx.logger.debug(`[superpowers] skip ${entry.name}: no SKILL.md (${code ?? String(err)})`);
-                continue;
-            }
-            let parsed;
-            try {
-                parsed = await parseSkillFile(skillPath);
-            }
-            catch (err) {
-                this.ctx.logger.warn(`[superpowers] skip ${skillPath}: YAML 解析失败 — ${String(err)}`);
-                continue;
-            }
-            if (!parsed) {
-                this.ctx.logger.warn(`[superpowers] skip ${entry.name}: missing or invalid frontmatter`);
-                continue;
-            }
-            const { data } = parsed;
-            const skillName = stringField(data, 'name');
-            const description = stringField(data, 'description');
-            if (!skillName || !description) {
-                this.ctx.logger.warn(`[superpowers] skip ${skillPath}: frontmatter requires name and description`);
-                continue;
-            }
-            if (!isSkillName(skillName)) {
-                this.ctx.logger.warn(`[superpowers] skip ${skillPath}: invalid skill name "${skillName}"`);
-                continue;
-            }
-            if (seen.has(skillName)) {
-                this.ctx.logger.warn(`[superpowers] skip ${skillPath}: duplicate skill name "${skillName}"`);
-                continue;
-            }
-            // 目录名与 skill name 不一致时以 frontmatter 为准，但打印提示
-            if (skillName !== entry.name) {
-                this.ctx.logger.warn(`[superpowers] skill name "${skillName}" != directory "${entry.name}" (using frontmatter)`);
-            }
-            let invocation;
-            try {
-                invocation = parseInvocationPolicy(data);
-            }
-            catch (e) {
-                this.ctx.logger.warn(`[superpowers] skip ${skillPath}: ${String(e)}`);
-                continue;
-            }
-            seen.add(skillName);
-            candidates.push({
-                name: skillName,
-                description,
-                ...optionalString(data, 'whenToUse'),
-                invocation,
-                source: 'bundled',
-                provider: this.name,
-                rank: SUPERPOWERS_RANK,
-                locator: { path: skillPath, directory: dirname(skillPath) },
-                resourceBase: { kind: 'directory', path: dirname(skillPath) },
-                path: skillPath,
-                ...optionalMetadata(data),
-            });
-        }
-        return candidates;
+        return this.catalog.listCandidates(this.name, SUPERPOWERS_RANK, {
+            signal: options.signal,
+            logger: this.ctx.logger,
+        });
     }
     async get(candidate, options) {
-        options.signal?.throwIfAborted();
-        const locator = candidate.locator;
-        if (!locator?.path || !locator?.directory)
-            return undefined;
-        let raw;
-        try {
-            raw = await readFile(locator.path, {
-                encoding: 'utf8',
-                signal: options.signal,
-            });
-        }
-        catch (err) {
-            if (err?.name === 'AbortError')
-                throw err;
-            const code = err?.code;
-            if (code === 'ENOENT')
-                return undefined;
-            this.ctx.logger.warn(`[superpowers] get ${candidate.name}: read failed (${code ?? String(err)})`);
-            return undefined;
-        }
-        if (raw === undefined)
-            return undefined;
-        options.signal?.throwIfAborted();
-        const parsed = parseFrontmatter(raw);
-        if (!parsed) {
-            this.ctx.logger.warn(`[superpowers] get ${candidate.name}: missing or invalid frontmatter`);
-            return undefined;
-        }
-        const data = parsed.data;
-        const skillName = stringField(data, 'name');
-        const description = stringField(data, 'description');
-        if (!skillName || !description) {
-            this.ctx.logger.warn(`[superpowers] get ${candidate.name}: frontmatter requires name and description`);
-            return undefined;
-        }
-        if (skillName !== candidate.name) {
-            // 名称漂移视为失效，触发上层 invalidate
-            this.ctx.logger.warn(`[superpowers] get ${candidate.name}: name drift "${skillName}" != "${candidate.name}"`);
-            return undefined;
-        }
-        let invocation;
-        try {
-            invocation = parseInvocationPolicy(data);
-        }
-        catch (e) {
-            this.ctx.logger.warn(`[superpowers] get ${candidate.name}: ${String(e)}`);
-            return undefined;
-        }
-        return {
-            name: skillName,
-            description,
-            ...optionalString(data, 'whenToUse'),
-            invocation,
-            source: 'bundled',
-            provider: this.name,
-            resourceBase: { kind: 'directory', path: locator.directory },
-            path: locator.path,
-            ...optionalMetadata(data),
-            content: parsed.body.trim(),
-        };
+        return this.catalog.getDefinition(candidate, this.name, {
+            signal: options.signal,
+            logger: this.ctx.logger,
+        });
     }
 }
-async function parseSkillFile(path) {
-    const raw = await readFile(path, 'utf8');
-    const parsed = parseFrontmatter(raw);
-    if (!parsed)
-        return undefined;
-    return parsed;
-}
 // ---------------------------------------------------------------------------
 // 插件入口 — 所有副作用走 ctx 注册，随 fiber 卸载自动清理
 // ---------------------------------------------------------------------------
@@ -309,18 +82,22 @@ export function apply(ctx, config) {
     ctx.logger.info(`[superpowers] registering provider "${config.providerName}"`);
     // 将 provider 注册与事件监听放入同一个 effect，保证卸载时的清理顺序可控
     ctx.effect(() => {
+        let activeProvider;
         const disposeProvider = ctx.skills.registerProvider((control) => {
-            return new SuperpowersProvider(ctx, control, config);
+            activeProvider = new SuperpowersProvider(ctx, control, config);
+            return activeProvider;
         });
-        // skills/change 为 emit 模式（见 @deepseek-ai/dsh-skill Events 定义：@mode emit），非 waterfall，无需 next()
+        // skills/change 为 emit 模式，感知外部变更并精准失效内存快照
         const disposeListener = ctx.on('skills/change', () => {
-            ctx.logger.debug('[superpowers] skills catalog changed');
+            ctx.logger.debug('[superpowers] skills catalog changed, invalidating snapshot');
+            activeProvider?.catalog.invalidate();
         });
         return () => {
             disposeListener();
             disposeProvider();
+            activeProvider?.catalog.invalidate();
         };
     });
 }
-export default { name, inject, Config, apply };
+export default { name, inject, Config, apply, SkillDocument, SkillCatalog };
 //# sourceMappingURL=superpowers.js.map