@blueking/bkui-knowledge 0.0.1-beta.1 → 0.0.1-beta.11

package/README.md

@@ -10,20 +10,57 @@
 
 只需添加 MCP 服务配置：
 
+### Cursor（默认）
+
 ```json
 {
   "mcpServers": {
     "bkui-knowledge": {
       "command": "npx",
-      "args": ["-y", "@blueking/bkui-knowledge"]
+      "args": ["-y", "@blueking/bkui-knowledge", "${workspaceFolder}"]
+    }
+  }
+}
+```
+
+### CodeBuddy
+
+在 CodeBuddy 设置 > MCP 标签页中添加：
+
+```json
+{
+  "bkui-knowledge": {
+    "command": "npx",
+    "args": ["-y", "@blueking/bkui-knowledge", "--ide=codebuddy"]
+  }
+}
+```
+
+> 💡 通过 `--ide` 参数指定目标 IDE，不指定时默认使用 Cursor
+
+### 本地开发
+
+```json
+{
+  "mcpServers": {
+    "bkui-knowledge": {
+      "command": "node",
+      "args": [
+        "/path/to/bkui-knowledge/bin/bkui-knowledge.js",
+        "${workspaceFolder}"
+      ]
     }
   }
 }
 ```
 
+> ⚠️ 必须传递项目路径，否则 skills 无法同步到正确位置
+
 **特性：**
-- ✅ 首次启动自动同步推荐 skills 到 `.cursor/skills/`
-- ✅ 自动生成 `.cursor/rules/bkui.mdc`（规则自动注入 AI 上下文）
+
+- ✅ 支持 Cursor 和 CodeBuddy 两种 IDE
+- ✅ 首次启动自动同步推荐 skills
+- ✅ 自动生成规则文件（自动注入 AI 上下文）
 - ✅ 自动检测版本更新，增量同步
 - ✅ 零 Token 消耗（skills 不经过 AI 上下文）
 - ✅ 离线可用（skills 已在本地）
@@ -36,15 +73,17 @@
 
 MCP 服务启动时，skills 会自动同步到用户项目：
 
-1. **首次启动**：自动同步推荐的 skills 到 `.cursor/skills/`
+1. **首次启动**：自动同步推荐的 skills
 2. **后续启动**：检测版本差异，自动增量更新
-3. **同步位置**：
-   - `.cursor/skills/*.md` - 技能文档
-   - `.cursor/commands/*.md` - 斜杠指令（可通过 `/skill-id` 调用）
-   - `.cursor/rules/bkui.mdc` - 规则文件（自动注入 AI 上下文）
-   - `.cursor/.bkui-knowledge-version` - 版本标记
+3. **同步位置**（根据 `--ide` 参数）：
+
+| IDE           | Skills               | Version                              |
+| ------------- | -------------------- | ------------------------------------ |
+| Cursor (默认) | `.cursor/skills/`    | `.cursor/.bkui-knowledge-version`    |
+| CodeBuddy     | `.codebuddy/skills/` | `.codebuddy/.bkui-knowledge-version` |
 
 **更新机制**：
+
 - skills 内置在 npm 包中
 - 更新时：修改代码 → `npm publish` 发布新版本
 - 用户使用 `npx -y` 会自动拉取最新版本
@@ -55,14 +94,15 @@ MCP 服务启动时，skills 会自动同步到用户项目：
 
 ## 使用方式
 
-### 推荐：@BKUI-EXPERT (设计稿还原 / 写组件)
+### 推荐：@bkui-knowledge/BKUI-EXPERT 或 /bkui-knowledge/BKUI-EXPERT (设计稿还原 / 写组件)
 
 ```
 [粘贴设计稿图片 或 描述需求]
-/BKUI-Knowledge/BKUI-EXPERT
+/bkui-knowledge/BKUI-EXPERT
 ```
 
 **效果：**
+
 1. 自动加载 `bkui-builder` 规则
 2. 自动获取相关组件的 API
 3. 按规范生成代码
@@ -70,9 +110,9 @@ MCP 服务启动时，skills 会自动同步到用户项目：
 
 ### @ 方式 (Prompts)
 
-| 命令 | 作用 | 推荐场景 |
-|------|------|----------|
-| `@BKUI-EXPERT` | 设计稿还原专家模式，引导 AI 按步骤执行 | **写组件 / 还原设计稿** |
+| 命令                                                           | 作用                                   | 推荐场景                |
+| -------------------------------------------------------------- | -------------------------------------- | ----------------------- |
+| `@bkui-knowledge/BKUI-EXPERT` or `/bkui-knowledge/BKUI-EXPERT` | 设计稿还原专家模式，引导 AI 按步骤执行 | **写组件 / 还原设计稿** |
 
 ### 直接对话 + 明确指定
 
@@ -93,13 +133,13 @@ MCP 服务启动时，skills 会自动同步到用户项目：
 
 ### 工具 (Tools)
 
