@wenaixi/dsh-superpower 6.3.1 → 7.0.1

package/README.md

@@ -4,7 +4,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
 [![DSH](https://img.shields.io/badge/DSH-Plugin-7c3aed)](https://github.com/deepseek-ai/deepseek-harness)
 
-[obra/superpowers](https://github.com/obra/superpowers) 的 DSH 完整移植 — 14 个技能注入 `ctx.skills`，开箱即用，全中文。
+[obra/superpowers](https://github.com/obra/superpowers) 的 DSH 专属移植版 — 15 个技能注入 `ctx.skills`，开箱即用，全中文，**仅支持 DSH (DeepSeek Harness) 平台**，不提供其它 AI 宿主适配。
 
 ## 安装
 
@@ -26,15 +26,15 @@ dsh --profile web --dump-config | grep -A2 "@wenaixi/dsh-superpower"
 dsh --profile web  # 进会话，技能自动可用
 ```
 
-> 如需锁定版本，在包名后追加 `@<version>`（如 `@wenaixi/dsh-superpower@<version>`）或 `#v<version>`（GitHub 形式）。
+> 如需锁定版本，在包名后追加 `@<version>`（如 `@wenaixi/dsh-superpower@7.0.1`）或 `#v7.0.1`（GitHub 形式）。
 >
-> > ⚠️ 旧名 `dsh-superpower`（无 scope）已废弃并 `npm deprecate`，请改用 `@wenaixi/dsh-superpower`。
+> > 旧名 `dsh-superpower`（无 scope）已废弃并 `npm deprecate`，请改用 `@wenaixi/dsh-superpower`。
 
 其它：
 
 ```bash
 git clone https://github.com/Wenaixi/dsh-superpower.git && cd dsh-superpower
-pnpm install && pnpm build && node scripts/verify.mjs   # 14/14 PASS
+pnpm install && pnpm build && node scripts/verify.mjs   # 15/15 PASS
 dsh plugin --profile web add ./                           # 本地路径安装
 pnpm pack && dsh plugin --profile web add ./wenaixi-dsh-superpower-*.tgz  # 离线 tarball
 
@@ -51,46 +51,52 @@ dsh plugin --profile web remove @wenaixi/dsh-superpower
 
 | 技能 | 触发时机 |
 |---|---|
-| `superpower-using-superpowers` | 任意会话起点（1% 原则） |
-| `superpower-brainstorming` | 新功能前，Spike / Bounded / Architectural 分级 |
-| `superpower-writing-plans` | 设计获批后，切 2–5 分钟任务 |
-| `superpower-using-git-worktrees` | 隔离分支 |
-| `superpower-executing-plans` / `superpower-subagent-driven-development` | 按计划执行，后者每任务一子智能体 + 两阶段评审 |
-| `superpower-dispatching-parallel-agents` | 并行分发 |
-| `superpower-test-driven-development` | RED-GREEN-REFACTOR |
-| `superpower-systematic-debugging` / `superpower-verification-before-completion` | 调试闭环 |
-| `superpower-requesting-code-review` / `superpower-receiving-code-review` | 评审 |
-| `superpower-finishing-a-development-branch` | 集成 |
-| `superpower-writing-skills` | 写新技能 |
-
-映射：`Bash→pwsh`、`Read/Write→fs` 等见 `skills/superpower-using-superpowers/references/dsh-tools.md`。
+| `using-superpowers` | 任意会话起点（1% 原则） |
+| `brainstorming` | 新功能前，Spike / Bounded / Architectural 分级 |
+| `writing-plans` | 设计获批后，切"一项可校验结果的动作"任务 |
+| `using-git-worktrees` | 隔离分支 |
+| `executing-plans` / `subagent-driven-development` | 按计划执行，前者内联整跑一次终审，后者每任务一 subagent + 两阶段评审 |
+| `dispatching-parallel-agents` | 并行分发 |
+| `test-driven-development` | RED-GREEN-REFACTOR |
+| `systematic-debugging` / `verification-before-completion` | 调试闭环 |
+| `requesting-code-review` / `receiving-code-review` | 评审 |
+| `diagnosing-superpowers` | 会话出问题后定位根因（`path:line` 证据） |
+| `finishing-a-development-branch` | 集成 |
+| `writing-skills` | 写新技能 |
+
+映射：`Bash→pwsh`、`Read/Write→fs` 等见 `skills/using-superpowers/references/dsh-tools.md`。
+
+> **同名技能优先（本插件优先级最高）**：官方注册表同层重名按 `rank → 提供方顺序 → 本地顺序` 裁决，**rank 越小优先级越高**；本包 rank 10 小于 `dsh-skill-filesystem` 的项目/用户根（100–500）与官方内置 bundled（600），因此与本包同名的本地技能（`~/.dsh/skills`、项目 `.dsh/skills` 等）或官方 bundled 技能均由本包胜出，本插件技能唯一生效。
 
 ## 使用
 
 ```
-“帮我做 XXX”  → superpower-brainstorming → superpower-writing-plans → superpower-subagent-driven-development
-“修这个缺陷”  → superpower-systematic-debugging
-“帮我评审”    → superpower-requesting-code-review
+“帮我做 XXX”  → brainstorming → writing-plans → subagent-driven-development
+“修这个缺陷”  → systematic-debugging
+“帮我评审”    → requesting-code-review
+“刚才会话出问题了” → diagnosing-superpowers
 ```
 
-校验：`await ctx.skills.list({cwd})` 应有 14 条 `provider: superpowers`。
+校验：`await ctx.skills.list({cwd})` 应有 15 条 `provider: superpowers`。
 
 ## 开发
 
 ```bash
 pnpm install && pnpm build && pnpm typecheck && node scripts/verify.mjs
+node scripts/check-same-name-priority.mjs    # 同名优先实测一：自研桩（rank 100/300/500/600 均不抢 / rank 0 可抢）
+node scripts/check-same-name-priority-fs.mjs # 同名优先实测二：官方 dsh-skill-filesystem 同层实测（rank 300 不抢）
 dsh --profile web --dump-config  # 断言 "# == @wenaixi/dsh-superpower"
 ```
 
 ## 目录
 
 ```
-src/superpowers.ts  # SkillProvider rank 550
-skills/             # 14 技能（中文化）
+src/superpowers.ts  # SkillProvider rank 10（本插件技能优先级最高）
+skills/             # 15 技能（中文化，v7.0.0 起无 superpower- 前缀）
 lib/                # 已提交，GitHub 直装零构建
 ```
 
-版本：`v6.3.1` 起本仓库脱离上游独立演进（上游基准锁定 `obra/superpowers v6.3.0`），后续变更以正式版本线发布；`tag v*` 触发发布，`push` 仅跑 CI。详见 `CHANGELOG.md`。
+版本：`v7.0.0` 起技能名回归上游命名（无 `superpower-` 前缀）并整批同步上游 `obra/superpowers v6.4.2`；本插件技能优先级最高（rank 10），同名技能本包胜出。`v7.0.0` 起本插件为 **DSH 专属**，已移除全部非 DSH 平台（Claude Code、Codex、Gemini CLI、Hermes、Muse、Pi、Antigravity、Copilot CLI）的参考文档与兼容层；`v7.0.1` 为修复版，重发干净 tarball（npm `7.0.0` 发布于专属化前、已废弃，勿使用）。详见 `CHANGELOG.md`。
 
 ## 常见问题
 

package/lib/catalog.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @wenaixi/dsh-superpower — SkillCatalog 深度模块
+ *
+ * 封装技能目录的发现、遍历、健康探测、排重、名称漂移校验与版本化快照索引。
+ *
+ * 核心设计：
+ * - Depth: 将文件系统遍历、mtime 存活检测、去重、状态回写与快照复用隐藏在极简接口之后；
+ * - Locality: 集中管理技能目录发现逻辑、缓存一致性与规范合规规则；
+ * - Leverage: 同时支撑 SuperpowersProvider 高性能运行时与 verify.mjs 质检治理。
+ */
+import type { SkillCandidate, SkillDefinition } from '@deepseek-ai/dsh-skill';
+import { SkillDocument } from './document.js';
+export interface CatalogLogger {
+    warn(msg: string): void;
+    debug?(msg: string): void;
+    info?(msg: string): void;
+}
+export interface CatalogLookupOptions {
+    signal?: AbortSignal;
+    logger?: CatalogLogger;
+    forceScan?: boolean;
+}
+export interface CatalogEntry {
+    directoryName: string;
+    skillPath: string;
+    document: SkillDocument;
+    nameDrift: boolean;
+}
+export interface CatalogIntegrityReport {
+    total: number;
+    entries: CatalogEntry[];
+    duplicates: string[];
+    missingSkillMd: string[];
+    errors: {
+        path: string;
+        error: string;
+    }[];
+    ok: boolean;
+}
+export declare class SkillCatalog {
+    readonly skillDir: string;
+    private readonly entriesByName;
+    private readonly entriesByDir;
+    private readonly duplicates;
+    private readonly missingSkillMd;
+    private readonly loadErrors;
+    private cachedCandidates;
+    private lastScannedMtimeMs;
+    private lastScanProviderName?;
+    private lastScanRank?;
+    constructor(skillDir: string);
+    /**
+     * 从指定目录异步扫描并构建已预热的 SkillCatalog 深度实例。
+     */
+    static fromDirectory(skillDir: string, options?: CatalogLookupOptions): Promise<SkillCatalog>;
+    /**
+     * 清空快照与索引，强制下一轮查询重新从磁盘装载。
+     */
+    invalidate(): void;
+    /**
+     * 探测目录是否发生变动。
+     */
+    private isDirModified;
+    /**
+     * 执行全量目录遍历与技能索引构建。
+     */
+    scan(options?: CatalogLookupOptions): Promise<void>;
+    /**
+     * 映射当前有效技能为 DSH SkillCandidate 快照。
+     * 自动按 mtime 评估有效性，未变动时直接复用不可变快照，零重复读盘。
+     */
+    listCandidates(providerName: string, rank: number, options?: CatalogLookupOptions): Promise<readonly SkillCandidate[]>;
+    /**
+     * 根据候选技能的 locator 与名称解析出完整 SkillDefinition。
+     * 优先命中内存缓存；若发生热重读，自动自愈更新回内存映射，消除状态撕裂缝隙。
+     */
+    getDefinition(candidate: SkillCandidate, providerName: string, options?: CatalogLookupOptions): Promise<SkillDefinition | undefined>;
+    /**
+     * 生成目录健康度与一致性完整体检报告（供 verify 脚本与 CI 质量门禁复用）。
+     */
+    verifyIntegrity(): CatalogIntegrityReport;
+}
+//# sourceMappingURL=catalog.d.ts.map

package/lib/catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAC7E,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAE7C,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,KAAK,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,MAAM,CAAC,EAAE,aAAa,CAAA;IACtB,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,aAAa,CAAA;IACvB,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;IACzC,EAAE,EAAE,OAAO,CAAA;CACZ;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkC;IAChE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAe;IAC9C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAwC;IAGnE,OAAO,CAAC,gBAAgB,CAAyC;IACjE,OAAO,CAAC,kBAAkB,CAAI;IAC9B,OAAO,CAAC,oBAAoB,CAAC,CAAQ;IACrC,OAAO,CAAC,YAAY,CAAC,CAAQ;gBAEjB,QAAQ,EAAE,MAAM;IAI5B;;OAEG;WACU,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC;IAOnG;;OAEG;IACH,UAAU,IAAI,IAAI;IAUlB;;OAEG;YACW,aAAa;IAW3B;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2FzD;;;OAGG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;IAwB5H;;;OAGG;IACG,aAAa,CAAC,SAAS,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IA2C1I;;OAEG;IACH,eAAe,IAAI,sBAAsB;CAY1C"}

package/lib/catalog.js

@@ -0,0 +1,231 @@
+/**
+ * @wenaixi/dsh-superpower — SkillCatalog 深度模块
+ *
+ * 封装技能目录的发现、遍历、健康探测、排重、名称漂移校验与版本化快照索引。
+ *
+ * 核心设计：
+ * - Depth: 将文件系统遍历、mtime 存活检测、去重、状态回写与快照复用隐藏在极简接口之后；
+ * - Locality: 集中管理技能目录发现逻辑、缓存一致性与规范合规规则；
+ * - Leverage: 同时支撑 SuperpowersProvider 高性能运行时与 verify.mjs 质检治理。
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { SkillDocument } from './document.js';
+export class SkillCatalog {
+    skillDir;
+    entriesByName = new Map();
+    entriesByDir = new Map();
+    duplicates = [];
+    missingSkillMd = [];
+    loadErrors = [];
+    // 快照缓存与版本探测状态
+    cachedCandidates = null;
+    lastScannedMtimeMs = 0;
+    lastScanProviderName;
+    lastScanRank;
+    constructor(skillDir) {
+        this.skillDir = skillDir;
+    }
+    /**
+     * 从指定目录异步扫描并构建已预热的 SkillCatalog 深度实例。
+     */
+    static async fromDirectory(skillDir, options) {
+        options?.signal?.throwIfAborted();
+        const catalog = new SkillCatalog(skillDir);
+        await catalog.scan(options);
+        return catalog;
+    }
+    /**
+     * 清空快照与索引，强制下一轮查询重新从磁盘装载。
+     */
+    invalidate() {
+        this.cachedCandidates = null;
+        this.lastScannedMtimeMs = 0;
+        this.entriesByName.clear();
+        this.entriesByDir.clear();
+        this.duplicates.length = 0;
+        this.missingSkillMd.length = 0;
+        this.loadErrors.length = 0;
+    }
+    /**
+     * 探测目录是否发生变动。
+     */
+    async isDirModified(signal) {
+        if (this.lastScannedMtimeMs === 0 || this.entriesByName.size === 0)
+            return true;
+        try {
+            signal?.throwIfAborted();
+            const dirStat = await stat(this.skillDir);
+            return dirStat.mtimeMs > this.lastScannedMtimeMs;
+        }
+        catch {
+            return true;
+        }
+    }
+    /**
+     * 执行全量目录遍历与技能索引构建。
+     */
+    async scan(options) {
+        const signal = options?.signal;
+        const logger = options?.logger;
+        let dirStat;
+        try {
+            dirStat = await stat(this.skillDir);
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                logger?.warn(`[SkillCatalog] skillDir not found: ${this.skillDir}`);
+                this.invalidate();
+                return;
+            }
+            throw err;
+        }
+        let dirents;
+        try {
+            dirents = await readdir(this.skillDir, { withFileTypes: true, signal });
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code === 'ENOENT' || code === 'ENOTDIR') {
+                logger?.warn(`[SkillCatalog] skillDir not found: ${this.skillDir}`);
+                this.invalidate();
+                return;
+            }
+            throw err;
+        }
+        // 重置内存临时状态
+        this.entriesByName.clear();
+        this.entriesByDir.clear();
+        this.duplicates.length = 0;
+        this.missingSkillMd.length = 0;
+        this.loadErrors.length = 0;
+        this.cachedCandidates = null;
+        const sorted = dirents.filter((e) => e.isDirectory() && !e.name.startsWith('.')).sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of sorted) {
+            signal?.throwIfAborted();
+            const skillPath = join(this.skillDir, entry.name, 'SKILL.md');
+            try {
+                await stat(skillPath);
+            }
+            catch (err) {
+                const code = err?.code;
+                logger?.debug?.(`[SkillCatalog] skip ${entry.name}: no SKILL.md (${code ?? String(err)})`);
+                this.missingSkillMd.push(entry.name);
+                continue;
+            }
+            let doc;
+            try {
+                doc = await SkillDocument.fromFile(skillPath, signal);
+            }
+            catch (err) {
+                const msg = String(err?.message ?? err);
+                logger?.warn(`[SkillCatalog] skip ${skillPath}: parse failed — ${msg}`);
+                this.loadErrors.push({ path: skillPath, error: msg });
+                continue;
+            }
+            if (this.entriesByName.has(doc.name)) {
+                logger?.warn(`[SkillCatalog] skip ${skillPath}: duplicate skill name "${doc.name}"`);
+                this.duplicates.push(doc.name);
+                continue;
+            }
+            const nameDrift = doc.name !== entry.name;
+            if (nameDrift) {
+                logger?.warn(`[SkillCatalog] skill name "${doc.name}" != directory "${entry.name}" (using frontmatter)`);
+            }
+            const catalogEntry = {
+                directoryName: entry.name,
+                skillPath,
+                document: doc,
+                nameDrift,
+            };
+            this.entriesByName.set(doc.name, catalogEntry);
+            this.entriesByDir.set(entry.name, catalogEntry);
+        }
+        this.lastScannedMtimeMs = dirStat.mtimeMs;
+    }
+    /**
+     * 映射当前有效技能为 DSH SkillCandidate 快照。
+     * 自动按 mtime 评估有效性，未变动时直接复用不可变快照，零重复读盘。
+     */
+    async listCandidates(providerName, rank, options) {
+        options?.signal?.throwIfAborted();
+        const needsScan = options?.forceScan ||
+            this.cachedCandidates === null ||
+            this.lastScanProviderName !== providerName ||
+            this.lastScanRank !== rank ||
+            (await this.isDirModified(options?.signal));
+        if (needsScan) {
+            await this.scan(options);
+            const list = [];
+            for (const entry of this.entriesByName.values()) {
+                list.push(entry.document.toCandidate(providerName, rank));
+            }
+            this.cachedCandidates = Object.freeze(list);
+            this.lastScanProviderName = providerName;
+            this.lastScanRank = rank;
+        }
+        return this.cachedCandidates;
+    }
+    /**
+     * 根据候选技能的 locator 与名称解析出完整 SkillDefinition。
+     * 优先命中内存缓存；若发生热重读，自动自愈更新回内存映射，消除状态撕裂缝隙。
+     */
+    async getDefinition(candidate, providerName, options) {
+        options?.signal?.throwIfAborted();
+        const locator = candidate.locator;
+        if (!locator?.path)
+            return undefined;
+        // 优先命中内存缓存
+        const cached = this.entriesByName.get(candidate.name);
+        if (cached && cached.skillPath === locator.path) {
+            return cached.document.toDefinition(providerName);
+        }
+        // 若缓存未命中则重新从文件读取
+        let doc;
+        try {
+            doc = await SkillDocument.fromFile(locator.path, options?.signal);
+        }
+        catch (err) {
+            if (err?.name === 'AbortError')
+                throw err;
+            const code = err?.code;
+            if (code === 'ENOENT')
+                return undefined;
+            options?.logger?.warn(`[SkillCatalog] get ${candidate.name}: read failed (${code ?? String(err)})`);
+            return undefined;
+        }
+        if (doc.name !== candidate.name) {
+            options?.logger?.warn(`[SkillCatalog] get ${candidate.name}: name drift "${doc.name}" != "${candidate.name}"`);
+            return undefined;
+        }
+        // 自愈回写：将重新读取解析出的文档更新进内部索引，保持状态严格一致
+        const dirName = cached?.directoryName ?? candidate.name;
+        const updatedEntry = {
+            directoryName: dirName,
+            skillPath: locator.path,
+            document: doc,
+            nameDrift: doc.name !== dirName,
+        };
+        this.entriesByName.set(doc.name, updatedEntry);
+        this.entriesByDir.set(dirName, updatedEntry);
+        this.cachedCandidates = null; // 快照失效，以便下一轮刷新
+        return doc.toDefinition(providerName);
+    }
+    /**
+     * 生成目录健康度与一致性完整体检报告（供 verify 脚本与 CI 质量门禁复用）。
+     */
+    verifyIntegrity() {
+        const entries = Array.from(this.entriesByName.values());
+        const ok = this.duplicates.length === 0 && this.loadErrors.length === 0 && entries.every((e) => !e.nameDrift);
+        return {
+            total: entries.length,
+            entries,
+            duplicates: [...this.duplicates],
+            missingSkillMd: [...this.missingSkillMd],
+            errors: [...this.loadErrors],
+            ok,
+        };
+    }
+}
+//# sourceMappingURL=catalog.js.map

package/lib/catalog.js.map

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

package/lib/document.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @wenaixi/dsh-superpower — SkillDocument 深度模块
+ *
+ * 封装单个技能文档的读取、BOM/CRLF 归一化、YAML frontmatter 解析、
+ * 规范字段与调用策略校验，以及向 SkillCandidate 和 SkillDefinition 的契约映射。
+ *
+ * 核心原则：
+ * - Depth: 将大量文件 I/O、边界扫描、YAML 解析与类型收敛封装在紧凑的小接口后；
+ * - Locality: 所有 frontmatter 规则与校验逻辑内聚于此；
+ * - Test Surface: 对外暴露规范接口，成为运行时与验证脚本的共同测试表面。
+ */
+import type { SkillCandidate, SkillDefinition } from '@deepseek-ai/dsh-skill';
+export interface SkillInvocationPolicy {
+    modelInvocable: boolean;
+    userInvocable: boolean;
+}
+export interface SkillDocumentData {
+    name: string;
+    description: string;
+    whenToUse?: string;
+    invocation: SkillInvocationPolicy;
+    metadata?: Record<string, unknown>;
+    extra: Record<string, unknown>;
+}
+export declare class SkillDocument {
+    readonly path: string;
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: SkillInvocationPolicy;
+    readonly metadata?: Record<string, unknown>;
+    readonly body: string;
+    readonly rawFrontmatterData: Record<string, unknown>;
+    private constructor();
+    /**
+     * 从指定文件路径异步解析 SkillDocument。
+     */
+    static fromFile(filePath: string, signal?: AbortSignal): Promise<SkillDocument>;
+    /**
+     * 从内存中的原始 markdown 字符串直接解析（用于测试或动态构建）。
+     */
+    static fromString(raw: string, filePath?: string): SkillDocument;
+    /**
+     * 映射为 DSH SkillCandidate 契约对象。
+     */
+    toCandidate(providerName: string, rank: number): SkillCandidate;
+    /**
+     * 映射为 DSH SkillDefinition 契约对象。
+     */
+    toDefinition(providerName: string): SkillDefinition;
+}
+//# sourceMappingURL=document.d.ts.map

package/lib/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAG7E,MAAM,WAAW,qBAAqB;IACpC,cAAc,EAAE,OAAO,CAAA;IACvB,aAAa,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,qBAAqB,CAAA;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AA+FD,qBAAa,aAAa;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAA;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAEpD,OAAO;IA6BP;;OAEG;WACU,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IAWrF;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,SAAa,GAAG,aAAa;IAKpE;;OAEG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc;IAiB/D;;OAEG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,eAAe;CAepD"}