蓝鲸前端知识库 (BKUI Knowledge Base)

本仓库致力于沉淀团队的技术资产，采用 渐进式披露架构，同时服务于人类开发者和 AI 助手。

如何贡献知识？ | 使用 Skill 模板

快速开始

只需添加 MCP 服务配置（通过 --ide 参数指定目标 IDE，不指定时默认使用 Cursor）：

Cursor（默认）

{
  "mcpServers": {
    "bkui-knowledge": {
      "command": "npx",
      "args": ["-y", "@blueking/bkui-knowledge", "${workspaceFolder}"]
    }
  }
}

CodeBuddy

在 CodeBuddy 设置 > MCP 标签页中添加：

{
  "bkui-knowledge": {
    "command": "npx",
    "args": ["-y", "@blueking/bkui-knowledge", "--ide=codebuddy"]
  }
}

Claude Code

Claude Code 支持从 MCP initialize 请求自动获取项目路径，无需手动传入

在 Claude Code 的 MCP 配置文件（~/.claude/.claude.json 或项目根目录 .mcp.json）中添加：

{
  "mcpServers": {
    "bkui-knowledge": {
      "command": "npx",
      "args": ["-y", "@blueking/bkui-knowledge", "--ide=claude-code"]
    }
  }
}

全局模式（推荐）

使用 --global 参数，skills 会安装到全局目录（~/.cursor/skills/），所有项目共享：

{
  "mcpServers": {
    "bkui-knowledge": {
      "command": "npx",
      "args": ["-y", "@blueking/bkui-knowledge", "--global"]
    }
  }
}

| 模式 | Skills 目录 | 配置文件位置 | 适用场景 | | --- | --- | --- | --- | | 全局模式 (--global) | ~/.cursor/skills/ | ~/.cursor/.bkui-knowledge.json | 多项目共享，统一管理 | | 项目模式 (默认) | 项目/.cursor/skills/ | 项目/.bkui-knowledge.json | 项目隔离，独立配置 |

本地开发

• 必须传递项目路径，否则 skills 无法同步到正确位置

• 使用 CodeBuddy 或者 Claude Code 本地开发时，无需 "${workspaceFolder}" 参数

{
  "mcpServers": {
    "bkui-knowledge": {
      "command": "node",
      "args": [
        "/path/to/bkui-knowledge/bin/bkui-knowledge.js",
        "${workspaceFolder}"
      ]
    }
  }
}

本地开发使用全局模式：

{
  "mcpServers": {
    "bkui-knowledge": {
      "command": "node",
      "args": [
        "/path/to/bkui-knowledge/bin/bkui-knowledge.js",
        "--global"
      ]
    }
  }
}

命令行参数

| 参数 | 说明 | 默认值 | | --- | --- | --- | | --ide=<ide> | 指定目标 IDE (cursor/codebuddy/claude-code) | cursor | | --global | 全局模式，skills 安装到 ~/.cursor/skills/（所有项目共享） | - | | --sync-skills=<bool> | 是否同步 skills 到项目 (true/false) | true | | --no-sync-skills | 禁用 skills 同步（等价于 --sync-skills=false） | - |

禁用自动同步示例：

{
  "mcpServers": {
    "bkui-knowledge": {
      "command": "npx",
      "args": ["-y", "@blueking/bkui-knowledge", "--no-sync-skills", "${workspaceFolder}"]
    }
  }
}

禁用自动同步后，可通过 sync_core_skills 工具手动触发同步

项目级配置文件

首次同步时会在项目根目录自动创建 .bkui-knowledge.json：

{
  "version": "0.0.1-beta.19",
  "defaultVueVersion": "vue3",
  "coreSkills": ["bkui-quick-start", "bkui-builder", "bkui-cheatsheet"],
  "installedSkills": []
}

| 字段 | 类型 | 说明 | 默认值 | | --- | --- | --- | --- | | version | string | 已同步的版本号（自动管理，勿手动修改） | - | | defaultVueVersion | string | 默认 Vue 版本: vue2 | vue3 | vue3 | | coreSkills | array | 核心 skills 列表（置空则不同步） | 预设列表 | | installedSkills | array | 已安装的可选 skills | [] |

