mcp-probe-kit 1.13.0 → 1.15.1

package/build/utils/ui-sync.js

@@ -0,0 +1,241 @@
+/**
+ * UI/UX 数据同步工具
+ *
+ * 从 npm 包 uipro-cli 同步数据到缓存目录
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import * as https from 'https';
+import * as tar from 'tar';
+import { createWriteStream } from 'fs';
+import { parse as parseCSV } from 'csv-parse/sync';
+/**
+ * 获取 npm 包的最新版本号
+ */
+async function getLatestVersion(packageName) {
+    return new Promise((resolve, reject) => {
+        const url = `https://registry.npmjs.org/${packageName}/latest`;
+        https.get(url, (res) => {
+            let data = '';
+            res.on('data', (chunk) => {
+                data += chunk;
+            });
+            res.on('end', () => {
+                try {
+                    const pkg = JSON.parse(data);
+                    resolve(pkg.version);
+                }
+                catch (error) {
+                    reject(new Error(`Failed to parse package metadata: ${error}`));
+                }
+            });
+        }).on('error', (error) => {
+            reject(new Error(`Failed to fetch package metadata: ${error}`));
+        });
+    });
+}
+/**
+ * 下载文件
+ */
+async function downloadFile(url, outputPath) {
+    return new Promise((resolve, reject) => {
+        https.get(url, (res) => {
+            if (res.statusCode === 302 || res.statusCode === 301) {
+                if (res.headers.location) {
+                    downloadFile(res.headers.location, outputPath).then(resolve).catch(reject);
+                    return;
+                }
+            }
+            if (res.statusCode !== 200) {
+                reject(new Error(`Failed to download: HTTP ${res.statusCode}`));
+                return;
+            }
+            const fileStream = createWriteStream(outputPath);
+            res.pipe(fileStream);
+            fileStream.on('finish', () => {
+                fileStream.close();
+                resolve();
+            });
+            fileStream.on('error', (error) => {
+                fs.unlinkSync(outputPath);
+                reject(error);
+            });
+        }).on('error', (error) => {
+            reject(error);
+        });
+    });
+}
+/**
+ * 解压 tarball 并提取指定目录
+ */
+async function extractTarball(tarballPath, extractPath, targetDir) {
+    const tempDir = path.join(extractPath, '.temp');
+    if (!fs.existsSync(tempDir)) {
+        fs.mkdirSync(tempDir, { recursive: true });
+    }
+    await tar.extract({
+        file: tarballPath,
+        cwd: tempDir,
+    });
+    const sourceDir = path.join(tempDir, targetDir);
+    if (!fs.existsSync(sourceDir)) {
+        throw new Error(`Target directory not found in tarball: ${targetDir}`);
+    }
+    return sourceDir;
+}
+/**
+ * 转换 CSV 到 JSON
+ */
+function convertCSVToJSON(csvContent, filename) {
+    try {
+        const records = parseCSV(csvContent, {
+            columns: true,
+            skip_empty_lines: true,
+            trim: true,
+            relax_quotes: true,
+            relax_column_count: true,
+            escape: '\\',
+            quote: '"',
+            skip_records_with_error: true,
+        });
+        return records;
+    }
+    catch (error) {
+        console.warn(`Warning: Failed to parse ${filename}, skipping: ${error}`);
+        return [];
+    }
+}
+/**
+ * 处理数据文件
+ */
+async function processDataFiles(sourceDir, outputDir, verbose) {
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+    const files = fs.readdirSync(sourceDir);
+    for (const file of files) {
+        const sourcePath = path.join(sourceDir, file);
+        const stat = fs.statSync(sourcePath);
+        if (stat.isDirectory()) {
+            const subOutputDir = path.join(outputDir, file);
+            await processDataFiles(sourcePath, subOutputDir, verbose);
+            continue;
+        }
+        if (!file.endsWith('.csv')) {
+            continue;
+        }
+        if (verbose) {
+            console.log(`Processing: ${file}`);
+        }
+        const csvContent = fs.readFileSync(sourcePath, 'utf-8');
+        const jsonData = convertCSVToJSON(csvContent, file);
+        if (jsonData.length === 0) {
+            if (verbose) {
+                console.log(`  ⚠️  Skipped ${file} (no valid records)`);
+            }
+            continue;
+        }
+        const outputFile = file.replace('.csv', '.json');
+        const outputPath = path.join(outputDir, outputFile);
+        fs.writeFileSync(outputPath, JSON.stringify(jsonData, null, 2), 'utf-8');
+        if (verbose) {
+            console.log(`  → ${outputFile} (${jsonData.length} records)`);
+        }
+    }
+}
+/**
+ * 写入元数据
+ */
+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 });
+    }
+}
+/**
+ * 同步 UI/UX 数据到指定目录（通用函数）
+ */
+export async function syncUIDataTo(outputDir, verbose = false) {
+    const packageName = 'uipro-cli';
+    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);
+        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 });
+        }
+        if (verbose) {
+            console.log(`Downloading tarball...`);
+        }
+        await downloadFile(tarballUrl, tarballPath);
+        if (verbose) {
+            console.log('✓ Downloaded tarball\n');
+        }
+        // 3. 解压并提取数据
+        if (verbose) {
+            console.log('Extracting data files...');
+        }
+        const extractedDataDir = await extractTarball(tarballPath, tempDir, 'package/assets/data');
+        if (verbose) {
+            console.log('✓ Extracted data files\n');
+        }
+        // 4. 处理数据文件
+        if (verbose) {
+            console.log('Processing data files...');
+        }
+        await processDataFiles(extractedDataDir, outputDir, verbose);
+        if (verbose) {
+            console.log('✓ Processed all data files\n');
+        }
+        // 5. 写入元数据
+        const metadata = {
+            version: latestVersion,
+            syncedAt: new Date().toISOString(),
+            source: packageName,
+            format: 'json',
+        };
+        writeMetadata(outputDir, metadata);
+        if (verbose) {
+            console.log('✓ Written metadata\n');
+        }
+        // 6. 清理临时文件
+        cleanup(tempDir);
+        if (verbose) {
+            console.log('✓ Cleaned up temporary files\n');
+            console.log('✅ Sync completed successfully!');
+            console.log(`   Version: ${latestVersion}`);
+            console.log(`   Output: ${outputDir}`);
+        }
+    }
+    catch (error) {
+        const tempDir = path.join(os.tmpdir(), '.mcp-ui-sync');
+        cleanup(tempDir);
+        throw error;
+    }
+}
+/**
+ * 同步 UI/UX 数据到缓存
+ */
+export async function syncUIDataToCache(force = false, verbose = false) {
+    const cacheDir = path.join(os.homedir(), '.mcp-probe-kit', 'ui-ux-data');
+    await syncUIDataTo(cacheDir, verbose);
+}

