@blueking/bkui-knowledge 0.0.1-beta.1

package/knowledge/skills/.template/README.md

@@ -0,0 +1,38 @@
+# Skill 模板使用说明
+
+这是一个标准的 Skill 模板，用于创建符合渐进式披露架构的知识文档。
+
+## 快速开始
+
+```bash
+# 1. 复制模板
+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. 更新 manifest.json
+vim knowledge/manifest.json
+
+# 5. 检查文件大小
+wc -c knowledge/skills/your-skill-id/SKILL.md
+```
+
+## 文件说明
+
+- **SKILL.md**: 核心文档，**必须 ≤ 3KB**
+- **references/**: 详细参考文档，按需加载
+- **assets/**: 代码模板、脚本等资产
+- **README.md**: 对内说明（不会被 AI 加载）
+
+## 注意事项
+
+1. SKILL.md 只包含最核心的规则和快速开始
+2. 详细内容必须拆分到 references/
+3. 在 SKILL.md 末尾提供按需加载的资源列表
+4. 更新 manifest.json 添加索引
+
+详细说明见：`/CONTRIBUTING.md`

package/knowledge/skills/.template/SKILL.md

@@ -0,0 +1,48 @@
+---
+id: category/skill-id
+name: 技能名称
+category: engineering
+description: 一句话描述这个技能的核心价值
+tags: [tag1, tag2, tag3]
+updated_at: 2026-01-16
+---
+
+# 技能名称
+
+## ⚠️ 核心规则
+
+1. **最重要的规则 1**: 简短描述
+2. **最重要的规则 2**: 简短描述
+3. **最重要的规则 3**: 简短描述
+
+## 快速开始
+
+```typescript
+// 最简单的使用示例
+import { Something } from 'xxx';
+
+// 一个完整的最小示例
+const example = () => {
+  // ...
+};
+```
+
+## 常见错误
+
+| 错误用法 | 正确用法 |
+|---------|---------|
+| ❌ 错误示例 | ✅ 正确示例 |
+| ❌ 错误示例 | ✅ 正确示例 |
+
+## 📦 按需加载资源
+
+需要更详细内容时，获取以下资源：
+
+| 资源 | URI | 说明 |
+|-----|-----|------|
+| 高级用法 | `skill://skill-id/references/advanced.md` | 进阶配置和用法 |
+| 示例代码 | `skill://skill-id/references/examples.md` | 完整示例合集 |
+| 问题排查 | `skill://skill-id/references/troubleshooting.md` | 常见问题解决 |
+| 代码模板 | `skill://skill-id/assets/template.xxx` | 可直接使用的模板 |
+
+> 💡 先用核心规则开始，遇到具体问题再按需加载详细资源

package/knowledge/skills/.template/assets/.gitkeep

@@ -0,0 +1,3 @@
+# 代码资产目录
+
+放置模板文件、脚本、配置文件等

package/knowledge/skills/.template/references/advanced.md

@@ -0,0 +1,23 @@
+# 高级用法
+
+> 详细的进阶内容，不需要放在 SKILL.md 中
+
+## 高级特性 1
+
+详细说明...
+
+```typescript
+// 代码示例
+```
+
+## 高级特性 2
+
+详细说明...
+
+## 性能优化
+
+...
+
+## 与其他技术集成
+
+...

package/knowledge/skills/.template/references/examples.md

@@ -0,0 +1,19 @@
+# 示例代码
+
+> 完整的使用示例集合
+
+## 示例 1: 基础场景
+
+```typescript
+// 完整代码
+```
+
+## 示例 2: 复杂场景
+
+```typescript
+// 完整代码
+```
+
+## 示例 3: 实战案例
+
+从实际项目中提取的案例...

package/knowledge/skills/.template/references/troubleshooting.md

@@ -0,0 +1,27 @@
+# 问题排查
+
+> 常见问题和解决方案
+
+## 问题 1: XXX 不生效
+
+**症状**：...
+
+**原因**：...
+
+**解决方案**：
+1. 检查 xxx
+2. 确认 yyy
+3. ...
+
+## 问题 2: 报错 "XXX"
+
+**症状**：...
+
+**原因**：...
+
+**解决方案**：...
+
+## 调试技巧
+
+- 技巧 1
+- 技巧 2

package/knowledge/skills/api-standard/SKILL.md

@@ -0,0 +1,64 @@
+---
+id: eng-api-standard
+name: 统一网络请求封装 (Axios)
+category: engineering
+description: 蓝鲸双协议兼容的 Axios 封装，自动处理旧版和新版 HTTP 协议
+tags: [axios, http, api, request, blueking]
+updated_at: 2026-01-16
+---
+
+# 统一网络请求封装 (Axios)
+
+蓝鲸体系处于 HTTP 协议升级过渡期，本封装自动兼容 **旧版协议** 和 **新版协议**。
+
+## ⚠️ 核心规则
+
+1. **统一导出**: 所有请求必须通过 `src/api/http.ts` 的实例发起
+2. **自动剥壳**: 响应拦截器自动提取 `data` 字段
+3. **自动登录**: 401 自动跳转登录页
+4. **统一错误**: 错误信息统一通过 Message 提示
+
+## 快速开始
+
+```typescript
+// src/api/http.ts
+import axios from 'axios';
+import { Message } from 'bkui-vue';
+
+const http = axios.create({ baseURL: '/api', timeout: 60000 });
+
+http.interceptors.response.use(
+  (res) => {
+    const { data } = res;
+    // 旧版协议（有 code 字段）
+    if (data.code !== undefined) {
+      if (data.code !== 0) {
+        Message({ theme: 'error', message: data.message });
+        return Promise.reject(new Error(data.message));
+      }
+      return data.data;
+    }
+    return data.data ?? data;
+  },
+  (error) => {
+    if (error.response?.status === 401) window.location.href = '/login';
+    Message({ theme: 'error', message: error.message });
+    return Promise.reject(error);
+  }
+);
+export default http;
+```
+
+## 常见错误
+
+| 错误 | 解决 |
+|------|------|
+| 401 循环跳转 | 登录页排除拦截器 |
+| 数据双层嵌套 | 删除多余的 `.data` |
+
+## 📦 按需加载资源
+
+| 资源 | URI |
+|-----|-----|
+| 完整实现 | `skill://api-standard/references/full-implementation.md` |
+| 协议迁移 | `skill://api-standard/references/protocol-migration.md` |

package/knowledge/skills/api-standard/assets/http.ts

@@ -0,0 +1,121 @@
+/**
+ * 统一 HTTP 请求封装
+ * 基于 Axios，包含拦截器、错误处理、Loading 状态管理
+ */
+
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+import { Message } from 'bkui-vue';
+
+// 响应数据结构
+interface ApiResponse<T = any> {
+  code: number;
+  data: T;
+  message: string;
+}
+
+// 请求配置扩展
+interface RequestConfig extends AxiosRequestConfig {
+  // 是否显示全局 Loading
+  showLoading?: boolean;
+  // 是否显示错误提示
+  showError?: boolean;
+  // 自定义错误处理
+  handleError?: boolean;
+}
+
+// 创建实例
+const createInstance = (): AxiosInstance => {
+  const instance = axios.create({
+    baseURL: import.meta.env.VITE_API_BASE_URL || '/api',
+    timeout: 30000,
+    headers: {
+      'Content-Type': 'application/json'
+    }
+  });
+
+  // 请求拦截器
+  instance.interceptors.request.use(
+    (config) => {
+      // 注入认证 Token
+      const token = localStorage.getItem('token');
+      if (token) {
+        config.headers.Authorization = `Bearer ${token}`;
+      }
+      return config;
+    },
+    (error) => Promise.reject(error)
+  );
+
+  // 响应拦截器
+  instance.interceptors.response.use(
+    (response: AxiosResponse<ApiResponse>) => {
+      const { code, data, message } = response.data;
+
+      // 业务成功
+      if (code === 0) {
+        return data;
+      }
+
+      // 业务错误
+      const error = new Error(message || '请求失败');
+      (error as any).code = code;
+      return Promise.reject(error);
+    },
+    (error) => {
+      // HTTP 错误处理
+      const status = error.response?.status;
+      let message = '网络错误，请稍后重试';
+
+      if (status === 401) {
+        message = '登录已过期，请重新登录';
+        // TODO: 跳转登录页
+      } else if (status === 403) {
+        message = '没有权限访问该资源';
+      } else if (status === 404) {
+        message = '请求的资源不存在';
+      } else if (status >= 500) {
+        message = '服务器错误，请稍后重试';
+      }
+
+      error.message = message;
+      return Promise.reject(error);
+    }
+  );
+
+  return instance;
+};
+
+const http = createInstance();
+
+// 封装请求方法
+export const request = async <T = any>(config: RequestConfig): Promise<T> => {
+  const { showError = true, ...axiosConfig } = config;
+
+  try {
+    const result = await http.request<any, T>(axiosConfig);
+    return result;
+  } catch (error: any) {
+    if (showError) {
+      Message({
+        theme: 'error',
+        message: error.message || '请求失败'
+      });
+    }
+    throw error;
+  }
+};
+
+// 便捷方法
+export const get = <T = any>(url: string, params?: any, config?: RequestConfig) =>
+  request<T>({ ...config, method: 'GET', url, params });
+
+export const post = <T = any>(url: string, data?: any, config?: RequestConfig) =>
+  request<T>({ ...config, method: 'POST', url, data });
+
+export const put = <T = any>(url: string, data?: any, config?: RequestConfig) =>
+  request<T>({ ...config, method: 'PUT', url, data });
+
+export const del = <T = any>(url: string, config?: RequestConfig) =>
+  request<T>({ ...config, method: 'DELETE', url });
+
+export default http;

