@blueking/bkui-knowledge 0.0.1-beta.1

package/knowledge/skills/pinia-setup/assets/store-template.ts

@@ -0,0 +1,122 @@
+/**
+ * Pinia Store 标准模版
+ * 使用 Setup Store 语法 (推荐)
+ */
+
+import { ref, computed } from 'vue';
+import { defineStore } from 'pinia';
+import { get, post } from '@/http';
+
+// 类型定义
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  avatar?: string;
+}
+
+/**
+ * 用户 Store
+ * 命名规范: use + 模块名 + Store
+ */
+export const useUserStore = defineStore('user', () => {
+  // ========== State ==========
+  const currentUser = ref<User | null>(null);
+  const isLoading = ref(false);
+  const error = ref<string | null>(null);
+
+  // ========== Getters ==========
+  const isLoggedIn = computed(() => !!currentUser.value);
+  const username = computed(() => currentUser.value?.name ?? '');
+
+  // ========== Actions ==========
+  
+  /**
+   * 获取当前用户信息
+   */
+  const fetchUser = async () => {
+    isLoading.value = true;
+    error.value = null;
+
+    try {
+      const data = await get<User>('/user/info');
+      currentUser.value = data;
+    } catch (e: any) {
+      error.value = e.message;
+      throw e;
+    } finally {
+      isLoading.value = false;
+    }
+  };
+
+  /**
+   * 用户登录
+   */
+  const login = async (credentials: { username: string; password: string }) => {
+    isLoading.value = true;
+    error.value = null;
+
+    try {
+      const data = await post<{ token: string; user: User }>('/user/login', credentials);
+      localStorage.setItem('token', data.token);
+      currentUser.value = data.user;
+      return data;
+    } catch (e: any) {
+      error.value = e.message;
+      throw e;
+    } finally {
+      isLoading.value = false;
+    }
+  };
+
+  /**
+   * 退出登录
+   */
+  const logout = () => {
+    localStorage.removeItem('token');
+    currentUser.value = null;
+  };
+
+  /**
+   * 重置 Store
+   */
+  const $reset = () => {
+    currentUser.value = null;
+    isLoading.value = false;
+    error.value = null;
+  };
+
+  return {
+    // State
+    currentUser,
+    isLoading,
+    error,
+    // Getters
+    isLoggedIn,
+    username,
+    // Actions
+    fetchUser,
+    login,
+    logout,
+    $reset
+  };
+});
+
+// ========== 使用示例 ==========
+/*
+<script setup lang="ts">
+import { useUserStore } from '@/stores/user';
+import { storeToRefs } from 'pinia';
+
+const userStore = useUserStore();
+
+// 解构响应式状态 (使用 storeToRefs 保持响应性)
+const { currentUser, isLoggedIn, isLoading } = storeToRefs(userStore);
+
+// Actions 可以直接解构
+const { login, logout, fetchUser } = userStore;
+
+// 调用 Action
+await fetchUser();
+</script>
+*/

package/knowledge/skills/unit-testing/SKILL.md

@@ -0,0 +1,71 @@
+---
+id: qual-unit-test
+name: Vue 3 组件单元测试指南 (Vitest)
+category: quality
+description: 使用 Vitest 和 Vue Test Utils 的标准模版与断言技巧
+tags: [test, vitest, vue-test-utils, quality]
+updated_at: 2026-01-09
+---
+
+# Vue 3 组件单元测试指南
+
+采用 **Vitest** 作为测试运行器，配合 **@vue/test-utils** 进行组件测试。
+
+## 环境准备
+
+```json
+"devDependencies": {
+  "vitest": "^1.0.0",
+  "@vue/test-utils": "^2.4.0",
+  "jsdom": "^23.0.0"
+}
+```
+
+## 测试模版
+
+```typescript
+import { mount } from '@vue/test-utils';
+import { describe, it, expect, vi } from 'vitest';
+import MyComponent from './MyComponent.vue';
+
+describe('MyComponent.vue', () => {
+  it('renders properly', () => {
+    const wrapper = mount(MyComponent, {
+      props: { title: 'Hello' }
+    });
+    expect(wrapper.text()).toContain('Hello');
+  });
+
+  it('emits event on click', async () => {
+    const wrapper = mount(MyComponent);
+    await wrapper.find('button').trigger('click');
+    expect(wrapper.emitted()).toHaveProperty('submit');
+  });
+});
+```
+
+## 常用技巧
+
+```typescript
+// Mock 第三方组件
+const wrapper = mount(MyComponent, {
+  global: { stubs: { 'bk-table': true } }
+});
+
+// Mock API（文件顶部）
+vi.mock('@/api/user', () => ({
+  getUserInfo: vi.fn(() => Promise.resolve({ id: 1 }))
+}));
+```
+
+## 运行测试
+
+```bash
+npm run test:unit
+```
+
+## 📦 按需加载资源
+
+| 资源 | URI |
+|-----|-----|
+| 完整测试示例 | `skill://unit-testing/assets/component.spec.ts` |

