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

package/knowledge/skills/bk-security-redlines/references/input-validation.md

@@ -0,0 +1,96 @@
+# 红线 1：外部输入未校验 - 详解
+
+## 定义
+
+外部输入在进入**高危操作**之前，未完成合理校验即违规。
+
+## 外部输入范围
+
+- HTTP 请求参数/Header/Cookie/Body/JSON
+- 文件名及文件内容
+- 环境变量、配置下发内容
+- DB 可写字段
+- 蓝鲸其他产品/组件/平台通过服务间调用、回调/Webhook、MQ/事件总线、任务参数等传入的数据
+
+> ⚠️ **互信不等于可信**，一律视为外部输入
+
+## 合理校验标准
+
+必须同时满足：
+
+1. **服务端校验**：发生在服务端/执行端，且在高危使用点之前
+2. **强约束**：类型/长度/格式/范围/枚举或白名单/字符集与归一化一致性
+3. **不可绕过**：不得因编码差异、大小写、分隔符、重复参数、路径归一化差异等被绕过
+4. **不依赖外部假设**：不得以"内网/互信/网关/前端已校验/仅管理员可用"等作为免检理由
+
+## 不合理校验（视为违规）
+
+- 仅判空
+- 仅黑名单
+- 仅简单正则
+- 仅前端校验
+- 仅网关策略
+- 仅依赖来源 IP
+
+---
+
+## 7 类高危操作场景
+
+### 1.1 外部输入用于命令执行
+
+**业务场景**：
+- shell/exec/subprocess/Runtime.exec/ProcessBuilder/child_process
+- 任务调度执行
+- 脚本调用
+- 运维命令封装
+
+### 1.2 外部输入进入模板解释
+
+**业务场景**：
+- eval/exec
+- 脚本引擎
+- 动态 import/反射调用
+- 表达式引擎
+- 反序列化入口
+- 模版渲染
+
+### 1.3 外部输入影响文件路径
+
+**业务场景**：
+- 文件写入、文件读取/下载
+- 上传落盘、导出落盘
+- 临时文件、缓存文件
+- 移动/重命名
+- 解压/解包（zip/tar）
+- 符号链接/硬链接导致的覆盖写（symlink/link attack）
+
+### 1.4 外部输入控制请求目标
+
+**业务场景**：
+- http client 请求（URL/Host/Port 由输入影响）
+- 回调地址
+- 代理转发
+- 跳转地址
+
+### 1.5 外部输入参与查询构造
+
+**业务场景**：
+- 拼接 SQL/NoSQL 条件
+- 管道
+- 排序字段/表名等结构化查询构造
+
+### 1.6 外部输入进入渲染解析
+
+**业务场景**：
+- XML 解析（上传/导入 XML、SOAP、SAML、Office 文档内嵌 XML 等）并可触发外部实体/DTD
+- HTML/模板渲染
+- 富文本预览
+- Markdown 渲染
+- 前端危险渲染通道（存储型/反射型/DOM 型 XSS）
+
+### 1.7 外部输入注入协议输出
+
+**业务场景**：
+- HTTP Header/响应拼接（Response Splitting）
+- 正则/解析器导致 ReDoS
+- 解析歧义绕过校验（URL/路径/Header 解析差异）

package/knowledge/skills/bk-skill-creator/SKILL.md

@@ -0,0 +1,37 @@
+---
+id: engineering/bk-skill-creator
+name: Skill 创建指南
+category: engineering
+description: 指导如何创建符合渐进式披露架构的 skill 文档
+tags: [skill, knowledge, template, guide]
+updated_at: 2026-01-23
+---
+
+# Skill 创建指南
+
+## ⚠️ 核心规则
+
+1. **SKILL.md ≤ 2KB**: 超出内容必须移到 `references/`
+2. **必须包含 Front Matter**: id, name, category, description, tags, updated_at
+3. **按需加载引导**: 详细内容通过 `skill://` URI 引用
+4. **存放位置**: 所有 skill 必须放在 `bkui-knowledge/knowledge/skills/` 目录下
+
+## 快速开始
+
+```bash
+cp -r knowledge/skills/.template knowledge/skills/your-skill-id
+vim knowledge/skills/your-skill-id/SKILL.md
+bash scripts/validate-skill.sh your-skill-id
+```
+
+详细步骤: `skill://bk-skill-creator/references/quick-start.md`
+
+## 📦 按需加载资源
+
+| 资源 | URI |
+|-----|-----|
+| 快速开始 | `skill://bk-skill-creator/references/quick-start.md` |
+| 目录结构 | `skill://bk-skill-creator/references/structure-guide.md` |
+| 常见错误 | `skill://bk-skill-creator/references/common-mistakes.md` |
+| 检查清单 | `skill://bk-skill-creator/references/skill-checklist.md` |
+| 写作技巧 | `skill://bk-skill-creator/references/writing-tips.md` |