package/knowledge/skills/api-standard/references/full-implementation.md

@@ -0,0 +1,249 @@
+# 完整 Axios 封装实现
+
+> 详细的代码实现和说明
+
+## 标准封装代码 (`src/api/http.ts`)
+
+```typescript
+import axios, { type AxiosResponse, type InternalAxiosRequestConfig } from 'axios';
+import { Message } from 'bkui-vue';
+
+// --- 类型定义 ---
+
+// 旧版响应结构
+interface LegacyResponse<T = any> {
+  code: number;
+  result: boolean;
+  message: string;
+  data: T;
+}
+
+// 新版标准响应结构
+interface StandardResponse<T = any> {
+  data: T;
+}
+
+// 新版错误结构
+interface StandardError {
+  error: {
+    code: string;
+    message: string;
+    system?: string;
+    data?: any; // 可能包含权限申请数据等
+    details?: any[];
+  };
+}
+
+// --- 实例初始化 ---
+
+const http = axios.create({
+  baseURL: window.PROJECT_CONFIG?.API_URL || '/api',
+  timeout: 60000,
+  withCredentials: true,
+  headers: {
+    'X-Requested-With': 'XMLHttpRequest', // 标记 AJAX 请求，部分后端需要
+  },
+});
+
+// --- 请求拦截器 ---
+
+http.interceptors.request.use(
+  (config: InternalAxiosRequestConfig) => {
+    // 可以在这里注入 CSRF Token
+    const token = getCookie('bk_token'); // 需自行实现 getCookie
+    if (token) {
+      // 蓝鲸网关通常要求 X-CSRFToken 或 Authorization
+      // config.headers['X-CSRFToken'] = token;
+    }
+    return config;
+  },
+  (error) => Promise.reject(error)
+);
+
+// --- 响应拦截器 ---
+
+http.interceptors.response.use(
+  (response: AxiosResponse) => {
+    const { data, status } = response;
+
+    // [兼容逻辑] 判定是否为旧版协议 (存在 code 且不为 undefined)
+    const isLegacyProtocol = data && typeof data.code !== 'undefined';
+
+    // 场景 A: 旧版协议处理
+    if (isLegacyProtocol) {
+      const legacyData = data as LegacyResponse;
+      if (legacyData.code !== 0) {
+        // 业务错误
+        const errorMessage = legacyData.message || '系统错误';
+
+        // 特殊：旧版 401 (虽然状态码是 200，但 code 可能是 401 或特定值)
+        if (legacyData.code === 401 || legacyData.code === 40100) {
+          handleLoginRedirect(legacyData.data?.login_url);
+          return Promise.reject(new Error('Login Expired'));
+        }
+
+        Message({ theme: 'error', message: errorMessage });
+        return Promise.reject(new Error(errorMessage));
+      }
+      // 成功：剥壳返回 data
+      return legacyData.data;
+    }
+
+    // 场景 B: 新版协议处理 (2xx 状态码)
+    // 根据规范，正常响应体为 { data: ... }
+    if (status >= 200 && status < 300) {
+      return data.data !== undefined ? data.data : data;
+    }
+
+    return data;
+  },
+  (error) => {
+    // 处理 HTTP 错误 (非 2xx) -> 主要是新版协议的错误处理
+    const { response } = error;
+
+    if (response) {
+      const { status, data } = response;
+      const errorBody = data as StandardError; // 尝试解析标准错误体
+
+      // 优先使用后端返回的详细错误信息
+      const serverMsg = errorBody?.error?.message;
+      const serverCode = errorBody?.error?.code;
+
+      // 1. 401 未登录
+      if (status === 401) {
+        const loginUrl = errorBody?.error?.data?.login_url;
+        handleLoginRedirect(loginUrl);
+        return Promise.reject(new Error('Login Expired'));
+      }
+
+      // 2. 403 无权限
+      if (status === 403) {
+        // 新版协议中，403 可能包含权限申请数据 (IAM_NO_PERMISSION)
+        if (serverCode === 'IAM_NO_PERMISSION') {
+           // TODO: 唤起权限申请弹窗 (需结合具体的权限组件)
+           console.warn('需申请权限:', errorBody.error.data);
+           Message({ theme: 'warning', message: '您没有访问权限，请申请。' });
+           return Promise.reject(errorBody.error);
+        }
+      }
+
+      // 3. 通用错误提示
+      const displayMsg = serverMsg || getHttpErrorMessage(status);
+      Message({ theme: 'error', message: displayMsg });
+    } else {
+      // 网络层面错误 (断网、超时)
+      Message({ theme: 'error', message: error.message || '网络连接异常' });
+    }
+
+    return Promise.reject(error);
+  }
+);
+
+// --- 辅助函数 ---
+
+function handleLoginRedirect(backendLoginUrl?: string) {
+  // 优先使用后端返回的登录地址，其次使用配置，最后兜底
+  const loginUrl = backendLoginUrl
+    || window.PROJECT_CONFIG?.LOGIN_URL
+    || 'https://paas.bk.tencent.com/login/';
+
+  // 避免死循环跳转
+  if (window.location.href.startsWith(loginUrl)) return;
+
+  const referer = window.location.href;
+  window.location.href = `${loginUrl}?c_url=${encodeURIComponent(referer)}`;
+}
+
+function getHttpErrorMessage(status: number): string {
+  const map: Record<number, string> = {
+    400: '请求参数错误 (400)',
+    403: '无权限访问 (403)',
+    404: '资源不存在 (404)',
+    500: '服务器内部错误 (500)',
+    502: '网关错误 (502)',
+    503: '服务不可用 (503)',
+  };
+  return map[status] || `请求异常 (${status})`;
+}
+
+// 简单的 Cookie 获取实现
+function getCookie(name: string): string | null {
+  const match = document.cookie.match(new RegExp('(^| )' + name + '=([^;]+)'));
+  return match ? decodeURIComponent(match[2]) : null;
+}
+
+export default http;
+```
+
+## API 定义示例
+
+在 `src/api/modules/` 下按模块定义 API：
+
+```typescript
+import http from '@/api/http';
+import type { Host } from '@/types/host';
+
+// 泛型参数：<ResponseData, ReturnData>
+// 通常我们不关心 ResponseData (AxiosResponse)，只关心最终剥壳后的 ReturnData
+export const getHosts = () => {
+  return http.get<any, Host[]>('/api/v2/hosts');
+};
+
+export const createHost = (data: Partial<Host>) => {
+  return http.post<any, Host>('/api/v2/hosts', data);
+};
+
+export const updateHost = (id: number, data: Partial<Host>) => {
+  return http.put<any, Host>(`/api/v2/hosts/${id}`, data);
+};
+
+export const deleteHost = (id: number) => {
+  return http.delete(`/api/v2/hosts/${id}`);
+};
+```
+
+## 高级用法
+
+### 自定义错误处理
+
+```typescript
+try {
+  const data = await getHosts();
+  // 处理数据
+} catch (error) {
+  // 自定义错误处理
+  console.error('获取主机列表失败:', error);
+}
+```
+
+### 请求/响应转换
+
+```typescript
+http.interceptors.request.use((config) => {
+  // 统一添加时间戳防止缓存
+  if (config.method === 'get') {
+    config.params = {
+      ...config.params,
+      _t: Date.now()
+    };
+  }
+  return config;
+});
+```
+
+### Loading 状态管理
+
+```typescript
+import { ref } from 'vue';
+
+const loading = ref(false);
+
+export const getHostsWithLoading = async () => {
+  loading.value = true;
+  try {
+    return await getHosts();
+  } finally {
+    loading.value = false;
+  }
+};
+```