-| 工具 | 作用 | 层级 |
-|------|------|------|
-| `get_knowledge_index` | 获取完整索引 | L0 |
-| `get_skill` | 获取技能文档 (Markdown + assets) | L1 |
-| `get_component_api` | 获取组件 API (JSON) | L2 |
-| `batch_load` | 批量加载多个资源 | L1+L2 |
-| `sync_skills` | 查看 skills 同步状态和信息 | - |
+| 工具                  | 作用                             | 层级  |
+| --------------------- | -------------------------------- | ----- |
+| `get_knowledge_index` | 获取完整索引                     | L0    |
+| `get_skill`           | 获取技能文档 (Markdown + assets) | L1    |
+| `get_component_api`   | 获取组件 API (JSON)              | L2    |
+| `batch_load`          | 批量加载多个资源                 | L1+L2 |
+| `sync_skills`         | 查看 skills 同步状态和信息       | -     |
 
 ### 组件示例 (Resources) - L3 层
 
@@ -122,33 +162,37 @@ AI: [获取 resource: example://table/basic]
 
 ### 技能 (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 安全审查 | 安全 |
+| 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` | 分步表单 |
+| `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' })` 时会自动列出可用模版
 
@@ -165,11 +209,13 @@ AI: [获取 resource: example://table/basic]
 工具描述中已包含以下规则，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
@@ -235,17 +281,70 @@ 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
+```
+
+---
+
 ## 贡献知识
 
 欢迎团队成员一起沉淀知识！所有贡献的内容都会自动遵循渐进式披露架构。
 
-### 快速开始
+### 使用 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
+- 执行验证脚本检查规范
+
+### 手动创建
 
 ```bash
 # 1. 使用模板创建新 Skill
 cp -r knowledge/skills/.template knowledge/skills/your-skill-id
 
-# 2. 编辑核心文档（保持 ≤ 3KB）
+# 2. 编辑核心文档（保持 ≤ 2KB）
 vim knowledge/skills/your-skill-id/SKILL.md
 
 # 3. 添加详细内容到 references/
@@ -254,13 +353,13 @@ vim knowledge/skills/your-skill-id/references/advanced.md
 # 4. 更新索引
 vim knowledge/manifest.json
 
-# 5. 验证大小
-wc -c knowledge/skills/your-skill-id/SKILL.md
+# 5. 验证规范
+bash scripts/validate-skill.sh your-skill-id
 ```
 
 ### 重要原则
 
-- ✅ **SKILL.md 必须 ≤ 3KB**（核心规则）
+- ✅ **SKILL.md 必须 ≤ 2KB**（核心规则）
 - ✅ **详细内容放 references/**（按需加载）
 - ✅ **代码资产放 assets/**（用户确认后加载）
 
@@ -282,6 +381,7 @@ npm run test:server   # 测试 MCP 服务器功能
 ```
 
 **注意**：
+
 - `npm test` 是运行测试套件（自动完成），用于验证规范
 
 详细说明见：[tests/README.md](./tests/README.md)
@@ -291,26 +391,34 @@ npm run test:server   # 测试 MCP 服务器功能
 ## 常见问题
 
 ### Q: 如何查看所有可用资源？
-A: 让 AI 调用 `get_knowledge_index()`，规则已自动注入到 `.cursor/rules/bkui.mdc`
+
+A: 让 AI 调用 `get_knowledge_index()`，规则已自动注入到对应 IDE 的 rules 目录
 
 ### Q: 设计稿还原效果不好？
+
 A: 使用 `@BKUI-EXPERT`，它会引导 AI 按完整流程执行
 
 ### Q: 知识库更新了怎么办？
-A: 发布新版本 npm 包后，用户下次启动 Cursor 时 `npx -y` 会自动拉取最新版本
+
+A: 发布新版本 npm 包后，用户下次启动 IDE 时 `npx -y` 会自动拉取最新版本
 
 ### Q: skills 没有同步成功？
-A: 检查 `.cursor/skills/` 目录是否存在，或查看 Cursor 的 MCP 日志
+
+A: 检查对应 IDE 的 skills 目录是否存在（Cursor: `.cursor/skills/`，CodeBuddy: `.codebuddy/skills/`），或查看 IDE 的 MCP 日志
+
+### Q: 如何切换到 CodeBuddy？
+
+A: 在 MCP 配置的 args 中添加 `--ide=codebuddy` 参数
 
 ---
 
 ## Token 消耗对比
 
-| 方案 | 初始化 | 按需加载 | 总计 |
-|------|--------|---------|------|
-| 全量注入 | ~15,000 | 0 | ~15,000 |
-| 纯按需加载 | ~200 | ~3,000 | ~3,200 |
-| **渐进式披露** | ~200 | ~2,000 | **~2,200** ✅ |
-| **npx 自动同步 skills** | 0 | ~2,000 | **~2,000** ✅✅ |
+| 方案                    | 初始化  | 按需加载 | 总计            |
+| ----------------------- | ------- | -------- | --------------- |
+| 全量注入                | ~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