@blueking/bkui-knowledge 0.0.1-beta.1

package/knowledge/skills/bkui-builder/references/code-snippets.md

@@ -0,0 +1,145 @@
+# 常用代码片段
+
+> 按需获取，用于快速复制粘贴
+
+---
+
+## Tab 按钮组样式
+
+当 Tab 外观类似按钮组（有外边框包围、选中项高亮）时：
+
+```vue
+<bk-tab v-model:active="activeTab" type="card" class="filter-tab">
+  <bk-tab-panel name="all" :label="`全部 (${totalCount})`" />
+  <bk-tab-panel name="enabled" :label="`启用 (${enabledCount})`" />
+  <bk-tab-panel name="disabled" :label="`停用 (${disabledCount})`" />
+</bk-tab>
+
+<style scoped>
+.filter-tab :deep(.bk-tab-header) {
+  border: 1px solid #dcdee5;
+  border-radius: 2px;
+  background: #fff;
+}
+.filter-tab :deep(.bk-tab-header-item) {
+  border: none;
+  background: transparent;
+}
+.filter-tab :deep(.bk-tab-header-item.is-active) {
+  background: #e1ecff;
+  color: #3a84ff;
+}
+</style>
+```
+
+---
+
+## 表格列配置详解
+
+```typescript
+// 典型的管理页表格列配置
+const columns = [
+  // 基础文本列
+  { label: '名称', field: 'name', width: 150 },
+
+  // 带排序的列 (设计稿有 ↑↓ 图标)
+  { label: '更新人', field: 'updatedBy', width: 100, sort: true },
+  { label: '更新时间', field: 'updatedAt', width: 170, sort: { value: 'desc' } },
+
+  // 带筛选的列 (设计稿有漏斗图标)
+  {
+    label: '来源',
+    field: 'source',
+    width: 100,
+    filter: {
+      list: [
+        { text: '内置', value: 'builtin' },
+        { text: '自定义', value: 'custom' }
+      ]
+    }
+  },
+
+  // 长文本溢出省略
+  { label: '定义', field: 'definition', showOverflowTooltip: true },
+
+  // 自定义渲染列 (Tag/Switcher/操作)
+  { label: '来源', field: 'source', width: 100 },  // 用 #source 插槽
+  { label: '启停', field: 'enabled', width: 80 },  // 用 #enabled 插槽
+  { label: '操作', field: 'operation', width: 120 } // 用 #operation 插槽
+];
+```
+
+## 表格自定义列插槽示例
+
+```vue
+<bk-table :data="tableData" :columns="columns">
+  <!-- Tag 列 -->
+  <template #source="{ row }">
+    <bk-tag :theme="row.source === 'builtin' ? 'info' : 'success'">
+      {{ row.source === 'builtin' ? '内置' : '自定义' }}
+    </bk-tag>
+  </template>
+
+  <!-- Switcher 列 -->
+  <template #enabled="{ row }">
+    <bk-switcher
+      v-model="row.enabled"
+      size="small"
+      @change="(val) => handleToggle(row, val)"
+    />
+  </template>
+
+  <!-- 操作列 -->
+  <template #operation="{ row }">
+    <bk-button text theme="primary" @click="handleEdit(row)">编辑</bk-button>
+    <bk-button text theme="danger" @click="handleDelete(row)">删除</bk-button>
+  </template>
+</bk-table>
+```
+
+## 工具栏布局示例
+
+```vue
+<!-- 左侧新建按钮 + 右侧 Tab 筛选和搜索框 -->
+<div class="toolbar">
+  <bk-button theme="primary" @click="handleCreate">
+    <Add class="mr5" />
+    新建
+  </bk-button>
+
+  <div class="toolbar-right">
+    <!-- Tab 筛选 -->
+    <bk-tab v-model:active="activeTab" type="unborder-card">
+      <bk-tab-panel name="all" :label="`全部(${totalCount})`" />
+      <bk-tab-panel name="enabled" :label="`启用(${enabledCount})`" />
+      <bk-tab-panel name="disabled" :label="`停用(${disabledCount})`" />
+    </bk-tab>
+
+    <!-- 搜索框 -->
+    <bk-input
+      v-model="searchKey"
+      placeholder="搜索 名称、描述、更新人、定义"
+      :clearable="true"
+      style="width: 280px"
+    >
+      <template #suffix>
+        <Search class="search-icon" @click="handleSearch" />
+      </template>
+    </bk-input>
+  </div>
+</div>
+
+<style scoped>
+.toolbar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 16px;
+}
+.toolbar-right {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+</style>
+```

