@blueking/bkui-knowledge 0.0.1-beta.1 → 0.0.1-beta.10

package/knowledge/skills/bk-skill-creator/references/writing-tips.md

@@ -0,0 +1,153 @@
+# Skill 写作技巧
+
+## 控制 SKILL.md 大小
+
+### 技巧 1: 只保留"必须知道"的内容
+
+**问自己**：如果 AI 只读这个文件，哪些信息是绝对必要的？
+
+- ✅ 核心规则（必须遵守）
+- ✅ 最简单的使用示例
+- ✅ 最常见的错误
+- ❌ 详细解释（移到 references/）
+- ❌ 多个完整示例（移到 references/）
+- ❌ 历史背景（删除或移走）
+
+### 技巧 2: 使用表格代替段落
+
+**Before（冗长）**：
+```markdown
+## 常见错误
+
+### 错误 1: 文件过大
+当 SKILL.md 超过 2KB 时，会导致 AI 消耗过多 token...
+
+### 错误 2: 缺少元数据
+如果没有 Front Matter，系统无法正确索引...
+```
+
+**After（精简）**：
+```markdown
+## 常见错误
+
+| 错误 | 正确做法 |
+|-----|---------|
+| ❌ 文件过大 | ✅ 拆分到 references/ |
+| ❌ 缺少元数据 | ✅ 添加 Front Matter |
+```
+
+### 技巧 3: 代码示例最小化
+
+只展示最核心的代码，完整示例放 references/。
+
+**Before（完整）**：
+```typescript
+import axios from 'axios';
+import { Message } from 'bkui-vue';
+
+const http = axios.create({
+  baseURL: '/api',
+  timeout: 30000,
+  headers: { 'Content-Type': 'application/json' }
+});
+
+http.interceptors.response.use(
+  response => response.data,
+  error => {
+    Message.error(error.message);
+    return Promise.reject(error);
+  }
+);
+
+export default http;
+```
+
+**After（最小）**：
+```typescript
+import axios from 'axios';
+const http = axios.create({ baseURL: '/api', timeout: 30000 });
+export default http;
+```
+
+> 完整实现见 `skill://api-standard/assets/http.ts`
+
+## 内容拆分策略
+
+### 拆分原则
+
+| 内容类型 | 放置位置 |
+|---------|---------|
+| 核心规则 | SKILL.md |
+| 快速开始 | SKILL.md |
+| 常见错误 | SKILL.md |
+| 详细配置 | references/advanced.md |
+| 完整示例 | references/examples.md |
+| 问题排查 | references/troubleshooting.md |
+| 代码模板 | assets/*.ts |
+
+### 拆分示例
+
+**原始内容**（3KB，需要拆分）：
+
+```markdown
+# API 封装规范
+
+## 核心规则
+...
+
+## 详细配置
+### 请求拦截器配置
+（500字详细说明）
+
+### 响应拦截器配置
+（500字详细说明）
+
+## 完整示例
+（800字完整代码）
+```
+
+**拆分后**：
+
+SKILL.md（1.5KB）：
+```markdown
+# API 封装规范
+## 核心规则
+...
+## 📦 按需加载资源
+- 详细配置: `skill://api-standard/references/advanced.md`
+- 完整示例: `skill://api-standard/assets/http.ts`
+```
+
+references/advanced.md：
+```markdown
+# 详细配置
+## 请求拦截器配置
+...
+## 响应拦截器配置
+...
+```
+
+## 好的 Skill 示例分析
+
+### bkui-builder
+
+**优点**：
+1. SKILL.md 只有 1.5KB，非常精简
+2. 使用表格展示模板选择逻辑
+3. 按需加载资源清晰列出
+
+**值得学习**：
+- 用"绝对禁令"强调最重要的规则
+- 用"还原流程"提供清晰步骤
+- 模板资源按场景分类
+
+### code-review
+
+**优点**：
+1. 核心规则简洁明确
+2. 详细检查清单放在 references/
+3. 评分标准独立成文件
+
+**值得学习**：
+- 将复杂的评审标准拆分到多个 references 文件
+- 使用 assets/ 存放可执行脚本

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

@@ -0,0 +1,52 @@
+---
+id: bkui-quick-start
+name: BKUI 快速入门
+category: engineering
+description: 蓝鲸前端知识库入口指南，包含规范、索引和工作流程
+tags: [bkui, 规范, 索引, 入门, vue3]
+updated_at: 2026-01-23
+---
+
+# 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` |
+
+## 高优先级组件
+
+- `bk-navigation` - 布局组件，易出错
+- `bk-menu` - 与 navigation 配合
+- `bk-table` - 列表页核心组件
+- `bk-form` - 表单验证
+- `bk-dialog` - v-model:isShow
+
+## 工作流程
+
+1. **分析需求** → 确定需要哪些资源
+2. **布局组件** → `get_component_api({ componentName: 'navigation' })`
+3. **模板代码** → `get_skill({ skillId: 'bkui-builder' })`
+
+## 触发条件
+
+遇到 bk- 前缀组件、bkui-vue、蓝鲸前端、设计稿还原时使用。
+
+---
+
+## 按需加载资源
+
+- `skill://bkui-quick-start/references/skills-index.md` - 完整 Skills 索引
+- `skill://bkui-quick-start/references/components-list.md` - 组件完整列表

package/knowledge/skills/bkui-quick-start/references/components-list.md

@@ -0,0 +1,17 @@
+# 组件完整列表
+
+通过 `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

package/knowledge/skills/bkui-quick-start/references/skills-index.md

@@ -0,0 +1,26 @@
+# 可用 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 | 长列表虚拟滚动 | 性能优化方案 |
+
+## 质量保障
+
+| ID | 名称 | 说明 |
+|----|------|------|
+| unit-testing | 组件单元测试 | Vitest 测试模板 |
+| code-review | 代码评审专家 | 评审规范和检查清单 |
+| js-security-check | JavaScript 安全审查 | 前端安全检查 |
+| nodejs-security-check | Node.js 安全审查 | 后端安全检查 |

package/knowledge/skills/external/vue-skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hyf0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/knowledge/skills/external/vue-skills/README.md

@@ -0,0 +1,69 @@
+# vue-skills
+
+Agent skills for Vue 3 development.
+
+> 🚧 **Early Experiment**
+>
+> This repository is an early experiment in creating specialized skills for AI agents to enhance their capabilities in Vue 3 development. The skills are derived from real-world issues and best practices, but might be incomplete or inaccurate due to hallucinations.
+>
+> Please give feedback when encountering any issues.
+
+## Installation
+
+```bash
+npx add-skill hyf0/vue-skills
+```
+
+## Available Skills
+
+### vue-best-practices (17 rules)
+
+Vue 3 development best practices covering TypeScript configuration, tooling troubleshooting, and testing patterns.
+
+| Type | Count | Examples |
+|------|-------|----------|
+| Capability | 15 | vue-tsc strictTemplates, Volar 3.0 breaking changes, Vue 3.5 deep watch, @vue-ignore directives |
+| Efficiency | 2 | HMR in SSR, Pinia store mocking |
+
+**Key rules that models don't know without the skill:**
+- `vue-tsc-strict-templates` - vueCompilerOptions.strictTemplates config
+- `deep-watch-numeric` - Vue 3.5 `deep: 1` for efficient partial-depth watching
+- `vue-directive-comments` - @vue-ignore, @vue-expect-error, @vue-skip directives
+- `pinia-store-mocking` - createSpy requirement in @pinia/testing 1.0+
+
+## Rule Types
+
+Rules are classified into two categories:
+
+- **Capability**: AI *cannot* solve the problem without the skill. These address version-specific issues, undocumented behaviors, recent features, or edge cases outside AI's training data.
+
+- **Efficiency**: AI *can* solve the problem but not well. These provide optimal patterns, best practices, and consistent approaches that improve solution quality.
+
+## Methodology
+
+Every skill in this repository is created through a rigorous, evidence-based process:
+
+**1. Real-World Issue Collection**
+
+Skills are sourced from actual developer pain points encountered in production.
+
+**2. Multi-Model Verification**
+
+Each skill undergoes systematic testing:
+- **Baseline test**: Verify the model fails to solve the problem *without* the skill
+- **Skill test**: Confirm the model correctly solves the problem *with* the skill
+- **Deletion criteria**: If both Sonnet AND Haiku pass without the skill, the rule will be deleted
+
+**3. Model Tier Validation**
+
+| Model | Without Skill | With Skill | Action |
+|-------|--------------|------------|--------|
+| Haiku | Fail | Pass | Keep |
+| Sonnet | Fail | Pass | Keep |
+| Both | Pass | - | Delete |
+
+**Acceptance criteria**: A skill is only kept if it enables Haiku or Sonnet to solve a problem they couldn't solve without it.
+
+## License
+
+MIT

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: vue-best-practices
+description: Vue 3 TypeScript, vue-tsc, Volar, Vite, component props, testing, composition API.
+license: MIT
+metadata:
+  author: hyf0
+  version: "7.0.0"
+---
+
+# Vue Best Practices
+
+## Capability Rules
+
+| Rule | Keywords | Description |
+|------|----------|-------------|
+| [vue-tsc-strict-templates](rules/vue-tsc-strict-templates.md) | undefined component, template error, strictTemplates | Catch undefined components in templates |
+| [fallthrough-attributes](rules/fallthrough-attributes.md) | fallthrough, $attrs, wrapper component | Type-check fallthrough attributes |
+| [strict-css-modules](rules/strict-css-modules.md) | css modules, $style, typo | Catch CSS module class typos |
+| [data-attributes-config](rules/data-attributes-config.md) | data-*, strictTemplates, attribute | Allow data-* attributes |
+| [volar-3-breaking-changes](rules/volar-3-breaking-changes.md) | volar, vue-language-server, editor | Fix Volar 3.0 upgrade issues |
+| [module-resolution-bundler](rules/module-resolution-bundler.md) | cannot find module, @vue/tsconfig, moduleResolution | Fix module resolution errors |
+| [unplugin-auto-import-conflicts](rules/unplugin-auto-import-conflicts.md) | unplugin, auto-import, types any | Fix unplugin type conflicts |
+| [codeactions-save-performance](rules/codeactions-save-performance.md) | slow save, vscode, performance | Fix slow save in large projects |
+| [duplicate-plugin-detection](rules/duplicate-plugin-detection.md) | duplicate plugin, vite, vue plugin | Detect duplicate plugins |
+| [define-model-update-event](rules/define-model-update-event.md) | defineModel, update event, undefined | Fix model update errors |
+| [with-defaults-union-types](rules/with-defaults-union-types.md) | withDefaults, union type, default | Fix union type defaults |
+| [deep-watch-numeric](rules/deep-watch-numeric.md) | watch, deep, array, Vue 3.5 | Efficient array watching |
+| [vue-directive-comments](rules/vue-directive-comments.md) | @vue-ignore, @vue-skip, template | Control template type checking |
+| [script-setup-jsdoc](rules/script-setup-jsdoc.md) | jsdoc, script setup, documentation | Add JSDoc to script setup |
+| [vue-router-typed-params](rules/vue-router-typed-params.md) | route params, typed router, unplugin | Fix route params typing |
+
+## Efficiency Rules
+
+| Rule | Keywords | Description |
+|------|----------|-------------|
+| [hmr-vue-ssr](rules/hmr-vue-ssr.md) | hmr, ssr, hot reload | Fix HMR in SSR apps |
+| [pinia-store-mocking](rules/pinia-store-mocking.md) | pinia, mock, vitest, store | Mock Pinia stores |
+
+## Reference
+
+- [Vue Language Tools](https://github.com/vuejs/language-tools)
+- [Vue 3 Documentation](https://vuejs.org/)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/codeactions-save-performance.md

@@ -0,0 +1,79 @@
+---
+title: Fix Slow Save Times with Code Actions Setting
+impact: HIGH
+impactDescription: fixes 30-60 second save delays in large Vue projects
+type: capability
+tags: performance, save-time, vscode, code-actions, volar
+---
+
+# Fix Slow Save Times with Code Actions Setting
+
+**Impact: HIGH** - fixes 30-60 second save delays in large Vue projects
+
+In large Vue projects, saving files can take 30-60+ seconds due to VSCode's code actions triggering expensive TypeScript state synchronization.
+
+## Problem
+
+Symptoms:
+- Save operation takes 30+ seconds
+- Editor becomes unresponsive during save
+- CPU spikes when saving Vue files
+- Happens more in larger projects
+
+## Root Cause
+
+VSCode emits document change events multiple times during save cycles. Each event triggers Volar to synchronize with TypeScript, causing expensive re-computation.
+
+## Solution
+
+Disable code actions or limit their timeout:
+
+**Option 1: Disable code actions (fastest)**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": false
+}
+```
+
+**Option 2: Limit code action time**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.savingTimeLimit": 1000
+}
+```
+
+**Option 3: Disable specific code actions**
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": true,
+  "editor.codeActionsOnSave": {
+    "source.organizeImports": "never"
+  }
+}
+```
+
+## VSCode Version Requirement
+
+VSCode 1.81.0+ includes fixes that reduce save time issues. Upgrade if using an older version.
+
+## Additional Optimizations
+
+```json
+// .vscode/settings.json
+{
+  "vue.codeActions.enabled": false,
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {},
+  "[vue]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "Vue.volar"
+  }
+}
+```
+
+## Reference
+
+- [Vue Language Tools Discussion #2740](https://github.com/vuejs/language-tools/discussions/2740)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/data-attributes-config.md

@@ -0,0 +1,74 @@
+---
+title: Allow Data Attributes with Strict Templates
+impact: MEDIUM
+impactDescription: fixes data-testid and data-* attribute errors in strict mode
+type: capability
+tags: dataAttributes, vueCompilerOptions, strictTemplates, data-testid, testing
+---
+
+# Allow Data Attributes with Strict Templates
+
+**Impact: MEDIUM** - fixes data-testid and data-* attribute errors in strict mode
+
+With `strictTemplates` enabled, `data-*` attributes on components cause type errors. Use the `dataAttributes` option to allow specific patterns.
+
+## Problem
+
+```vue
+<template>
+  <!-- Error: Property 'data-testid' does not exist on type... -->
+  <MyComponent data-testid="submit-button" />
+
+  <!-- Error: Property 'data-cy' does not exist on type... -->
+  <MyComponent data-cy="login-form" />
+</template>
+```
+
+## Solution
+
+Configure `dataAttributes` to allow specific patterns:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "strictTemplates": true,
+    "dataAttributes": ["data-*"]
+  }
+}
+```
+
+Now all `data-*` attributes are allowed on any component.
+
+## Specific Patterns
+
+You can be more selective:
+
+```json
+{
+  "vueCompilerOptions": {
+    "dataAttributes": [
+      "data-testid",
+      "data-cy",
+      "data-test-*"
+    ]
+  }
+}
+```
+
+This only allows the specified patterns, not all data attributes.
+
+## Common Testing Attributes
+
+For testing libraries, allow their specific attributes:
+
+| Library | Attribute | Pattern |
+|---------|-----------|---------|
+| Testing Library | `data-testid` | `"data-testid"` |
+| Cypress | `data-cy` | `"data-cy"` |
+| Playwright | `data-testid` | `"data-testid"` |
+| Generic | All data attributes | `"data-*"` |
+
+## Reference
+
+- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/deep-watch-numeric.md

@@ -0,0 +1,102 @@
+---
+title: Vue 3.5+ Deep Watch Numeric Depth
+impact: MEDIUM
+impactDescription: enables efficient array mutation watching with numeric deep option
+type: capability
+tags: watch, deep, vue-3.5, array, mutation, performance
+---
+
+# Vue 3.5+ Deep Watch Numeric Depth
+
+**Impact: MEDIUM** - enables efficient array mutation watching with numeric deep option
+
+Vue 3.5 introduced `deep: number` for watch depth control. This allows watching array mutations without the performance cost of deep traversal.
+
+## Symptoms
+
+- Array mutations not triggering watch callback
+- Deep watch causing performance issues on large nested objects
+- Unaware of new Vue 3.5 feature
+
+> **Note:** TypeScript error "Type 'number' is not assignable to type 'boolean'" no longer occurs with Vue 3.5+ and current TypeScript versions. The types now correctly support numeric `deep` values.
+
+## The Feature
+
+```typescript
+// Vue 3.5+ only
+watch(items, (newVal) => {
+  // Triggered on array mutations (push, pop, splice, etc.)
+}, { deep: 1 })
+```
+
+| deep value | Behavior |
+|------------|----------|
+| `true` | Full recursive traversal (original behavior) |
+| `false` | Only reference changes |
+| `1` | One level deep - array mutations, not nested objects |
+| `2` | Two levels deep |
+| `n` | N levels deep |
+
+## Fix
+
+**Step 1: Ensure Vue 3.5+**
+```bash
+npm install vue@^3.5.0
+```
+
+**Step 2: Update @vue/runtime-core types**
+```bash
+npm install -D @vue/runtime-core@latest
+```
+
+**Step 3: Use numeric depth**
+```typescript
+import { watch, ref } from 'vue'
+
+const items = ref([{ id: 1, data: { nested: 'value' } }])
+
+// Watch array mutations only (push, pop, etc.)
+watch(items, (newItems) => {
+  console.log('Array mutated')
+}, { deep: 1 })
+
+// Won't trigger on: items.value[0].data.nested = 'new'
+// Will trigger on: items.value.push(newItem)
+```
+
+## Performance Comparison
+
+```typescript
+const largeNestedData = ref({ /* deeply nested structure */ })
+
+// SLOW - traverses entire structure
+watch(largeNestedData, handler, { deep: true })
+
+// FAST - only watches top-level changes
+watch(largeNestedData, handler, { deep: 1 })
+
+// FASTEST - only reference changes
+watch(largeNestedData, handler, { deep: false })
+```
+
+## Alternative: watchEffect for Selective Tracking
+
+```typescript
+// Only tracks properties actually accessed
+watchEffect(() => {
+  // Only re-runs when items.value.length or first item changes
+  console.log(items.value.length, items.value[0]?.id)
+})
+```
+
+## TypeScript Note
+
+If TypeScript complains about numeric deep, ensure:
+1. Vue version is 3.5+
+2. `@vue/runtime-core` types are updated
+3. tsconfig targets correct node_modules types
+
+## Reference
+
+- [Vue Watchers Docs](https://vuejs.org/guide/essentials/watchers.html)
+- [Vue 3.5 Release Notes](https://blog.vuejs.org/posts/vue-3-5)