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

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)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/define-model-update-event.md

@@ -0,0 +1,79 @@
+---
+title: defineModel Fires Update Event with Undefined
+impact: MEDIUM
+impactDescription: fixes runtime errors from unexpected undefined in model updates
+type: capability
+tags: defineModel, v-model, update-event, undefined, vue-3.5
+---
+
+# defineModel Fires Update Event with Undefined
+
+**Impact: MEDIUM** - fixes runtime errors from unexpected undefined in model updates
+
+> **Version Note (2025):** This issue may be resolved in Vue 3.5+. Testing with Vue 3.5.26 could not reproduce the double emission with `undefined`. If you're on Vue 3.5+, verify the issue exists in your specific scenario before applying workarounds.
+
+Components using `defineModel` may fire the `@update:model-value` event with `undefined` in certain edge cases. TypeScript types don't always reflect this behavior, potentially causing runtime errors when the parent expects a non-nullable value.
+
+## Symptoms
+
+- Parent component receives `undefined` unexpectedly
+- Runtime error: "Cannot read property of undefined"
+- Type mismatch between expected `T` and received `T | undefined`
+- Issue appears when clearing/resetting the model value
+
+## Root Cause
+
+`defineModel` returns `Ref<T | undefined>` by default, even when `T` is non-nullable. The update event can fire with `undefined` when:
+- Component unmounts
+- Model is explicitly cleared
+- Internal state resets
+
+## Fix
+
+**Option 1: Use required option (Vue 3.5+)**
+```typescript
+// Returns Ref<Item> instead of Ref<Item | undefined>
+const model = defineModel<Item>({ required: true })
+```
+
+**Option 2: Type parent handler to accept undefined**
+```vue
+<template>
+  <MyComponent
+    v-model="item"
+    @update:model-value="handleUpdate"
+  />
+</template>
+
+<script setup lang="ts">
+// Handle both value and undefined
+const handleUpdate = (value: Item | undefined) => {
+  if (value !== undefined) {
+    item.value = value
+  }
+}
+</script>
+```
+
+**Option 3: Use default value in defineModel**
+```typescript
+const model = defineModel<string>({ default: '' })
+```
+
+## Type Declaration Pattern
+
+```typescript
+// In child component
+interface Props {
+  modelValue: Item
+}
+const model = defineModel<Item>({ required: true })
+
+// Emits will be typed as (value: Item) not (value: Item | undefined)
+```
+
+## Reference
+
+- [vuejs/core#12817](https://github.com/vuejs/core/issues/12817)
+- [vuejs/core#10103](https://github.com/vuejs/core/issues/10103)
+- [defineModel docs](https://vuejs.org/api/sfc-script-setup.html#definemodel)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/duplicate-plugin-detection.md

@@ -0,0 +1,102 @@
+---
+title: Duplicate Vue Plugin Detection
+impact: MEDIUM
+impactDescription: fixes cryptic build errors from Vue plugin registered twice
+type: capability
+tags: vite, plugin, vue, duplicate, config, inline
+---
+
+# Duplicate Vue Plugin Detection
+
+**Impact: MEDIUM** - fixes cryptic build errors from Vue plugin registered twice
+
+When using Vite's JavaScript API, if the Vue plugin is loaded in `vite.config.js` and specified again in `inlineConfig`, it gets registered twice, causing cryptic build errors.
+
+## Symptoms
+
+- Build produces unexpected output or fails silently
+- "Cannot read property of undefined" during build
+- Different build behavior between CLI and JavaScript API
+- Vue components render incorrectly after build
+
+## Root Cause
+
+Vite doesn't deduplicate plugins by name when merging configs. The Vue plugin's internal state gets corrupted when registered twice.
+
+## Fix
+
+**Option 1: Use configFile: false with inline plugins**
+```typescript
+import { build } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+await build({
+  configFile: false,  // Don't load vite.config.js
+  plugins: [vue()],
+  // ... rest of config
+})
+```
+
+**Option 2: Don't specify plugins in inlineConfig**
+```typescript
+// vite.config.js already has vue plugin
+import { build } from 'vite'
+
+await build({
+  // Don't add vue plugin here - it's in vite.config.js
+  root: './src',
+  build: { outDir: '../dist' }
+})
+```
+
+**Option 3: Filter out Vue plugin before merging**
+```typescript
+import { build, loadConfigFromFile } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+const { config } = await loadConfigFromFile({ command: 'build', mode: 'production' })
+
+// Remove existing Vue plugin
+const filteredPlugins = config.plugins?.filter(
+  p => !p || (Array.isArray(p) ? false : p.name !== 'vite:vue')
+) || []
+
+await build({
+  ...config,
+  plugins: [...filteredPlugins, vue({ /* your options */ })]
+})
+```
+
+## Detection Script
+
+Add this to debug plugin registration:
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    vue(),
+    {
+      name: 'debug-plugins',
+      configResolved(config) {
+        const vuePlugins = config.plugins.filter(p => p.name?.includes('vue'))
+        if (vuePlugins.length > 1) {
+          console.warn('WARNING: Multiple Vue plugins detected:', vuePlugins.map(p => p.name))
+        }
+      }
+    }
+  ]
+})
+```
+
+## Common Scenarios
+
+| Scenario | Solution |
+|----------|----------|
+| Using `vite.createServer()` | Use `configFile: false` |
+| Build script with custom config | Don't duplicate plugins |
+| Monorepo with shared config | Check for plugin inheritance |
+
+## Reference
+
+- [Vite Issue #5335](https://github.com/vitejs/vite/issues/5335)
+- [Vite JavaScript API](https://vite.dev/guide/api-javascript.html)

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

@@ -0,0 +1,63 @@
+---
+title: Enable Fallthrough Attributes Type Checking
+impact: HIGH
+impactDescription: enables type-safe fallthrough attributes in component libraries
+type: capability
+tags: fallthroughAttributes, vueCompilerOptions, component-library, wrapper-components
+---
+
+# Enable Fallthrough Attributes Type Checking
+
+**Impact: MEDIUM** - enables type-aware attribute forwarding in component libraries
+
+When building component libraries with wrapper components, enable `fallthroughAttributes` to get IDE autocomplete for attributes that will be forwarded to child elements.
+
+## What It Does
+
+Wrapper components that pass attributes to child elements can benefit from type-aware completion:
+
+```vue
+<!-- MyButton.vue - wrapper around native button -->
+<template>
+  <button v-bind="$attrs"><slot /></button>
+</template>
+```
+
+## Solution
+
+Enable `fallthroughAttributes` in your tsconfig:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "fallthroughAttributes": true
+  }
+}
+```
+
+## How It Works
+
+When `fallthroughAttributes: true`:
+- Vue Language Server analyzes which element receives `$attrs`
+- IDE autocomplete suggests valid attributes for the target element
+- Helps developers discover available attributes
+
+> **Note:** This primarily enables IDE autocomplete for valid fallthrough attributes. It does NOT reject invalid attributes as type errors - arbitrary attributes are still allowed.
+
+## Related Options
+
+Combine with `strictTemplates` for comprehensive checking:
+
+```json
+{
+  "vueCompilerOptions": {
+    "strictTemplates": true,
+    "fallthroughAttributes": true
+  }
+}
+```
+
+## Reference
+
+- [Vue Language Tools Wiki - Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)