package/docs/BEST_PRACTICES.md

@@ -2,11 +2,15 @@
 
 > 完整的工具调用指南和使用技巧
 
+**版本**: v1.14.0 | **工具总数**: 46 个
+
 ---
 
 ## 📖 目录
 
 - [工具调用写法指南](#工具调用写法指南)
+  - [UI/UX 工具调用](#uiux-工具调用) 🆕
+  - [访谈工具调用](#访谈工具调用)
   - [基础工具调用](#基础工具调用)
   - [智能编排调用](#智能编排调用)
 - [使用技巧](#使用技巧)
@@ -17,7 +21,90 @@
 
 ## 🎯 工具调用写法指南
 
-### 访谈工具调用 🆕
+### UI/UX 工具调用 🆕
+
+#### ui_design_system - 设计系统生成
+
+```
+# 方式 1：最简单（只指定技术栈）
+ui_design_system --stack react
+
+# 方式 2：指定主色调
+ui_design_system --stack react --primary-color "#3b82f6"
+
+# 方式 3：完整配置
+ui_design_system \
+  --stack nextjs \
+  --color-scheme light \
+  --primary-color "#3b82f6" \
+  --typography modern \
+  --spacing normal \
+  --border-radius medium
+
+# 方式 4：对话式
+"帮我生成一个 React 设计系统，主色调用蓝色"
+"为我的 Tailwind 项目生成配置"
+
+# 自动完成：
+# ✓ 生成完整的色彩系统（11 级色阶）
+# ✓ 生成字体系统（Sans/Serif/Mono）
+# ✓ 生成间距系统（基于 4px）
+# ✓ 生成组件样式（圆角、阴影、动画）
+# ✓ 输出可直接使用的代码
+```
+
+#### ui_search - UI/UX 智能搜索
+
+```
+# 方式 1：简单搜索
+ui_search "button primary"
+
+# 方式 2：指定类别
+ui_search "button" --category react
+
+# 方式 3：完整配置
+ui_search \
+  --query "button primary hover" \
+  --category react \
+  --limit 5 \
+  --min-score 1.0
+
+# 方式 4：对话式
+"我需要一个 React 的主按钮组件"
+"搜索一下蓝色主题的配色方案"
+"表单验证有什么 UX 最佳实践？"
+
+# 搜索技巧：
+# ✓ 使用具体关键词："primary button hover" 而不是 "button"
+# ✓ 指定类别：colors, icons, react, vue, ux-guidelines 等
+# ✓ 调整结果数量：--limit 3（快速预览）或 --limit 20（详细搜索）
+# ✓ 支持中英文：可以搜索 "按钮" 或 "button"
+```
+
+#### sync_ui_data - 数据同步
+
+```
+# 方式 1：检查更新
+sync_ui_data
+
+# 方式 2：强制同步
+sync_ui_data --force
+
+# 方式 3：详细日志
+sync_ui_data --force --verbose
+
+# 方式 4：对话式
+"检查一下 UI 数据有没有更新"
+"强制更新 UI 数据"
+
+# 数据位置：
+# ✓ 内嵌数据：npm 包内部（离线可用）
+# ✓ 缓存数据：~/.mcp-probe-kit/ui-ux-data/（自动更新）
+```
+
+---
+
+### 访谈工具调用
 
 #### interview - 需求访谈
 
@@ -918,10 +1005,179 @@ AI: 好的，我来对支付 API 进行全面体检。
 
 ---
 
+## 🎨 UI/UX 工具使用技巧 🆕
+
+### 设计系统生成技巧
+
+**1. 新项目启动**
+```
+# 步骤 1：生成基础设计系统
+ui_design_system --stack react
+
+# 步骤 2：根据需求调整
+ui_design_system --stack react --primary-color "#3b82f6" --border-radius large
+
+# 步骤 3：复制生成的代码到项目中
+```
+
+**2. 技术栈选择**
+```
+# React 项目
+ui_design_system --stack react
+
+# Next.js 项目
+ui_design_system --stack nextjs
+
+# Tailwind 项目（生成 tailwind.config.js）
+ui_design_system --stack tailwind
+
+# Vue 项目
+ui_design_system --stack vue
+```
+
+**3. 主题定制**
+```
+# 浅色主题
+ui_design_system --stack react --color-scheme light
+
+# 深色主题
+ui_design_system --stack react --color-scheme dark
+
+# 自适应主题
+ui_design_system --stack react --color-scheme auto
+```
+
+### UI 搜索技巧
+
+**1. 组件搜索**
+```
+# ❌ 不好：太模糊
+ui_search "button"
+
+# ✅ 好：具体明确
+ui_search "button primary hover effect" --category react
+
+# ✅ 更好：指定技术栈
+ui_search "button primary" --category react --limit 5
+```
+
+**2. 颜色搜索**
+```
+# 搜索配色方案
+ui_search "blue professional" --category colors
+
+# 搜索特定用途的颜色
+ui_search "saas tech primary color" --category colors
+
+# 搜索完整色阶
+ui_search "blue gradient" --category colors
+```
+
+**3. 最佳实践搜索**
+```
+# 搜索 UX 指南
+ui_search "form validation" --category ux-guidelines
+
+# 搜索性能优化
+ui_search "react performance" --category react-performance
+
+# 搜索设计模式
+ui_search "card layout" --category web-interface
+```
+
+**4. 调整搜索结果**
+```
+# 快速预览（3 个结果）
+ui_search "button" --limit 3
+
+# 详细搜索（20 个结果）
+ui_search "button" --limit 20
+
+# 过滤低相关性结果
+ui_search "button" --min-score 2.0
+```
+
+### 数据同步技巧
+
+**1. 定期检查**
+```
+# 每周检查一次（推荐）
+sync_ui_data
+
+# 如果已是最新版本，不会重复下载
+```
+
+**2. 遇到问题时**
+```
+# 搜索结果不准确？强制更新
+sync_ui_data --force --verbose
+
+# 查看详细日志
+sync_ui_data --verbose
+```
+
+**3. 数据位置**
+```
+# 内嵌数据（离线可用）
+位置：npm 包内部
+更新：重新安装 mcp-probe-kit
+
+# 缓存数据（自动更新）
+位置：~/.mcp-probe-kit/ui-ux-data/
+更新：首次使用时自动检查
+
+# 手动同步（立即更新）
+命令：sync_ui_data --force
+```
+
+### 组合使用技巧
+
+**场景 1：新项目完整流程**
+```
+# 步骤 1：生成设计系统
+ui_design_system --stack react --primary-color "#3b82f6"
+
+# 步骤 2：搜索需要的组件
+ui_search "button card form" --category react
+
+# 步骤 3：搜索配色方案
+ui_search "blue professional" --category colors
+
+# 步骤 4：应用到项目
+```
+
+**场景 2：优化现有项目**
+```
+# 步骤 1：搜索最佳实践
+ui_search "form validation ux" --category ux-guidelines
+
+# 步骤 2：搜索优化方案
+ui_search "react performance" --category react-performance
+
+# 步骤 3：搜索改进的组件
+ui_search "button loading state" --category react
+```
+
+**场景 3：设计系统迁移**
+```
+# 步骤 1：生成新的设计系统
+ui_design_system --stack tailwind
+
+# 步骤 2：搜索对应的组件
+ui_search "button" --category tailwind
+
+# 步骤 3：逐步替换旧组件
+```
+
+---
+
 ## 📚 相关文档
 
 - [README](../README.md) - 项目介绍和快速开始
 - [工具列表](../README.md#功能特性) - 所有工具的详细说明
+- [UI/UX 快速开始](../QUICK-START-UI-UX.md) - UI/UX 工具快速入门 🆕
+- [UI/UX 完整文档](./UI-UX-PRO-MAX-GUIDE.md) - UI/UX 工具详细文档 🆕
+- [UI/UX 使用演示](./UI-UX-DEMO.md) - UI/UX 工具使用示例 🆕
 - [常见问题](../README.md#常见问题) - FAQ
 
 ---

package/docs/HOW_TO_TRIGGER.md

@@ -2,6 +2,8 @@
 
 > 实用的对话技巧，让 AI 准确理解你的意图并调用正确的工具
 
+**版本**: v1.14.0 | **工具总数**: 46 个
+
 ---
 
 ## 📖 目录
@@ -26,7 +28,75 @@ AI 需要理解你的意图才能调用正确的工具。使用明确的关键
 
 ## 🔑 工具触发关键词
 
-### 🆕 0️⃣ 需求访谈 → `interview` / `ask_user`
+### 🎨 0️⃣ UI/UX 设计 → `ui_design_system` / `ui_search` / `sync_ui_data` 🆕
+
+**触发关键词**：设计系统、配色、颜色、按钮、组件、UI、UX、图标、字体
+
+#### `ui_design_system` - 设计系统生成
+
+**✅ 推荐说法**
+```
+"帮我生成一个 React 设计系统"
+"为我的 Next.js 项目生成 Tailwind 配置"
+"生成一个蓝色主题的设计系统"
+"我需要一套完整的设计系统"
+"帮我配置项目的色彩和字体"
+```
+
+**❌ 不推荐说法**
+```
+"设计一下"（太模糊）
+"好看一点"（没有具体需求）
+```
+
+**使用场景**
+- 新项目启动，需要设计系统
+- 需要统一的色彩、字体、间距配置
+- 想要生成 Tailwind/React/Vue 配置
+- 需要完整的主题配置
+
+#### `ui_search` - UI/UX 智能搜索
+
+**✅ 推荐说法**
+```
+"我需要一个 React 的主按钮组件"
+"搜索一下蓝色主题的配色方案"
+"表单验证有什么 UX 最佳实践？"
+"给我推荐一些图标"
+"找一个加载动画组件"
+"有什么好的卡片设计？"
+```
+
+**❌ 不推荐说法**
+```
+"找个东西"（太模糊）
+"搜索"（没有说明搜索什么）
+```
+
+**使用场景**
+- 需要特定的 UI 组件实现
+- 寻找配色方案
+- 查找设计最佳实践
+- 需要图标、图表等设计元素
+
+#### `sync_ui_data` - 数据同步
+
+**✅ 推荐说法**
+```
+"检查一下 UI 数据有没有更新"
+"更新 UI/UX 数据"
+"同步最新的设计数据"
+"强制更新 UI 数据"
+```
+
+**使用场景**
+- 定期检查数据更新
+- 遇到搜索结果不准确
+- 需要最新的设计数据
+
+---
+
+### 🎯 1️⃣ 需求访谈 → `interview` / `ask_user`
 
 **触发关键词**：访谈、需求不明确、想清楚、澄清需求、提问、确认