@blueking/bkui-knowledge 0.0.1-beta.3 → 0.0.1-beta.5

package/README.md

@@ -10,7 +10,7 @@
 
 只需添加 MCP 服务配置：
 
-**方式一：npx（推荐）**
+### Cursor（默认）
 
 ```json
 {
@@ -23,15 +23,29 @@
 }
 ```
 
-**方式二：本地开发**
+### CodeBuddy
+
+在 CodeBuddy 设置 > MCP 标签页中添加：
+
+```json
+{
+  "bkui-knowledge": {
+    "command": "npx",
+    "args": ["-y", "@blueking/bkui-knowledge", "${workspaceFolder}", "--ide=codebuddy"]
+  }
+}
+```
+
+> 💡 通过 `--ide` 参数指定目标 IDE，不指定时默认使用 Cursor
+
+### 本地开发
 
 ```json
 {
   "mcpServers": {
     "bkui-knowledge": {
       "command": "node",
-      "args": ["/path/to/bkui-knowledge/bin/bkui-knowledge.js"],
-      "cwd": "/path/to/your-project"
+      "args": ["/path/to/bkui-knowledge/bin/bkui-knowledge.js", "${workspaceFolder}"]
     }
   }
 }
@@ -40,8 +54,9 @@
 > ⚠️ 必须传递项目路径，否则 skills 无法同步到正确位置
 
 **特性：**
-- ✅ 首次启动自动同步推荐 skills 到 `.cursor/skills/`
-- ✅ 自动生成 `.cursor/rules/bkui.mdc`（规则自动注入 AI 上下文）
+- ✅ 支持 Cursor 和 CodeBuddy 两种 IDE
+- ✅ 首次启动自动同步推荐 skills
+- ✅ 自动生成规则文件（自动注入 AI 上下文）
 - ✅ 自动检测版本更新，增量同步
 - ✅ 零 Token 消耗（skills 不经过 AI 上下文）
 - ✅ 离线可用（skills 已在本地）
@@ -54,13 +69,14 @@
 
 MCP 服务启动时，skills 会自动同步到用户项目：
 
-1. **首次启动**：自动同步推荐的 skills 到 `.cursor/skills/`
+1. **首次启动**：自动同步推荐的 skills
 2. **后续启动**：检测版本差异，自动增量更新
-3. **同步位置**：
-   - `.cursor/skills/*.md` - 技能文档
-   - `.cursor/commands/*.md` - 斜杠指令（可通过 `/skill-id` 调用）
-   - `.cursor/rules/bkui.mdc` - 规则文件（自动注入 AI 上下文）
-   - `.cursor/.bkui-knowledge-version` - 版本标记
+3. **同步位置**（根据 `--ide` 参数）：
+
+| IDE | Skills | Rules | Version |
+|-----|--------|-------|---------|
+| Cursor (默认) | `.cursor/skills/` | `.cursor/rules/bkui.mdc` | `.cursor/.bkui-knowledge-version` |
+| CodeBuddy | `.codebuddy/skills/` | `.codebuddy/rules/bkui.mdc` | `.codebuddy/.bkui-knowledge-version` |
 
 **更新机制**：
 - skills 内置在 npm 包中
@@ -309,16 +325,19 @@ npm run test:server   # 测试 MCP 服务器功能
 ## 常见问题
 
 ### Q: 如何查看所有可用资源？
-A: 让 AI 调用 `get_knowledge_index()`，规则已自动注入到 `.cursor/rules/bkui.mdc`
+A: 让 AI 调用 `get_knowledge_index()`，规则已自动注入到对应 IDE 的 rules 目录
 
 ### Q: 设计稿还原效果不好？
 A: 使用 `@BKUI-EXPERT`，它会引导 AI 按完整流程执行
 
 ### Q: 知识库更新了怎么办？
-A: 发布新版本 npm 包后，用户下次启动 Cursor 时 `npx -y` 会自动拉取最新版本
+A: 发布新版本 npm 包后，用户下次启动 IDE 时 `npx -y` 会自动拉取最新版本
 
 ### Q: skills 没有同步成功？
-A: 检查 `.cursor/skills/` 目录是否存在，或查看 Cursor 的 MCP 日志
+A: 检查对应 IDE 的 skills 目录是否存在（Cursor: `.cursor/skills/`，CodeBuddy: `.codebuddy/skills/`），或查看 IDE 的 MCP 日志
+
+### Q: 如何切换到 CodeBuddy？
+A: 在 MCP 配置的 args 中添加 `--ide=codebuddy` 参数
 
 ---
 

package/bin/bkui-knowledge.js

@@ -7,6 +7,8 @@
  * 2. 启动 MCP stdio 服务
  *
  * 用法（用户只需配置一次）：
+ *
+ * Cursor（默认）：
  * {
  *   "mcpServers": {
  *     "bkui-knowledge": {
@@ -16,6 +18,18 @@
  *   }
  * }
  *
+ * CodeBuddy：
+ * {
+ *   "bkui-knowledge": {
+ *     "command": "npx",
+ *     "args": ["-y", "@blueking/bkui-knowledge", "${workspaceFolder}", "--ide=codebuddy"]
+ *   }
+ * }
+ *
+ * 参数说明：
+ * - 第一个非 -- 开头的参数: 项目路径
+ * - --ide=cursor|codebuddy: 指定目标 IDE（默认 cursor）
+ *
  * 项目路径传递方式（优先级从高到低）：
  * 1. 命令行参数: npx @blueking/bkui-knowledge /path/to/project
  * 2. 环境变量: BKUI_PROJECT_ROOT=/path/to/project
@@ -30,12 +44,20 @@
 const fs = require('fs');
 const path = require('path');
 
-// 配置
-const CONFIG = {
-  skillsDir: '.cursor/skills',
-  commandsDir: '.cursor/commands',
-  rulesDir: '.cursor/rules',
-  versionFile: '.cursor/.bkui-knowledge-version'
+// IDE 配置映射
+const IDE_CONFIGS = {
+  cursor: {
+    name: 'Cursor',
+    configDir: '.cursor',
+    skillsDir: '.cursor/skills',
+    versionFile: '.cursor/.bkui-knowledge-version'
+  },
+  codebuddy: {
+    name: 'CodeBuddy',
+    configDir: '.codebuddy',
+    skillsDir: '.codebuddy/skills',
+    versionFile: '.codebuddy/.bkui-knowledge-version'
+  }
 };
 
 // npm 包根目录
@@ -46,14 +68,40 @@ function log(msg) {
   process.stderr.write(`[BKUI-Knowledge] ${msg}\n`);
 }
 
+/**
+ * 解析 --ide 参数，获取目标 IDE
+ * @returns {string} IDE 标识符 (cursor | codebuddy)
+ */
+function getTargetIDE() {
+  const ideArg = process.argv.find(arg => arg.startsWith('--ide='));
+  if (ideArg) {
+    const ide = ideArg.split('=')[1].toLowerCase();
+    if (IDE_CONFIGS[ide]) {
+      return ide;
+    }
+    log(`警告: 未知 IDE "${ide}"，使用默认值 cursor`);
+  }
+  return 'cursor'; // 默认使用 Cursor
+}
+
+/**
+ * 获取当前 IDE 配置
+ * @returns {object} IDE 配置对象
+ */
+function getIDEConfig() {
+  const ide = getTargetIDE();
+  return IDE_CONFIGS[ide];
+}
+
 /**
  * 获取用户项目根目录
  * 优先级：命令行参数 > 环境变量 > cwd
  */
 function getProjectRoot() {
-  // 1. 命令行参数: node bkui-knowledge.js /path/to/project
-  if (process.argv[2] && !process.argv[2].startsWith('-')) {
-    return process.argv[2];
+  // 1. 命令行参数: node bkui-knowledge.js /path/to/project (过滤掉 -- 开头的参数)
+  const pathArg = process.argv.slice(2).find(arg => !arg.startsWith('-'));
+  if (pathArg) {
+    return pathArg;
   }
   // 2. 环境变量: BKUI_PROJECT_ROOT=/path/to/project
   if (process.env.BKUI_PROJECT_ROOT) {
@@ -77,9 +125,12 @@ function getPackageVersion() {
 
 /**
  * 检查是否需要同步
+ * @param {string} projectRoot - 项目根目录
+ * @param {string} currentVersion - 当前版本
+ * @param {object} ideConfig - IDE 配置
  */
-function needsSync(projectRoot, currentVersion) {
-  const versionFile = path.join(projectRoot, CONFIG.versionFile);
+function needsSync(projectRoot, currentVersion, ideConfig) {
+  const versionFile = path.join(projectRoot, ideConfig.versionFile);
   if (!fs.existsSync(versionFile)) {
     return true;
   }
@@ -87,71 +138,12 @@ function needsSync(projectRoot, currentVersion) {
   return localVersion !== currentVersion;
 }
 
-/**
- * 生成 Cursor Rules 文件（自动注入 AI 上下文）
- */
-function generateRules(projectRoot, manifest) {
-  const rulesDir = path.join(projectRoot, CONFIG.rulesDir);
-  fs.mkdirSync(rulesDir, { recursive: true });
-
-  const skillList = manifest.skills.items.map(s => `| ${s.id} | ${s.name} |`).join('\n');
-  const apiPriority = manifest.componentApis.priority.map(n => `bk-${n}`).join(', ');
-  const allApis = manifest.componentApis.items.map(a => a.id).join(', ');
-  const recommendedSkills = manifest.recommendedSkills || [];
-
-  const rulesContent = `---
-description: BKUI 蓝鲸前端知识库规则（自动注入）
-globs: ["**/*.vue", "**/*.ts", "**/*.tsx"]
----
-
-# BKUI 蓝鲸前端技术规范
-
-你是蓝鲸前端技术专家，拥有团队知识库访问权限。采用**渐进式披露架构**。
-
-## ✅ Skills 已自动同步
-
-推荐的 skills 已自动同步到 \`.cursor/skills/\` 目录：
-${recommendedSkills.map(id => `- ${id}`).join('\n')}
-
-## 可用资源索引
-
-### Skills (调用 get_skill 获取详情)
-| ID | 名称 |
-|----|------|
-${skillList}
-
-> 💡 bkui-builder 包含布局模版和页面模版 (assets/)
-
-### Component APIs (调用 get_component_api 获取文档)
-⚠️ **高优先级 (必须先查询):** ${apiPriority}
-
-全部组件: ${allApis}
-
-## 工作流程
-1. 分析需求 → 确定需要哪些资源
-2. 使用布局组件? → get_component_api({ componentName: 'navigation' })
-3. 需要模板代码? → get_skill({ skillId: 'bkui-builder' })
-4. 批量获取? → batch_load({ skillIds: [...], componentNames: [...] })
-
-## 强制规范
-- 组件库: bkui-vue (前缀 bk-)
-- 语法: Vue 3 <script setup lang="ts">
-- 布局: 必须使用 bk-navigation
-
-## 常见错误 (必须避免)
-❌ <bk-navigation :default-open-keys> → ✅ default-open
-❌ <bk-menu :default-open-keys> → ✅ :opened-keys
-❌ <bk-dialog v-model> → ✅ v-model:isShow
-`;
-
-  fs.writeFileSync(path.join(rulesDir, 'bkui.mdc'), rulesContent, 'utf-8');
-  log('  ✓ .cursor/rules/bkui.mdc (规则自动注入)');
-}
-
 /**
  * 同步 skills 到用户项目（从 npm 包内置的 knowledge 目录）
+ * @param {string} projectRoot - 项目根目录
+ * @param {object} ideConfig - IDE 配置
  */
-function syncSkills(projectRoot) {
+function syncSkills(projectRoot, ideConfig) {
   try {
     const manifestPath = path.join(PKG_ROOT, 'knowledge/manifest.json');
 
@@ -166,18 +158,16 @@ function syncSkills(projectRoot) {
     const version = `${pkgVersion}-${manifest.updated_at || 'unknown'}`;
 
     // 检查是否需要同步
-    if (!needsSync(projectRoot, version)) {
-      log(`skills 已是最新版本 (v${pkgVersion})`);
+    if (!needsSync(projectRoot, version, ideConfig)) {
+      log(`[${ideConfig.name}] skills 已是最新版本 (v${pkgVersion})`);
       return;
     }
 
-    log(`同步 skills (v${pkgVersion})...`);
+    log(`[${ideConfig.name}] 同步 skills (v${pkgVersion})...`);
 
     // 创建目录
-    const skillsDir = path.join(projectRoot, CONFIG.skillsDir);
-    const commandsDir = path.join(projectRoot, CONFIG.commandsDir);
+    const skillsDir = path.join(projectRoot, ideConfig.skillsDir);
     fs.mkdirSync(skillsDir, { recursive: true });
-    fs.mkdirSync(commandsDir, { recursive: true });
 
     // 同步推荐的 skills
     let count = 0;
@@ -190,23 +180,19 @@ function syncSkills(projectRoot) {
 
       const content = fs.readFileSync(skillFilePath, 'utf-8');
       fs.writeFileSync(path.join(skillsDir, `${skillId}.md`), content, 'utf-8');
-      fs.writeFileSync(path.join(commandsDir, `${skillId}.md`), `请加载使用 ${skillId} skill`, 'utf-8');
 
       log(`  ✓ ${skillId}`);
       count++;
     }
 
-    // 生成 Cursor Rules 文件
-    generateRules(projectRoot, manifest);
-
     // 保存版本信息
-    fs.mkdirSync(path.dirname(path.join(projectRoot, CONFIG.versionFile)), { recursive: true });
-    fs.writeFileSync(path.join(projectRoot, CONFIG.versionFile), version, 'utf-8');
+    fs.mkdirSync(path.dirname(path.join(projectRoot, ideConfig.versionFile)), { recursive: true });
+    fs.writeFileSync(path.join(projectRoot, ideConfig.versionFile), version, 'utf-8');
 
-    log(`同步完成！共 ${count} 个 skills + rules`);
+    log(`[${ideConfig.name}] 同步完成！共 ${count} 个 skills`);
 
   } catch (error) {
-    log(`同步失败: ${error.message}（不影响 MCP 服务）`);
+    log(`[${ideConfig.name}] 同步失败: ${error.message}（不影响 MCP 服务）`);
   }
 }
 
@@ -322,12 +308,14 @@ async function startMcpServer() {
  */
 async function main() {
   const projectRoot = getProjectRoot();
+  const ideConfig = getIDEConfig();
 
-  // 调试：输出实际的工作目录
+  // 调试：输出实际的工作目录和目标 IDE
   log(`工作目录: ${projectRoot}`);
+  log(`目标 IDE: ${ideConfig.name}`);
 
   // 1. 同步 skills（同步执行，从 npm 包读取）
-  syncSkills(projectRoot);
+  syncSkills(projectRoot, ideConfig);
 
   // 2. 启动 MCP 服务
   await startMcpServer();

package/knowledge/manifest.json

@@ -107,6 +107,13 @@
         "category": "security",
         "path": "nodejs-security-check/SKILL.md",
         "tags": ["security", "nodejs", "backend", "ssrf", "sql-injection"]
+      },
+      {
+        "id": "bkui-quick-start",
+        "name": "BKUI 快速入门",
+        "category": "engineering",
+        "path": "bkui-quick-start/SKILL.md",
+        "tags": ["bkui", "规范", "索引", "入门"]
       }
     ]
   },
@@ -663,5 +670,5 @@
     ]
   },
 
-  "recommendedSkills": ["bkui-builder", "bkui-cheatsheet", "code-review", "js-security-check"]
+  "recommendedSkills": ["bkui-quick-start", "bkui-builder", "bkui-cheatsheet", "code-review", "js-security-check"]
 }

package/knowledge/skills/bkui-quick-start/SKILL.md

@@ -0,0 +1,68 @@
+# BKUI 快速入门
+
+> 蓝鲸前端知识库入口指南，包含规范、索引和工作流程。
+
+## 强制规范
+
+- **组件库**: bkui-vue (前缀 `bk-`)
+- **语法**: Vue 3 `<script setup lang="ts">`
+- **样式**: MagicBox 原子类 (mt10, mb20)
+- **布局**: 必须使用 `bk-navigation`
+
+## 常见错误 (必须避免)
+
+| 组件 | 错误写法 | 正确写法 |
+|------|----------|----------|
+| bk-navigation | `:default-open-keys` | `default-open` |
+| bk-menu | `:default-open-keys` | `:opened-keys` |
+| bk-dialog | `v-model` | `v-model:isShow` |
+
+## 可用 Skills
+
+通过 `get_skill({ skillId: 'xxx' })` 获取详情：
+
+| ID | 名称 | 说明 |
+|----|------|------|
+| bkui-builder | 设计稿还原专家 | 包含布局模版和页面模版 (assets/) |
+| bkui-cheatsheet | BKUI 组件速查 | Props 速查、常见坑点 |
+| api-standard | 统一网络请求封装 | Axios 封装规范 |
+| pinia-setup | 全局状态管理 | Pinia Store 模板 |
+| permission-directive | 前端权限控制 | IAM 权限指令 |
+| vite-migration | Webpack 到 Vite 迁移 | 迁移检查脚本 |
+| bundle-optimization | Vite 构建优化 | 性能优化配置 |
+| vue-composables | Vue 3 Composables | 最佳实践和模板 |
+| virtual-list | 长列表虚拟滚动 | 性能优化方案 |
+| unit-testing | 组件单元测试 | Vitest 测试模板 |
+| code-review | 代码评审专家 | 评审规范和检查清单 |
+| js-security-check | JavaScript 安全审查 | 前端安全检查 |
+| nodejs-security-check | Node.js 安全审查 | 后端安全检查 |
+
+## Component APIs
+
+通过 `get_component_api({ componentName: 'xxx' })` 获取文档：
+
+### 高优先级 (必须先查询)
+
+- `bk-navigation` - 布局组件，易出错
+- `bk-menu` - 与 navigation 配合
+- `bk-table` - 列表页核心组件
+- `bk-form` - 表单验证
+- `bk-dialog` - v-model:isShow
+
+### 全部组件
+
+navigation, menu, table, form, dialog, button, input, select, checkbox, radio, date-picker, time-picker, pagination, message, notify, loading, popover, pop-confirm, tag, tag-input, alert, dropdown, tab, cascader, tree, steps, upload, sideslider, breadcrumb, card, collapse, affix, backtop, badge, divider, exception, image, link, progress, rate, slider, switcher, timeline, process, transfer, search-select, color-picker, container, resize-layout, fixed-navbar, code-diff, swiper, animate-number, overflow-title, virtual-render, scrollbar, info-box, config-provider
+
+## 工作流程
+
+1. **分析需求** → 确定需要哪些资源
+2. **使用布局组件?** → `get_component_api({ componentName: 'navigation' })`
+3. **需要模板代码?** → `get_skill({ skillId: 'bkui-builder' })`
+4. **批量获取?** → `batch_load({ skillIds: [...], componentNames: [...] })`
+
+## 触发条件
+
+遇到以下关键词时，应主动使用本知识库：
+- bk-navigation, bk-menu, bk-table, bk-form, bk-dialog 等 bk- 前缀组件
+- bkui-vue, 蓝鲸组件库, MagicBox, 蓝鲸前端
+- 设计稿还原, 管理后台页面

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blueking/bkui-knowledge",
-  "version": "0.0.1-beta.3",
-  "description": "蓝鲸前端知识库 MCP 服务 - 自动同步 skills，支持 Cursor/VSCode",
+  "version": "0.0.1-beta.5",
+  "description": "蓝鲸前端知识库 MCP 服务 - 自动同步 skills，支持 Cursor/CodeBuddy",
   "main": "server/mcp-core.js",
   "bin": {
     "bkui-knowledge": "./bin/bkui-knowledge.js"
@@ -20,7 +20,7 @@
   "repository": {
     "type": "git"
   },
-  "keywords": ["mcp", "cursor", "ai", "knowledge-base", "bkui", "vue3"],
+  "keywords": ["mcp", "cursor", "codebuddy", "ai", "knowledge-base", "bkui", "vue3"],
   "author": "ielgnaw",
   "license": "ISC"
 }

package/server/mcp-core.js

@@ -21,31 +21,17 @@ const KNOWLEDGE_DIR = path.join(ROOT_DIR, 'knowledge');
 // 重要: 工具描述会被自动注入到 AI 上下文，因此在此嵌入核心规则
 // ---------------------------------------------------------
 const TOOLS = [
-  // L0 工具: 获取索引 (核心工具，描述中嵌入规则)
+  // 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. 根据布局分析报告按需加载模版资源`,
+    description: `【蓝鲸前端知识库】遇到 bk- 组件、bkui-vue、蓝鲸组件库时必须使用。
+
+首次使用时，请先读取 .cursor/skills/bkui-quick-start.md 获取完整规范和索引。
+
+快速参考：
+- bk-dialog 用 v-model:isShow（不是 v-model）
+- bk-menu 用 opened-keys（不是 default-open-keys）
+- bk-navigation 用 default-open（不是 default-open-keys）`,
     inputSchema: {
       type: "object",
       properties: {
@@ -61,7 +47,7 @@ const TOOLS = [
   // 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(速查表)",
+    description: "获取技能文档 (Markdown)。可用 ID: bkui-quick-start(入门指南), bkui-builder(设计稿还原), bkui-cheatsheet(速查表), api-standard(请求封装), pinia-setup(状态管理), vite-migration(Vite迁移), bundle-optimization(构建优化), virtual-list(虚拟滚动), unit-testing(单测), code-review(代码评审)",
     inputSchema: {
       type: "object",
       properties: {
@@ -447,7 +433,6 @@ ${recommendedIds.map(id => {
 ### 同步位置
 
 - \`.cursor/skills/*.md\` - 技能文档
-- \`.cursor/commands/*.md\` - 斜杠指令 (可通过 /${recommendedIds[0]} 调用)
 - \`.cursor/rules/bkui.mdc\` - 规则文件 (自动注入 AI 上下文)
 - \`.cursor/.bkui-knowledge-version\` - 版本标记