scan-debug-skill 1.0.5 → 1.0.7

package/README.md

@@ -1,26 +1,64 @@
-# scan-debug-skill
-
-一套用于代码扫描与调试技能（Scan & Debug Skill）。
-主要应用于sonar和奇安信的常见问题快速修复
-
-## 使用方法
-
-### 通过 npx 安装
-
-在您的项目根目录下运行以下命令：
-
-```bash
-npx scan-debug-skill
-```
-
-运行后，脚本会提示您选择安装目标：
-
-1.  **Trae**：安装到 `.trae/scan-debug-skill`
-2.  **Cursor**：安装到 `.cursor/scan-debug-skill`
-3.  **Custom**：安装到指定目录
-
-### 包含的内容
-
-- CSS 最佳实践与规范
-- HTML 语义化与安全规范
-- JS/TS 编码规范与安全指南
+# scan-debug-skill
+
+一套用于代码扫描与调试技能（Scan & Debug Skill）。
+主要应用于 SonarQube 和奇安信的常见问题快速修复。
+
+A set of code scanning and debugging skills (Scan & Debug Skill).
+Primarily used for quick fixes of common SonarQube and Qianxin issues.
+
+## 使用方法 / Usage
+
+### 通过 npx 安装 / Install via npx
+
+在您的项目根目录下运行以下命令：
+Run the following command in your project root directory:
+
+```bash
+npx scan-debug-skill
+```
+
+运行后，脚本会提示您选择安装目标：
+After running, the script will prompt you to select an installation target:
+
+1.  **Trae**：安装到 `.trae/scan-debug-skill` (Install to `.trae/scan-debug-skill`)
+2.  **Cursor**：安装到 `.cursor/scan-debug-skill` (Install to `.cursor/scan-debug-skill`)
+3.  **Custom**：安装到指定目录 (Install to a specified directory)
+
+### 包含的内容 / Contents
+
+- CSS 最佳实践与规范 / CSS Best Practices & Standards
+- HTML 语义化与安全规范 / HTML Semantics & Security Standards
+- JS/TS 编码规范与安全指南 / JS/TS Coding Standards & Security Guidelines
+
+### AI 辅助编码 / AI Assisted Coding
+
+在编辑器中使用 AI 生成或修复代码时，可以通过以下提示词引用此规范：
+When using AI to generate or fix code in the editor, you can reference this standard with the following prompts:
+
+- "请根据 `scan-debug-skill` 规范修复当前文件的 Sonar 问题"
+  "Please fix Sonar issues in the current file according to `scan-debug-skill` standards"
+- "生成一段 API 请求代码，要求符合 `scan-debug-skill` 中的 JS 安全规范"
+  "Generate API request code that complies with the JS security standards in `scan-debug-skill`"
+
+### 项目规则引用 / Project Rules Reference
+
+您可以在 `.cursorrules` 或 `.trae/rules` 文件中添加以下规则，以确保 AI 始终遵循此规范：
+You can add the following rules to your `.cursorrules` or `.trae/rules` file to ensure AI always follows this standard:
+```
+- When fixing issues, refer to the specific rules in the `scan-debug-skill` documentation.
+```
+
+## 注意事项 / Notes
+
+⚠️ **资源消耗提醒 (Resource Consumption Warning)**
+
+对整个项目进行全量扫描并自动修复可能会消耗大量的 AI 编码请求次数（Tokens）。
+Scanning and automatically fixing the entire project may consume a large amount of AI coding requests (Tokens).
+
+**建议做法 (Recommended Practice)**：
+1.  **按需引用**：在生成新代码时，直接引用本技能规范（如上文 "AI 辅助编码" 所示），从源头保证代码质量。
+2.  **局部修复**：针对单个文件或特定文件夹进行扫描和修复，避免全量操作，以节约资源。
+
+**Recommendation**:
+1.  **Reference on Demand**: When generating new code, directly reference this skill standard (as shown in "AI Assisted Coding" above) to ensure code quality from the start.
+2.  **Partial Fix**: Scan and fix specific files or folders instead of the entire project to save resources.