package/knowledge/skills/unit-testing/assets/component.spec.ts

@@ -0,0 +1,153 @@
+/**
+ * Vue 组件单元测试模版
+ * 基于 Vitest + @vue/test-utils
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { mount, VueWrapper } from '@vue/test-utils';
+import { nextTick } from 'vue';
+import MyComponent from '../MyComponent.vue';
+
+// Mock 依赖
+vi.mock('@/http', () => ({
+  get: vi.fn(),
+  post: vi.fn()
+}));
+
+describe('MyComponent', () => {
+  let wrapper: VueWrapper;
+
+  // 每个测试前重置
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  // ========== 渲染测试 ==========
+  describe('渲染', () => {
+    it('应该正确渲染组件', () => {
+      wrapper = mount(MyComponent, {
+        props: {
+          title: '测试标题'
+        }
+      });
+
+      expect(wrapper.exists()).toBe(true);
+      expect(wrapper.text()).toContain('测试标题');
+    });
+
+    it('应该根据 props 显示不同内容', async () => {
+      wrapper = mount(MyComponent, {
+        props: {
+          visible: false
+        }
+      });
+
+      expect(wrapper.find('.content').exists()).toBe(false);
+
+      await wrapper.setProps({ visible: true });
+      expect(wrapper.find('.content').exists()).toBe(true);
+    });
+  });
+
+  // ========== 交互测试 ==========
+  describe('交互', () => {
+    it('点击按钮应该触发事件', async () => {
+      wrapper = mount(MyComponent);
+
+      await wrapper.find('button').trigger('click');
+
+      expect(wrapper.emitted('submit')).toBeTruthy();
+      expect(wrapper.emitted('submit')![0]).toEqual([{ id: 1 }]);
+    });
+
+    it('输入框变化应该更新 v-model', async () => {
+      wrapper = mount(MyComponent, {
+        props: {
+          modelValue: '',
+          'onUpdate:modelValue': (val: string) => wrapper.setProps({ modelValue: val })
+        }
+      });
+
+      await wrapper.find('input').setValue('新值');
+      expect(wrapper.props('modelValue')).toBe('新值');
+    });
+  });
+
+  // ========== 异步测试 ==========
+  describe('异步操作', () => {
+    it('应该正确处理异步数据加载', async () => {
+      const mockData = [{ id: 1, name: 'Item 1' }];
+      const { get } = await import('@/http');
+      (get as any).mockResolvedValue(mockData);
+
+      wrapper = mount(MyComponent);
+
+      // 等待异步操作完成
+      await nextTick();
+      await new Promise(resolve => setTimeout(resolve, 0));
+
+      expect(wrapper.findAll('.list-item')).toHaveLength(1);
+    });
+
+    it('应该正确处理加载错误', async () => {
+      const { get } = await import('@/http');
+      (get as any).mockRejectedValue(new Error('加载失败'));
+
+      wrapper = mount(MyComponent);
+
+      await nextTick();
+      await new Promise(resolve => setTimeout(resolve, 0));
+
+      expect(wrapper.find('.error-message').text()).toContain('加载失败');
+    });
+  });
+
+  // ========== 插槽测试 ==========
+  describe('插槽', () => {
+    it('应该正确渲染默认插槽', () => {
+      wrapper = mount(MyComponent, {
+        slots: {
+          default: '<span class="slot-content">自定义内容</span>'
+        }
+      });
+
+      expect(wrapper.find('.slot-content').exists()).toBe(true);
+    });
+
+    it('应该正确渲染作用域插槽', () => {
+      wrapper = mount(MyComponent, {
+        slots: {
+          item: `<template #item="{ data }">
+            <span class="custom-item">{{ data.name }}</span>
+          </template>`
+        }
+      });
+
+      expect(wrapper.find('.custom-item').exists()).toBe(true);
+    });
+  });
+});
+
+// ========== 配置示例: vitest.config.ts ==========
+/*
+import { defineConfig } from 'vitest/config';
+import vue from '@vitejs/plugin-vue';
+
+export default defineConfig({
+  plugins: [vue()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html'],
+      exclude: ['node_modules/', 'tests/']
+    }
+  },
+  resolve: {
+    alias: {
+      '@': '/src'
+    }
+  }
+});
+*/

