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

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

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

---

快速开始

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

$3

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

$3

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

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

$3

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

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

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

$3

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

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

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

$3

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

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

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

本地开发使用全局模式：

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

$3

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

禁用自动同步示例：

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

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

$3

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

`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 可供按需安装。

$3

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

$3

可选 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... |

$3

方式一：使用 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
`

$3

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

---

使用方式

$3

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


$3

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

效果：

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

$3

| 命令 | 作用 | 推荐场景 |
| -------------------------------------------------------------- | -------------------------------------- | ----------------------- |
| @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 | 扩展功能 |

$3

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

$3

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

---

可用资源

$3

| 工具 | 作用 | 层级 |
| --------------------- | -------------------------------- | ----- |
| 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 | - |

$3

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

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

用户: 给我 basic 示例

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

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

$3

| 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 十大漏洞 |

$3

| 文件 | 描述 |
| ------------------------------- | ------------------- |
| 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' }) 时会自动列出可用模版

$3

高优先级 (使用前必须查询): 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 会自动遵守：

$3

- 组件库: bkui-vue (前缀 bk-)
- 语法: Vue 3