蓝鲸前端知识库 (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"]
    }
  }
}

本地开发

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

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

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

特性：

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

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

Skills 自动同步

MCP 服务启动时，skills 会自动同步到用户项目：

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

| IDE | Skills | Version | | ------------- | -------------------- | ------------------------------------ | | Cursor (默认) | .cursor/skills/ | .cursor/.bkui-knowledge-version | | CodeBuddy | .codebuddy/skills/ | .codebuddy/.bkui-knowledge-version | | Claude Code | .claude/skills/ | .claude/.bkui-knowledge-version |

更新机制：

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

💡 无需任何手动操作，skills 自动同步，零 Token 消耗

使用方式

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 获取 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 同步状态和信息 | - |

组件示例 (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: 如何切换到其他 IDE？

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

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