package/knowledge/skills/virtual-list/SKILL.md

@@ -0,0 +1,63 @@
+---
+id: perf-virtual-list
+name: 长列表虚拟滚动优化方案
+category: performance
+description: 处理超过 1000 条数据的大型列表渲染时的性能优化方案，包含定高和不定高两种策略。
+tags: [performance, vue3, virtual-scroll, list]
+updated_at: 2026-01-09
+---
+
+# 长列表虚拟滚动优化方案
+
+当列表数据量巨大（如日志列表、审计记录，n > 1000）时，直接渲染会导致 DOM 节点过多，页面卡顿。
+
+## 核心原理
+只渲染当前**可视区域 (Viewport)** 内的元素，加上缓冲区 (Buffer) 的元素。随着滚动条滚动，动态替换 DOM 内容。
+
+## 推荐方案
+
+### 1. 定高列表 (Item Height Fixed)
+
+如果每一行高度固定（例如 40px），推荐使用轻量实现。
+
+**使用方式：**
+```html
+<VirtualList :items="logList" :item-height="40" :container-height="400">
+  <template #default="{ item }">
+    <div class="log-item">{{ item.message }}</div>
+  </template>
+</VirtualList>
+```
+
+> 📦 获取完整组件实现：`skill://virtual-list/assets/VirtualList.vue`
+
+### 2. 不定高列表 (Dynamic Height)
+如果列表项高度不固定（如包含展开/收起、不同长度文本），计算逻辑会变得复杂。
+**推荐库**: `vue-virtual-scroller` 的 `DynamicScroller` 组件。
+
+```html
+<template>
+  <DynamicScroller
+    :items="items"
+    :min-item-size="54"
+    class="scroller"
+  >
+    <template #default="{ item, index, active }">
+      <DynamicScrollerItem
+        :item="item"
+        :active="active"
+        :size-dependencies="[
+          item.message,
+        ]"
+        :data-index="index"
+      >
+        <div class="message">{{ item.message }}</div>
+      </DynamicScrollerItem>
+    </template>
+  </DynamicScroller>
+</template>
+```
+
+## 注意事项
+1. **滚动白屏**: 滚动过快时可能出现瞬间白屏，适当增加 `buffer` 缓冲区大小。
+2. **搜索/筛选**: 虚拟列表与搜索过滤不冲突，只需对 `props.items` 进行 computed 过滤即可。

package/knowledge/skills/virtual-list/assets/VirtualList.vue

