@blueking/bkui-knowledge

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

Codex

在 Codex 的 MCP 配置中添加：

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

全局模式（推荐）

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

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

本地开发

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

• 使用 CodeBuddy、Claude Code 或 Codex 本地开发时，无需 "${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"
      ]
    }
  }
}

命令行参数

禁用自动同步示例：

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

禁用自动同步后，可通过 manage_skills({ action: "sync_core" }) 手动触发同步

项目级配置文件

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

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

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

特性：

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

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

Skills 自动同步

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

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

项目模式（默认）：

全局模式（--global）：

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

更新机制：

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

手动同步：

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

用户: 请帮我同步核心 skills
AI: [调用 manage_skills({ action: "sync_core" }) 工具]

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

可选 Skills

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

核心 Skills（自动安装）

可选 Skills（按需安装）

可选 Skills 分为三类：

安装可选 Skills

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

在对话中输入：

/bkui-knowledge/SELECT-SKILLS

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

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

用户: 1, 7, 8

方式二：直接调用工具

用户: 调用 manage_skills({ action: "list_optional" }) 查看可选 skills
用户: 调用 manage_skills({ action: "add", skillIds: ["unit-testing", "code-review"] }) 安装可选 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. 自动生成可预览的独立 HTML 文件（PM/设计师双击即可在浏览器查看效果）；生成后会询问是否需要本地 HTTP 服务预览命令（不默认启动）
5. 询问是否需要查看组件示例

仅 HTML 预览（不走完整还原流程）

适合「只要快速出可点预览、不写完整 .vue 业务代码」时使用：

[描述页面：表格/表单/仪表盘等]
/bkui-knowledge/BKUI-DEMO

生成 demos/<name>-preview.html 后，同样会询问是否需要本地服务命令（默认不启动）。

@ 方式 (Prompts)

直接对话 + 明确指定

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

手动调用工具

用户: 用 bkui-vue CLI 获取 navigation 组件的 API
用户: CLI 暂不可用时，调用 get_component_api 兜底获取 navigation 组件的 API

默认情况下，索引、组件 API 和批量加载工具会返回 compact 摘要，减少上下文占用。需要完整内容时显式传入 compact: false：

get_knowledge_index({ category: "all", compact: false })
get_component_api({ componentName: "table", compact: false })
batch_load({ componentNames: ["table", "dialog"], compact: false, maxChars: 12000 })

可用资源

工具 (Tools)

组件示例 (Resources) - L3 层

Vue3 示例优先用 bkui-vue demo / bkui-vue snippet 查询。使用 get_component_api 兜底后，会提示可用示例；用户确认后才加载：

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

用户: 给我 basic 示例

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

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

技能 (Skills)

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

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

即时预览 (HTML Preview)

AI 生成 .vue 代码后，会同时输出一个独立 HTML 预览文件到项目 demos/ 目录。

工作原理： 通过 jsDelivr CDN 加载 Vue 3 + bkui-vue UMD 构建，在浏览器中渲染真实组件，无需任何本地构建环境。

使用方式：

1. AI 生成代码时自动输出 demos/xxx-preview.html（或使用 /bkui-knowledge/BKUI-DEMO 仅生成预览）
2. 双击文件在浏览器中打开，即可看到高保真页面效果
3. 支持完整交互（Tab 切换、弹窗、表单、表格分页等）
4. 可直接通过微信/邮件发给团队成员查看
5. 本地 HTTP 服务（可选）：生成后 AI 会询问是否给出预览命令；同意后再在终端执行（不默认自动启动）。示例（需 Node.js）：在项目根目录 npx --yes serve demos -l 8765，浏览器访问 http://localhost:8765/xxx-preview.html（serve 以 demos 为根目录）

适用场景： 产品经理和设计师快速验证需求、评审会演示、设计方案对比

组件 API (58 个)

Vue3 优先使用 @bkui-vue/cli 查询；MCP get_component_api 仅作为 CLI 不可用时的兜底。高优先级: 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；Vue3 API 优先 CLI，MCP 兜底)   │
│  - 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: 技能文档（数量以 manifest.json 为准）
│   │   ├── bkui-builder/
│   │   │   ├── SKILL.md       ← 必须：核心指令
│   │   │   ├── scripts/       ← 可选：工具脚本
│   │   │   ├── references/    ← 可选：参考文档
│   │   │   └── assets/        ← 可选：模版素材
│   │   └── ...
│   ├── component-apis/        ← L2: 组件 API (58 个 JSON)
│   └── examples/              ← L3: 组件示例 (150+ 个 Vue)
│
└── tests/                     ← 测试套件

外部技能 (External Skills)

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

更新外部技能

# 使用脚本更新
./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/，Codex: .codex/skills/），或查看 IDE 的 MCP 日志

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

A: 在 MCP 配置的 args 中添加 --no-sync-skills 或 --sync-skills=false 参数。禁用后可通过 AI 调用 manage_skills({ action: "sync_core" }) 手动同步

Q: 如何切换到其他 IDE？

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

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

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

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

A:

• 全局模式：Skills 安装到对应 IDE 的全局 skills 目录，所有项目共享同一份 skills
• 项目模式：Skills 安装到对应 IDE 的项目 skills 目录，每个项目独立管理

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

Token 消耗对比

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