package/knowledge/skills/bk-skill-creator/references/common-mistakes.md

@@ -0,0 +1,43 @@
+# 常见错误
+
+## 错误对照表
+
+| 错误 | 正确做法 |
+|-----|---------|
+| ❌ SKILL.md 内容过多 | ✅ 只保留核心规则，详细内容移到 references/ |
+| ❌ 忘记更新索引 | ✅ 同时更新 manifest.json 和 README.md |
+| ❌ 缺少 Front Matter | ✅ 必须包含 YAML 头部元数据 |
+| ❌ 文件大小超限 | ✅ 使用 `bash scripts/validate-skill.sh` 验证 |
+| ❌ 缺少按需加载引导 | ✅ 在 SKILL.md 末尾添加资源列表 |
+
+## 详细说明
+
+### SKILL.md 内容过多
+
+**问题**: 将所有内容都放在 SKILL.md 中，导致文件超过 2KB 限制。
+
+**解决**: 
+- 只保留核心规则和快速开始
+- 详细步骤、示例、错误说明等移到 `references/` 目录
+- 通过 `skill://` URI 引用详细内容
+
+### 忘记更新索引
+
+**问题**: 创建了 skill 但忘记在 manifest.json 和 README.md 中注册。
+
+**解决**:
+- 在 `knowledge/manifest.json` 的 `skills.items` 中添加条目
+- 在 `README.md` 的技能表格中添加一行
+- 使用验证脚本检查是否已正确注册
+
+### 缺少 Front Matter
+
+**问题**: SKILL.md 文件开头没有 YAML 格式的元数据。
+
+**解决**: 必须在文件开头添加 Front Matter，包含：
+- `id`: skill 的唯一标识符
+- `name`: skill 的显示名称
+- `category`: 分类（engineering/performance/quality）
+- `description`: 简短描述
+- `tags`: 标签数组
+- `updated_at`: 更新日期

package/knowledge/skills/bk-skill-creator/references/quick-start.md

@@ -0,0 +1,42 @@
+# 快速开始详细步骤
+
+## 完整流程
+
+```bash
+# 进入 bkui-knowledge 项目根目录
+cd /path/to/bkui-knowledge
+
+# 1. 复制模板到 knowledge/skills 目录
+cp -r knowledge/skills/.template knowledge/skills/your-skill-id
+
+# 2. 编辑 SKILL.md（保持精简）
+vim knowledge/skills/your-skill-id/SKILL.md
+
+# 3. 详细内容放 references/
+vim knowledge/skills/your-skill-id/references/advanced.md
+
+# 4. 更新索引
+vim knowledge/manifest.json  # skills.items 添加条目
+vim README.md                # 技能表格添加一行
+
+# 5. 验证
+bash scripts/validate-skill.sh your-skill-id
+```
+
+## 目录结构示例
+
+```
+bkui-knowledge/
+└── knowledge/
+    └── skills/
+        ├── .template/           # 模板目录
+        └── your-skill-id/       # 新 skill 放这里
+            ├── SKILL.md         # 主文件 (≤2KB)
+            └── references/      # 详细内容
+```
+
+## 注意事项
+
+- SKILL.md 必须控制在 2KB 以内
+- 详细内容应放在 references/ 目录
+- 创建后记得更新 manifest.json 和 README.md

package/knowledge/skills/bk-skill-creator/references/skill-checklist.md