💡 禁用 skills 同步：将 coreSkills 和 installedSkills 都设为空数组，或使用 --no-sync-skills 参数

特性：

• ✅ 支持 Cursor、CodeBuddy 和 Claude Code 三种 IDE
• ✅ 支持全局模式（--global），所有项目共享 skills
• ✅ 首次启动自动同步推荐 skills
• ✅ 自动生成规则文件（自动注入 AI 上下文）
• ✅ 自动检测版本更新，增量同步
• ✅ 零 Token 消耗（skills 不经过 AI 上下文）
• ✅ 离线可用（skills 已在本地）

配置完成后，直接在对话中使用！

Skills 自动同步

MCP 服务启动时，skills 会自动同步：

1. 首次启动：自动同步推荐的 skills
2. 后续启动：检测版本差异，自动增量更新
3. 同步位置（根据 --global 和 --ide 参数）：

项目模式（默认）：

| IDE | Skills 目录 | | ------------- | -------------------- | | Cursor (默认) | 项目/.cursor/skills/ | | CodeBuddy | 项目/.codebuddy/skills/ | | Claude Code | 项目/.claude/skills/ |

全局模式（--global）：

| IDE | Skills 目录 | | ------------- | -------------------- | | Cursor (默认) | ~/.cursor/skills/ | | CodeBuddy | ~/.codebuddy/skills/ | | Claude Code | ~/.claude/skills/ |

4. 版本信息：
   • 项目模式：存储在 项目/.bkui-knowledge.json
   • 全局模式：存储在 ~/.cursor/.bkui-knowledge.json

更新机制：

• skills 内置在 npm 包中
• 更新时：修改代码 → npm publish 发布新版本
• 用户使用 npx -y 会自动拉取最新版本

手动同步：

如果使用 --no-sync-skills 禁用了自动同步，可通过以下方式手动同步：

用户: 请帮我同步核心 skills
AI: [调用 sync_core_skills 工具]

💡 默认情况下无需任何手动操作，skills 自动同步，零 Token 消耗

可选 Skills

MCP 服务启动时只会自动同步核心 Skills（6 个），还有 20+ 个可选 Skills 可供按需安装。

核心 Skills（自动安装）

| ID | 名称 | 场景 | | --- | --- | --- | | bkui-quick-start | 入口指南 | 首次使用 | | bkui-builder | 设计稿还原专家 | UI 开发 | | api-standard | 统一网络请求 | HTTP 封装 | | pinia-setup | 全局状态管理 | Pinia | | bkui-cheatsheet | BKUI 组件速查 | 快速参考 | | vue-best-practices | Vue 3 开发最佳实践 | TypeScript/Volar |

可选 Skills（按需安装）

可选 Skills 分为三类：

| 分类 | 包含 | 示例 | | --- | --- | --- | | 🔧 工程化 | 12 个 | vite-migration、virtual-list、bundle-optimization... | | 🧪 质量保障 | 3 个 | unit-testing、code-review、chat-x-unit-test | | 🔒 安全审计 | 5 个 | js-security-check、nodejs-security-check、bk-security-redlines... |

安装可选 Skills

方式一：使用 SELECT-SKILLS 命令（推荐）

在对话中输入：

/bkui-knowledge/SELECT-SKILLS

AI 会展示可选 Skills 列表，输入编号即可安装：

请输入要安装的 Skills 编号（用逗号分隔，如 1, 5, 8），输入 all 安装全部，输入 skip 跳过

用户: 1, 7, 8

方式二：直接调用工具

用户: 调用 list_optional_skills 查看可选 skills
用户: 调用 add_skill 安装 unit-testing 和 code-review

相关工具

| 工具 | 作用 | | --- | --- | | list_optional_skills | 列出所有可选 Skills | | add_skill | 安装指定的 Skills | | install_selected_skills | 解析编号并安装（配合 SELECT-SKILLS 使用） |

使用方式

Vue3 推荐：@bkui-knowledge/BKUI-EXPERT 或 /bkui-knowledge/BKUI-EXPERT (设计稿还原 / 写组件)

[粘贴设计稿图片 或 描述需求]
/bkui-knowledge/BKUI-EXPERT

