@blueking/bkui-knowledge 0.0.1-beta.14 → 0.0.1-beta.15

package/knowledge/rules/bk-monitor-project.mdc

@@ -0,0 +1,17 @@
+---
+description: 监控前端
+globs:
+alwaysApply: true
+---
+
+### 不需要做的事项
+
+- 任何对话、询问的回复使用中文
+- 任何代码如果有 eslint 或者 格式问题 你都不需要主动去处理 这类处理前必须经过我的同意
+- 执行任何脚本必须经过我的同意
+
+### 你一定需要做的
+
+- 每次开发新的组件或者需求需先抛出你的实现思路以及方案 然后再询问我确认
+- 有任何不确定都需要主动来询问我
+- 每次对话结束后主动询问是否总结经验更新到关联的 skill references QA 文档中

package/knowledge/rules/chat-x-project.mdc

@@ -0,0 +1,17 @@
+---
+description: 监控前端项目介绍
+globs:
+alwaysApply: true
+---
+
+### 不需要做的事项
+
+- 任何对话、询问的回复使用中文
+- 任何代码如果有 eslint 或者 格式问题 你都不需要主动去处理 这类处理前必须经过我的同意
+- 执行任何脚本必须经过我的同意
+
+### 你一定需要做的
+
+- 每次开发新的组件或者需求需先抛出你的实现思路以及方案 然后再询问我确认
+- 有任何不确定都需要主动来询问我
+- 每次对话结束后主动询问是否总结经验更新到关联的 skill references QA 文档中

package/knowledge/skills/bk-monitor-dev-server/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: bk-monitor-dev-server
+description: 帮助配置和启动本地开发服务器。当用户提到启动开发服务器、dev server、pnpm dev 时使用。
+---
+
+# 本地开发服务器配置
+
+## 工作流程
+
+### Step 0: 检查配置（优先）
+
+```bash
+node .cursor/skills/dev-server/scripts/setup-config.js
+```
+
+- `CONFIG_VALID` → 跳到 Step 5
+- `CONFIG_INVALID:*` → 需配置，向用户索要 URL/Cookie/Token
+
+### Step 1-4: 环境配置
+
+1. 环境检查：`bash .cursor/skills/dev-server/scripts/check-env.sh`
+2. 安装依赖：`pnpm i`
+3. 生成配置（详见 config-guide.md）
+4. 配置 hosts
+
+### Step 5: 启动服务
+
+- monitor-pc: `make dev-pc`
+- trace (Vue3): `make dev-vue3`
+
+### Step 6: 验证
+
+等待 `Compiled successfully`，访问 `http://appdev.xxx.com:7001`
+
+---
+
+## 常见问题速查
+
+| 问题          | 可能原因          | 解决方案                       |
+| ------------- | ----------------- | ------------------------------ |
+| 端口被占用    | 其他进程占用 7001 | 服务会自动换端口               |
+| API 401/403   | Cookie/Token 过期 | 重新获取 Cookie 和 X-CSRFToken |
+| API 连接失败  | 代理配置错误      | 检查 devProxyUrl               |
+| 页面空白      | hosts 未配置      | 添加 hosts 映射                |
+| 依赖安装失败  | 未使用 pnpm       | 使用 `pnpm i`                  |
+
+详细排查见 [references/troubleshooting.md](references/troubleshooting.md)
+
+---
+
+## 📦 可用资源
+
+- `skill://bk-monitor-dev-server/references/config-guide.md`
+- `skill://bk-monitor-dev-server/references/troubleshooting.md`
+- `skill://bk-monitor-dev-server/scripts/check-env.sh`
+- `skill://bk-monitor-dev-server/scripts/setup-config.js`

package/knowledge/skills/bk-monitor-dev-server/references/config-guide.md

