@blueking/bkui-knowledge 0.0.1-beta.1

package/server/mcp-core.js

@@ -0,0 +1,636 @@
+/**
+ * MCP Core Server - 渐进式披露架构
+ *
+ * 架构设计:
+ * - L0: System Prompt 注入索引 (skills/componentApis 的名称列表)
+ * - L1: 按需加载 Skill 详情 (Markdown + assets)
+ * - L2: 按需加载 Component API (JSON)
+ * - L3: 组件示例 (Resources，按需获取)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// 根目录定位
+const ROOT_DIR = path.resolve(__dirname, '../');
+const KNOWLEDGE_DIR = path.join(ROOT_DIR, 'knowledge');
+
+
+// ---------------------------------------------------------
+// 1. 工具定义 (Tools)
+// 重要: 工具描述会被自动注入到 AI 上下文，因此在此嵌入核心规则
+// ---------------------------------------------------------
+const TOOLS = [
+  // L0 工具: 获取索引 (核心工具，描述中嵌入规则)
+  {
+    name: "get_knowledge_index",
+    description: `【蓝鲸前端知识库】当用户需要使用 bk- 组件、bkui-vue、蓝鲸组件库、MagicBox 时，必须使用此知识库的工具。
+
+## 自动触发条件
+遇到以下关键词时，应主动调用本知识库工具：
+- bk-navigation, bk-menu, bk-table, bk-form, bk-dialog 等 bk- 前缀组件
+- bkui-vue, 蓝鲸组件库, MagicBox, 蓝鲸前端
+- 设计稿还原, 管理后台页面
+
+## 强制规范
+- 组件库: bkui-vue (前缀 bk-)
+- 语法: Vue 3 <script setup lang="ts">
+- 样式: MagicBox 原子类 (mt10, mb20)
+
+## ⚠️ 常见错误
+- bk-navigation 用 default-open，不是 default-open-keys
+- bk-menu 用 opened-keys，不是 default-open-keys
+- bk-dialog 用 v-model:isShow，不是 v-model
+
+## 工作流程
+1. 使用 bk- 组件前，先调用 get_component_api 获取 API
+2. 需要页面模板时，调用 get_skill({ skillId: 'bkui-builder' }) 获取规则
+3. 根据布局分析报告按需加载模版资源`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: {
+          type: "string",
+          description: "可选，筛选类别: skills | componentApis | all",
+          enum: ["skills", "componentApis", "all"]
+        }
+      }
+    }
+  },
+
+  // L1 工具: 获取 Skill 详情
+  {
+    name: "get_skill",
+    description: "获取技能文档 (Markdown)。可用 ID: bkui-builder(设计稿还原), layout-rules(布局规范), api-standard(请求封装), pinia-setup(状态管理), vite-migration(Vite迁移), bundle-optimization(构建优化), virtual-list(虚拟滚动), unit-testing(单测), bkui-cheatsheet(速查表)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skillId: {
+          type: "string",
+          description: "技能 ID"
+        }
+      },
+      required: ["skillId"]
+    }
+  },
+
+  // L2 工具: 获取组件 API
+  {
+    name: "get_component_api",
+    description: "【必须调用】获取 bk- 组件的 API 文档 (Props/Slots/Events/常见错误)。使用任何 bk- 组件前都应先调用此工具，避免使用错误的属性名。共 58 个组件: navigation, menu, table, form, dialog, button, input, select, checkbox, radio, date-picker, upload, tab, tree, cascader, steps, popover, message, notify, loading 等。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        componentName: {
+          type: "string",
+          description: "组件名 (不含 bk- 前缀)，如: navigation, menu, table, form, dialog, button, input, select..."
+        }
+      },
+      required: ["componentName"]
+    }
+  },
+
+  // 批量加载工具: 减少调用轮次
+  {
+    name: "batch_load",
+    description: "批量加载多个资源，减少调用轮次。推荐用于一次获取多个 skill/component-api。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skillIds: {
+          type: "array",
+          items: { type: "string" },
+          description: "skill ID 列表"
+        },
+        componentNames: {
+          type: "array",
+          items: { type: "string" },
+          description: "组件名列表 (不含 bk- 前缀)"
+        }
+      }
+    }
+  },
+
+  // 查看 Skills 同步状态
+  {
+    name: "sync_skills",
+    description: "查看 skills 同步状态和信息。使用 npx @blueking/bkui-knowledge 时，推荐的 skills 会自动同步到 .cursor/skills/ 目录。",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  }
+];
+
+// ---------------------------------------------------------
+// 2. 提示词定义 (Prompts)
+// ---------------------------------------------------------
+const PROMPTS = [
+  {
+    name: "BKUI-EXPERT",
+    description: "设计稿还原专家模式。完整的 CoT 流程。",
+    arguments: []
+  }
+];
+
+// ---------------------------------------------------------
+// 3. 资源定义 (Resources) - 动态生成
+// ---------------------------------------------------------
+function buildResources() {
+  const resources = [
+    {
+      uri: "knowledge://manifest",
+      name: "知识库完整索引",
+      description: "包含所有 skills/componentApis 的完整索引",
+      mimeType: "application/json"
+    }
+  ];
+
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(KNOWLEDGE_DIR, 'manifest.json'), 'utf-8'));
+
+    // 从 manifest 动态生成组件示例资源
+    if (manifest.componentExamples && manifest.componentExamples.items) {
+      manifest.componentExamples.items.forEach(comp => {
+        comp.examples.forEach(ex => {
+          resources.push({
+            uri: `example://${comp.id}/${ex.name}`,
+            name: `${comp.id} - ${ex.description}`,
+            description: `bk-${comp.id} 组件示例: ${ex.description}`,
+            mimeType: "text/x-vue"
+          });
+        });
+      });
+    }
+
+    // 从 skills 目录动态生成 skill:// 资源
+    if (manifest.skills && manifest.skills.items) {
+      const skillsBasePath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path);
+      manifest.skills.items.forEach(skill => {
+        const skillDir = path.join(skillsBasePath, skill.id);
+        ['scripts', 'references', 'assets'].forEach(subDir => {
+          const subDirPath = path.join(skillDir, subDir);
+          if (fs.existsSync(subDirPath)) {
+            scanSkillDir(subDirPath, '').forEach(filePath => {
+              const ext = path.extname(filePath);
+              const mimeType = ext === '.vue' ? 'text/x-vue' :
+                               ext === '.ts' ? 'text/typescript' :
+                               ext === '.js' ? 'text/javascript' :
+                               ext === '.md' ? 'text/markdown' : 'text/plain';
+              resources.push({
+                uri: `skill://${skill.id}/${subDir}/${filePath}`,
+                name: `${skill.id}/${subDir}/${filePath}`,
+                description: `Skill ${skill.name} 的 ${subDir}`,
+                mimeType
+              });
+            });
+          }
+        });
+      });
+    }
+  } catch (e) {
+    console.error('Failed to build resources:', e.message);
+  }
+
+  return resources;
+}
+
+// 递归扫描目录，返回相对路径列表
+function scanSkillDir(dirPath, relativePath) {
+  const results = [];
+  if (!fs.existsSync(dirPath)) return results;
+
+  const files = fs.readdirSync(dirPath);
+  files.forEach(file => {
+    const fullPath = path.join(dirPath, file);
+    const relPath = relativePath ? `${relativePath}/${file}` : file;
+    const stat = fs.statSync(fullPath);
+    if (stat.isDirectory()) {
+      results.push(...scanSkillDir(fullPath, relPath));
+    } else {
+      results.push(relPath);
+    }
+  });
+  return results;
+}
+
+const RESOURCES = buildResources();
+
+// ---------------------------------------------------------
+// 工具函数
+// ---------------------------------------------------------
+
+function loadManifest() {
+  const manifestPath = path.join(KNOWLEDGE_DIR, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error('Manifest not found');
+  }
+  return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+}
+
+function formatSkillsSummary(skills) {
+  let result = "| ID | 名称 | 标签 |\n|-----|------|------|\n";
+  skills.items.forEach(s => {
+    const tags = s.tags.slice(0, 3).join(', ');
+    result += `| ${s.id} | ${s.name} | ${tags} |\n`;
+  });
+  return result;
+}
+
+function formatApisSummary(apis) {
+  const priority = apis.priority || [];
+  let result = `⚠️ 高优先级 (必须先查询): ${priority.map(n => `bk-${n}`).join(', ')}\n\n`;
+  result += "| 组件 | 说明 |\n|------|------|\n";
+  apis.items.forEach(a => {
+    const marker = a.priority === 'high' ? '⚠️' : '';
+    result += `| ${marker} bk-${a.id} | ${a.note || ''} |\n`;
+  });
+  return result;
+}
+
+// ---------------------------------------------------------
+// 核心处理函数
+// ---------------------------------------------------------
+const Handlers = {
+
+  // L0: 获取索引
+  async get_knowledge_index({ category = 'all' }) {
+    const manifest = loadManifest();
+    let result = "# 知识库索引\n\n";
+
+    if (category === 'all' || category === 'skills') {
+      result += "## 技能文档 (调用 get_skill 获取详情)\n\n";
+      result += formatSkillsSummary(manifest.skills);
+      result += "\n";
+    }
+
+    if (category === 'all' || category === 'componentApis') {
+      result += "## 组件 API (调用 get_component_api 获取文档)\n\n";
+      result += formatApisSummary(manifest.componentApis);
+    }
+
+    return { content: [{ type: "text", text: result }] };
+  },
+
+  // L1: 获取 Skill 详情 (支持标准目录结构)
+  async get_skill({ skillId }) {
+    const manifest = loadManifest();
+    const skill = manifest.skills.items.find(s => s.id === skillId);
+    if (!skill) {
+      throw new Error(`Skill '${skillId}' not found. Use get_knowledge_index to see available skills.`);
+    }
+
+    const filePath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path, skill.path);
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`Skill file not found: ${skill.path}`);
+    }
+
+    let content = fs.readFileSync(filePath, 'utf-8');
+
+    // 检查 skill 目录下的附属资源，生成 skill:// URIs
+    const skillDir = path.dirname(filePath);
+    const subDirs = ['scripts', 'references', 'assets'];
+    const availableResources = [];
+
+    subDirs.forEach(dir => {
+      const dirPath = path.join(skillDir, dir);
+      if (fs.existsSync(dirPath)) {
+        const files = scanSkillDir(dirPath, '');
+        files.forEach(file => {
+          availableResources.push(`- \`skill://${skillId}/${dir}/${file}\``);
+        });
+      }
+    });
+
+    if (availableResources.length > 0) {
+      content += `\n\n---\n## 📦 可用资源\n\n`;
+      content += availableResources.join('\n');
+      content += `\n\n> 根据 SKILL.md 中的 IF-THEN 规则判断是否需要加载\n`;
+    }
+
+    return { content: [{ type: "text", text: content }] };
+  },
+
+  // L2: 获取组件 API
+  async get_component_api({ componentName }) {
+    const manifest = loadManifest();
+    const normalizedName = componentName.toLowerCase().replace('bk-', '');
+
+    const apiPath = path.join(KNOWLEDGE_DIR, manifest.componentApis.base_path, `${normalizedName}.json`);
+
+    if (!fs.existsSync(apiPath)) {
+      // 降级：尝试从 reference 中搜索源码
+      return {
+        content: [{
+          type: "text",
+          text: `⚠️ 未找到 bk-${normalizedName} 的 API 文档。\n\n建议：\n1. 查看官方文档\n2. 或在 reference/bkui-vue-source 中搜索源码`
+        }]
+      };
+    }
+
+    const apiData = JSON.parse(fs.readFileSync(apiPath, 'utf-8'));
+    let result = `# ${apiData.name} 组件 API\n\n`;
+    result += `> ${apiData.description}\n\n`;
+
+    // Props
+    result += `## Props\n\n| 属性 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n`;
+    for (const [name, prop] of Object.entries(apiData.props)) {
+      result += `| ${name} | ${prop.type} | ${prop.default} | ${prop.description} |\n`;
+    }
+
+    // Slots
+    if (apiData.slots) {
+      result += `\n## Slots\n\n| 名称 | 说明 |\n|------|------|\n`;
+      for (const [name, slot] of Object.entries(apiData.slots)) {
+        result += `| #${name} | ${slot.description} |\n`;
+      }
+    }
+
+    // Events
+    if (apiData.events) {
+      result += `\n## Events\n\n| 事件名 | 参数 | 说明 |\n|--------|------|------|\n`;
+      for (const [name, event] of Object.entries(apiData.events)) {
+        result += `| @${name} | ${event.params} | ${event.description} |\n`;
+      }
+    }
+
+    // Common Mistakes (重要!)
+    if (apiData.commonMistakes && apiData.commonMistakes.length > 0) {
+      result += `\n## ⚠️ 常见错误 (必读!)\n\n`;
+      apiData.commonMistakes.forEach((m, i) => {
+        result += `### 错误 ${i + 1}\n`;
+        result += `- ❌ 错误: \`${m.wrong}\`\n`;
+        result += `- ✅ 正确: \`${m.correct}\`\n`;
+        result += `- 原因: ${m.reason}\n\n`;
+      });
+    }
+
+    // Related Components
+    if (apiData.relatedComponents) {
+      result += `\n## 关联组件\n\n`;
+      for (const [compName, info] of Object.entries(apiData.relatedComponents)) {
+        result += `### ${compName}\n`;
+        result += `Props: \`${JSON.stringify(info.props)}\`\n\n`;
+      }
+    }
+
+    // 检查是否有可用示例 (L3 层)
+    const compExamples = manifest.componentExamples?.items?.find(c => c.id === normalizedName);
+    if (compExamples && compExamples.examples.length > 0) {
+      result += `\n## 📦 可用示例 (询问用户是否需要)\n\n`;
+      result += `如需查看完整示例代码，请询问用户后获取对应 resource:\n\n`;
+      compExamples.examples.forEach(ex => {
+        result += `- \`example://${normalizedName}/${ex.name}\` - ${ex.description}\n`;
+      });
+      result += `\n> 提示: 询问用户 "是否需要查看 ${apiData.name} 的示例代码？" 确认后再获取\n`;
+    }
+
+    return { content: [{ type: "text", text: result }] };
+  },
+
+  // 批量加载
+  async batch_load({ skillIds = [], componentNames = [] }) {
+    const results = [];
+
+    // 加载 skills
+    for (const id of skillIds) {
+      try {
+        const skill = await Handlers.get_skill({ skillId: id });
+        results.push({ type: 'skill', id, content: skill.content[0].text });
+      } catch (e) {
+        results.push({ type: 'skill', id, error: e.message });
+      }
+    }
+
+    // 加载 component APIs
+    for (const name of componentNames) {
+      try {
+        const api = await Handlers.get_component_api({ componentName: name });
+        results.push({ type: 'componentApi', name, content: api.content[0].text });
+      } catch (e) {
+        results.push({ type: 'componentApi', name, error: e.message });
+      }
+    }
+
+    // 格式化输出
+    let output = `# 批量加载结果\n\n`;
+    output += `共加载 ${results.length} 项资源\n\n`;
+
+    results.forEach((r, i) => {
+      output += `---\n\n## [${i + 1}] ${r.type}: ${r.id || r.name}\n\n`;
+      if (r.error) {
+        output += `❌ 加载失败: ${r.error}\n\n`;
+      } else {
+        output += r.content + '\n\n';
+      }
+    });
+
+    return { content: [{ type: "text", text: output }] };
+  },
+
+  // 同步 Skills 信息
+  async sync_skills({ preset, skillIds = [] }) {
+    const manifest = loadManifest();
+    const recommendedIds = manifest.recommendedSkills || [];
+
+    const result = `## ✅ Skills 与规则自动同步
+
+使用 \`npx @blueking/bkui-knowledge\` 时，推荐的 skills 和规则会**自动同步**到项目目录。
+
+### 已配置的推荐 Skills (${recommendedIds.length} 个)
+
+${recommendedIds.map(id => {
+  const skill = manifest.skills.items.find(s => s.id === id);
+  return `- **${id}** - ${skill ? skill.name : ''}`;
+}).join('\n')}
+
+### 同步位置
+
+- \`.cursor/skills/*.md\` - 技能文档
+- \`.cursor/commands/*.md\` - 斜杠指令 (可通过 /${recommendedIds[0]} 调用)
+- \`.cursor/rules/bkui.mdc\` - 规则文件 (自动注入 AI 上下文)
+- \`.cursor/.bkui-knowledge-version\` - 版本标记
+
+### 更新机制
+
+1. skills 和规则内置在 npm 包中
+2. 更新时：修改代码 → \`npm publish\`
+3. 用户使用 \`npx -y\` 会自动拉取最新版本
+
+> 💡 无需手动操作，MCP 服务启动时自动完成同步`;
+
+    return { content: [{ type: "text", text: result }] };
+  },
+
+  // Prompt 处理
+  async get_prompt({ name }) {
+    if (name === "BKUI-EXPERT") {
+      const prompt = `[设计稿还原专家模式]
+
+## 执行步骤
+
+**Step 1: 加载核心规则**
+调用 get_skill({ skillId: 'bkui-builder' })
+
+**Step 2: 输出布局分析报告（必须输出以下格式）**
+
+请按此格式输出分析结果：
+\`\`\`
+【布局分析报告】
+- 主题: 深色(侧边栏深蓝黑) / 浅色(侧边栏白色)
+- 页面类型: 表格页/表单页/仪表盘
+- 筛选组件: 无 / Radio胶囊(选项间有竖线分隔) / Tab(选项有下划线)
+- 菜单图标: 有/无
+- 表头特殊列: 筛选漏斗/排序箭头/设置齿轮
+- 表格启停列: 有Switch开关 / 无
+- 表格操作列: 编辑按钮(蓝色文字) / 删除按钮(红色文字) / 都有 / 无
+\`\`\`
+
+⚠️ 主题判断要点：
+- 侧边栏是深蓝黑色(#1a1a2e) → 深色主题 → 必须加 .admin-layout--dark CSS
+- 侧边栏是白色/浅灰 → 浅色主题
+
+⚠️ 筛选组件判断要点：
+- 选项之间有竖线分隔 → Radio Capsule (bk-radio-group type="capsule")
+- 选项有下划线高亮 → Tab (bk-tab)
+
+⚠️ 表格操作列判断要点：
+- 滑动开关(蓝色/绿色) → <bk-switcher v-model="row.enabled">
+- "编辑"文字链接 → <bk-button theme="primary" text>编辑</bk-button>
+- "删除"文字链接(红色) → <bk-button theme="danger" text>删除</bk-button>
+
+**Step 3: 等待用户确认（必须停下来！）**
+
+输出分析报告后，**必须停止并等待用户回复**，不要继续执行！
+
+输出以下内容后停止：
+"根据分析，我将加载以下模版：
+- 布局: admin-layout-left/dark
+- 页面: table-page
+- 细节映射: visual-mapping.md
+
+**请回复 Y 确认，或告诉我需要调整的部分。**"
+
+⚠️ 重要：在用户回复之前，不要执行 Step 4！
+
+**Step 4: 用户确认后加载资源**
+只有在用户回复确认后，才加载对应资源：
+- skill://bkui-builder/assets/layouts/xxx.vue
+- skill://bkui-builder/assets/pages/xxx.vue
+- skill://bkui-builder/references/visual-mapping.md
+- 调用 get_component_api 获取组件 API
+
+**Step 5: 参考模版生成代码**
+
+请回复："任务收到，开始执行 Step 1..."`;
+
+      return {
+        messages: [{
+          role: "user",
+          content: { type: "text", text: prompt }
+        }]
+      };
+    }
+
+    throw new Error(`Prompt '${name}' not found`);
+  }
+};
+
+// Resource 处理函数
+const ResourceHandlers = {
+  async "knowledge://manifest"() {
+    const manifest = loadManifest();
+    return { content: JSON.stringify(manifest, null, 2) };
+  }
+};
+
+// 动态处理 example:// 资源
+async function handleExampleResource(uri) {
+  // uri 格式: example://componentId/exampleName
+  const match = uri.match(/^example:\/\/([^/]+)\/(.+)$/);
+  if (!match) {
+    throw new Error(`Invalid example URI: ${uri}`);
+  }
+
+  const [, componentId, exampleName] = match;
+  const manifest = loadManifest();
+
+  // 查找组件示例配置
+  const compExamples = manifest.componentExamples?.items?.find(c => c.id === componentId);
+  if (!compExamples) {
+    throw new Error(`No examples found for component: ${componentId}`);
+  }
+
+  const example = compExamples.examples.find(e => e.name === exampleName);
+  if (!example) {
+    throw new Error(`Example '${exampleName}' not found for ${componentId}. Available: ${compExamples.examples.map(e => e.name).join(', ')}`);
+  }
+
+  // 读取示例文件
+  const examplePath = path.join(ROOT_DIR, manifest.componentExamples.base_path, example.file);
+  if (!fs.existsSync(examplePath)) {
+    throw new Error(`Example file not found: ${example.file}`);
+  }
+
+  const content = fs.readFileSync(examplePath, 'utf-8');
+  return {
+    content: `<!-- ${example.description} -->\n<!-- 文件: ${example.file} -->\n\n${content}`
+  };
+}
+
+// 动态处理 skill:// 资源
+async function handleSkillResource(uri) {
+  // uri 格式: skill://skillId/subDir/path
+  const match = uri.match(/^skill:\/\/([^/]+)\/([^/]+)\/(.+)$/);
+  if (!match) {
+    throw new Error(`Invalid skill URI: ${uri}. Expected format: skill://skillId/subDir/path`);
+  }
+
+  const [, skillId, subDir, filePath] = match;
+
+  if (!['scripts', 'references', 'assets'].includes(subDir)) {
+    throw new Error(`Invalid skill subDir: ${subDir}. Must be scripts, references, or assets`);
+  }
+
+  const manifest = loadManifest();
+  const skill = manifest.skills.items.find(s => s.id === skillId);
+  if (!skill) {
+    throw new Error(`Skill not found: ${skillId}`);
+  }
+
+  const fullPath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path, skillId, subDir, filePath);
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`Skill resource not found: ${subDir}/${filePath}`);
+  }
+
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const ext = path.extname(filePath);
+  const langMap = { '.vue': 'vue', '.ts': 'typescript', '.js': 'javascript', '.md': 'markdown' };
+  const lang = langMap[ext] || '';
+
+  return {
+    content: `<!-- Skill: ${skill.name} -->\n<!-- File: ${subDir}/${filePath} -->\n\n\`\`\`${lang}\n${content}\n\`\`\``
+  };
+}
+
+// 通用资源处理器
+async function readResource(uri) {
+  // 静态资源
+  if (ResourceHandlers[uri]) {
+    return await ResourceHandlers[uri]();
+  }
+
+  // 动态 example:// 资源
+  if (uri.startsWith('example://')) {
+    return await handleExampleResource(uri);
+  }
+
+  // 动态 skill:// 资源
+  if (uri.startsWith('skill://')) {
+    return await handleSkillResource(uri);
+  }
+
+  throw new Error(`Unknown resource: ${uri}`);
+}
+
+module.exports = { TOOLS, RESOURCES, PROMPTS, Handlers, ResourceHandlers, readResource };