@@ -0,0 +1,123 @@
+<!--
+  虚拟滚动列表组件
+
+  用途：处理大数据量列表（n > 1000）的渲染性能问题
+  原理：只渲染可视区域内的元素，滚动时动态替换
+
+  使用示例：
+  <VirtualList
+    :items="logList"
+    :item-height="40"
+    :container-height="400"
+  >
+    <template #default="{ item }">
+      <div class="log-item">{{ item.message }}</div>
+    </template>
+  </VirtualList>
+-->
+<script setup lang="ts" generic="T extends { id: string | number }">
+import { ref, computed, type StyleValue } from 'vue';
+
+interface Props {
+  /** 完整数据列表 */
+  items: T[];
+  /** 单行高度 (px) */
+  itemHeight?: number;
+  /** 容器高度 (px) */
+  containerHeight?: number;
+  /** 缓冲区大小 (上下各渲染多少额外项) */
+  buffer?: number;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  itemHeight: 40,
+  containerHeight: 400,
+  buffer: 2
+});
+
+const scrollTop = ref(0);
+
+// 总高度 = 数据量 × 单行高度
+const totalHeight = computed(() => props.items.length * props.itemHeight);
+
+// 可视区域能容纳的条数
+const visibleCount = computed(() =>
+  Math.ceil(props.containerHeight / props.itemHeight)
+);
+
+// 起始索引（含缓冲区）
+const startIndex = computed(() =>
+  Math.max(0, Math.floor(scrollTop.value / props.itemHeight) - props.buffer)
+);
+
+// 结束索引（含缓冲区）
+const endIndex = computed(() =>
+  Math.min(
+    props.items.length,
+    startIndex.value + visibleCount.value + props.buffer * 2
+  )
+);
+
+// 当前实际渲染的数据
+const visibleItems = computed(() => {
+  return props.items.slice(startIndex.value, endIndex.value).map((item, index) => ({
+    item,
+    style: {
+      position: 'absolute',
+      width: '100%',
+      height: `${props.itemHeight}px`,
+      top: `${(startIndex.value + index) * props.itemHeight}px`,
+      left: 0
+    } as StyleValue
+  }));
+});
+
+// 容器样式
+const containerStyle = computed<StyleValue>(() => ({
+  height: `${props.containerHeight}px`,
+  position: 'relative',
+  overflow: 'auto'
+}));
+
+// 占位元素样式（撑开滚动条）
+const phantomStyle = computed<StyleValue>(() => ({
+  height: `${totalHeight.value}px`
+}));
+
+const handleScroll = (e: Event) => {
+  scrollTop.value = (e.target as HTMLElement).scrollTop;
+};
+</script>
+
+<template>
+  <div
+    class="virtual-list-container"
+    :style="containerStyle"
+    @scroll="handleScroll"
+  >
+    <!-- 撑开滚动条的幽灵元素 -->
+    <div class="virtual-list-phantom" :style="phantomStyle" />
+
+    <!-- 实际渲染区域 -->
+    <div class="virtual-list-content">
+      <div
+        v-for="{ item, style } in visibleItems"
+        :key="item.id"
+        class="virtual-list-item"
+        :style="style"
+      >
+        <slot :item="item" />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.virtual-list-container {
+  will-change: transform;
+}
+
+.virtual-list-item {
+  box-sizing: border-box;
+}
+</style>

package/knowledge/skills/vite-migration/SKILL.md

@@ -0,0 +1,12 @@
+---
+id: eng-vite-migration
+name: Webpack 到 Vite 迁移指南
+description: 详细记录了大型 Vue 项目从 Webpack 迁移到 Vite 的完整步骤，包括别名配置、环境变量处理和 CommonJS 兼容性问题的解决。
+tags: [engineering, vite, migration, build-tool]
+updated_at: 2026-01-09
+---
+
+# Webpack 到 Vite 迁移指南
+
+## 1. 依赖安装
+...

