mcp-probe-kit 3.0.19 → 3.0.22

package/build/utils/ui-data-loader.js

@@ -150,9 +150,20 @@ export class UIDataLoader {
      * 提取类别名称
      */
     extractCategory(filename) {
-        // 移除扩展名
         let category = filename.replace(/\.json$/, '');
-        // 处理子目录（如 stacks/react.json -> react）
+        // themes/presets.json -> ui-themes
+        if (category.startsWith('themes/')) {
+            return 'ui-themes';
+        }
+        // guidelines/vercel-web-interface.json -> ui-guidelines-vercel
+        if (category.startsWith('guidelines/')) {
+            return 'ui-guidelines-vercel';
+        }
+        // shadcn/blocks.json -> shadcn-blocks
+        if (category.startsWith('shadcn/')) {
+            return category.replace('/', '-');
+        }
+        // stacks/react.json -> react
         if (category.includes('/')) {
             const parts = category.split('/');
             category = parts[parts.length - 1];

package/build/utils/ui-metadata.d.ts

@@ -0,0 +1,27 @@
+/**
+ * UI/UX 多源同步元数据
+ */
+export interface UISourceMetadata {
+    version: string;
+    syncedAt: string;
+    checksum?: string;
+    style?: string;
+    blocks?: number;
+    components?: number;
+}
+export interface UISyncMetadata {
+    /** @deprecated 兼容旧版：等同 uipro-cli version */
+    version: string;
+    syncedAt: string;
+    /** @deprecated 兼容旧版 */
+    source: string;
+    format: 'json';
+    sources: {
+        'uipro-cli'?: UISourceMetadata;
+        shadcn?: UISourceMetadata;
+        themes?: UISourceMetadata;
+        vercel?: UISourceMetadata;
+    };
+}
+export declare function readUISyncMetadata(outputDir: string): UISyncMetadata | null;
+export declare function writeUISyncMetadata(outputDir: string, metadata: UISyncMetadata): void;

package/build/utils/ui-metadata.js

@@ -0,0 +1,39 @@
+/**
+ * UI/UX 多源同步元数据
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export function readUISyncMetadata(outputDir) {
+    const metadataPath = path.join(outputDir, 'metadata.json');
+    if (!fs.existsSync(metadataPath)) {
+        return null;
+    }
+    try {
+        const raw = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
+        if (!raw.sources) {
+            return {
+                version: raw.version || 'unknown',
+                syncedAt: raw.syncedAt || new Date(0).toISOString(),
+                source: raw.source || 'uipro-cli',
+                format: 'json',
+                sources: {
+                    'uipro-cli': {
+                        version: raw.version || 'unknown',
+                        syncedAt: raw.syncedAt || new Date(0).toISOString(),
+                    },
+                },
+            };
+        }
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeUISyncMetadata(outputDir, metadata) {
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+    const metadataPath = path.join(outputDir, 'metadata.json');
+    fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf-8');
+}

package/build/utils/ui-search-engine.d.ts

@@ -42,6 +42,7 @@ export declare class UISearchEngine {
      * 搜索 UI/UX 数据
      */
     search(query: string, options?: UISearchOptions): UISearchResult[];
+    private matchesStack;
     /**
      * 获取所有类别
      */

package/build/utils/ui-search-engine.js

@@ -72,16 +72,13 @@ export class UISearchEngine {
      * 搜索 UI/UX 数据
      */
     search(query, options = {}) {
-        const { category, limit = 10, minScore = 0, } = options;
-        // 执行 BM25 搜索
-        const bm25Results = this.bm25.search(query, limit * 2);
-        // 转换结果
+        const { category, stack, limit = 10, minScore = 0, } = options;
+        const bm25Results = this.bm25.search(query, limit * 3, category ? (metadata) => metadata?.category === category : undefined);
         const results = [];
         for (const result of bm25Results) {
             if (result.score < minScore)
                 continue;
             const { category: resultCategory, index } = result.metadata;
-            // 过滤类别
             if (category && resultCategory !== category) {
                 continue;
             }
@@ -89,11 +86,15 @@ export class UISearchEngine {
             if (!dataset || index >= dataset.length) {
                 continue;
             }
+            const item = dataset[index];
+            if (stack && !this.matchesStack(item, stack)) {
+                continue;
+            }
             results.push({
                 id: result.id,
                 score: result.score,
                 category: resultCategory,
-                data: dataset[index],
+                data: item,
             });
             if (results.length >= limit) {
                 break;
@@ -101,6 +102,19 @@ export class UISearchEngine {
         }
         return results;
     }
+    matchesStack(item, stack) {
+        const normalized = stack.toLowerCase();
+        const itemStack = String(item.stack || '').toLowerCase();
+        if (itemStack && itemStack !== normalized) {
+            if (!(normalized.includes('next') && itemStack === 'react')) {
+                return false;
+            }
+        }
+        if (normalized.includes('shadcn') || normalized.includes('react') || normalized.includes('next')) {
+            return item.category?.startsWith('shadcn-') || itemStack === 'react' || !itemStack;
+        }
+        return true;
+    }
     /**
      * 获取所有类别
      */

package/build/utils/ui-sync.d.ts

@@ -1,16 +1,38 @@
 /**
  * UI/UX 数据同步工具
  *
- * 从 npm 包 uipro-cli 同步数据到缓存目录
+ * 多源同步：
+ * - uipro-cli（设计词典）
+ * - shadcn/ui registry（blocks + components 索引）
+ * - ui-themes（shadcn 兼容 CSS 变量主题预设）
+ * - Vercel Web Interface Guidelines（可搜索规范条文）
  */
+import { type UISyncMetadata } from './ui-metadata.js';
 export interface SyncRuntimeOptions {
     signal?: AbortSignal;
     onProgress?: (progress: number, message: string) => Promise<void> | void;
+    force?: boolean;
 }
+export interface UISourceUpdateStatus {
+    current?: string;
+    latest: string;
+    upToDate: boolean;
+}
+export interface UIUpdateCheckResult {
+    hasUpdate: boolean;
+    uipro: UISourceUpdateStatus;
+    shadcn: UISourceUpdateStatus;
+    themes: UISourceUpdateStatus;
+    vercel: UISourceUpdateStatus;
+}
+export declare function checkUISourcesUpdate(outputDir: string, signal?: AbortSignal): Promise<UIUpdateCheckResult>;
 /**
  * 同步 UI/UX 数据到指定目录（通用函数）
  */
-export declare function syncUIDataTo(outputDir: string, verbose?: boolean, options?: SyncRuntimeOptions): Promise<void>;
+export declare function syncUIDataTo(outputDir: string, verbose?: boolean, options?: SyncRuntimeOptions): Promise<{
+    skipped: boolean;
+    metadata: UISyncMetadata;
+}>;
 /**
  * 同步 UI/UX 数据到缓存
  */

package/build/utils/ui-sync.js

@@ -1,7 +1,11 @@
 /**
  * UI/UX 数据同步工具
  *
- * 从 npm 包 uipro-cli 同步数据到缓存目录
+ * 多源同步：
+ * - uipro-cli（设计词典）
+ * - shadcn/ui registry（blocks + components 索引）
+ * - ui-themes（shadcn 兼容 CSS 变量主题预设）
+ * - Vercel Web Interface Guidelines（可搜索规范条文）
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -10,6 +14,10 @@ import * as https from 'https';
 import * as tar from 'tar';
 import { createWriteStream } from 'fs';
 import { parse as parseCSV } from 'csv-parse/sync';
+import { readUISyncMetadata, writeUISyncMetadata } from './ui-metadata.js';
+import { computeRegistryChecksum, fetchShadcnRegistry, syncShadcnTo, } from './shadcn-sync.js';
+import { computeThemesChecksum, syncThemesTo } from './themes-sync.js';
+import { getVercelGuidelinesChecksum, syncVercelGuidelinesTo } from './vercel-guidelines-sync.js';
 function throwIfAborted(signal, message) {
     if (!signal?.aborted) {
         return;
@@ -24,9 +32,6 @@ async function emitProgress(options, progress, message) {
     }
     await options.onProgress(progress, message);
 }
-/**
- * 获取 npm 包的最新版本号
- */
 async function getLatestVersion(packageName, signal) {
     throwIfAborted(signal, 'Sync cancelled before fetching latest version');
     return new Promise((resolve, reject) => {
@@ -68,9 +73,6 @@ async function getLatestVersion(packageName, signal) {
         });
     });
 }
-/**
- * 下载文件
- */
 async function downloadFile(url, outputPath, signal) {
     throwIfAborted(signal, 'Sync cancelled before download');
     return new Promise((resolve, reject) => {
@@ -122,9 +124,6 @@ async function downloadFile(url, outputPath, signal) {
         });
     });
 }
-/**
- * 解压 tarball 并提取指定目录
- */
 async function extractTarball(tarballPath, extractPath, targetDir, signal) {
     throwIfAborted(signal, 'Sync cancelled before extract');
     const tempDir = path.join(extractPath, '.temp');
@@ -142,9 +141,6 @@ async function extractTarball(tarballPath, extractPath, targetDir, signal) {
     }
     return sourceDir;
 }
-/**
- * 转换 CSV 到 JSON
- */
 function convertCSVToJSON(csvContent, filename) {
     try {
         const records = parseCSV(csvContent, {
@@ -164,9 +160,6 @@ function convertCSVToJSON(csvContent, filename) {
         return [];
     }
 }
-/**
- * 收集目录下所有 CSV 文件（递归）
- */
 function collectCsvFiles(rootDir) {
     const files = [];
     const entries = fs.readdirSync(rootDir, { withFileTypes: true });
@@ -182,9 +175,6 @@ function collectCsvFiles(rootDir) {
     }
     return files;
 }
-/**
- * 处理数据文件
- */
 async function processDataFiles(sourceDir, outputDir, verbose, options) {
     throwIfAborted(options?.signal, 'Sync cancelled before processing files');
     if (!fs.existsSync(outputDir)) {
@@ -218,7 +208,7 @@ async function processDataFiles(sourceDir, outputDir, verbose, options) {
             fs.mkdirSync(outputSubDir, { recursive: true });
         }
         const outputPath = path.join(outputSubDir, outputFile);
-        fs.writeFileSync(outputPath, JSON.stringify(jsonData, null, 2), 'utf-8');
+        fs.writeFileSync(outputPath, `${JSON.stringify(jsonData, null, 2)}\n`, 'utf-8');
         if (verbose) {
             console.log(`  → ${outputFile} (${jsonData.length} records)`);
         }
@@ -226,104 +216,181 @@ async function processDataFiles(sourceDir, outputDir, verbose, options) {
         await emitProgress(options, fileProgress, `Processed ${index + 1}/${csvFiles.length}: ${relativePath}`);
     }
 }
-/**
- * 写入元数据
- */
-function writeMetadata(outputDir, metadata) {
-    const metadataPath = path.join(outputDir, 'metadata.json');
-    fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2), 'utf-8');
-}
-/**
- * 清理临时文件
- */
 function cleanup(tempDir) {
     if (fs.existsSync(tempDir)) {
         fs.rmSync(tempDir, { recursive: true, force: true });
     }
 }
+export async function checkUISourcesUpdate(outputDir, signal) {
+    const existing = readUISyncMetadata(outputDir);
+    const latestUipro = await getLatestVersion('uipro-cli', signal);
+    const registry = await fetchShadcnRegistry(signal);
+    const latestShadcn = computeRegistryChecksum(registry);
+    const uiproCurrent = existing?.sources['uipro-cli']?.version || existing?.version;
+    const shadcnCurrent = existing?.sources.shadcn?.checksum || existing?.sources.shadcn?.version;
+    const themesCurrent = existing?.sources.themes?.checksum || existing?.sources.themes?.version;
+    const vercelCurrent = existing?.sources.vercel?.checksum || existing?.sources.vercel?.version;
+    const latestThemes = computeThemesChecksum();
+    const latestVercel = await getVercelGuidelinesChecksum(signal);
+    const uiproUpToDate = uiproCurrent === latestUipro;
+    const shadcnUpToDate = shadcnCurrent === latestShadcn;
+    const themesUpToDate = themesCurrent === latestThemes;
+    const vercelUpToDate = vercelCurrent === latestVercel;
+    return {
+        hasUpdate: !uiproUpToDate || !shadcnUpToDate || !themesUpToDate || !vercelUpToDate,
+        uipro: {
+            current: uiproCurrent,
+            latest: latestUipro,
+            upToDate: uiproUpToDate,
+        },
+        shadcn: {
+            current: shadcnCurrent,
+            latest: latestShadcn,
+            upToDate: shadcnUpToDate,
+        },
+        themes: {
+            current: themesCurrent,
+            latest: latestThemes,
+            upToDate: themesUpToDate,
+        },
+        vercel: {
+            current: vercelCurrent,
+            latest: latestVercel,
+            upToDate: vercelUpToDate,
+        },
+    };
+}
+async function syncUiproPackage(outputDir, latestVersion, verbose, options) {
+    const packageName = 'uipro-cli';
+    const tarballUrl = `https://registry.npmjs.org/${packageName}/-/${packageName}-${latestVersion}.tgz`;
+    const tempDir = path.join(os.tmpdir(), '.mcp-ui-sync');
+    const tarballPath = path.join(tempDir, 'package.tgz');
+    if (!fs.existsSync(tempDir)) {
+        fs.mkdirSync(tempDir, { recursive: true });
+    }
+    if (verbose) {
+        console.log('Downloading uipro-cli tarball...');
+    }
+    await downloadFile(tarballUrl, tarballPath, options?.signal);
+    await emitProgress(options, 40, 'Downloaded uipro-cli tarball');
+    const extractedDataDir = await extractTarball(tarballPath, tempDir, 'package/assets/data', options?.signal);
+    await emitProgress(options, 50, 'Extracted uipro-cli data');
+    await processDataFiles(extractedDataDir, outputDir, verbose, {
+        signal: options?.signal,
+        onProgress: async (progress, message) => {
+            const normalized = 50 + Math.round(progress * 0.25);
+            await emitProgress(options, normalized, message);
+        },
+    });
+    cleanup(tempDir);
+    return {
+        version: latestVersion,
+        syncedAt: new Date().toISOString(),
+    };
+}
 /**
  * 同步 UI/UX 数据到指定目录（通用函数）
  */
 export async function syncUIDataTo(outputDir, verbose = false, options) {
-    const packageName = 'uipro-cli';
+    const force = options?.force ?? false;
     throwIfAborted(options?.signal, 'Sync cancelled before start');
     await emitProgress(options, 5, 'Initializing sync');
     if (verbose) {
         console.log('🚀 Starting UI/UX data sync...\n');
     }
-    try {
-        // 1. 获取最新版本
-        if (verbose) {
-            console.log(`Fetching latest version of ${packageName}...`);
-        }
-        const latestVersion = await getLatestVersion(packageName, options?.signal);
-        await emitProgress(options, 15, `Fetched latest version: ${latestVersion}`);
+    const existing = readUISyncMetadata(outputDir);
+    const updateCheck = await checkUISourcesUpdate(outputDir, options?.signal);
+    await emitProgress(options, 15, 'Checked upstream versions');
+    if (!force && !updateCheck.hasUpdate && existing) {
+        await emitProgress(options, 100, 'All UI sources up to date');
         if (verbose) {
-            console.log(`✓ Latest version: ${latestVersion}\n`);
-        }
-        // 2. 下载 tarball
-        const tarballUrl = `https://registry.npmjs.org/${packageName}/-/${packageName}-${latestVersion}.tgz`;
-        const tempDir = path.join(os.tmpdir(), '.mcp-ui-sync');
-        const tarballPath = path.join(tempDir, 'package.tgz');
-        if (!fs.existsSync(tempDir)) {
-            fs.mkdirSync(tempDir, { recursive: true });
+            console.log('✅ All UI sources up to date, skipping sync.');
+            console.log(`   uipro-cli: ${updateCheck.uipro.latest}`);
+            console.log(`   shadcn: ${updateCheck.shadcn.latest}`);
+            console.log(`   themes: ${updateCheck.themes.latest}`);
+            console.log(`   vercel: ${updateCheck.vercel.latest}`);
         }
-        if (verbose) {
-            console.log(`Downloading tarball...`);
+        return { skipped: true, metadata: existing };
+    }
+    const sources = {
+        ...(existing?.sources || {}),
+    };
+    try {
+        if (force || !updateCheck.uipro.upToDate) {
+            if (verbose) {
+                console.log(`Syncing uipro-cli ${updateCheck.uipro.latest}...`);
+            }
+            const uiproMeta = await syncUiproPackage(outputDir, updateCheck.uipro.latest, verbose, options);
+            sources['uipro-cli'] = {
+                version: uiproMeta.version,
+                syncedAt: uiproMeta.syncedAt,
+            };
         }
-        await downloadFile(tarballUrl, tarballPath, options?.signal);
-        await emitProgress(options, 35, 'Downloaded package tarball');
-        if (verbose) {
-            console.log('✓ Downloaded tarball\n');
+        await emitProgress(options, 78, 'Syncing shadcn/ui registry');
+        const shadcnResult = await syncShadcnTo(outputDir, {
+            signal: options?.signal,
+            force,
+            existingChecksum: updateCheck.shadcn.current,
+        });
+        if (shadcnResult) {
+            sources.shadcn = shadcnResult.metadata;
+            if (verbose) {
+                console.log(`✓ shadcn registry synced (${shadcnResult.blocks} blocks, ${shadcnResult.components} components)`);
+            }
         }
-        // 3. 解压并提取数据
-        if (verbose) {
-            console.log('Extracting data files...');
+        else if (verbose) {
+            console.log('✓ shadcn registry unchanged');
         }
-        const extractedDataDir = await extractTarball(tarballPath, tempDir, 'package/assets/data', options?.signal);
-        await emitProgress(options, 50, 'Extracted package data files');
-        if (verbose) {
-            console.log('✓ Extracted data files\n');
+        await emitProgress(options, 85, 'Syncing UI theme presets');
+        const themesResult = syncThemesTo(outputDir, {
+            force,
+            existingChecksum: updateCheck.themes.current,
+        });
+        if (themesResult) {
+            sources.themes = themesResult.metadata;
+            if (verbose) {
+                console.log(`✓ UI themes synced (${themesResult.count} presets)`);
+            }
         }
-        // 4. 处理数据文件
-        if (verbose) {
-            console.log('Processing data files...');
+        else if (verbose) {
+            console.log('✓ UI themes unchanged');
         }
-        await processDataFiles(extractedDataDir, outputDir, verbose, {
+        await emitProgress(options, 92, 'Syncing Vercel Web Interface Guidelines');
+        const vercelResult = await syncVercelGuidelinesTo(outputDir, {
             signal: options?.signal,
-            onProgress: async (progress, message) => {
-                const normalized = 50 + Math.round(progress * 0.35);
-                await emitProgress(options, normalized, message);
-            },
+            force,
+            existingChecksum: updateCheck.vercel.current,
         });
-        if (verbose) {
-            console.log('✓ Processed all data files\n');
+        if (vercelResult) {
+            sources.vercel = vercelResult.metadata;
+            if (verbose) {
+                console.log(`✓ Vercel guidelines synced (${vercelResult.count} rules)`);
+            }
+        }
+        else if (verbose) {
+            console.log('✓ Vercel guidelines unchanged');
         }
-        // 5. 写入元数据
         const metadata = {
-            version: latestVersion,
+            version: sources['uipro-cli']?.version || updateCheck.uipro.latest,
             syncedAt: new Date().toISOString(),
-            source: packageName,
+            source: 'uipro-cli',
             format: 'json',
+            sources,
         };
-        writeMetadata(outputDir, metadata);
-        await emitProgress(options, 90, 'Wrote metadata');
-        if (verbose) {
-            console.log('✓ Written metadata\n');
-        }
-        // 6. 清理临时文件
-        cleanup(tempDir);
+        writeUISyncMetadata(outputDir, metadata);
         await emitProgress(options, 100, 'Sync completed');
         if (verbose) {
-            console.log('✓ Cleaned up temporary files\n');
-            console.log('✅ Sync completed successfully!');
-            console.log(`   Version: ${latestVersion}`);
+            console.log('\n✅ Sync completed successfully!');
+            console.log(`   uipro-cli: ${metadata.sources['uipro-cli']?.version}`);
+            console.log(`   shadcn: ${metadata.sources.shadcn?.blocks || 0} blocks, ${metadata.sources.shadcn?.components || 0} components`);
+            console.log(`   themes: ${sources.themes?.version || 'n/a'} (${sources.themes?.checksum?.slice(0, 8) || '—'})`);
+            console.log(`   vercel: ${sources.vercel?.checksum?.slice(0, 8) || 'n/a'} rules checksum`);
             console.log(`   Output: ${outputDir}`);
         }
+        return { skipped: false, metadata };
     }
     catch (error) {
-        const tempDir = path.join(os.tmpdir(), '.mcp-ui-sync');
-        cleanup(tempDir);
+        cleanup(path.join(os.tmpdir(), '.mcp-ui-sync'));
         throw error;
     }
 }
@@ -332,6 +399,5 @@ export async function syncUIDataTo(outputDir, verbose = false, options) {
  */
 export async function syncUIDataToCache(force = false, verbose = false, options) {
     const cacheDir = path.join(os.homedir(), '.mcp-probe-kit', 'ui-ux-data');
-    void force;
-    await syncUIDataTo(cacheDir, verbose, options);
+    await syncUIDataTo(cacheDir, verbose, { ...options, force });
 }

package/build/utils/vercel-guidelines-sync.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Vercel Web Interface Guidelines → 可搜索 JSON
+ * @see https://github.com/vercel-labs/web-interface-guidelines
+ */
+import type { UISourceMetadata } from './ui-metadata.js';
+export declare const VERCEL_GUIDELINES_URL = "https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/AGENTS.md";
+export declare const VERCEL_GUIDELINES_VERSION = "2026-04-06";
+export interface VercelGuidelineRecord {
+    id: string;
+    title: string;
+    section: string;
+    subsection: string;
+    level: 'MUST' | 'SHOULD' | 'NEVER' | 'INFO';
+    rule: string;
+    description: string;
+    category: string;
+    source: string;
+    tags: string[];
+}
+export interface VercelGuidelinesSyncResult {
+    metadata: UISourceMetadata;
+    count: number;
+}
+export declare function parseVercelGuidelinesMarkdown(markdown: string): VercelGuidelineRecord[];
+export declare function syncVercelGuidelinesTo(outputDir: string, options?: {
+    signal?: AbortSignal;
+    force?: boolean;
+    existingChecksum?: string;
+}): Promise<VercelGuidelinesSyncResult | null>;
+export declare function getVercelGuidelinesChecksum(signal?: AbortSignal): Promise<string>;