@blueking/bkui-knowledge 0.0.1-beta.6 → 0.0.1-beta.8

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/strict-css-modules.md

@@ -0,0 +1,68 @@
+---
+title: Enable Strict CSS Modules Type Checking
+impact: MEDIUM
+impactDescription: catches typos in CSS module class names at compile time
+type: capability
+tags: strictCssModules, vueCompilerOptions, css-modules, style-module
+---
+
+# Enable Strict CSS Modules Type Checking
+
+**Impact: MEDIUM** - catches typos in CSS module class names at compile time
+
+When using CSS modules with `<style module>`, Vue doesn't validate class names by default. Enable `strictCssModules` to catch typos and undefined classes.
+
+## Problem
+
+CSS module class name errors go undetected:
+
+```vue
+<script setup lang="ts">
+// No error for typo in class name
+</script>
+
+<template>
+  <div :class="$style.buttn">Click me</div>
+</template>
+
+<style module>
+.button {
+  background: blue;
+}
+</style>
+```
+
+The typo `buttn` instead of `button` silently fails at runtime.
+
+## Solution
+
+Enable `strictCssModules` in your tsconfig:
+
+```json
+// tsconfig.json or tsconfig.app.json
+{
+  "vueCompilerOptions": {
+    "strictCssModules": true
+  }
+}
+```
+
+Now `$style.buttn` will show a type error because `buttn` doesn't exist in the CSS module.
+
+## What Gets Checked
+
+| Access | With strictCssModules |
+|--------|----------------------|
+| `$style.validClass` | OK |
+| `$style.typo` | Error: Property 'typo' does not exist |
+| `$style['dynamic']` | OK (dynamic access not checked) |
+
+## Limitations
+
+- Only checks static property access (`$style.className`)
+- Dynamic access (`$style[variable]`) is not validated
+- Only works with `<style module>`, not external CSS files
+
+## 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/unplugin-auto-import-conflicts.md