package/knowledge/skills/vite-migration/scripts/check-migration.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+/**
+ * Webpack to Vite 迁移检查脚本
+ * 用法: node check-migration.js [项目路径]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const projectPath = process.argv[2] || process.cwd();
+
+console.log('🔍 检查项目迁移准备状态...\n');
+console.log(`📁 项目路径: ${projectPath}\n`);
+
+const issues = [];
+const warnings = [];
+const passed = [];
+
+// ========== 检查函数 ==========
+
+function checkFile(filePath) {
+  return fs.existsSync(path.join(projectPath, filePath));
+}
+
+function readFile(filePath) {
+  const fullPath = path.join(projectPath, filePath);
+  if (fs.existsSync(fullPath)) {
+    return fs.readFileSync(fullPath, 'utf-8');
+  }
+  return null;
+}
+
+function checkPackageJson() {
+  const pkg = readFile('package.json');
+  if (!pkg) {
+    issues.push('❌ 未找到 package.json');
+    return;
+  }
+
+  const json = JSON.parse(pkg);
+  const deps = { ...json.dependencies, ...json.devDependencies };
+
+  // 检查 Vue 版本
+  if (deps.vue) {
+    const vueVersion = deps.vue.replace(/[\^~]/g, '');
+    if (vueVersion.startsWith('2')) {
+      issues.push('❌ Vue 2.x 需要先升级到 Vue 3.x');
+    } else {
+      passed.push('✅ Vue 3.x');
+    }
+  }
+
+  // 检查 Webpack 相关依赖
+  const webpackDeps = Object.keys(deps).filter(
+    d => d.includes('webpack') || d.includes('babel-loader') || d.includes('vue-loader')
+  );
+  if (webpackDeps.length > 0) {
+    warnings.push(`⚠️  迁移后需删除: ${webpackDeps.join(', ')}`);
+  }
+
+  // 检查 CommonJS 依赖
+  const cjsDeps = ['lodash', 'moment', 'jquery'];
+  const foundCjs = cjsDeps.filter(d => deps[d]);
+  if (foundCjs.length > 0) {
+    warnings.push(`⚠️  CommonJS 依赖需配置优化: ${foundCjs.join(', ')}`);
+  }
+}
+
+function checkConfigFiles() {
+  // 检查 Webpack 配置
+  if (checkFile('webpack.config.js') || checkFile('vue.config.js')) {
+    passed.push('✅ 找到 Webpack 配置，可进行迁移');
+  }
+
+  // 检查是否已有 Vite 配置
+  if (checkFile('vite.config.js') || checkFile('vite.config.ts')) {
+    warnings.push('⚠️  已存在 Vite 配置文件');
+  }
+
+  // 检查 TypeScript
+  if (checkFile('tsconfig.json')) {
+    passed.push('✅ TypeScript 项目');
+  }
+}
+
+function checkEnvFiles() {
+  const envFiles = ['.env', '.env.development', '.env.production'];
+  const foundEnv = envFiles.filter(f => checkFile(f));
+
+  if (foundEnv.length > 0) {
+    warnings.push(`⚠️  环境变量文件需更新前缀: VUE_APP_ → VITE_`);
+  }
+}
+
+function checkImports() {
+  // 简单检查 src 目录下的 require 用法
+  const srcPath = path.join(projectPath, 'src');
+  if (!fs.existsSync(srcPath)) return;
+
+  let requireCount = 0;
+
+  function scanDir(dir) {
+    const files = fs.readdirSync(dir);
+    for (const file of files) {
+      const fullPath = path.join(dir, file);
+      const stat = fs.statSync(fullPath);
+
+      if (stat.isDirectory() && !file.includes('node_modules')) {
+        scanDir(fullPath);
+      } else if (file.match(/\.(js|ts|vue)$/)) {
+        const content = fs.readFileSync(fullPath, 'utf-8');
+        const matches = content.match(/require\s*\(/g);
+        if (matches) {
+          requireCount += matches.length;
+        }
+      }
+    }
+  }
+
+  scanDir(srcPath);
+
+  if (requireCount > 0) {
+    warnings.push(`⚠️  发现 ${requireCount} 处 require() 调用，需改为 import`);
+  } else {
+    passed.push('✅ 未发现 CommonJS require 语法');
+  }
+}
+
+// ========== 执行检查 ==========
+
+checkPackageJson();
+checkConfigFiles();
+checkEnvFiles();
+checkImports();
+
+// ========== 输出结果 ==========
+
+console.log('📋 检查结果:\n');
+
+if (passed.length > 0) {
+  console.log('通过:');
+  passed.forEach(p => console.log(`  ${p}`));
+  console.log();
+}
+
+if (warnings.length > 0) {
+  console.log('警告:');
+  warnings.forEach(w => console.log(`  ${w}`));
+  console.log();
+}
+
+if (issues.length > 0) {
+  console.log('问题:');
+  issues.forEach(i => console.log(`  ${i}`));
+  console.log();
+}
+
+// 总结
+console.log('─'.repeat(50));
+if (issues.length === 0) {
+  console.log('✅ 项目可以开始迁移到 Vite');
+} else {
+  console.log('❌ 请先解决上述问题后再进行迁移');
+}