@@ -0,0 +1,261 @@
+# 配置文件详细说明
+
+## 触发场景
+
+在以下情况下主动使用此 skill：
+
+1. **环境配置**：用户询问如何配置本地开发环境、local.settings.js
+2. **启动开发服务**：用户想要启动 dev server、运行 pnpm dev、make dev
+3. **问题排查**：开发服务器启动失败、API 请求失败、端口冲突等问题
+4. **新人入门**：新加入团队成员首次配置开发环境
+
+## 快速开始工作流（手动）
+
+复制此清单跟踪配置进度：
+
+```
+开发环境配置进度：
+- [ ] 1. 环境检查（Node.js、pnpm）
+- [ ] 2. 安装依赖
+- [ ] 3. 配置 local.settings.js
+- [ ] 4. 配置 hosts 文件
+- [ ] 5. 启动开发服务器
+- [ ] 6. 验证服务正常
+```
+
+## 获取 Cookie 和 Token 的指引模板
+
+向用户发送以下说明：
+
+```
+请按以下步骤获取认证信息：
+
+1. 在浏览器中打开目标环境并登录
+2. 打开开发者工具（F12）→ Network 标签
+3. 刷新页面，点击任意 API 请求（如 rest/ 开头的请求）
+4. 在 Request Headers 中找到并复制：
+   - Cookie：完整的 cookie 字符串
+   - X-CSRFToken：token 值
+
+请把这两个值发给我。
+```
+
+## setup-config.js 脚本使用说明
+
+**检查配置状态**（无参数）：
+
+```bash
+node .cursor/skills/dev-server/scripts/setup-config.js
+# 输出: CONFIG_VALID 或 CONFIG_INVALID:<原因>
+```
+
+**输出状态说明**：
+
+- `CONFIG_VALID` → 配置完整，可以启动服务
+- `CONFIG_INVALID:CONFIG_NOT_FOUND` → 配置文件不存在，需要创建
+- `CONFIG_INVALID:URL_NOT_CONFIGURED` → URL 未配置
+- `CONFIG_INVALID:COOKIE_NOT_CONFIGURED` → Cookie 未配置
+- `CONFIG_INVALID:TOKEN_NOT_CONFIGURED` → Token 未配置
+
+**配置缺失时的处理流程**：
+
+1. 向用户索要：环境 URL、Cookie、X-CSRFToken
+2. 收集完整后使用脚本自动生成配置
+3. 根据输出的 HOST 值提醒用户配置 hosts
+
+**生成配置**（带参数）：
+
+```bash
+node .cursor/skills/dev-server/scripts/setup-config.js \
+  --url "https://bkmonitor.xxx.com" \
+  --cookie "bk_token=xxx; bk_biz_id=2; ..." \
+  --token "csrf-token" \
+  --bizId "2" \      # 可选，默认从 cookie 提取
+  --force "true"     # 可选，覆盖已有配置
+```
+
+**输出示例**：
+
+```
+CONFIG_CREATED
+HOST:appdev.xxx.com
+BIZ_ID:2
+URL:https://bkmonitor.xxx.com
+```
+
+## local.settings.js 完整配置模板
+
+在项目根目录创建 `local.settings.js`：
+
+```javascript
+const context = [
+  '/apm',
+  '/rest',
+  '/fta',
+  '/weixin',
+  '/version_log',
+  '/calendars',
+  '/alert',
+  '/query-api',
+  '/ai_agent',
+  '/ai_whale',
+];
+const logContext = ['/apm_log_forward', '/api', '/search'];
+const changeOrigin = true;
+const secure = false;
+const devProxyUrl = 'http://xxx.com'; // ← 替换为目标环境地址
+
+const host = `appdev.${devProxyUrl.match(/\.([^.]+)\.com\/?/)[1]}.com`;
+const proxy = {
+  context,
+  changeOrigin,
+  secure,
+  target: devProxyUrl,
+  headers: {
+    host: devProxyUrl.replace(/https?:\/\//i, ''),
+    referer: devProxyUrl,
+    'X-CSRFToken': '', // ← 从浏览器获取
+    Cookie: ``, // ← 从浏览器获取
+  },
+};
+
+// 日志平台代理：将 bkmonitor 替换为 bklog
+const logProxy = {
+  ...proxy,
+  context: logContext,
+  changeOrigin,
+  secure,
+  target: devProxyUrl.replace('bkmonitor.', 'bklog.').replace('bkm.', 'bklog.'),
+};
+
+const defaultBizId = proxy.headers.Cookie.match(/bk_biz_id=([^;]+);?/)?.[1] || '2';
+
+module.exports = {
+  devProxyUrl,
+  host,
+  proxy,
+  logProxy,
+  defaultBizId,
+};
+```
+
+## 获取 Cookie 和 X-CSRFToken
+
+1. 登录目标环境（如 `http://xxx.bktencent.com`）
+2. 打开浏览器开发者工具 → Network
+3. 刷新页面，选择任意 API 请求
+4. 在 Request Headers 中找到：
+   - `Cookie`：完整复制
+   - `X-CSRFToken`：复制值
+
+**注意**：`local.settings.js` 已加入 `.gitignore`，不会提交到 Git。
+
+## hosts 文件配置
+
+根据 `local.settings.js` 中的 `host` 配置，在系统 hosts 文件添加映射。
+
+**macOS/Linux**：
+
+```bash
+sudo vim /etc/hosts
+# 添加：127.0.0.1 appdev.xxx.com
+```
+
+**示例**：
+如果 `devProxyUrl` 是 `http://bkmonitor.bktencent.com`，则：
+
+```
+127.0.0.1 appdev.bktencent.com
+```
+
+## 模块启动命令速查表
+
+| 模块       | Make 命令           | pnpm 命令           | 说明                  |
+| ---------- | ------------------- | ------------------- | --------------------- |
+| monitor-pc | `make dev-pc`       | `pnpm pc:dev`       | 监控平台主应用 (Vue2) |
+| trace      | `make dev-vue3`     | `pnpm trace:dev`    | 链路追踪 (Vue3)       |
+| apm        | `make dev-apm`      | `pnpm apm:dev`      | 应用性能监控 (Vue2)   |
+| fta        | `make dev-fta`      | `pnpm fta:dev`      | 故障自愈 (Vue2)       |
+| mobile     | `make dev-mobile`   | `pnpm mobile:dev`   | 移动端 (Vue2)         |
+| external   | `make dev-external` | `pnpm external:dev` | 外部应用 (Vue2)       |
+
+**默认端口**：7001（自动寻找可用端口，范围 7001-8888）
+
+## Step 1: 环境检查
+
+运行环境检查脚本：
+
+```bash
+bash .cursor/skills/dev-server/scripts/check-env.sh
+```
+
+### 手动检查要点
+
+| 检查项  | 要求       | 检查命令        |
+| ------- | ---------- | --------------- |
+| Node.js | >= 20.17.0 | `node -v`       |
+| pnpm    | 已安装     | `pnpm -v`       |
+| nvm     | 推荐使用   | `nvm --version` |
+
+**Node.js 版本不符？**
+
+```bash
+nvm install 20.17.0
+nvm use 20.17.0
+```
+
+**pnpm 未安装？**
+
+```bash
+npm i -g pnpm@8
+```
+
+## Step 2: 安装依赖
+
+```bash
+# 使用 nvm 切换版本
+nvm use
+
+# 安装依赖
+pnpm i
+# 或
+make deps
+```
+
+**常见问题**：
+
+- 必须使用 pnpm，项目强制检查 `only-allow pnpm`
+- 如果安装失败，尝试：`pnpm store prune` 然后重试
+
+## Step 6: 验证服务
+
+1. 等待编译完成（控制台显示 `Compiled successfully`）
+2. 访问：`http://appdev.xxx.com:7001`（根据 hosts 配置）
+3. 检查：
+   - 页面正常加载
+   - API 请求返回正常（开发者工具 Network）
+   - 无跨域错误
+
+## 工具脚本
+
+| 脚本               | 用途                             | 命令                                                        |
+| ------------------ | -------------------------------- | ----------------------------------------------------------- |
+| check-env.sh       | 检查开发环境                     | `bash .cursor/skills/dev-server/scripts/check-env.sh`       |
+| generate-config.js | 交互式生成配置                   | `node .cursor/skills/dev-server/scripts/generate-config.js` |
+| setup-config.js    | 非交互式生成/检查配置（AI 使用） | `node .cursor/skills/dev-server/scripts/setup-config.js`    |
+
+## 快速响应模板
+
+**用户询问如何配置开发环境时**：
+
+1. 运行环境检查脚本
+2. 根据检查结果指导修复
+3. 帮助生成 local.settings.js
+4. 指导启动服务
+
+**用户启动失败时**：
+
+1. 询问错误信息
+2. 根据问题速查表定位
+3. 提供具体解决步骤
+4. 验证修复结果