Vue2 推荐：@bkui-knowledge/BKUI-EXPERT-VUE2 或 /bkui-knowledge/BKUI-EXPERT-VUE2 (设计稿还原 / 写组件)

[粘贴设计稿图片 或 描述需求]
/bkui-knowledge/BKUI-EXPERT-VUE2

效果：

1. 自动加载 bkui-builder 规则
2. 自动获取相关组件的 API
3. 按规范生成代码
4. 询问是否需要查看组件示例

@ 方式 (Prompts)

| 命令 | 作用 | 推荐场景 | | -------------------------------------------------------------- | -------------------------------------- | ----------------------- | | @bkui-knowledge/BKUI-EXPERT or /bkui-knowledge/BKUI-EXPERT | 设计稿还原专家模式(Vue3组件库)，引导 AI 按步骤执行 | 写组件 / 还原设计稿 | | @bkui-knowledge/BKUI-EXPERT-VUE2 or /bkui-knowledge/BKUI-EXPERT-VUE2 | 设计稿还原专家模式(Vue2组件库) | 写组件 / 还原设计稿 | | /bkui-knowledge/SELECT-SKILLS | 选择并安装可选 Skills | 扩展功能 |

直接对话 + 明确指定

用户: 使用 BKUI-Knowledge 获取 bk-table 的 API，帮我写一个表格页面

手动调用工具

用户: 调用 get_component_api 获取 navigation 组件的 API
用户: 用 batch_load 获取 navigation、menu、table 的 API

可用资源

工具 (Tools)

| 工具 | 作用 | 层级 | | --------------------- | -------------------------------- | ----- | | get_knowledge_index | 获取完整索引 | L0 | | get_skill | 获取技能文档 (Markdown + assets) | L1 | | get_component_api | 获取 Vue3 组件 API (JSON) | L2 | | get_component_api_vue2 | 获取 Vue2 组件 API (JSON) | L2 | | batch_load | 批量加载多个资源 | L1+L2 | | batch_load_vue2 | 批量加载 vue2 组件库多个组件 | L2 | | sync_skills | 查看 skills 同步状态和信息 | - | | sync_core_skills | 手动同步核心 Skills（禁用自动同步时使用） | - | | list_optional_skills | 列出所有可选 Skills | - | | add_skill | 安装指定的可选 Skills | - | | install_selected_skills | 解析编号并安装 Skills | - |

组件示例 (Resources) - L3 层

获取 get_component_api 后，会提示可用示例。用户确认后才加载：

AI: 已获取 bk-table 的 API 文档。是否需要查看示例代码？
    可用示例:
    - basic (基础表格 + 分页)
    - selection (可选择表格)
    - filter (筛选表格)

用户: 给我 basic 示例