package/SKILL.md

@@ -22,8 +22,8 @@ author: [scan-debug-skill](https://github.com/k73333333/ScanDebugSkill)
 ## 目录结构
 
 *   **[JS/TS 修复技能](./js/SKILL.md)**
-    *   包含 JavaScript、TypeScript、Vue、React 的修复规则。
-    *   涉及：注释规范、最佳实践、框架规范、安全合规。
+    *   包含 JavaScript、TypeScript 的修复规则。
+    *   涉及：注释规范、最佳实践、安全合规。
 
 *   **[CSS 修复技能](./css/SKILL.md)**
     *   包含 CSS、SASS、LESS 的样式修复规则。
@@ -38,6 +38,17 @@ author: [scan-debug-skill](https://github.com/k73333333/ScanDebugSkill)
 
 请点击上述链接进入相应的技能目录查看详细指南。
 
+### 引用指南
+
+在编辑器中使用 AI 助手生成或修复代码时，可以通过以下方式引用本规范：
+
+1.  **代码生成**：在生成代码时，显式要求遵循 `scan-debug-skill` 规范。
+    > "生成一段 API 请求代码，请遵循 `scan-debug-skill` 中的 JS 安全规范。"
+2.  **问题修复**：在修复代码问题时，要求 AI 参考本技能集。
+    > "请按照 `scan-debug-skill` 修复当前代码的 Sonar 问题。"
+3.  **项目规则配置**：在项目的 `.cursorrules` 或 `.trae/rules` 文件中配置全局引用，使 AI 默认遵循此规范。
+    > "Follow the `scan-debug-skill` standards for all code generation and fixes."
+
 ## 扫描结果概览输出规则
 
 当用户提供扫描报告或提及多个代码问题时，应首先以表格形式输出扫描结果概览，遵循以下规范：

package/bin/install.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 /*
- * @Author: fukaidong fukaidong@aspirecn.com
+ * @Author: fukaidong
  * @Date: 2026-02-25 15:50:10
- * @LastEditors: fukaidong fukaidong@aspirecn.com
- * @LastEditTime: 2026-02-25 16:15:00
+ * @LastEditors: fukaidong qiji777@yeah.net
+ * @LastEditTime: 2026-02-26 18:33:02
  * @Description: scan-debug-skill 安装脚本 (ScanDebugSkill Install Script)
  *               包含更新处理逻辑：安装前清理旧版本核心目录，确保无残留文件。
  */

package/css/reference/best-practices.md

@@ -6,6 +6,24 @@
 *   **单位统一**：
     *   当值为 `0` 时，省略单位（如 `0px` -> `0`）。
     *   避免使用绝对单位（如 `cm`, `in`），除非在打印样式表中。
+*   **命名规范**：推荐使用 **BEM (Block Element Modifier)** 命名规则，提高样式的可维护性和复用性。
+    *   Block: `.block`
+    *   Element: `.block__element`
+    *   Modifier: `.block--modifier`
+
+## 示例：BEM 命名规范
+**场景**：样式类名杂乱，层级嵌套过深，难以维护。
+
+**修复后代码**：
+```css
+/* Non-Compliant: 嵌套过深，命名无结构 */
+.list .item .active { ... }
+
+/* Compliant: BEM 命名 */
+.user-list { }                 /* Block */
+.user-list__item { }           /* Element */
+.user-list__item--active { }   /* Modifier */
+```
 
 ## 示例：省略零值单位
 **场景**：Sonar 提示 "Unexpected unit"。

package/js/SKILL.md

@@ -19,9 +19,7 @@ description: JavaScript/TypeScript 代码 SonarQube 扫描问题修复指南，
 ### 基础规范
 - 注释与文档规范 (JSDoc, 详细逻辑注释, 变量注释) → 详见 [comments-documentation](reference/comments-documentation.md)
 - JS/TS 通用最佳实践 (ES6 Class, 异步处理, 日志规范) → 详见 [js-ts-best-practices](reference/js-ts-best-practices.md)
-
-### 框架规范
-- Vue/React 框架特定规范 (架构分离, List Key, Props, Side Effects) → 详见 [framework-vue-react](reference/framework-vue-react.md)
+- 代码命名与工程规范 (目录命名, 变量命名, Hooks) → 详见 [naming-conventions](reference/naming-conventions.md)
 
 ### 安全合规
 - 安全漏洞与合规性 (XSS, 敏感信息, 堆栈泄露) → 详见 [security-compliance](reference/security-compliance.md)

package/js/reference/js-ts-best-practices.md

@@ -19,6 +19,16 @@
 *   **魔法数字 (Magic Numbers)**：避免直接使用无意义的数字（0 和 1 除外），应将其定义为具名常量。
 *   **冗余条件判断**：当 `if` 和 `else` 分支执行逻辑完全一致时，应移除条件判断，直接执行公共逻辑。
 *   **空值检查 (Null Safety)**：在访问对象的深层属性前，必须进行非空检查，推荐使用可选链操作符 (`?.`) 和空值合并操作符 (`??`)，避免 "Cannot read property of undefined" 错误。
+*   **性能优化**：
+    *   **正则表达式预编译**：避免在循环内创建 `RegExp` 实例，应提取到循环外部或模块作用域。
+    *   **避免嵌套循环**：3 层以上的嵌套循环（O(n³)）必须优化，建议使用 `flatMap` 或 Map 索引。
+    *   **字符串拼接**：循环内避免使用 `+=` 拼接大量字符串，应使用数组 `push` 后 `join`。
+*   **异常处理**：
+    *   **禁止 Finally Return**：`finally` 块中严禁使用 `return`，否则会覆盖 `try/catch` 中的异常抛出。
+    *   **流程控制**：禁止使用异常（try-catch）来处理正常的业务流程控制（如判断 JSON 格式，应先用正则预判）。
+*   **状态管理**：
+    *   **状态回滚**：前端乐观更新（Optimistic UI）时，若请求失败必须回滚状态。
+    *   **避免全局锁**：避免使用单一的全局 `loading` 状态控制并发请求，应使用独立的 loading 变量。
 
 ## 示例：认知复杂度与魔法数字
 
@@ -104,3 +114,42 @@ function processOrders(orders) {
   }
 }
 ```
+
+## 示例：性能优化与异常处理
+
+**场景**：Sonar 提示 "Regular expressions should not be created in a loop" 或 "Jump statements should not occur in finally blocks"。
+
+**修复后代码**：
+```javascript
+// 1. 正则预编译
+// Non-Compliant: 循环内重复创建正则
+// items.forEach(item => { if (new RegExp('^\\d{4}').test(item)) ... })
+
+// Compliant: 提取为常量
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+items.forEach(item => {
+  if (DATE_PATTERN.test(item.date)) { /* ... */ }
+});
+
+// 2. 字符串拼接优化
+// Non-Compliant: 使用 += 拼接
+// let html = ""; list.forEach(i => html += `<li>${i}</li>`);
+
+// Compliant: 使用 Array.join
+const html = list.map(i => `<li>${i}</li>`).join("");
+
+// 3. 禁止 Finally Return
+async function submitData() {
+  try {
+    await api.post('/submit');
+  } catch (error) {
+    console.error('提交失败', error);
+    return Promise.reject(error);
+  } finally {
+    // Non-Compliant: return true; // 这会吞掉上面的 reject
+    
+    // Compliant: 仅做清理工作
+    this.loading = false;
+  }
+}
+```

package/js/reference/naming-conventions.md

@@ -0,0 +1,78 @@
+# 代码命名与工程规范
+
+## 规则详情
+
+*   **目录与文件命名**：
+    *   统一使用 `kebab-case`（短横线连接），例如 `src/components/user-list.js`、`src/hooks/use-user-info.ts`。
+    *   组件/类文件可使用 `PascalCase`（大驼峰）或 `kebab-case`，但项目中应保持统一。
+*   **组件/类命名**：
+    *   文件名：`UserList.ts` 或 `user-list.ts`。
+    *   类名：`UserList` (PascalCase)。
+    *   使用时：`new UserList()` (PascalCase)。
+*   **变量与函数命名**：
+    *   变量/函数：使用 `camelCase`（小驼峰），例如 `userInfo`, `fetchData`。
+    *   常量：使用 `UPPER_CASE`（全大写下划线），例如 `MAX_COUNT`, `API_BASE_URL`。
+    *   **方法名**：必须使用动宾结构，例如 `getUserList` (获取), `handleSubmit` (处理), `isFinished` (判断)。
+    *   **布尔变量**：推荐以 `is`, `has`, `should` 开头，例如 `isVisible`, `hasError`。
+*   **类型与接口命名**：
+    *   统一使用 `PascalCase`（大驼峰），例如 `interface UserInfo {}`, `type ApiResponse = {}`。
+    *   不要使用下划线命名法（如 `user_info`）。
+*   **Hooks 命名**：
+    *   文件名：`use-auth.ts` (kebab-case)。
+    *   导出函数：`useAuth` (camelCase，以 use 开头)。
+
+## 示例：命名规范
+
+**场景**：Sonar 提示 "Rename this file to match the regular expression..." 或 "Identifier 'xxx' does not match usage"。
+
+**修复后代码**：
+```typescript
+// 文件名: src/hooks/use-user-info.ts
+
+// Non-Compliant: 接口命名不规范
+// interface user_info {}
+
+// Compliant: 接口使用 PascalCase
+export interface UserInfo {
+  id: number;
+  name: string;
+}
+
+// Non-Compliant: 函数名无动宾结构
+// function data() {}
+
+// Compliant: 函数名动宾结构，变量小驼峰
+export function useUserInfo() {
+  const isLoading = ref(false);
+
+  async function fetchUserData() {
+    // ...
+  }
+
+  return {
+    isLoading,
+    fetchUserData
+  };
+}
+```
+
+## 示例：目录结构分层
+
+**场景**：代码耦合度高，API 请求散落在组件中。
+
+**修复后代码**：
+```javascript
+// ❌ Non-Compliant: API 请求写在组件/UI层内部
+// src/components/UserList.ts
+const res = await axios.post("/api/user/list", data);
+
+// ✅ Compliant: API 调用集中在 src/api/，UI层只调用服务
+// src/api/user.ts
+export function fetchUserList(data) {
+  return request.post('/api/user/list', data);
+}
+
+// src/components/UserList.ts
+import { fetchUserList } from "@/api/user";
+const res = await fetchUserList(data);
+```

package/js/reference/security-compliance.md

@@ -3,7 +3,7 @@
 ## 规则详情
 *   **XSS 防范**：
     *   严禁使用 `eval()`、`new Function()`。
-    *   慎用 `v-html` (Vue) 或 `dangerouslySetInnerHTML` (React)，必须确保内容已经过 DOMPurify 等库的清洗。
+    *   处理用户输入的 HTML 内容时，必须确保内容已经过 DOMPurify 等库的清洗，避免直接插入未过滤的 HTML。
 *   **敏感信息**：代码中禁止硬编码密码、Token、密钥（AK/SK）、内网 IP 等敏感信息，应通过环境变量或配置接口获取。
 *   **日志安全**：
     *   禁止在生产环境日志中输出敏感信息（如密码、Token 等）。
@@ -23,7 +23,7 @@
 
 // Compliant: 使用环境变量
 // 说明：确保环境变量在构建或运行时已正确注入
-const API_KEY = process.env.VUE_APP_API_KEY;
+const API_KEY = process.env.API_KEY;
 ```
 
 ## 示例：日志安全与异常处理

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scan-debug-skill",
-  "version": "1.0.5",
-  "description": "一套用代码扫描与调试技能（Scan & Debug Skill）。主要应用于sonar和奇安信的常见问题快速修复",
+  "version": "1.0.7",
+  "description": "A set of code scanning and debugging skills, primarily for quick fixes of common SonarQube and Qianxin issues. | 一套代码扫描与调试技能，主要应用于 SonarQube 和奇安信常见问题的快速修复。",
   "bin": {
     "scan-debug-skill": "./bin/install.js"
   },
@@ -12,7 +12,10 @@
     "trae",
     "skill",
     "debug",
-    "scan"
+    "scan",
+    "sonar 扫描和问题修复",
+    "奇安信 扫描和问题修复",
+    "代码扫描修复skill"
   ],
   "author": "",
   "license": "MIT",