package/knowledge/skills/api-standard/references/protocol-migration.md

@@ -0,0 +1,51 @@
+# 协议迁移指南
+
+> 旧版 → 新版协议的迁移说明
+
+## 协议特征对比
+
+| 特征 | 旧版协议 (Legacy) | 新版协议 (Standard) |
+| :--- | :--- | :--- |
+| **成功状态码** | 始终 `200` | `200`, `201`, `204` |
+| **失败状态码** | 始终 `200` | `400`, `401`, `403`, `500`... |
+| **成功响应体** | `{ code: 0, result: true, data: ... }` | `{ data: ... }` |
+| **失败响应体** | `{ code: 123, message: "...", data: null }` | `{ error: { code: "...", message: "..." } }` |
+
+## 兼容策略
+
+本封装通过检测 `data.code` 是否存在来判断协议版本：
+
+```typescript
+const isLegacyProtocol = data && typeof data.code !== 'undefined';
+```
+
+- **存在 `code`** → 旧版协议，检查 `code === 0`
+- **不存在 `code`** → 新版协议，检查 HTTP 状态码
+
+## 迁移步骤
+
+### 后端迁移
+
+1. **逐步升级**: 先保持旧版响应格式，添加标准 HTTP 状态码
+2. **移除 code**: 逐步去掉 `code`/`result` 字段
+3. **规范错误**: 使用 `{ error: { code, message } }` 结构
+
+### 前端适配
+
+1. **无需改动**: 使用本封装的项目无需修改业务代码
+2. **测试验证**: 两种协议分别测试
+3. **清理代码**: 后端全面升级后，可简化拦截器逻辑
+
+## 常见问题
+
+### Q: 如何判断当前接口是新版还是旧版？
+
+A: 查看响应体结构，有 `code` 字段就是旧版。
+
+### Q: 两种协议可以共存吗？
+
+A: 可以，本封装会自动识别并分别处理。
+
+### Q: 迁移后需要改业务代码吗？
+
+A: 不需要，封装层会自动剥壳，业务代码统一获得 `data`。