AI: [获取 resource: example://table/basic]
    这是示例代码...

优势: 默认不消耗 token，用户控制是否加载。

技能 (Skills)

| ID | 名称 | 场景 | | ----------------------- | -------------------------- | ------------------------ | | bkui-builder | 设计稿还原专家 | UI 开发 | | api-standard | 统一网络请求 | HTTP 封装 | | pinia-setup | 全局状态管理 | Pinia | | permission-directive | 前端权限控制 (IAM) | 权限管理 | | vue-composables | Vue 3 Composables 最佳实践 | 组合式函数 | | vite-migration | Webpack 到 Vite 迁移 | 构建工具 | | bundle-optimization | Vite 构建优化 | 性能 | | virtual-list | 长列表虚拟滚动 | 性能 | | unit-testing | 组件单元测试 | 质量 | | bkui-cheatsheet | BKUI 组件速查 | 快速参考 | | code-review | 代码评审专家 | 代码审查 | | js-security-check | JavaScript 安全审查 | 安全 | | nodejs-security-check | Node.js 安全审查 | 安全 | | vue-best-practices | Vue 3 开发最佳实践 (外部) | TypeScript/Volar/vue-tsc | | bk-skill-creator | Skill 创建指南 | 知识沉淀 | | bk-security-redlines | 蓝鲸代码安全三大红线 | 安全审查 | | web-security-guide | Web 安全漏洞学习指南 | OWASP 十大漏洞 |

页面模版 (在 bkui-builder 的 assets/ 中)

| 文件 | 描述 | | ------------------------------- | ------------------- | | layouts/admin-layout-left.vue | 左右布局 (管理后台) | | layouts/admin-layout-top.vue | 上下布局 (门户页) | | layouts/admin-layout-dark.vue | 暗色主题布局 | | pages/table-page.vue | 表格页 (CRUD) | | pages/dashboard-page.vue | 仪表盘 | | pages/detail-page.vue | 详情页 | | pages/wizard-form.vue | 分步表单 |

调用 get_skill({ skillId: 'bkui-builder' }) 时会自动列出可用模版

组件 API (58 个)

高优先级 (使用前必须查询): navigation, menu, table, form, dialog

全部组件: button, input, select, checkbox, radio, date-picker, time-picker, cascader, tag-input, slider, switcher, rate, color-picker, upload, transfer, search-select, pagination, tree, tag, badge, collapse, timeline, progress, image, tab, steps, process, breadcrumb, dropdown, sideslider, message, notify, loading, alert, popover, pop-confirm, info-box, exception, card, container, resize-layout, divider, link, affix, backtop, fixed-navbar, code-diff, swiper, animate-number, overflow-title, virtual-render, scrollbar, config-provider

已嵌入的核心规则

工具描述中已包含以下规则，AI 会自动遵守：

强制规范

• 组件库: bkui-vue (前缀 bk-)
• 语法: Vue 3 <script setup lang="ts">
• 样式: MagicBox 原子类 (mt10, mb20, flex-row)

常见错误 (必须避免)

❌ <bk-navigation :default-open-keys>  → ✅ default-open
❌ <bk-menu :default-open-keys>        → ✅ :opened-keys
❌ <bk-dialog v-model>                 → ✅ v-model:isShow

架构设计

┌─────────────────────────────────────────────────────────────┐
│  工具描述 (自动注入)                                          │
│  - 核心规范 + 常见错误 + 工作流程                              │
│  - Token: ~200                                               │
└─────────────────────────────────────────────────────────────┘
                              ↓ AI 按需调用
┌─────────────────────────────────────────────────────────────┐
│  L0: get_knowledge_index                                    │
│  - skills/patterns/apis 完整列表                             │
│  - Token: ~400                                              │
└─────────────────────────────────────────────────────────────┘
                              ↓ AI 按需调用
┌─────────────────────────────────────────────────────────────┐
│  L1/L2: get_skill / get_pattern / get_component_api         │
│  - 具体内容 (Markdown/Vue/JSON)                              │
│  - Token: ~500-1000/项                                       │
└─────────────────────────────────────────────────────────────┘
                              ↓ 用户确认后加载
┌─────────────────────────────────────────────────────────────┐
│  L3: example://component/name (MCP Resource)                │
│  - 组件完整示例代码                                           │
│  - Token: ~300-800/项 (仅用户确认后消耗)                       │
└─────────────────────────────────────────────────────────────┘

目录结构

bkui-knowledge/
├── bin/
│   └── bkui-knowledge.js      ← CLI 入口 (自动同步 skills + MCP 服务)
│
├── server/
│   └── mcp-core.js            ← 核心逻辑 (Tools/Prompts/Resources)
│
├── knowledge/                 ← 知识层 (核心)
│   ├── manifest.json          ← 统一索引
│   ├── skills/                ← L1: 技能文档 (13 个)
│   │   ├── bkui-builder/
│   │   │   ├── SKILL.md       ← 必须：核心指令
│   │   │   ├── scripts/       ← 可选：工具脚本
│   │   │   ├── references/    ← 可选：参考文档
│   │   │   └── assets/        ← 可选：模版素材
│   │   └── ...
│   ├── component-apis/        ← L2: 组件 API (58 个 JSON)
│   └── examples/              ← L3: 组件示例 (150+ 个 Vue)
│
└── tests/                     ← 测试套件

外部技能 (External Skills)

本项目集成了社区优秀的 Agent Skills 作为外部依赖：

| 技能 | 来源 | 描述 | | -------------------- | ----------------------------------------------------- | --------------------------------------------------- | | vue-best-practices | hyf0/vue-skills | Vue 3 TypeScript/vue-tsc/Volar 最佳实践 (17 条规则) |

更新外部技能

# 使用脚本更新
./scripts/update-external-skills.sh

# 或手动更新
git submodule update --remote --merge

首次克隆项目

# 克隆时初始化子模块
git clone --recurse-submodules https://github.com/xxx/bkui-knowledge.git

# 或克隆后初始化
git submodule init
git submodule update

贡献知识

欢迎团队成员一起沉淀知识！所有贡献的内容都会自动遵循渐进式披露架构。

使用 bk-skill-creator（推荐）

在 Cursor 中直接让 AI 帮你创建 skill：

用户: 我想创建一个关于 [主题] 的 skill
AI: [自动加载 bk-skill-creator 技能，引导你完成创建流程]

或者显式调用：

用户: 调用 get_skill 获取 bk-skill-creator，然后帮我创建一个新的 skill

bk-skill-creator 会自动：

• 引导你使用正确的模板
• 确保 SKILL.md ≤ 2KB
• 提醒更新 manifest.json 和 README.md
• 执行验证脚本检查规范

手动创建

# 1. 使用模板创建新 Skill
cp -r knowledge/skills/.template knowledge/skills/your-skill-id

# 2. 编辑核心文档（保持 ≤ 2KB）
vim knowledge/skills/your-skill-id/SKILL.md

# 3. 添加详细内容到 references/
vim knowledge/skills/your-skill-id/references/advanced.md

# 4. 更新索引
vim knowledge/manifest.json

# 5. 验证规范
bash scripts/validate-skill.sh your-skill-id

重要原则

• ✅ SKILL.md 必须 ≤ 2KB（核心规则）
• ✅ 详细内容放 references/（按需加载）
• ✅ 代码资产放 assets/（用户确认后加载）

详细指南请查看：CONTRIBUTING.md

本地测试

重要：测试不需要启动服务器！

# 运行所有测试（推荐）
npm test

# 单独测试
npm run test:skills   # 验证知识库 Skills 是否符合规范
npm run test:server   # 测试 MCP 服务器功能

注意：

• npm test 是运行测试套件（自动完成），用于验证规范

详细说明见：tests/README.md

常见问题

Q: 如何查看所有可用资源？

A: 让 AI 调用 get_knowledge_index()，规则已自动注入到对应 IDE 的 rules 目录

Q: 设计稿还原效果不好？

A: 使用 @BKUI-EXPERT，它会引导 AI 按完整流程执行

Q: 知识库更新了怎么办？

A: 发布新版本 npm 包后，用户下次启动 IDE 时 npx -y 会自动拉取最新版本

Q: skills 没有同步成功？

A: 检查对应 IDE 的 skills 目录是否存在（Cursor: .cursor/skills/，CodeBuddy: .codebuddy/skills/，Claude Code: .claude/skills/），或查看 IDE 的 MCP 日志

Q: 如何禁用自动同步 skills？

A: 在 MCP 配置的 args 中添加 --no-sync-skills 或 --sync-skills=false 参数。禁用后可通过 AI 调用 sync_core_skills 工具手动同步

Q: 如何切换到其他 IDE？

A: 在 MCP 配置的 args 中添加 --ide=codebuddy 或 --ide=claude-code 参数

Q: 如何让 skills 在所有项目中共享？

A: 使用全局模式，在 MCP 配置的 args 中添加 --global 参数。Skills 会安装到 ~/.cursor/skills/，所有项目都能访问

Q: 全局模式和项目模式有什么区别？

A:

• 全局模式：Skills 安装到 ~/.cursor/skills/，所有项目共享同一份 skills
• 项目模式：Skills 安装到 项目/.cursor/skills/，每个项目独立管理

推荐使用全局模式，便于统一管理和节省磁盘空间

Token 消耗对比

| 方案 | 初始化 | 按需加载 | 总计 | | ----------------------- | ------- | -------- | --------------- | | 全量注入 | ~15,000 | 0 | ~15,000 | | 纯按需加载 | ~200 | ~3,000 | ~3,200 | | 渐进式披露 | ~200 | ~2,000 | ~2,200 ✅ | | npx 自动同步 skills | 0 | ~2,000 | ~2,000 ✅✅ |

💡 使用 npx 模式时，推荐的 skills 自动同步到本地，AI 无需读取内容，节省更多 token