package/js/reference/framework-vue-react.md

@@ -1,80 +0,0 @@
-# 前端框架规范 (Vue/React)
-
-## 规则详情
-*   **架构分离 (Architecture Separation)**：
-    *   **业务逻辑抽离**：复杂的业务逻辑（如数据处理、API 请求组合）必须从组件中抽离，封装到独立的 `Service` 类或工具函数中（此为建议非强制）。
-    *   **组件职责**：UI 组件应仅负责视图渲染、用户交互响应和简单的状态管理（此为建议非强制）。
-*   **列表渲染**：`v-for` (Vue) 或 `map` (React) 循环渲染时，必须提供唯一的 `key`，且**避免使用数组索引 (index) 作为 key**（除非列表是静态且不排序的）。
-*   **Props 验证**：组件接收的 Props 必须定义类型验证和默认值。
-*   **副作用清理**：在组件销毁生命周期（`beforeUnmount`, `useEffect cleanup`）中，必须清理定时器、事件监听器等副作用。
-
-## 示例：架构分离与副作用清理
-
-**场景**：组件内包含了大量的数据获取和处理逻辑，且使用了定时器。
-
-**修复后代码 (React 示例)**：
-
-```javascript
-// 1. 业务逻辑抽离 (UserService.js)
-import { api } from './api';
-
-export class UserService {
-  /**
-   * 轮询获取用户状态
-   * @param {string} userId - 用户ID
-   * @returns {Promise<Object>} - 用户状态
-   */
-  static async fetchStatus(userId) {
-    try {
-      return await api.get(`/user/${userId}/status`);
-    } catch (error) {
-      console.error('UserService: 获取状态失败');
-      return null;
-    }
-  }
-}
-
-// 2. 组件逻辑 (UserStatus.jsx)
-import React, { useEffect, useState } from 'react';
-import { UserService } from './UserService';
-
-export function UserStatus({ userId }) {
-  const [status, setStatus] = useState(null);
-
-  useEffect(() => {
-    let timerId = null;
-
-    const loadData = async () => {
-      // 调用抽离的业务逻辑
-      const data = await UserService.fetchStatus(userId);
-      if (data) setStatus(data);
-    };
-
-    // 初始加载
-    loadData();
-
-    // 设置轮询
-    timerId = setInterval(loadData, 5000);
-
-    // Compliant: 清理副作用
-    return () => {
-      if (timerId) clearInterval(timerId);
-    };
-  }, [userId]);
-
-  return <div>状态: {status}</div>;
-}
-```
-
-## 示例：Vue/React 列表 Key 问题
-
-**场景**：Sonar 提示 "Use a unique value for the key attribute"。
-
-**修复后代码**：
-```html
-<!-- Compliant: 使用数据的唯一 ID 作为 key -->
-<div v-for="item in list" :key="item.id">
-  <!-- 显示用户名称 -->
-  {{ item.name }}
-</div>
-```