package/knowledge/skills/bkui-builder/references/visual-mapping.md

@@ -0,0 +1,190 @@
+# 视觉特征映射规则
+
+> 按需加载，用于精确还原设计稿细节
+
+---
+
+## 0. 主题识别（优先判断）
+
+### 深色主题 vs 浅色主题
+
+| 视觉特征 | 深色主题 | 浅色主题 |
+|---------|---------|---------|
+| **侧边栏背景** | 深蓝黑 (#1a1a2e ~ #2c2c3e) | 白色/浅灰 |
+| **顶部导航** | 深色背景 (#2c2c3e) | 白色背景 |
+| **表格背景** | 深灰 (#2c2c3e) | 白色 |
+| **文字颜色** | 浅色 (rgba(255,255,255,0.8)) | 深色 (#63656e) |
+
+**深色侧边栏 CSS（必须添加）：**
+```css
+.admin-layout--dark :deep(.bk-navigation) {
+  --bk-navigation-bg-color: #1a1a2e;
+}
+.admin-layout--dark :deep(.bk-menu) {
+  --menu-bg-color: transparent;
+  --menu-text-color: rgba(255,255,255,0.8);
+  --menu-active-bg-color: rgba(58,132,255,0.2);
+  --menu-active-text-color: #fff;
+}
+.admin-layout--dark :deep(.bk-table) {
+  --table-bg-color: #2c2c3e;
+  --table-header-bg-color: #252535;
+}
+```
+
+---
+
+## 1. 菜单图标
+
+当菜单项左侧有图标时，使用 `#icon` 插槽：
+
+```vue
+<script setup>
+// ⚠️ 正确导入方式 - 只能从 bkui-vue/lib/icon 导入
+import { Search, Plus, Close, Edit, Delete, Setting } from 'bkui-vue/lib/icon';
+</script>
+
+<template>
+  <bk-menu-item key="log-collect">
+    <template #icon><Search /></template>
+    日志采集
+  </bk-menu-item>
+</template>
+```
+
+### 可用图标列表（从源码提取）
+
+**箭头/方向：**
+`AngleDown`, `AngleUp`, `AngleLeft`, `AngleRight`, `AngleDownFill`, `AngleUpFill`, `AngleDownLine`, `AngleDoubleLeft`, `AngleDoubleRight`, `DownShape`, `UpShape`, `LeftShape`, `RightShape`, `DownSmall`, `ArrowsLeft`, `ArrowsRight`
+
+**通用操作：**
+`Search`, `Plus`, `Close`, `CloseLine`, `Copy`, `CopyShape`, `Del`, `EditLine`, `Upload`, `Share`, `Transfer`, `Done`
+
+**文件/文档：**
+`Folder`, `FolderOpen`, `FolderShape`, `FolderShapeOpen`, `DocFill`, `TextFile`, `TextFill`, `Code`, `PdfFill`, `ExcelFill`, `ImageFill`, `VideoFill`, `AudioFill`, `ArchiveFill`
+
+**状态/提示：**
+`Info`, `InfoLine`, `Help`, `HelpFill`, `HelpDocumentFill`, `Warn`, `Error`, `Success`, `ExclamationCircleShape`
+
+**功能图标：**
+`CogShape`, `DataShape`, `Eye`, `Unvisible`, `Funnel`, `Ellipsis`, `Loading`, `Spinner`, `CollapseLeft`, `FixLine`, `FixShape`, `TreeApplicationShape`
+
+**完整导入示例：**
+```typescript
+import { Search, Plus, Close, CogShape, FolderOpen, Funnel, EditLine, Del, Help } from 'bkui-vue/lib/icon';
+```
+
+> ⚠️ CSS 类名备选：`<i class="bk-icon icon-search"></i>`
+> ❌ 错误路径：`import { X } from '@bkui-vue/icon'`
+
+---
+
+## 2. 表格列特征
+
+| 表头特征 | 列配置 |
+|---------|-------|
+| 漏斗图标 (筛选) | `filter: { list: [{ text, value }] }` |
+| 箭头图标 (排序) | `sort: true` 或 `sort: { value: 'desc' }` |
+| 齿轮图标 (设置) | 表格属性 `:settings="true"` |
+
+### 表格操作列
+
+| 视觉特征 | 组件 | 代码 |
+|---------|-----|------|
+| **蓝色/绿色滑动开关** | `<bk-switcher>` | `<template #enabled="{ row }"><bk-switcher v-model="row.enabled" /></template>` |
+| **"编辑" 文字链接** | `<bk-button text>` | `<bk-button theme="primary" text>编辑</bk-button>` |
+| **"删除" 文字链接（红色）** | `<bk-button text>` | `<bk-button theme="danger" text>删除</bk-button>` |
+
+⚠️ **常见错误**：
+- ❌ 操作列显示 `true/false` 文本 → ✅ 应该用 `<bk-switcher>`
+- ❌ 操作列空白 → ✅ 必须添加"编辑""删除"按钮
+- ❌ 按钮有边框 → ✅ 必须加 `text` 属性
+
+---
+
+## 3. 顶部水平菜单
+
+当顶部有检索/监控/仪表盘等菜单时：
+
+```vue
+<bk-menu mode="horizontal" :active-key="activeNav">
+  <bk-menu-item key="search">检索</bk-menu-item>
+</bk-menu>
+```
+
+---
+
+## 4. Tag 颜色映射
+
+| 视觉颜色 | bk-tag 配置 | 使用场景 |
+|---------|------------|---------|
+| 蓝色背景 (如"内置") | `<bk-tag theme="info">` | 系统内置标识 |
+| 绿色背景 (如"自定义") | `<bk-tag theme="success">` | 用户自定义标识 |
+| 橙色背景 (如"警告") | `<bk-tag theme="warning">` | 警告状态 |
+| 红色背景 (如"危险") | `<bk-tag theme="danger">` | 错误/危险状态 |
+| 灰色边框 | `<bk-tag type="stroke">` | 普通标签 |
+
+## 开关组件识别
+
+| 视觉特征 | 组件 | 关键属性 |
+|---------|-----|---------|
+| 圆角滑动开关（绿色） | `<bk-switcher>` | 默认绿色 |
+| 圆角滑动开关（蓝色） | `<bk-switcher theme="primary">` | 蓝色主题 |
+| 方形勾选框 | `<bk-checkbox>` | - |
+| 圆形单选 | `<bk-radio>` | - |
+
+## 分页布局识别
+
+| 视觉特征 | 配置 |
+|---------|-----|
+| 左侧显示"共计 XX 条" | `:show-total-count="true"` + `location="left"` |
+| 右侧显示"每页 XX 条" | 默认配置 |
+| 紧凑小尺寸分页 | `size="small"` |
+
+## 筛选组件识别 (Tab vs Radio Capsule)
+
+**⚠️ 关键区分：看是否有分隔线 + 是否切换内容面板**
+
+| 视觉特征 | 组件 | 说明 |
+|---------|-----|------|
+| **选项之间有竖线分隔** | `bk-radio-group type="capsule"` | 胶囊样式 Radio |
+| 选项下方有内容面板切换 | `bk-tab` | Tab 组件 |
+| 选项有下划线高亮 | `bk-tab type="unborder-card"` | Tab 无边框样式 |
+
+### 胶囊样式 Radio（用于筛选）
+
+当看到选项被边框包裹、**选项之间有竖线分隔**时，使用 Radio Capsule：
+
+```vue
+<bk-radio-group v-model="activeFilter" type="capsule">
+  <bk-radio-button label="all">全部(24)</bk-radio-button>
+  <bk-radio-button label="enabled">启用(10)</bk-radio-button>
+  <bk-radio-button label="disabled">停用(14)</bk-radio-button>
+</bk-radio-group>
+```
+
+### Tab（用于切换内容面板）
+
+当选项下方有对应的内容区域需要切换显示时，使用 Tab：
+
+```vue
+<bk-tab v-model:active="activeTab" type="unborder-card">
+  <bk-tab-panel name="basic" label="基本信息">内容1</bk-tab-panel>
+  <bk-tab-panel name="config" label="配置信息">内容2</bk-tab-panel>
+</bk-tab>
+```
+
+> ⚠️ Tab 常见错误：`v-model="activeTab"` → 正确：`v-model:active="activeTab"`
+
+## 5. 提示信息 (Alert)
+
+| 视觉特征 | 组件 |
+|---------|-----|
+| 蓝色背景提示条 | `<bk-alert theme="info">` |
+| 绿色成功提示 | `<bk-alert theme="success">` |
+| 黄色警告提示 | `<bk-alert theme="warning">` |
+| 红色错误提示 | `<bk-alert theme="error">` |
+
+---
+
+> 完整代码示例 → 加载 `code-snippets.md`

package/knowledge/skills/bkui-cheatsheet/SKILL.md

@@ -0,0 +1,62 @@
+---
+id: eng-bkui-cheatsheet
+name: BKUI 组件属性速查表
+category: engineering
+description: 高频易错属性映射和避坑指南
+tags: [bkui, cheatsheet, props, pitfalls]
+updated_at: 2026-01-16
+---
+
+# BKUI 组件属性速查表
+
+还原设计稿时，严格遵守以下属性映射，**严禁使用 ElementUI/AntD 的属性名**。
+
+## ⚠️ 高频错误速查
+
+| 组件 | 错误 | 正确 |
+|------|------|------|
+| Button | `type="primary"` | `theme="primary"` |
+| Input | `prefix-icon="xx"` | `<template #prefix>` |
+| Icon | `<i class="bk-icon...">` | `import { Plus } from 'bkui-vue/lib/icon'` |
+| Dialog | `v-model="show"` | `v-model:isShow="show"` |
+| Table | 忘记 `remote-pagination` | 远程分页必须加 |
+| DatePicker | `shortcuts.value: []` | `shortcuts.value: () => []` |
+
+## 基础组件
+
+```vue
+<!-- Button -->
+<bk-button theme="primary">主要</bk-button>
+<bk-button text theme="primary">编辑</bk-button>
+
+<!-- Icon -->
+<script setup>
+import { Plus, Search } from 'bkui-vue/lib/icon';
+</script>
+
+<!-- Input -->
+<bk-input v-model="value">
+  <template #prefix><Search /></template>
+</bk-input>
+```
+
+## 表格开发
+
+```vue
+<bk-table :data="list" :pagination="pagination" remote-pagination>
+  <bk-table-column label="名称" prop="name" />
+  <bk-table-column label="操作">
+    <template #default="{ row }">
+      <bk-button text theme="primary">编辑</bk-button>
+    </template>
+  </bk-table-column>
+</bk-table>
+```
+
+> 分页对象: `{ current, limit, count }`
+
+## 📦 按需加载资源
+
+| 资源 | URI |
+|-----|-----|
+| 复杂组件 | `skill://bkui-cheatsheet/references/complex-components.md` |

package/knowledge/skills/bkui-cheatsheet/references/complex-components.md

@@ -0,0 +1,242 @@
+# 高级组件避坑指南
+
+> 详细的复杂组件使用说明
+
+## Select / SearchSelect
+
+### 多选 Tag 模式
+- **Select**: 必须显式设置 `multiple-mode="tag"`，否则默认是文本拼接
+- **SearchSelect**: 使用 `display-tag` 属性
+
+```vue
+<!-- Select -->
+<bk-select v-model="value" multiple multiple-mode="tag">
+  <bk-option value="1" label="选项1" />
+</bk-select>
+
+<!-- SearchSelect -->
+<bk-search-select v-model="value" :data="list" display-tag />
+```
+
+### 键名配置差异
+
+**重要**：两者默认值不同！
+
+| 组件 | id-key 默认值 | display-key 默认值 |
+|------|--------------|-------------------|
+| Select | `value` | `label` |
+| SearchSelect | `id` | `name` |
+
+```typescript
+// Select 数据格式
+const selectOptions = [
+  { value: '1', label: '选项1' }
+];
+
+// SearchSelect 数据格式
+const searchOptions = [
+  { id: '1', name: '选项1' }
+];
+```
+
+### 远程搜索
+
+必须配合 `filterable` 和 `remote-method`：
+
+```vue
+<bk-select
+  v-model="value"
+  filterable
+  :remote-method="handleSearch"
+  :loading="loading"
+>
+  <bk-option
+    v-for="item in filteredList"
+    :key="item.id"
+    :value="item.id"
+    :label="item.name"
+  />
+</bk-select>
+```
+
+## DatePicker 日期选择
+
+### 快捷方式陷阱
+
+`shortcuts` 的 `value` **必须是函数**，不能是静态值！
+
+```javascript
+// ❌ 错误：静态值
+const shortcuts = [
+  {
+    text: '今天',
+    value: [new Date(), new Date()] // 只会计算一次
+  }
+];
+
+// ✅ 正确：函数
+const shortcuts = [
+  {
+    text: '今天',
+    value: () => {
+      const now = new Date();
+      return [now, now];
+    }
+  },
+  {
+    text: '最近7天',
+    value: () => {
+      const end = new Date();
+      const start = new Date();
+      start.setDate(start.getDate() - 7);
+      return [start, end];
+    }
+  }
+];
+```
+
+### 类型名称陷阱
+
+范围类型是**一个单词**，中间没有连字符：
+
+| 错误 | 正确 |
+|------|------|
+| `datetime-range` | `datetimerange` |
+| `date-range` | `daterange` |
+
+```vue
+<bk-date-picker
+  v-model="dateRange"
+  type="datetimerange"
+  :shortcuts="shortcuts"
+/>
+```
+
+## Upload 文件上传
+
+### 响应码判断
+
+默认只认 `res.code === 0`，如果后端返回 `result: true`，需要自定义：
+
+```vue
+<bk-upload
+  :url="uploadUrl"
+  :handle-res-code="(res) => res.result === true"
+/>
+```
+
+### 大小限制单位
+
+`size` 属性单位是 **MB**：
+
+```vue
+<!-- 限制 10MB -->
+<bk-upload :size="10" />
+```
+
+### 文件数组绑定
+
+`files` 是**单向绑定**的初始值，不要用 v-model：
+
+```vue
+<!-- ❌ 错误 -->
+<bk-upload v-model:files="fileList" />
+
+<!-- ✅ 正确 -->
+<bk-upload
+  :files="fileList"
+  @change="handleFileChange"
+/>
+```
+
+## Tree 树形组件
+
+### 唯一标识
+
+推荐显式设置 `node-key`：
+
+```vue
+<bk-tree
+  :data="treeData"
+  node-key="id"
+/>
+```
+
+### 虚拟滚动高度
+
+默认开启虚拟滚动，必须设置高度：
+
+```vue
+<bk-tree
+  :data="treeData"
+  :height="500"
+/>
+```
+
+或者确保父容器有明确高度：
+
+```css
+.tree-container {
+  height: 500px;
+}
+```
+
+### 数据刷新
+
+修改 `data` 数组后，建议手动重置：
+
+```typescript
+const treeRef = ref();
+
+const refreshTree = () => {
+  treeData.value = [...newData];
+  nextTick(() => {
+    treeRef.value?.reset();
+  });
+};
+```
+
+## Form 表单验证
+
+### 验证时机
+
+- `trigger: 'blur'` - 失焦时验证
+- `trigger: 'change'` - 值改变时验证
+- 手动验证：`formRef.value.validate()`
+
+### 异步验证
+
+validator 可以返回 Promise：
+
+```typescript
+const rules = {
+  username: [
+    {
+      validator: async (value) => {
+        const exists = await checkUsernameExists(value);
+        if (exists) {
+          return '用户名已存在';
+        }
+        return true;
+      },
+      trigger: 'blur'
+    }
+  ]
+};
+```
+
+### 动态表单项
+
+使用 `v-for` 生成的表单项，`property` 必须用数组语法：
+
+```vue
+<bk-form-item
+  v-for="(item, index) in list"
+  :key="index"
+  :label="`项目${index + 1}`"
+  :property="`list.${index}.value`"
+  :rules="[{ required: true }]"
+>
+  <bk-input v-model="list[index].value" />
+</bk-form-item>
+```

package/knowledge/skills/bundle-optimization/SKILL.md

@@ -0,0 +1,44 @@
+---
+id: eng-bundle-opt
+name: Vite 构建产物体积优化
+category: engineering
+description: 使用 Rollup Visualizer 分析产物，并通过拆包 (Code Splitting) 和 Tree Shaking 减少首屏体积。
+tags: [vite, rollup, performance, optimization]
+updated_at: 2026-01-09
+---
+
+# Vite 构建产物体积优化
+
+当首屏加载慢 (FCP > 1.5s) 时，通常需要检查 JS Bundle 的体积。
+
+## 1. 产物分析 (Visualizer)
+
+首先"看见"哪些包最大。
+
+```bash
+npm install rollup-plugin-visualizer -D
+```
+
+## 2. 常用优化策略
+
+### 路由懒加载 (Route Lazy Loading)
+**这是收益最大的优化点**。
+
+❌ `import UserList from './views/UserList.vue'`
+✅ `component: () => import('./views/UserList.vue')`
+
+### 依赖分包 (Manual Chunks)
+将大型库（ECharts, bkui-vue）单独打包，避免 vendor hash 频繁变化。
+
+### 按需引入 (Tree Shaking)
+❌ `import _ from 'lodash'`
+✅ `import debounce from 'lodash-es/debounce'`
+
+### Gzip 压缩
+```bash
+npm install vite-plugin-compression -D
+```
+
+## 3. 完整配置模版
+
+> 📦 获取完整 vite.config.ts 配置：`skill://bundle-optimization/assets/vite.config.optimization.ts`