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

package/README.md

@@ -172,6 +172,7 @@ AI: [获取 resource: example://table/basic]
 | `code-review` | 代码评审专家 | 代码审查 |
 | `js-security-check` | JavaScript 安全审查 | 安全 |
 | `nodejs-security-check` | Node.js 安全审查 | 安全 |
+| `vue-best-practices` | Vue 3 开发最佳实践 (外部) | TypeScript/Volar/vue-tsc |
 
 ### 页面模版 (在 bkui-builder 的 assets/ 中)
 
@@ -270,6 +271,37 @@ bkui-knowledge/
 
 ---
 
+## 外部技能 (External Skills)
+
+本项目集成了社区优秀的 Agent Skills 作为外部依赖：
+
+| 技能 | 来源 | 描述 |
+|------|------|------|
+| `vue-best-practices` | [hyf0/vue-skills](https://github.com/hyf0/vue-skills) | Vue 3 TypeScript/vue-tsc/Volar 最佳实践 (17 条规则) |
+
+### 更新外部技能
+
+```bash
+# 使用脚本更新
+./scripts/update-external-skills.sh
+
+# 或手动更新
+git submodule update --remote --merge
+```
+
+### 首次克隆项目
+
+```bash
+# 克隆时初始化子模块
+git clone --recurse-submodules https://github.com/xxx/bkui-knowledge.git
+
+# 或克隆后初始化
+git submodule init
+git submodule update
+```
+
+---
+
 ## 贡献知识
 
 欢迎团队成员一起沉淀知识！所有贡献的内容都会自动遵循渐进式披露架构。

package/bin/bkui-knowledge.js

@@ -138,6 +138,58 @@ function needsSync(projectRoot, currentVersion, ideConfig) {
   return localVersion !== currentVersion;
 }
 
+/**
+ * 递归扫描目录，返回相对路径列表
+ * @param {string} dirPath - 目录路径
+ * @param {string} relativePath - 相对路径前缀
+ * @returns {string[]} 文件相对路径列表
+ */
+function scanSkillDir(dirPath, relativePath) {
+  const results = [];
+  try {
+    const items = fs.readdirSync(dirPath);
+    for (const item of items) {
+      const fullPath = path.join(dirPath, item);
+      const relPath = relativePath ? `${relativePath}/${item}` : item;
+      const stat = fs.statSync(fullPath);
+      if (stat.isDirectory()) {
+        results.push(...scanSkillDir(fullPath, relPath));
+      } else {
+        results.push(relPath);
+      }
+    }
+  } catch (e) {
+    // 忽略错误
+  }
+  return results;
+}
+
+/**
+ * 生成 skill 的可用资源列表
+ * @param {string} skillDir - skill 目录路径
+ * @param {string} skillId - skill ID
+ * @returns {string} 资源列表 Markdown
+ */
+function generateResourcesList(skillDir, skillId) {
+  const subDirs = ['scripts', 'references', 'assets', 'rules'];
+  const resources = [];
+
+  subDirs.forEach(dir => {
+    const dirPath = path.join(skillDir, dir);
+    if (fs.existsSync(dirPath)) {
+      const files = scanSkillDir(dirPath, '');
+      files.forEach(file => {
+        resources.push(`- \`skill://${skillId}/${dir}/${file}\``);
+      });
+    }
+  });
+
+  if (resources.length > 0) {
+    return `\n\n---\n## 📦 可用资源\n\n${resources.join('\n')}\n\n> 根据 SKILL.md 中的 IF-THEN 规则判断是否需要加载\n`;
+  }
+  return '';
+}
+
 /**
  * 同步 skills 到用户项目（从 npm 包内置的 knowledge 目录）
  * @param {string} projectRoot - 项目根目录
@@ -178,7 +230,14 @@ function syncSkills(projectRoot, ideConfig) {
       const skillFilePath = path.join(PKG_ROOT, 'knowledge', manifest.skills.base_path, skill.path);
       if (!fs.existsSync(skillFilePath)) continue;
 
-      const content = fs.readFileSync(skillFilePath, 'utf-8');
+      // 读取原始内容
+      let content = fs.readFileSync(skillFilePath, 'utf-8');
+
+      // 生成并附加资源列表（与 mcp-core.js 的 get_skill 逻辑一致）
+      const skillDir = path.dirname(skillFilePath);
+      const resourcesList = generateResourcesList(skillDir, skillId);
+      content += resourcesList;
+
       fs.writeFileSync(path.join(skillsDir, `${skillId}.md`), content, 'utf-8');
 
       log(`  ✓ ${skillId}`);

package/knowledge/manifest.json

@@ -114,6 +114,15 @@
         "category": "engineering",
         "path": "bkui-quick-start/SKILL.md",
         "tags": ["bkui", "规范", "索引", "入门"]
+      },
+      {
+        "id": "vue-best-practices",
+        "name": "Vue 3 开发最佳实践",
+        "category": "engineering",
+        "path": "external/vue-skills/skills/vue-best-practices/SKILL.md",
+        "tags": ["vue3", "typescript", "vue-tsc", "volar", "vite", "pinia"],
+        "external": true,
+        "source": "https://github.com/hyf0/vue-skills"
       }
     ]
   },
@@ -670,5 +679,5 @@
     ]
   },
 
-  "recommendedSkills": ["bkui-quick-start", "bkui-builder", "bkui-cheatsheet", "code-review", "js-security-check"]
+  "recommendedSkills": ["bkui-quick-start", "bkui-builder", "bkui-cheatsheet", "vue-best-practices", "code-review", "js-security-check"]
 }

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

@@ -1,6 +1,15 @@
+---
+id: bkui-quick-start
+name: BKUI 快速入门
+category: engineering
+description: 蓝鲸前端知识库入口指南，包含规范、索引和工作流程
+tags: [bkui, 规范, 索引, 入门, vue3]
+updated_at: 2026-01-23
+---
+
 # BKUI 快速入门
 
-> 蓝鲸前端知识库入口指南，包含规范、索引和工作流程。
+> 蓝鲸前端知识库入口指南。
 
 ## 强制规范
 
@@ -17,31 +26,7 @@
 | bk-menu | `:default-open-keys` | `:opened-keys` |
 | bk-dialog | `v-model` | `v-model:isShow` |
 
-## 可用 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 | 长列表虚拟滚动 | 性能优化方案 |
-| unit-testing | 组件单元测试 | Vitest 测试模板 |
-| code-review | 代码评审专家 | 评审规范和检查清单 |
-| js-security-check | JavaScript 安全审查 | 前端安全检查 |
-| nodejs-security-check | Node.js 安全审查 | 后端安全检查 |
-
-## Component APIs
-
-通过 `get_component_api({ componentName: 'xxx' })` 获取文档：
-
-### 高优先级 (必须先查询)
+## 高优先级组件
 
 - `bk-navigation` - 布局组件，易出错
 - `bk-menu` - 与 navigation 配合
@@ -49,20 +34,19 @@
 - `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
-
 ## 工作流程
 
 1. **分析需求** → 确定需要哪些资源
-2. **使用布局组件?** → `get_component_api({ componentName: 'navigation' })`
-3. **需要模板代码?** → `get_skill({ skillId: 'bkui-builder' })`
-4. **批量获取?** → `batch_load({ skillIds: [...], componentNames: [...] })`
+2. **布局组件** → `get_component_api({ componentName: 'navigation' })`
+3. **模板代码** → `get_skill({ skillId: 'bkui-builder' })`
 
 ## 触发条件
 
-遇到以下关键词时，应主动使用本知识库：
-- bk-navigation, bk-menu, bk-table, bk-form, bk-dialog 等 bk- 前缀组件
-- bkui-vue, 蓝鲸组件库, MagicBox, 蓝鲸前端
-- 设计稿还原, 管理后台页面
+遇到 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)