@@ -0,0 +1,97 @@
+---
+title: unplugin-vue-components and unplugin-auto-import Type Conflicts
+impact: HIGH
+impactDescription: fixes component types resolving as any when using both plugins
+type: capability
+tags: unplugin-vue-components, unplugin-auto-import, types, any, dts
+---
+
+# unplugin-vue-components and unplugin-auto-import Type Conflicts
+
+**Impact: HIGH** - fixes component types resolving as any when using both plugins
+
+Installing both `unplugin-vue-components` and `unplugin-auto-import` can cause component types to resolve as `any`. The generated `.d.ts` files conflict with each other.
+
+## Symptoms
+
+- Components typed as `any` instead of proper component types
+- No autocomplete for component props
+- No type errors for invalid props
+- Types work when using only one plugin but break with both
+
+## Root Cause
+
+Both plugins generate declaration files (`components.d.ts` and `auto-imports.d.ts`) that can have conflicting declarations. TypeScript declaration merging fails silently.
+
+## Fix
+
+**Step 1: Ensure both .d.ts files are in tsconfig include**
+```json
+{
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.vue",
+    "components.d.ts",
+    "auto-imports.d.ts"
+  ]
+}
+```
+
+**Step 2: Set explicit, different dts paths**
+```typescript
+// vite.config.ts
+import Components from 'unplugin-vue-components/vite'
+import AutoImport from 'unplugin-auto-import/vite'
+
+export default defineConfig({
+  plugins: [
+    Components({
+      dts: 'src/types/components.d.ts'  // Explicit unique path
+    }),
+    AutoImport({
+      dts: 'src/types/auto-imports.d.ts'  // Explicit unique path
+    })
+  ]
+})
+```
+
+**Step 3: Regenerate type files**
+```bash
+# Delete existing .d.ts files
+rm components.d.ts auto-imports.d.ts
+
+# Restart dev server to regenerate
+npm run dev
+```
+
+**Step 4: Verify no duplicate declarations**
+
+Check that the same component isn't declared in both files.
+
+## Plugin Order Matters
+
+Configure Components plugin AFTER AutoImport:
+```typescript
+plugins: [
+  AutoImport({ /* ... */ }),
+  Components({ /* ... */ })  // Must come after AutoImport
+]
+```
+
+## Common Mistake: Duplicate Imports
+
+Don't configure the same import in both plugins:
+```typescript
+// Wrong - Vue imported in both
+AutoImport({
+  imports: ['vue']
+})
+Components({
+  resolvers: [/* includes Vue components */]
+})
+```
+
+## Reference
+
+- [unplugin-vue-components#640](https://github.com/unplugin/unplugin-vue-components/issues/640)
+- [unplugin-auto-import docs](https://github.com/unplugin/unplugin-auto-import)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/volar-3-breaking-changes.md

@@ -0,0 +1,66 @@
+---
+title: Volar 3.0 Breaking Changes
+impact: HIGH
+impactDescription: fixes editor integration after Volar/vue-language-server upgrade
+type: capability
+tags: volar, vue-language-server, neovim, vscode, ide, ts_ls, vtsls
+---
+
+# Volar 3.0 Breaking Changes
+
+**Impact: HIGH** - fixes editor integration after Volar/vue-language-server upgrade
+
+Volar 3.0 (vue-language-server 3.x) introduced breaking changes to the language server protocol. Editors configured for Volar 2.x will break with errors like "vue_ls doesn't work with ts_ls.. it expects vtsls".
+
+## Symptoms
+
+- `vue_ls doesn't work with ts_ls`
+- TypeScript features stop working in Vue files
+- No autocomplete, type hints, or error highlighting
+- Editor shows "Language server initialization failed"
+
+## Fix by Editor
+
+### VSCode
+
+Update the "Vue - Official" extension to latest version. It manages the language server automatically.
+
+### NeoVim (nvim-lspconfig)
+
+**Option 1: Use vtsls instead of ts_ls**
+```lua
+-- Replace ts_ls/tsserver with vtsls
+require('lspconfig').vtsls.setup({})
+require('lspconfig').volar.setup({})
+```
+
+**Option 2: Downgrade vue-language-server**
+```bash
+npm install -g @vue/language-server@2.1.10
+```
+
+### JetBrains IDEs
+
+Update to latest Vue plugin. If issues persist, disable and re-enable the Vue plugin.
+
+## What Changed in 3.0
+
+| Feature | Volar 2.x | Volar 3.0 |
+|---------|-----------|-----------|
+| Package name | volar | vue_ls |
+| TypeScript integration | ts_ls/tsserver | vtsls required |
+| Hybrid mode | Optional | Default |
+
+## Workaround: Stay on 2.x
+
+If upgrading is not possible:
+```bash
+npm install -g @vue/language-server@^2.0.0
+```
+
+Pin in your project's package.json to prevent accidental upgrades.
+
+## Reference
+
+- [vuejs/language-tools#5598](https://github.com/vuejs/language-tools/issues/5598)
+- [NeoVim Vue Setup Guide](https://dev.to/danwalsh/solved-vue-3-typescript-inlay-hint-support-in-neovim-53ej)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/vue-directive-comments.md

@@ -0,0 +1,73 @@
+---
+title: Vue Template Directive Comments
+impact: HIGH
+impactDescription: enables fine-grained control over template type checking
+type: capability
+tags: vue-directive, vue-ignore, vue-expect-error, vue-skip, template, type-checking
+---
+
+# Vue Template Directive Comments
+
+**Impact: HIGH** - enables fine-grained control over template type checking
+
+Vue Language Tools supports special directive comments to control type checking behavior in templates.
+
+## Available Directives
+
+### @vue-ignore
+
+Suppress type errors for the next line:
+
+```vue
+<template>
+  <!-- @vue-ignore -->
+  <Component :prop="valueWithTypeError" />
+</template>
+```
+
+### @vue-expect-error
+
+Assert that the next line should have a type error (useful for testing):
+
+```vue
+<template>
+  <!-- @vue-expect-error -->
+  <Component :invalid-prop="value" />
+</template>
+```
+
+### @vue-skip
+
+Skip type checking for an entire block:
+
+```vue
+<template>
+  <!-- @vue-skip -->
+  <div>
+    <!-- Everything in here is not type-checked -->
+    <LegacyComponent :any="props" :go="here" />
+  </div>
+</template>
+```
+
+### @vue-generic
+
+Declare template-level generic types:
+
+```vue
+<template>
+  <!-- @vue-generic {T extends string} -->
+  <GenericList :items="items as T[]" />
+</template>
+```
+
+## Use Cases
+
+- Migrating legacy components with incomplete types
+- Working with third-party components that have incorrect type definitions
+- Temporarily suppressing errors during refactoring
+- Testing that certain patterns produce expected type errors
+
+## Reference
+
+- [Vue Language Tools Wiki - Directive Comments](https://github.com/vuejs/language-tools/wiki/Directive-Comments)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/vue-router-typed-params.md

@@ -0,0 +1,81 @@
+---
+title: Vue Router useRoute Params Union Type Narrowing
+impact: MEDIUM
+impactDescription: fixes "Property does not exist" errors with typed route params
+type: capability
+tags: vue-router, useRoute, unplugin-vue-router, typed-routes, params
+---
+
+# Vue Router useRoute Params Union Type Narrowing
+
+**Impact: MEDIUM** - fixes "Property does not exist" errors with typed route params
+
+With `unplugin-vue-router` typed routes, `route.params` becomes a union of ALL page param types. TypeScript cannot narrow `Record<never, never> | { id: string }` properly, causing "Property 'id' does not exist" errors even on the correct page.
+
+## Symptoms
+
+- "Property 'id' does not exist on type 'RouteParams'"
+- `route.params.id` shows as `string | undefined` everywhere
+- Union type of all route params instead of specific route
+- Type narrowing with `if (route.name === 'users-id')` doesn't work
+
+## Root Cause
+
+`unplugin-vue-router` generates a union type of all possible route params. TypeScript's control flow analysis can't narrow this union based on route name checks.
+
+## Fix
+
+**Option 1: Pass route name to useRoute (recommended)**
+```typescript
+// pages/users/[id].vue
+import { useRoute } from 'vue-router/auto'
+
+// Specify the route path for proper typing
+const route = useRoute('/users/[id]')
+
+// Now properly typed as { id: string }
+console.log(route.params.id)  // string, not string | undefined
+```
+
+**Option 2: Type assertion with specific route**
+```typescript
+import { useRoute } from 'vue-router'
+import type { RouteLocationNormalized } from 'vue-router/auto-routes'
+
+const route = useRoute() as RouteLocationNormalized<'/users/[id]'>
+route.params.id  // Properly typed
+```
+
+**Option 3: Define route-specific param type**
+```typescript
+// In your page component
+interface UserRouteParams {
+  id: string
+}
+
+const route = useRoute()
+const { id } = route.params as UserRouteParams
+```
+
+## Required tsconfig Setting
+
+Ensure `moduleResolution: "bundler"` for unplugin-vue-router:
+```json
+{
+  "compilerOptions": {
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+## Caveat: Route Name Format
+
+The route name matches the file path pattern:
+- `pages/users/[id].vue` → `/users/[id]`
+- `pages/posts/[slug]/comments.vue` → `/posts/[slug]/comments`
+
+## Reference
+
+- [unplugin-vue-router#337](https://github.com/posva/unplugin-vue-router/issues/337)
+- [unplugin-vue-router#176](https://github.com/posva/unplugin-vue-router/discussions/176)
+- [unplugin-vue-router TypeScript docs](https://uvr.esm.is/guide/typescript.html)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/vue-tsc-strict-templates.md

@@ -0,0 +1,69 @@
+---
+title: Enable Strict Template Checking
+impact: HIGH
+impactDescription: catches undefined components and props at compile time
+type: capability
+tags: vue-tsc, typescript, type-checking, templates, vueCompilerOptions
+---
+
+# Enable Strict Template Checking
+
+**Impact: HIGH** - catches undefined components and props at compile time
+
+By default, vue-tsc does not report errors for undefined components in templates. Enable `strictTemplates` to catch these issues during type checking.
+
+## Which tsconfig?
+
+Add `vueCompilerOptions` to the tsconfig that includes Vue source files. In projects with multiple tsconfigs (like those created with `create-vue`), this is typically `tsconfig.app.json`, not the root `tsconfig.json` or `tsconfig.node.json`.
+
+**Incorrect (missing strict checking):**
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  }
+  // vueCompilerOptions not configured - undefined components won't error
+}
+```
+
+**Correct (strict template checking enabled):**
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  },
+  "vueCompilerOptions": {
+    "strictTemplates": true
+  }
+}
+```
+
+## Available Options
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `strictTemplates` | `false` | Enables all checkUnknown* options below |
+| `checkUnknownComponents` | `false` | Error on undefined/unregistered components |
+| `checkUnknownProps` | `false` | Error on props not declared in component definition |
+| `checkUnknownEvents` | `false` | Error on events not declared via `defineEmits` |
+| `checkUnknownDirectives` | `false` | Error on unregistered custom directives |
+
+## Granular Control
+
+If `strictTemplates` is too strict, enable individual checks:
+
+```json
+{
+  "vueCompilerOptions": {
+    "checkUnknownComponents": true,
+    "checkUnknownProps": false
+  }
+}
+```
+
+## Reference
+
+- [Vue Compiler Options](https://github.com/vuejs/language-tools/wiki/Vue-Compiler-Options)
+- [Vite Vue+TS Template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-vue-ts)

package/knowledge/skills/external/vue-skills/skills/vue-best-practices/rules/with-defaults-union-types.md

@@ -0,0 +1,102 @@
+---
+title: withDefaults Incorrect Default with Union Types
+impact: MEDIUM
+impactDescription: fixes incorrect default value behavior with union type props
+type: capability
+tags: withDefaults, defineProps, union-types, defaults, vue-3.5
+---
+
+# withDefaults Incorrect Default with Union Types
+
+**Impact: MEDIUM** - fixes spurious "Missing required prop" warning with union type props
+
+Using `withDefaults` with union types like `false | string` may produce a Vue runtime warning "Missing required prop" even when a default is provided. The runtime value IS applied correctly, but the warning can be confusing.
+
+## Symptoms
+
+- Vue warns "Missing required prop" despite default being set
+- Warning appears only with union types like `false | string`
+- TypeScript types are correct
+- Runtime value IS correct (the default is applied)
+
+## Problematic Pattern
+
+```typescript
+// This produces a spurious warning (but works at runtime)
+interface Props {
+  value: false | string  // Union type
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  value: 'default'  // Runtime value IS correct, but Vue warns about missing prop
+})
+```
+
+## Fix
+
+**Option 1: Use Reactive Props Destructure (Vue 3.5+)**
+```vue
+<script setup lang="ts">
+interface Props {
+  value: false | string
+}
+
+// Preferred in Vue 3.5+
+const { value = 'default' } = defineProps<Props>()
+</script>
+```
+
+**Option 2: Use runtime declaration**
+```vue
+<script setup lang="ts">
+const props = defineProps({
+  value: {
+    type: [Boolean, String] as PropType<false | string>,
+    default: 'default'
+  }
+})
+</script>
+```
+
+**Option 3: Split into separate props**
+```typescript
+interface Props {
+  enabled: boolean
+  customValue?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  enabled: false,
+  customValue: 'default'
+})
+```
+
+## Why Reactive Props Destructure Works
+
+Vue 3.5's Reactive Props Destructure handles default values at the destructuring level, bypassing the type inference issues with `withDefaults`.
+
+```typescript
+// The default is applied during destructuring, not type inference
+const { prop = 'default' } = defineProps<{ prop?: string }>()
+```
+
+## Enable Reactive Props Destructure
+
+This is enabled by default in Vue 3.5+. For older versions:
+```javascript
+// vite.config.js
+export default {
+  plugins: [
+    vue({
+      script: {
+        propsDestructure: true
+      }
+    })
+  ]
+}
+```
+
+## Reference
+
+- [vuejs/core#12897](https://github.com/vuejs/core/issues/12897)
+- [Reactive Props Destructure RFC](https://github.com/vuejs/rfcs/discussions/502)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueking/bkui-knowledge",
-  "version": "0.0.1-beta.6",
+  "version": "0.0.1-beta.8",
   "description": "蓝鲸前端知识库 MCP 服务 - 自动同步 skills，支持 Cursor/CodeBuddy",
   "main": "server/mcp-core.js",
   "bin": {

package/server/mcp-core.js

@@ -105,6 +105,22 @@ const TOOLS = [
       type: "object",
       properties: {}
     }
+  },
+
+  // L3 工具: 获取资源文件 (绕过 Cursor FetchMcpResource bug)
+  {
+    name: "get_resource",
+    description: "获取 skill 或 example 资源文件内容。URI 格式: skill://skillId/subDir/path 或 example://componentId/exampleName。用于获取布局模板、代码示例等资源。",
+    inputSchema: {
+      type: "object",
+      properties: {
+        uri: {
+          type: "string",
+          description: "资源 URI，如: skill://bkui-builder/assets/layouts/admin-layout-dark.vue, example://table/basic"
+        }
+      },
+      required: ["uri"]
+    }
   }
 ];
 
@@ -153,8 +169,9 @@ function buildResources() {
     if (manifest.skills && manifest.skills.items) {
       const skillsBasePath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path);
       manifest.skills.items.forEach(skill => {
-        const skillDir = path.join(skillsBasePath, skill.id);
-        ['scripts', 'references', 'assets'].forEach(subDir => {
+        // 使用 skill.path 推断目录（支持外部 skill）
+        const skillDir = path.join(skillsBasePath, path.dirname(skill.path));
+        ['scripts', 'references', 'assets', 'rules'].forEach(subDir => {
           const subDirPath = path.join(skillDir, subDir);
           if (fs.existsSync(subDirPath)) {
             scanSkillDir(subDirPath, '').forEach(filePath => {
@@ -275,7 +292,7 @@ const Handlers = {
 
     // 检查 skill 目录下的附属资源，生成 skill:// URIs
     const skillDir = path.dirname(filePath);
-    const subDirs = ['scripts', 'references', 'assets'];
+    const subDirs = ['scripts', 'references', 'assets', 'rules'];
     const availableResources = [];
 
     subDirs.forEach(dir => {
@@ -447,6 +464,17 @@ ${recommendedIds.map(id => {
     return { content: [{ type: "text", text: result }] };
   },
 
+  // L3: 获取资源文件 (绕过 Cursor FetchMcpResource bug)
+  async get_resource({ uri }) {
+    const result = await readResource(uri);
+    // readResource 返回 { content: string } 或 { contents: [{ text }] }
+    const text = result.content || (result.contents && result.contents[0] && result.contents[0].text);
+    if (!text) {
+      throw new Error(`Resource not found or empty: ${uri}`);
+    }
+    return { content: [{ type: "text", text }] };
+  },
+
   // Prompt 处理
   async get_prompt({ name }) {
     if (name === "BKUI-EXPERT") {
@@ -551,8 +579,8 @@ async function handleExampleResource(uri) {
     throw new Error(`Example '${exampleName}' not found for ${componentId}. Available: ${compExamples.examples.map(e => e.name).join(', ')}`);
   }
 
-  // 读取示例文件
-  const examplePath = path.join(ROOT_DIR, manifest.componentExamples.base_path, example.file);
+  // 读取示例文件 (base_path 相对于 KNOWLEDGE_DIR)
+  const examplePath = path.join(KNOWLEDGE_DIR, manifest.componentExamples.base_path, example.file);
   if (!fs.existsSync(examplePath)) {
     throw new Error(`Example file not found: ${example.file}`);
   }
@@ -573,8 +601,8 @@ async function handleSkillResource(uri) {
 
   const [, skillId, subDir, filePath] = match;
 
-  if (!['scripts', 'references', 'assets'].includes(subDir)) {
-    throw new Error(`Invalid skill subDir: ${subDir}. Must be scripts, references, or assets`);
+  if (!['scripts', 'references', 'assets', 'rules'].includes(subDir)) {
+    throw new Error(`Invalid skill subDir: ${subDir}. Must be scripts, references, assets, or rules`);
   }
 
   const manifest = loadManifest();
@@ -583,7 +611,9 @@ async function handleSkillResource(uri) {
     throw new Error(`Skill not found: ${skillId}`);
   }
 
-  const fullPath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path, skillId, subDir, filePath);
+  // 使用 skill.path 推断目录（支持外部 skill）
+  const skillDir = path.dirname(skill.path);
+  const fullPath = path.join(KNOWLEDGE_DIR, manifest.skills.base_path, skillDir, subDir, filePath);
   if (!fs.existsSync(fullPath)) {
     throw new Error(`Skill resource not found: ${subDir}/${filePath}`);
   }