@@ -0,0 +1,93 @@
+# Skill 提交检查清单
+
+## 自动验证
+
+使用验证脚本一键检查：
+
+```bash
+bash scripts/validate-skill.sh your-skill-id
+```
+
+**验证项**：
+- 文件大小是否 ≤ 2KB
+- 是否包含 Front Matter
+- 是否有按需加载引导
+- 是否在 manifest.json 中注册
+
+## 手动检查清单
+
+### 1. SKILL.md 文件
+
+- [ ] 文件大小 ≤ 2KB（`wc -c knowledge/skills/your-skill-id/SKILL.md`）
+- [ ] 包含完整 Front Matter：
+  ```yaml
+  ---
+  id: category/your-skill-id
+  name: 技能名称
+  category: engineering | performance | quality | security
+  description: 一句话描述
+  tags: [tag1, tag2]
+  updated_at: YYYY-MM-DD
+  ---
+  ```
+- [ ] 包含"核心规则"章节
+- [ ] 包含"快速开始"章节
+- [ ] 如有 references/ 或 assets/，包含按需加载资源列表
+
+### 2. 索引更新
+
+- [ ] `manifest.json` 已添加条目：
+  ```json
+  {
+    "id": "your-skill-id",
+    "name": "技能名称",
+    "category": "engineering",
+    "path": "your-skill-id/SKILL.md",
+    "tags": ["tag1", "tag2"]
+  }
+  ```
+- [ ] `README.md` 技能表格已添加一行
+
+### 3. 内容质量
+
+- [ ] 核心规则精简（3-5 条）
+- [ ] 快速开始示例可运行
+- [ ] 详细内容已拆分到 references/
+- [ ] 代码示例遵循团队规范
+
+## 常见问题排查
+
+### Q: 验证脚本报错 "未在 manifest.json 中找到"
+
+检查 `manifest.json` 中的 `id` 字段是否与 skill 目录名一致。
+
+### Q: 文件大小超过 2KB
+
+1. 识别核心内容（必读的规则）
+2. 将详细说明移到 `references/`
+3. 在 SKILL.md 末尾添加资源引导
+
+### Q: 按需加载资源格式
+
+正确格式：`skill://skill-id/references/xxx.md`
+
+```markdown
+## 📦 按需加载资源
+
+| 资源 | URI |
+|-----|-----|
+| 高级用法 | `skill://your-skill-id/references/advanced.md` |
+```
+
+## 测试方式
+
+```bash
+# 1. 运行所有测试
+npm test
+
+# 2. 单独测试 Skills 规范
+npm run test:skills
+
+# 3. 在 Cursor 中调用测试
+# 对话中输入：请调用 get_skill({ skillId: 'your-skill-id' })
+```

package/knowledge/skills/bk-skill-creator/references/structure-guide.md

@@ -0,0 +1,88 @@
+# Skill 目录结构详解
+
+## 标准结构
+
+```
+knowledge/skills/your-skill-id/
+├── SKILL.md              # 【必须】核心文档 (≤ 2KB)
+├── references/           # 【可选】详细参考文档
+│   ├── advanced.md       # 高级用法
+│   ├── examples.md       # 示例代码
+│   └── troubleshooting.md # 问题排查
+├── assets/               # 【可选】代码资产
+│   ├── templates/        # 模板文件
+│   ├── scripts/          # 工具脚本
+│   └── configs/          # 配置文件
+└── README.md             # 【可选】对内说明（不会被 AI 加载）
+```
+
+## 各目录用途
+
+### SKILL.md（必须）
+
+- **用途**: 核心指令，AI 首先加载的文档
+- **大小限制**: ≤ 2KB
+- **内容要求**:
+  - Front Matter 元数据
+  - 核心规则（3-5 条）
+  - 快速开始示例
+  - 按需加载资源引导
+
+### references/（可选）
+
+- **用途**: 详细参考文档，按需加载
+- **大小限制**: 每个文件 ≤ 5KB
+- **命名建议**:
+  - `advanced.md` - 高级用法
+  - `examples.md` - 完整示例
+  - `troubleshooting.md` - 问题排查
+  - `checklist.md` - 检查清单
+
+### assets/（可选）
+
+- **用途**: 代码模板、脚本、配置文件
+- **大小限制**: 无限制（用户确认后加载）
+- **命名建议**:
+  - `template.vue` / `template.ts` - 代码模板
+  - `config.ts` - 配置示例
+  - `helper.js` - 工具脚本
+
+## 现有 Skill 结构示例
+
+### bkui-builder（复杂示例）
+
+```
+bkui-builder/
+├── SKILL.md
+├── references/
+│   ├── checklist.md
+│   ├── code-snippets.md
+│   └── visual-mapping.md
+└── assets/
+    ├── layouts/
+    │   ├── admin-layout-dark.vue
+    │   ├── admin-layout-left.vue
+    │   └── admin-layout-top.vue
+    └── pages/
+        ├── table-page.vue
+        └── dashboard-page.vue
+```
+
+### api-standard（简单示例）
+
+```
+api-standard/
+├── SKILL.md
+├── references/
+│   ├── full-implementation.md
+│   └── protocol-migration.md
+└── assets/
+    └── http.ts
+```
+
+## 文件命名规范
+
+1. **skill-id**: 使用 kebab-case，如 `bk-skill-creator`
+2. **SKILL.md**: 必须大写，固定名称
+3. **references/**: 使用 kebab-case，如 `structure-guide.md`
+4. **assets/**: 使用原始文件扩展名，如 `.vue`, `.ts`

package/knowledge/skills/bk-skill-creator/references/writing-tips.md

@@ -0,0 +1,153 @@
+# Skill 写作技巧
+
+## 控制 SKILL.md 大小
+
+### 技巧 1: 只保留"必须知道"的内容
+
+**问自己**：如果 AI 只读这个文件，哪些信息是绝对必要的？
+
+- ✅ 核心规则（必须遵守）
+- ✅ 最简单的使用示例
+- ✅ 最常见的错误
+- ❌ 详细解释（移到 references/）
+- ❌ 多个完整示例（移到 references/）
+- ❌ 历史背景（删除或移走）
+
+### 技巧 2: 使用表格代替段落
+
+**Before（冗长）**：
+```markdown
+## 常见错误
+
+### 错误 1: 文件过大
+当 SKILL.md 超过 2KB 时，会导致 AI 消耗过多 token...
+
+### 错误 2: 缺少元数据
+如果没有 Front Matter，系统无法正确索引...
+```
+
+**After（精简）**：
+```markdown
+## 常见错误
+
+| 错误 | 正确做法 |
+|-----|---------|
+| ❌ 文件过大 | ✅ 拆分到 references/ |
+| ❌ 缺少元数据 | ✅ 添加 Front Matter |
+```
+
+### 技巧 3: 代码示例最小化
+
+只展示最核心的代码，完整示例放 references/。
+
+**Before（完整）**：
+```typescript
+import axios from 'axios';
+import { Message } from 'bkui-vue';
+
+const http = axios.create({
+  baseURL: '/api',
+  timeout: 30000,
+  headers: { 'Content-Type': 'application/json' }
+});
+
+http.interceptors.response.use(
+  response => response.data,
+  error => {
+    Message.error(error.message);
+    return Promise.reject(error);
+  }
+);
+
+export default http;
+```
+
+**After（最小）**：
+```typescript
+import axios from 'axios';
+const http = axios.create({ baseURL: '/api', timeout: 30000 });
+export default http;
+```
+
+> 完整实现见 `skill://api-standard/assets/http.ts`
+
+## 内容拆分策略
+
+### 拆分原则
+
+| 内容类型 | 放置位置 |
+|---------|---------|
+| 核心规则 | SKILL.md |
+| 快速开始 | SKILL.md |
+| 常见错误 | SKILL.md |
+| 详细配置 | references/advanced.md |
+| 完整示例 | references/examples.md |
+| 问题排查 | references/troubleshooting.md |
+| 代码模板 | assets/*.ts |
+
+### 拆分示例
+
+**原始内容**（3KB，需要拆分）：
+
+```markdown
+# API 封装规范
+
+## 核心规则
+...
+
+## 详细配置
+### 请求拦截器配置
+（500字详细说明）
+
+### 响应拦截器配置
+（500字详细说明）
+
+## 完整示例
+（800字完整代码）
+```
+
+**拆分后**：
+
+SKILL.md（1.5KB）：
+```markdown
+# API 封装规范
+## 核心规则
+...
+## 📦 按需加载资源
+- 详细配置: `skill://api-standard/references/advanced.md`
+- 完整示例: `skill://api-standard/assets/http.ts`
+```
+
+references/advanced.md：
+```markdown
+# 详细配置
+## 请求拦截器配置
+...
+## 响应拦截器配置
+...
+```
+
+## 好的 Skill 示例分析
+
+### bkui-builder
+
+**优点**：
+1. SKILL.md 只有 1.5KB，非常精简
+2. 使用表格展示模板选择逻辑
+3. 按需加载资源清晰列出
+
+**值得学习**：
+- 用"绝对禁令"强调最重要的规则
+- 用"还原流程"提供清晰步骤
+- 模板资源按场景分类
+
+### code-review
+
+**优点**：
+1. 核心规则简洁明确
+2. 详细检查清单放在 references/
+3. 评分标准独立成文件
+
+**值得学习**：
+- 将复杂的评审标准拆分到多个 references 文件
+- 使用 assets/ 存放可执行脚本

package/knowledge/skills/bkui-quick-start/SKILL.md

@@ -0,0 +1,52 @@
+---
+id: bkui-quick-start
+name: BKUI 快速入门
+category: engineering
+description: 蓝鲸前端知识库入口指南，包含规范、索引和工作流程
+tags: [bkui, 规范, 索引, 入门, vue3]
+updated_at: 2026-01-23
+---
+
+# BKUI 快速入门
+
+> 蓝鲸前端知识库入口指南。
+
+## 强制规范
+
+- **组件库**: bkui-vue (前缀 `bk-`)
+- **语法**: Vue 3 `<script setup lang="ts">`
+- **样式**: MagicBox 原子类 (mt10, mb20)
+- **布局**: 必须使用 `bk-navigation`
+
+## 常见错误 (必须避免)
+
+| 组件 | 错误写法 | 正确写法 |
+|------|----------|----------|
+| bk-navigation | `:default-open-keys` | `default-open` |
+| bk-menu | `:default-open-keys` | `:opened-keys` |
+| bk-dialog | `v-model` | `v-model:isShow` |
+
+## 高优先级组件
+
+- `bk-navigation` - 布局组件，易出错
+- `bk-menu` - 与 navigation 配合
+- `bk-table` - 列表页核心组件
+- `bk-form` - 表单验证
+- `bk-dialog` - v-model:isShow
+
+## 工作流程
+
+1. **分析需求** → 确定需要哪些资源
+2. **布局组件** → `get_component_api({ componentName: 'navigation' })`
+3. **模板代码** → `get_skill({ skillId: 'bkui-builder' })`
+
+## 触发条件
+
+遇到 bk- 前缀组件、bkui-vue、蓝鲸前端、设计稿还原时使用。
+
+---
+
+## 按需加载资源
+
+- `skill://bkui-quick-start/references/skills-index.md` - 完整 Skills 索引
+- `skill://bkui-quick-start/references/components-list.md` - 组件完整列表

package/knowledge/skills/bkui-quick-start/references/components-list.md

@@ -0,0 +1,17 @@
+# 组件完整列表
+
+通过 `get_component_api({ componentName: 'xxx' })` 获取文档。
+
+## 高优先级 (必须先查询)
+
+| 组件 | 说明 |
+|------|------|
+| bk-navigation | 布局组件，易出错 |
+| bk-menu | 与 navigation 配合 |
+| bk-table | 列表页核心组件 |
+| bk-form | 表单验证 |
+| bk-dialog | v-model:isShow |
+
+## 全部组件
+
+navigation, menu, table, form, dialog, button, input, select, checkbox, radio, date-picker, time-picker, pagination, message, notify, loading, popover, pop-confirm, tag, tag-input, alert, dropdown, tab, cascader, tree, steps, upload, sideslider, breadcrumb, card, collapse, affix, backtop, badge, divider, exception, image, link, progress, rate, slider, switcher, timeline, process, transfer, search-select, color-picker, container, resize-layout, fixed-navbar, code-diff, swiper, animate-number, overflow-title, virtual-render, scrollbar, info-box, config-provider

package/knowledge/skills/bkui-quick-start/references/skills-index.md

@@ -0,0 +1,26 @@
+# 可用 Skills 索引
+
+通过 `get_skill({ skillId: 'xxx' })` 获取详情：
+
+## 工程化
+
+| ID | 名称 | 说明 |
+|----|------|------|
+| bkui-builder | 设计稿还原专家 | 包含布局模版和页面模版 (assets/) |
+| bkui-cheatsheet | BKUI 组件速查 | Props 速查、常见坑点 |
+| api-standard | 统一网络请求封装 | Axios 封装规范 |
+| pinia-setup | 全局状态管理 | Pinia Store 模板 |
+| permission-directive | 前端权限控制 | IAM 权限指令 |
+| vite-migration | Webpack 到 Vite 迁移 | 迁移检查脚本 |
+| bundle-optimization | Vite 构建优化 | 性能优化配置 |
+| vue-composables | Vue 3 Composables | 最佳实践和模板 |
+| virtual-list | 长列表虚拟滚动 | 性能优化方案 |
+
+## 质量保障
+
+| ID | 名称 | 说明 |
+|----|------|------|
+| unit-testing | 组件单元测试 | Vitest 测试模板 |
+| code-review | 代码评审专家 | 评审规范和检查清单 |
+| js-security-check | JavaScript 安全审查 | 前端安全检查 |
+| nodejs-security-check | Node.js 安全审查 | 后端安全检查 |

package/knowledge/skills/external/vue-skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hyf0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.