@blueking/bkui-knowledge 0.0.1-beta.1

package/README.md

@@ -0,0 +1,316 @@
+# 蓝鲸前端知识库 (BKUI Knowledge Base)
+
+本仓库致力于沉淀团队的技术资产，采用 **渐进式披露架构**，同时服务于**人类开发者**和 **AI 助手**。
+
+**[如何贡献知识？](./CONTRIBUTING.md)** | **[使用 Skill 模板](./knowledge/skills/.template/)**
+
+---
+
+## 快速开始
+
+只需添加 MCP 服务配置：
+
+```json
+{
+  "mcpServers": {
+    "bkui-knowledge": {
+      "command": "npx",
+      "args": ["-y", "@blueking/bkui-knowledge"]
+    }
+  }
+}
+```
+
+**特性：**
+- ✅ 首次启动自动同步推荐 skills 到 `.cursor/skills/`
+- ✅ 自动生成 `.cursor/rules/bkui.mdc`（规则自动注入 AI 上下文）
+- ✅ 自动检测版本更新，增量同步
+- ✅ 零 Token 消耗（skills 不经过 AI 上下文）
+- ✅ 离线可用（skills 已在本地）
+
+配置完成后，直接在对话中使用！
+
+---
+
+## Skills 自动同步
+
+MCP 服务启动时，skills 会自动同步到用户项目：
+
+1. **首次启动**：自动同步推荐的 skills 到 `.cursor/skills/`
+2. **后续启动**：检测版本差异，自动增量更新
+3. **同步位置**：
+   - `.cursor/skills/*.md` - 技能文档
+   - `.cursor/commands/*.md` - 斜杠指令（可通过 `/skill-id` 调用）
+   - `.cursor/rules/bkui.mdc` - 规则文件（自动注入 AI 上下文）
+   - `.cursor/.bkui-knowledge-version` - 版本标记
+
+**更新机制**：
+- skills 内置在 npm 包中
+- 更新时：修改代码 → `npm publish` 发布新版本
+- 用户使用 `npx -y` 会自动拉取最新版本
+
+> 💡 无需任何手动操作，skills 自动同步，零 Token 消耗
+
+---
+
+## 使用方式
+
+### 推荐：@BKUI-EXPERT (设计稿还原 / 写组件)
+
+```
+[粘贴设计稿图片 或 描述需求]
+/BKUI-Knowledge/BKUI-EXPERT
+```
+
+**效果：**
+1. 自动加载 `bkui-builder` 规则
+2. 自动获取相关组件的 API
+3. 按规范生成代码
+4. 询问是否需要查看组件示例
+
+### @ 方式 (Prompts)
+
+| 命令 | 作用 | 推荐场景 |
+|------|------|----------|
+| `@BKUI-EXPERT` | 设计稿还原专家模式，引导 AI 按步骤执行 | **写组件 / 还原设计稿** |
+
+### 直接对话 + 明确指定
+
+```
+用户: 使用 BKUI-Knowledge 获取 bk-table 的 API，帮我写一个表格页面
+```
+
+### 手动调用工具
+
+```
+用户: 调用 get_component_api 获取 navigation 组件的 API
+用户: 用 batch_load 获取 navigation、menu、table 的 API
+```
+
+---
+
+## 可用资源
+
+### 工具 (Tools)
+
+| 工具 | 作用 | 层级 |
+|------|------|------|
+| `get_knowledge_index` | 获取完整索引 | L0 |
+| `get_skill` | 获取技能文档 (Markdown + assets) | L1 |
+| `get_component_api` | 获取组件 API (JSON) | L2 |
+| `batch_load` | 批量加载多个资源 | L1+L2 |
+| `sync_skills` | 查看 skills 同步状态和信息 | - |
+
+### 组件示例 (Resources) - L3 层
+
+获取 `get_component_api` 后，会提示可用示例。**用户确认后**才加载：
+
+```
+AI: 已获取 bk-table 的 API 文档。是否需要查看示例代码？
+    可用示例:
+    - basic (基础表格 + 分页)
+    - selection (可选择表格)
+    - filter (筛选表格)
+
+用户: 给我 basic 示例
+
+AI: [获取 resource: example://table/basic]
+    这是示例代码...
+```
+
+**优势**: 默认不消耗 token，用户控制是否加载。
+
+### 技能 (Skills)
+
+| ID | 名称 | 场景 |
+|----|------|------|
+| `bkui-builder` | 设计稿还原专家 | UI 开发 |
+| `api-standard` | 统一网络请求 | HTTP 封装 |
+| `pinia-setup` | 全局状态管理 | Pinia |
+| `permission-directive` | 前端权限控制 (IAM) | 权限管理 |
+| `vue-composables` | Vue 3 Composables 最佳实践 | 组合式函数 |
+| `vite-migration` | Webpack 到 Vite 迁移 | 构建工具 |
+| `bundle-optimization` | Vite 构建优化 | 性能 |
+| `virtual-list` | 长列表虚拟滚动 | 性能 |
+| `unit-testing` | 组件单元测试 | 质量 |
+| `bkui-cheatsheet` | BKUI 组件速查 | 快速参考 |
+| `code-review` | 代码评审专家 | 代码审查 |
+| `js-security-check` | JavaScript 安全审查 | 安全 |
+| `nodejs-security-check` | Node.js 安全审查 | 安全 |
+
+### 页面模版 (在 bkui-builder 的 assets/ 中)
+
+| 文件 | 描述 |
+|------|------|
+| `layouts/admin-layout-left.vue` | 左右布局 (管理后台) |
+| `layouts/admin-layout-top.vue` | 上下布局 (门户页) |
+| `layouts/admin-layout-dark.vue` | 暗色主题布局 |
+| `pages/table-page.vue` | 表格页 (CRUD) |
+| `pages/dashboard-page.vue` | 仪表盘 |
+| `pages/detail-page.vue` | 详情页 |
+| `pages/wizard-form.vue` | 分步表单 |
+
+> 调用 `get_skill({ skillId: 'bkui-builder' })` 时会自动列出可用模版
+
+### 组件 API (58 个)
+
+**高优先级 (使用前必须查询):** `navigation`, `menu`, `table`, `form`, `dialog`
+
+**全部组件:** button, input, select, checkbox, radio, date-picker, time-picker, cascader, tag-input, slider, switcher, rate, color-picker, upload, transfer, search-select, pagination, tree, tag, badge, collapse, timeline, progress, image, tab, steps, process, breadcrumb, dropdown, sideslider, message, notify, loading, alert, popover, pop-confirm, info-box, exception, card, container, resize-layout, divider, link, affix, backtop, fixed-navbar, code-diff, swiper, animate-number, overflow-title, virtual-render, scrollbar, config-provider
+
+---
+
+## 已嵌入的核心规则
+
+工具描述中已包含以下规则，AI 会自动遵守：
+
+### 强制规范
+- 组件库: `bkui-vue` (前缀 `bk-`)
+- 语法: Vue 3 `<script setup lang="ts">`
+- 样式: MagicBox 原子类 (`mt10`, `mb20`, `flex-row`)
+
+### 常见错误 (必须避免)
+```
+❌ <bk-navigation :default-open-keys>  → ✅ default-open
+❌ <bk-menu :default-open-keys>        → ✅ :opened-keys
+❌ <bk-dialog v-model>                 → ✅ v-model:isShow
+```
+
+---
+
+## 架构设计
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  工具描述 (自动注入)                                          │
+│  - 核心规范 + 常见错误 + 工作流程                              │
+│  - Token: ~200                                               │
+└─────────────────────────────────────────────────────────────┘
+                              ↓ AI 按需调用
+┌─────────────────────────────────────────────────────────────┐
+│  L0: get_knowledge_index                                    │
+│  - skills/patterns/apis 完整列表                             │
+│  - Token: ~400                                              │
+└─────────────────────────────────────────────────────────────┘
+                              ↓ AI 按需调用
+┌─────────────────────────────────────────────────────────────┐
+│  L1/L2: get_skill / get_pattern / get_component_api         │
+│  - 具体内容 (Markdown/Vue/JSON)                              │
+│  - Token: ~500-1000/项                                       │
+└─────────────────────────────────────────────────────────────┘
+                              ↓ 用户确认后加载
+┌─────────────────────────────────────────────────────────────┐
+│  L3: example://component/name (MCP Resource)                │
+│  - 组件完整示例代码                                           │
+│  - Token: ~300-800/项 (仅用户确认后消耗)                       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 目录结构
+
+```
+bkui-knowledge/
+├── bin/
+│   └── bkui-knowledge.js      ← CLI 入口 (自动同步 skills + MCP 服务)
+│
+├── server/
+│   └── mcp-core.js            ← 核心逻辑 (Tools/Prompts/Resources)
+│
+├── knowledge/                 ← 知识层 (核心)
+│   ├── manifest.json          ← 统一索引
+│   ├── skills/                ← L1: 技能文档 (13 个)
+│   │   ├── bkui-builder/
+│   │   │   ├── SKILL.md       ← 必须：核心指令
+│   │   │   ├── scripts/       ← 可选：工具脚本
+│   │   │   ├── references/    ← 可选：参考文档
+│   │   │   └── assets/        ← 可选：模版素材
+│   │   └── ...
+│   ├── component-apis/        ← L2: 组件 API (58 个 JSON)
+│   └── examples/              ← L3: 组件示例 (150+ 个 Vue)
+│
+└── tests/                     ← 测试套件
+```
+
+---
+
+## 贡献知识
+
+欢迎团队成员一起沉淀知识！所有贡献的内容都会自动遵循渐进式披露架构。
+
+### 快速开始
+
+```bash
+# 1. 使用模板创建新 Skill
+cp -r knowledge/skills/.template knowledge/skills/your-skill-id
+
+# 2. 编辑核心文档（保持 ≤ 3KB）
+vim knowledge/skills/your-skill-id/SKILL.md
+
+# 3. 添加详细内容到 references/
+vim knowledge/skills/your-skill-id/references/advanced.md
+
+# 4. 更新索引
+vim knowledge/manifest.json
+
+# 5. 验证大小
+wc -c knowledge/skills/your-skill-id/SKILL.md
+```
+
+### 重要原则
+
+- ✅ **SKILL.md 必须 ≤ 3KB**（核心规则）
+- ✅ **详细内容放 references/**（按需加载）
+- ✅ **代码资产放 assets/**（用户确认后加载）
+
+详细指南请查看：**[CONTRIBUTING.md](./CONTRIBUTING.md)**
+
+---
+
+## 本地测试
+
+**重要**：测试不需要启动服务器！
+
+```bash
+# 运行所有测试（推荐）
+npm test
+
+# 单独测试
+npm run test:skills   # 验证知识库 Skills 是否符合规范
+npm run test:server   # 测试 MCP 服务器功能
+```
+
+**注意**：
+- `npm test` 是运行测试套件（自动完成），用于验证规范
+
+详细说明见：[tests/README.md](./tests/README.md)
+
+---
+
+## 常见问题
+
+### Q: 如何查看所有可用资源？
+A: 让 AI 调用 `get_knowledge_index()`，规则已自动注入到 `.cursor/rules/bkui.mdc`
+
+### Q: 设计稿还原效果不好？
+A: 使用 `@BKUI-EXPERT`，它会引导 AI 按完整流程执行
+
+### Q: 知识库更新了怎么办？
+A: 发布新版本 npm 包后，用户下次启动 Cursor 时 `npx -y` 会自动拉取最新版本
+
+### Q: skills 没有同步成功？
+A: 检查 `.cursor/skills/` 目录是否存在，或查看 Cursor 的 MCP 日志
+
+---
+
+## Token 消耗对比
+
+| 方案 | 初始化 | 按需加载 | 总计 |
+|------|--------|---------|------|
+| 全量注入 | ~15,000 | 0 | ~15,000 |
+| 纯按需加载 | ~200 | ~3,000 | ~3,200 |
+| **渐进式披露** | ~200 | ~2,000 | **~2,200** ✅ |
+| **npx 自动同步 skills** | 0 | ~2,000 | **~2,000** ✅✅ |
+
+> 💡 使用 npx 模式时，推荐的 skills 自动同步到本地，AI 无需读取内容，节省更多 token

package/bin/bkui-knowledge.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+/**
+ * BKUI Knowledge MCP CLI
+ *
+ * 功能：
+ * 1. 启动时自动同步 skills 到用户项目（从 npm 包内置的 knowledge 目录）
+ * 2. 启动 MCP stdio 服务
+ *
+ * 用法（用户只需配置一次）：
+ * {
+ *   "mcpServers": {
+ *     "bkui-knowledge": {
+ *       "command": "npx",
+ *       "args": ["-y", "@blueking/bkui-knowledge"]
+ *     }
+ *   }
+ * }
+ *
+ * 更新机制：
+ * - skills 内置在 npm 包中
+ * - 更新 skills 时：修改代码 → npm publish
+ * - 用户使用 npx -y 会自动拉取最新版本
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// 配置
+const CONFIG = {
+  skillsDir: '.cursor/skills',
+  commandsDir: '.cursor/commands',
+  rulesDir: '.cursor/rules',
+  versionFile: '.cursor/.bkui-knowledge-version'
+};
+
+// npm 包根目录
+const PKG_ROOT = path.join(__dirname, '..');
+
+// 日志输出到 stderr（不影响 stdio 通信）
+function log(msg) {
+  process.stderr.write(`[BKUI-Knowledge] ${msg}\n`);
+}
+
+/**
+ * 获取用户项目根目录（cwd）
+ */
+function getProjectRoot() {
+  return process.cwd();
+}
+
+/**
+ * 获取当前包版本
+ */
+function getPackageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch (e) {
+    return '0.0.0';
+  }
+}
+
+/**
+ * 检查是否需要同步
+ */
+function needsSync(projectRoot, currentVersion) {
+  const versionFile = path.join(projectRoot, CONFIG.versionFile);
+  if (!fs.existsSync(versionFile)) {
+    return true;
+  }
+  const localVersion = fs.readFileSync(versionFile, 'utf-8').trim();
+  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 目录）
+ */
+function syncSkills(projectRoot) {
+  try {
+    const manifestPath = path.join(PKG_ROOT, 'knowledge/manifest.json');
+
+    if (!fs.existsSync(manifestPath)) {
+      log('knowledge 目录不存在，跳过同步');
+      return;
+    }
+
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    const recommendedIds = manifest.recommendedSkills || [];
+    const pkgVersion = getPackageVersion();
+    const version = `${pkgVersion}-${manifest.updated_at || 'unknown'}`;
+
+    // 检查是否需要同步
+    if (!needsSync(projectRoot, version)) {
+      log(`skills 已是最新版本 (v${pkgVersion})`);
+      return;
+    }
+
+    log(`同步 skills (v${pkgVersion})...`);
+
+    // 创建目录
+    const skillsDir = path.join(projectRoot, CONFIG.skillsDir);
+    const commandsDir = path.join(projectRoot, CONFIG.commandsDir);
+    fs.mkdirSync(skillsDir, { recursive: true });
+    fs.mkdirSync(commandsDir, { recursive: true });
+
+    // 同步推荐的 skills
+    let count = 0;
+    for (const skillId of recommendedIds) {
+      const skill = manifest.skills.items.find(s => s.id === skillId);
+      if (!skill) continue;
+
+      const skillFilePath = path.join(PKG_ROOT, 'knowledge', manifest.skills.base_path, skill.path);
+      if (!fs.existsSync(skillFilePath)) continue;
+
+      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');
+
+    log(`同步完成！共 ${count} 个 skills + rules`);
+
+  } catch (error) {
+    log(`同步失败: ${error.message}（不影响 MCP 服务）`);
+  }
+}
+
+/**
+ * 启动 MCP stdio 服务
+ */
+async function startMcpServer() {
+  // 加载 mcp-core（相对于当前文件位置）
+  // bin/bkui-knowledge.js -> server/mcp-core.js
+  const mcpCorePath = path.join(__dirname, '../server/mcp-core.js');
+  const mcpCore = require(mcpCorePath);
+
+  const { TOOLS, RESOURCES, PROMPTS, Handlers, readResource } = mcpCore;
+
+  async function handleMessage(message) {
+    if (message.method === "initialize") {
+      return {
+        protocolVersion: "2024-11-05",
+        serverInfo: { name: "bkui-knowledge-server", version: "1.0.0" },
+        capabilities: {
+          tools: {},
+          resources: {},
+          prompts: {}
+        }
+      };
+    }
+
+    if (message.method === "notifications/initialized") {
+      return null;
+    }
+
+    if (message.method === "tools/list") {
+      return { tools: TOOLS };
+    }
+
+    if (message.method === "tools/call") {
+      const { name, arguments: args } = message.params;
+      if (Handlers[name]) {
+        return await Handlers[name](args || {});
+      }
+      throw new Error(`Tool not found: ${name}`);
+    }
+
+    if (message.method === "resources/list") {
+      return { resources: RESOURCES };
+    }
+
+    if (message.method === "resources/read") {
+      const { uri } = message.params;
+      return await readResource(uri);
+    }
+
+    if (message.method === "prompts/list") {
+      return { prompts: PROMPTS };
+    }
+
+    if (message.method === "prompts/get") {
+      const { name, arguments: args } = message.params;
+      return await Handlers.get_prompt({ name, ...args });
+    }
+
+    throw new Error(`Method not found: ${message.method}`);
+  }
+
+  // stdio 处理
+  process.stdin.on('data', async (data) => {
+    const lines = data.toString().split('\n').filter(line => line.trim());
+    for (const line of lines) {
+      try {
+        const message = JSON.parse(line);
+
+        if (message.method && message.method.startsWith('notifications/')) {
+          await handleMessage(message);
+          continue;
+        }
+
+        if (message.id === undefined) {
+          try { await handleMessage(message); } catch (e) {}
+          continue;
+        }
+
+        try {
+          const result = await handleMessage(message);
+          if (result === null) continue;
+
+          process.stdout.write(JSON.stringify({
+            jsonrpc: "2.0",
+            id: message.id,
+            result: result
+          }) + '\n');
+        } catch (error) {
+          process.stdout.write(JSON.stringify({
+            jsonrpc: "2.0",
+            id: message.id,
+            error: { code: -32603, message: error.message }
+          }) + '\n');
+        }
+      } catch (parseError) {
+        process.stdout.write(JSON.stringify({
+          jsonrpc: "2.0",
+          id: null,
+          error: { code: -32700, message: 'Parse error' }
+        }) + '\n');
+      }
+    }
+  });
+
+  log('MCP stdio 服务已启动');
+}
+
+/**
+ * 主入口
+ */
+async function main() {
+  const projectRoot = getProjectRoot();
+
+  // 1. 同步 skills（同步执行，从 npm 包读取）
+  syncSkills(projectRoot);
+
+  // 2. 启动 MCP 服务
+  await startMcpServer();
+}
+
+main().catch(error => {
+  log(`启动失败: ${error.message}`);
+  process.exit(1);
+});

package/knowledge/component-apis/affix.json

@@ -0,0 +1,41 @@
+{
+  "name": "bk-affix",
+  "description": "固钉组件，将元素固定在可视区域",
+  "version": "3.0",
+
+  "props": {
+    "offsetTop": {
+      "type": "number",
+      "default": "0",
+      "description": "距离顶部的偏移量"
+    },
+    "offsetBottom": {
+      "type": "number",
+      "default": "undefined",
+      "description": "距离底部的偏移量"
+    },
+    "target": {
+      "type": "string",
+      "default": "''",
+      "description": "滚动容器选择器"
+    },
+    "zIndex": {
+      "type": "number",
+      "default": "1000",
+      "description": "层级"
+    }
+  },
+
+  "slots": {
+    "default": {
+      "description": "需要固定的内容"
+    }
+  },
+
+  "events": {
+    "change": {
+      "params": "(affixed: boolean)",
+      "description": "固定状态变化时触发"
+    }
+  }
+}