package/knowledge/skills/bk-monitor-dev-server/references/troubleshooting.md

@@ -0,0 +1,353 @@
+# 开发服务器问题排查指南
+
+本文档提供详细的问题排查步骤。
+
+---
+
+## 一、环境问题
+
+### 1.1 Node.js 版本不符
+
+**症状**：
+- 运行命令报错 `Unsupported Node version`
+- 某些语法不支持
+
+**检查**：
+```bash
+node -v
+# 应为 v20.17.0 或更高
+```
+
+**解决**：
+```bash
+# 使用 nvm 切换
+nvm install 20.17.0
+nvm use 20.17.0
+
+# 设为默认版本
+nvm alias default 20.17.0
+
+# 验证
+node -v
+```
+
+### 1.2 pnpm 未安装或版本问题
+
+**症状**：
+- `pnpm: command not found`
+- 运行 `npm install` 被拒绝
+
+**检查**：
+```bash
+pnpm -v
+```
+
+**解决**：
+```bash
+npm i -g pnpm@8
+```
+
+### 1.3 依赖安装失败
+
+**症状**：
+- `pnpm i` 报各种错误
+- 缺少某些模块
+
+**解决步骤**：
+
+1. 清除缓存：
+```bash
+pnpm store prune
+```
+
+2. 删除已有依赖：
+```bash
+rm -rf node_modules
+rm -f pnpm-lock.yaml
+```
+
+3. 重新安装：
+```bash
+pnpm i
+```
+
+4. 如仍失败，检查网络或使用镜像：
+```bash
+pnpm config set registry https://registry.npmmirror.com
+pnpm i
+```
+
+---
+
+## 二、配置问题
+
+### 2.1 local.settings.js 不存在
+
+**症状**：
+- 启动时报 `Cannot find module './local.settings.js'`
+
+**解决**：
+创建 `local.settings.js` 文件，参考 SKILL.md 中的配置模板。
+
+### 2.2 devProxyUrl 配置错误
+
+**症状**：
+- API 请求返回 502/504
+- 请求超时
+
+**检查**：
+1. 确认 devProxyUrl 地址可访问
+2. 确认地址格式正确（包含 `http://` 或 `https://`）
+
+```javascript
+// ✅ 正确
+const devProxyUrl = 'http://bkmonitor.bktencent.com';
+
+// ❌ 错误
+const devProxyUrl = 'bkmonitor.bktencent.com'; // 缺少协议
+const devProxyUrl = 'http://bkmonitor.bktencent.com/'; // 末尾多余斜杠可能影响 host 解析
+```
+
+### 2.3 Cookie/X-CSRFToken 问题
+
+**症状**：
+- API 返回 401 Unauthorized
+- API 返回 403 Forbidden
+- 提示 CSRF 验证失败
+
+**诊断步骤**：
+
+1. 登录目标环境，确认账号有效
+2. 打开开发者工具 → Network
+3. 找到任意 API 请求，检查 Request Headers
+4. 复制完整的 Cookie 值
+5. 复制 X-CSRFToken 值
+6. 更新 local.settings.js
+
+**注意事项**：
+- Cookie 可能包含多个值，用分号分隔，全部复制
+- X-CSRFToken 是单独的 header，不在 Cookie 中
+- Token 有有效期，过期需要重新获取
+
+### 2.4 host 配置与 hosts 文件不匹配
+
+**症状**：
+- 浏览器访问 `appdev.xxx.com:7001` 无法打开
+- DNS 解析失败
+
+**检查**：
+
+1. 查看 local.settings.js 中的 host：
+```javascript
+const host = `appdev.${devProxyUrl.match(/\.([^.]+)\.com\/?/)[1]}.com`;
+console.log(host); // 确认生成的 host 值
+```
+
+2. 检查 hosts 文件：
+```bash
+cat /etc/hosts | grep appdev
+```
+
+3. 确保匹配：
+```
+127.0.0.1 appdev.xxx.com
+```
+
+**macOS 刷新 DNS**：
+```bash
+sudo dscacheutil -flushcache
+sudo killall -HUP mDNSResponder
+```
+
+---
+
+## 三、启动问题
+
+### 3.1 端口被占用
+
+**症状**：
+- 提示 `Port 7001 is already in use`
+
+**诊断**：
+```bash
+lsof -i :7001
+```
+
+**解决**：
+1. 开发服务器会自动寻找可用端口（7001-8888）
+2. 如需手动关闭占用进程：
+```bash
+kill -9 <PID>
+```
+
+### 3.2 编译错误
+
+**症状**：
+- 控制台红色错误信息
+- `Compiled with errors`
+
+**常见原因**：
+
+1. **语法错误**：检查最近修改的代码
+2. **类型错误**：TypeScript 类型不匹配
+3. **导入错误**：模块路径错误
+
+**调试**：
+```bash
+# 查看详细错误
+# 错误信息会显示文件路径和行号
+```
+
+### 3.3 nodemon 重启循环
+
+**症状**：
+- 服务不断重启
+- 控制台刷屏
+
+**原因**：
+- nodemon 监听的文件被频繁修改
+
+**解决**：
+检查 `package.json` 中的 nodemonConfig：
+```json
+"nodemonConfig": {
+  "watch": [
+    "local.settings.js",
+    "webpack.config.js",
+    "pnpm-lock.yaml"
+  ]
+}
+```
+
+确保监听的文件不会被其他进程修改。
+
+---
+
+## 四、请求问题
+
+### 4.1 跨域错误 (CORS)
+
+**症状**：
+- 控制台报 `Access-Control-Allow-Origin` 错误
+- 请求被浏览器阻止
+
+**原因**：
+- 通常是代理配置问题
+
+**检查**：
+1. 确认 local.settings.js 中 `changeOrigin: true`
+2. 确认 `host` header 配置正确
+3. 确认访问地址与 hosts 配置一致
+
+### 4.2 API 返回 404
+
+**症状**：
+- 接口返回 404 Not Found
+
+**检查**：
+1. 确认 API 路径正确
+2. 确认 context 包含该 API 前缀：
+```javascript
+const context = ['/apm', '/rest', '/fta', '/api', ...];
+```
+3. 如有新的 API 前缀，添加到 context 数组
+
+### 4.3 请求被取消
+
+**症状**：
+- Network 中请求状态为 `(canceled)`
+
+**可能原因**：
+1. 组件卸载时取消了请求
+2. 重复请求被取消（needCancel 配置）
+3. 请求超时
+
+---
+
+## 五、页面问题
+
+### 5.1 页面空白
+
+**排查步骤**：
+
+1. 检查控制台是否有 JavaScript 错误
+2. 检查 Network 是否有请求失败
+3. 确认编译成功（无红色错误）
+4. 确认访问地址正确
+
+### 5.2 样式异常
+
+**可能原因**：
+1. SCSS 编译错误
+2. 样式文件未正确导入
+3. 浏览器缓存
+
+**解决**：
+```bash
+# 强制刷新
+Cmd + Shift + R (Mac)
+Ctrl + Shift + R (Windows)
+```
+
+### 5.3 微前端路由问题
+
+**症状**：
+- 路由跳转异常
+- 路径多了或少了前缀
+
+**检查**：
+```javascript
+// 判断微前端环境
+if (window.__POWERED_BY_BK_WEWEB__) {
+  const parentRoute = window.__BK_WEWEB_DATA__?.parentRoute || '/';
+}
+```
+
+---
+
+## 六、性能问题
+
+### 6.1 编译慢
+
+**优化建议**：
+1. 只启动需要的模块
+2. 确保 Node.js 版本正确
+3. 使用 SSD 硬盘
+4. 增加可用内存
+
+### 6.2 热更新慢
+
+**可能原因**：
+1. 项目文件过多
+2. 某些文件变更触发全量编译
+
+**建议**：
+- 减少不必要的文件监听
+- 使用增量编译
+
+---
+
+## 诊断命令速查
+
+```bash
+# 检查 Node 版本
+node -v
+
+# 检查 pnpm
+pnpm -v
+
+# 检查端口占用
+lsof -i :7001
+
+# 检查 hosts 配置
+cat /etc/hosts | grep appdev
+
+# 清除 npm 缓存
+pnpm store prune
+
+# 清除依赖重装
+rm -rf node_modules && pnpm i
+
+# macOS 刷新 DNS
+sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
+```