scan-debug-skill 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # scan-debug-skill
2
2
 
3
3
  这个包包含了一套用于 IDE 的代码扫描与调试技能(Scan & Debug Skill)。
4
- 支持 **Trae** 和 **Cursor** 两种 IDE。
4
+ 主要应用于sonar和奇安信的常见问题快速修复
5
5
 
6
6
  ## 使用方法
7
7
 
package/SKILL.md CHANGED
@@ -1,3 +1,20 @@
1
+ ---
2
+ name: 扫描问题
3
+ description: SonarQube和安全扫描的时候触发。分析并修复 SonarQube 扫描出的代码问题,确保符合安全与质量规范。当用户要求修复 Sonar 问题时调用。
4
+ triggers:
5
+ - sonar问题修复
6
+ - 奇安信问题修复
7
+ - sonar问题扫描
8
+ - 奇安信问题扫描
9
+ - 扫描问题修复
10
+ - 扫描代码问题
11
+ - scan-debug-skill扫描
12
+ - scan-debug-skill
13
+ - scan-debug
14
+ license: MIT
15
+ author: [scan-debug-skill](https://github.com/k73333333/ScanDebugSkill)
16
+ ---
17
+
1
18
  # Sonar 代码质量与安全修复技能集
2
19
 
3
20
  本项目包含针对前端不同技术栈(JS/TS, CSS, HTML)的 SonarQube 修复技能指南。
@@ -17,4 +34,24 @@
17
34
  * 涉及:注释规范、图片/表单/语义化结构、安全合规。
18
35
 
19
36
  ## 使用说明
37
+ 对指定代码/文件/目录进行扫描问题然后根据扫描结果概览进行修复。
38
+
20
39
  请点击上述链接进入相应的技能目录查看详细指南。
40
+
41
+ ## 扫描结果概览输出规则
42
+
43
+ 当用户提供扫描报告或提及多个代码问题时,应首先以表格形式输出扫描结果概览,遵循以下规范:
44
+
45
+ - **表格列**:必须包含 类别、严重程度、问题描述、涉及文件。
46
+ - **严重程度标识**:使用 🔴 高危、🟡 中、🔵 低、⚪ 建议 进行视觉区分。
47
+ - **示例格式**:
48
+
49
+ | 类别 | 严重程度 | 问题描述 | 涉及文件 |
50
+ | :--- | :--- | :--- | :--- |
51
+ | JS/TS 安全 | 🔴 高危 | window.open 缺少 noopener (反向 Tabnabbing 漏洞) | src/views/Assistant.vue |
52
+ | 代码质量 | 🔴 高危 | 遗留 debugger 调试断点 | vite.config.ts |
53
+ | 代码质量 | 🟡 中 | 遗留 console.log 调试日志 | vite.config.ts |
54
+ | CSS 规范 | 🟡 中 | 滥用 !important 破坏级联规则 | src/assets/assistant.css |
55
+ | JS/TS 规范 | 🟡 中 | 使用原生 confirm 阻塞交互 | src/views/Assistant.vue |
56
+ | Vue 规范 | 🔵 低 | v-for 使用 index 作为 key (潜在渲染风险) | src/views/Assistant.vue |
57
+ | 代码风格 | ⚪ 建议 | 变量命名可优化为更具语义化的名称 | src/utils/format.js |
package/css/SKILL.md CHANGED
@@ -1,23 +1,23 @@
1
- ---
2
- name: css-sonar-repair
3
- description: CSS/SASS/LESS 样式代码 SonarQube 扫描问题修复指南,涵盖样式规范、兼容性及最佳实践。
4
- ---
5
-
6
- # Sonar CSS 代码质量与安全修复技能
7
-
8
- 此技能用于指导 AI 助手协助用户修复 SonarQube 及奇安信安全扫描发现的 CSS/SASS/LESS 样式代码问题。
9
-
10
- ## 核心原则
11
- 1. **直接高效**:直接给出修复后的完整代码片段,**始终保持中文输出**。
12
- 2. **规范统一**:严格遵守项目的代码风格与注释规范。
13
- 3. **兼容性优先**:考虑不同浏览器的兼容性回退方案。
14
-
15
- ## 技能索引
16
-
17
- ### 基础规范
18
- - 注释与文档规范 (Hack 注释, 中文注释) → 详见 [comments-documentation](reference/comments-documentation.md)
19
- - CSS 通用最佳实践 (ID 选择器, !important) → 详见 [best-practices](reference/best-practices.md)
20
-
21
- ### 样式规范
22
- - 字体族回退 (Font Family Fallback) → 详见 [font-family-fallback](reference/font-family-fallback.md)
23
- - 重复属性与单位 (Duplicate Properties, Units) → 详见 [duplicate-properties](reference/duplicate-properties.md)
1
+ ---
2
+ name: css-sonar-repair
3
+ description: CSS/SASS/LESS 样式代码 SonarQube 扫描问题修复指南,涵盖样式规范、兼容性及最佳实践。
4
+ ---
5
+
6
+ # Sonar CSS 代码质量与安全修复技能
7
+
8
+ 此技能用于指导 AI 助手协助用户修复 SonarQube 及奇安信安全扫描发现的 CSS/SASS/LESS 样式代码问题。
9
+
10
+ ## 核心原则
11
+ 1. **直接高效**:直接给出修复后的完整代码片段,**始终保持中文输出**。
12
+ 2. **规范统一**:严格遵守项目的代码风格与注释规范。
13
+ 3. **兼容性优先**:考虑不同浏览器的兼容性回退方案。
14
+
15
+ ## 技能索引
16
+
17
+ ### 基础规范
18
+ - 注释与文档规范 (Hack 注释, 中文注释) → 详见 [comments-documentation](reference/comments-documentation.md)
19
+ - CSS 通用最佳实践 (ID 选择器, !important) → 详见 [best-practices](reference/best-practices.md)
20
+
21
+ ### 样式规范
22
+ - 字体族回退 (Font Family Fallback) → 详见 [font-family-fallback](reference/font-family-fallback.md)
23
+ - 重复属性与单位 (Duplicate Properties, Units) → 详见 [duplicate-properties](reference/duplicate-properties.md)
package/html/SKILL.md CHANGED
@@ -16,7 +16,7 @@ description: HTML/Template 代码 SonarQube 扫描问题修复指南,涵盖可
16
16
 
17
17
  ### 基础规范
18
18
  - 注释与文档规范 (中文注释) → 详见 [comments-documentation](reference/comments-documentation.md)
19
- - HTML 语义化结构 (Lang, Doctype, Table) → 详见 [semantic-structure](reference/semantic-structure.md)
19
+ - HTML 语义化结构 (Lang, Doctype, Table, Nesting) → 详见 [semantic-structure](reference/semantic-structure.md)
20
20
 
21
21
  ### 元素规范
22
22
  - 图片替代文本 (Image Alt Text) → 详见 [image-alt-text](reference/image-alt-text.md)
@@ -5,6 +5,10 @@
5
5
  * **Doctype**:每个 HTML 文档必须声明 `<!DOCTYPE html>`。
6
6
  * **Lang 属性**:`<html>` 标签必须包含 `lang` 属性,声明页面语言(如 `lang="zh-CN"`)。
7
7
  * **表格结构**:`<table>` 必须包含 `<caption>` (标题) 或 `summary` 属性(虽已废弃但部分旧标准仍用),以及正确使用 `<thead>`, `<tbody>`, `<tfoot>`。
8
+ * **标签嵌套**:严禁错误的标签嵌套,例如:
9
+ * `<a>` 标签内禁止嵌套其他交互元素(如 `<button>`, `<input>`, `<a>`)。
10
+ * `<p>` 标签内禁止嵌套块级元素(如 `<div>`, `<h1>`, `<ul>`)。
11
+ * `<ul>`/`<ol>` 的直接子元素必须是 `<li>`。
8
12
 
9
13
  ## 示例:链接文本为空
10
14
  **场景**:Sonar 提示 "Links must have discernible text"。
@@ -19,3 +23,21 @@
19
23
  <i class="icon-settings"></i>
20
24
  </a>
21
25
  ```
26
+
27
+ ## 示例:标签错误嵌套
28
+ **场景**:Sonar 提示 "The element 'button' must not appear as a descendant of the 'a' element" 或 "The element 'div' must not appear as a descendant of the 'p' element"。
29
+
30
+ **修复后代码**:
31
+ ```html
32
+ <!-- Non-Compliant: a 标签嵌套 button (非法交互元素嵌套) -->
33
+ <!-- <a href="/login"><button>登录</button></a> -->
34
+
35
+ <!-- Compliant: 使用样式将 a 标签伪装成按钮,或使用 JS 跳转 -->
36
+ <a href="/login" class="btn">登录</a>
37
+
38
+ <!-- Non-Compliant: p 标签嵌套 div (非法块级元素嵌套) -->
39
+ <!-- <p>这是一个段落 <div>错误嵌套</div></p> -->
40
+
41
+ <!-- Compliant: 将外层 p 改为 div -->
42
+ <div>这是一个段落 <div>正确嵌套</div></div>
43
+ ```
package/js/SKILL.md CHANGED
@@ -9,17 +9,21 @@ description: JavaScript/TypeScript 代码 SonarQube 扫描问题修复指南,
9
9
 
10
10
  ## 核心原则
11
11
  1. **直接高效**:直接给出修复后的完整代码片段,**始终保持中文输出**。
12
- 2. **安全优先**:严格遵循 SonarQube 安全热点和奇安信漏洞扫描标准。
13
- 3. **规范统一**:严格遵守项目的代码风格与注释规范。
12
+ 2. **详细注释**:代码逻辑必须包含详细的中文注释(每一步流程),变量和引入也需注释用途。
13
+ 3. **安全优先**:严格遵循 SonarQube 安全热点和奇安信漏洞扫描标准,避免敏感信息泄露。
14
+ 4. **规范统一**:异步操作统一使用 Promise/async/await 并强制捕获异常。
15
+ 5. **模块化建议**:建议使用 ES6 Class 组织代码(特别是 API 封装),分离业务逻辑与组件交互(此为建议非强制)。
14
16
 
15
17
  ## 技能索引
16
18
 
17
19
  ### 基础规范
18
- - 注释与文档规范 (JSDoc, 中文注释) → 详见 [comments-documentation](reference/comments-documentation.md)
19
- - JS/TS 通用最佳实践 (类型判断, 变量声明, 复杂度) → 详见 [js-ts-best-practices](reference/js-ts-best-practices.md)
20
+ - 注释与文档规范 (JSDoc, 详细逻辑注释, 变量注释) → 详见 [comments-documentation](reference/comments-documentation.md)
21
+ - JS/TS 通用最佳实践 (ES6 Class, 异步处理, 日志规范) → 详见 [js-ts-best-practices](reference/js-ts-best-practices.md)
20
22
 
21
23
  ### 框架规范
22
- - Vue/React 框架特定规范 (List Key, Props, Side Effects) → 详见 [framework-vue-react](reference/framework-vue-react.md)
24
+ - Vue/React 框架特定规范 (架构分离, List Key, Props, Side Effects) → 详见 [framework-vue-react](reference/framework-vue-react.md)
23
25
 
24
26
  ### 安全合规
25
27
  - 安全漏洞与合规性 (XSS, 敏感信息, 堆栈泄露) → 详见 [security-compliance](reference/security-compliance.md)
28
+
29
+
@@ -3,20 +3,42 @@
3
3
  ## 规则详情
4
4
  * **语言**:所有注释必须使用 **中文**。
5
5
  * **JSDoc**:导出的函数、类、接口必须包含 JSDoc 注释,说明 `@param` (参数)、`@returns` (返回值) 和 `@throws` (异常)。
6
- * **逻辑解释**:关键的业务逻辑判断、复杂的正则表达式、非显而易见的修复原因,需在代码上方添加单行注释 `//`。
6
+ * **详细逻辑注释**:
7
+ * **流程注释**:代码逻辑的每一个关键步骤和流程分支,都必须有详细的中文单行注释 `//` 说明其意图和处理逻辑。
8
+ * **变量/引入注释**:所有引入的模块 (`import`) 和定义的关键变量 (`const`, `let`),必须在其上方或右侧添加注释,说明其用途或来源。
9
+ * **非显而易见的修复原因**:对于为了修复 Sonar 问题而做的特殊改动,必须注释说明原因。
7
10
 
8
11
  ## 示例
9
12
  ```javascript
13
+ // 引入日期处理工具库
14
+ import { format } from 'date-fns';
15
+
10
16
  /**
11
17
  * 计算两个日期之间的天数差
12
- * @param {Date} startDate - 开始日期
13
- * @param {Date} endDate - 结束日期
14
- * @returns {number} - 天数差(绝对值)
18
+ * @description 用于计算合同期限或逾期天数
19
+ * @param {Date} startDate - 开始日期对象
20
+ * @param {Date} endDate - 结束日期对象
21
+ * @returns {number} - 两个日期之间的天数差(绝对值)
22
+ * @throws {Error} - 如果参数不是有效的日期对象抛出异常
15
23
  */
16
24
  function getDaysDiff(startDate, endDate) {
17
- // 校验参数是否有效
18
- if (!startDate || !endDate) return 0;
25
+ // 1. 参数校验:检查传入的日期对象是否有效
26
+ if (!startDate || !endDate) {
27
+ // 如果日期无效,返回 0 天
28
+ return 0;
29
+ }
30
+
31
+ // 2. 获取时间戳:将日期对象转换为毫秒数
32
+ const startObj = startDate.getTime(); // 开始时间毫秒数
33
+ const endObj = endDate.getTime(); // 结束时间毫秒数
34
+
35
+ // 3. 计算差值:取绝对值以确保结果为正数
36
+ const diffTime = Math.abs(endObj - startObj);
19
37
 
20
- // ...
38
+ // 定义一天的毫秒数常量
39
+ const ONE_DAY_MS = 1000 * 60 * 60 * 24;
40
+
41
+ // 4. 转换天数:向上取整,不足一天按一天计算(根据业务需求调整)
42
+ return Math.ceil(diffTime / ONE_DAY_MS);
21
43
  }
22
44
  ```
@@ -1,10 +1,71 @@
1
1
  # 前端框架规范 (Vue/React)
2
2
 
3
3
  ## 规则详情
4
+ * **架构分离 (Architecture Separation)**:
5
+ * **业务逻辑抽离**:复杂的业务逻辑(如数据处理、API 请求组合)必须从组件中抽离,封装到独立的 `Service` 类或工具函数中(此为建议非强制)。
6
+ * **组件职责**:UI 组件应仅负责视图渲染、用户交互响应和简单的状态管理(此为建议非强制)。
4
7
  * **列表渲染**:`v-for` (Vue) 或 `map` (React) 循环渲染时,必须提供唯一的 `key`,且**避免使用数组索引 (index) 作为 key**(除非列表是静态且不排序的)。
5
8
  * **Props 验证**:组件接收的 Props 必须定义类型验证和默认值。
6
9
  * **副作用清理**:在组件销毁生命周期(`beforeUnmount`, `useEffect cleanup`)中,必须清理定时器、事件监听器等副作用。
7
10
 
11
+ ## 示例:架构分离与副作用清理
12
+
13
+ **场景**:组件内包含了大量的数据获取和处理逻辑,且使用了定时器。
14
+
15
+ **修复后代码 (React 示例)**:
16
+
17
+ ```javascript
18
+ // 1. 业务逻辑抽离 (UserService.js)
19
+ import { api } from './api';
20
+
21
+ export class UserService {
22
+ /**
23
+ * 轮询获取用户状态
24
+ * @param {string} userId - 用户ID
25
+ * @returns {Promise<Object>} - 用户状态
26
+ */
27
+ static async fetchStatus(userId) {
28
+ try {
29
+ return await api.get(`/user/${userId}/status`);
30
+ } catch (error) {
31
+ console.error('UserService: 获取状态失败');
32
+ return null;
33
+ }
34
+ }
35
+ }
36
+
37
+ // 2. 组件逻辑 (UserStatus.jsx)
38
+ import React, { useEffect, useState } from 'react';
39
+ import { UserService } from './UserService';
40
+
41
+ export function UserStatus({ userId }) {
42
+ const [status, setStatus] = useState(null);
43
+
44
+ useEffect(() => {
45
+ let timerId = null;
46
+
47
+ const loadData = async () => {
48
+ // 调用抽离的业务逻辑
49
+ const data = await UserService.fetchStatus(userId);
50
+ if (data) setStatus(data);
51
+ };
52
+
53
+ // 初始加载
54
+ loadData();
55
+
56
+ // 设置轮询
57
+ timerId = setInterval(loadData, 5000);
58
+
59
+ // Compliant: 清理副作用
60
+ return () => {
61
+ if (timerId) clearInterval(timerId);
62
+ };
63
+ }, [userId]);
64
+
65
+ return <div>状态: {status}</div>;
66
+ }
67
+ ```
68
+
8
69
  ## 示例:Vue/React 列表 Key 问题
9
70
 
10
71
  **场景**:Sonar 提示 "Use a unique value for the key attribute"。
@@ -1,14 +1,24 @@
1
1
  # JS/TS 通用最佳实践
2
2
 
3
3
  ## 规则详情
4
+ * **模块化与组织 (Class-based)**:
5
+ * 优先使用 ES6 Class 语法进行模块化组织,特别是 API 请求封装。
6
+ * 通过继承 (`extends`) 实现常量和通用逻辑的复用。
7
+ * **异步处理 (Async/Await)**:
8
+ * 统一采用 `Promise` / `async/await` 进行异步处理。
9
+ * **强制捕获异常**:所有 Promise 调用必须追加 `.catch()` 方法或包裹在 `try...catch` 中。
10
+ * **异常处理规范**:
11
+ * **严禁空 Catch**:`catch` 块或 `.catch()` 回调中必须包含处理逻辑,禁止留空。
12
+ * **安全打印**:遵循 [安全合规规范 - 日志安全](security-compliance.md) 要求,严禁打印堆栈信息。
13
+ * **日志与异常 (Logging)**:
14
+ * **分级打印**:建议根据场景正确使用 `console.error()` (错误), `console.warn()` (警告), `console.info()` (信息)。
15
+ * **异常输出**:避免打印冗余的堆栈详情 (`error.stack`),仅输出关键信息(如 `***方法报错/接口请求失败`)。
4
16
  * **强类型判断**:始终使用 `===` 和 `!==` 代替 `==` 和 `!=`,避免隐式类型转换带来的 Bug。
5
17
  * **变量声明**:优先使用 `const`,其次使用 `let`,**严禁使用 `var`**。
6
- * **认知复杂度 (Cognitive Complexity)**:当 Sonar 提示函数复杂度过高(通常 > 15)时,必须将逻辑拆分为多个职责单一的子函数。
18
+ * **认知复杂度 (Cognitive Complexity)**:当 Sonar 提示函数复杂度过高(通常 > 15)时,须逻辑拆分为多个职责单一的子函数(此为建议非强制)。
7
19
  * **魔法数字 (Magic Numbers)**:避免直接使用无意义的数字(0 和 1 除外),应将其定义为具名常量。
8
- * **异步处理**:
9
- * 优先使用 `async/await`。
10
- * 所有 Promise 链必须以 `.catch()` 结束,或在 `try...catch` 块中处理错误。
11
20
  * **冗余条件判断**:当 `if` 和 `else` 分支执行逻辑完全一致时,应移除条件判断,直接执行公共逻辑。
21
+ * **空值检查 (Null Safety)**:在访问对象的深层属性前,必须进行非空检查,推荐使用可选链操作符 (`?.`) 和空值合并操作符 (`??`),避免 "Cannot read property of undefined" 错误。
12
22
 
13
23
  ## 示例:认知复杂度与魔法数字
14
24
 
@@ -61,3 +71,36 @@ function handleRedirect() {
61
71
  navigateTo('/home');
62
72
  }
63
73
  ```
74
+
75
+ ## 示例:空指针异常修复
76
+
77
+ **场景**:代码运行时抛出 "TypeError: Cannot read property 'name' of undefined",或 Sonar 提示可能存在空指针访问风险。
78
+
79
+ **修复后代码**:
80
+ ```javascript
81
+ /**
82
+ * 获取用户显示名称
83
+ * @param {Object} user - 用户对象
84
+ * @returns {string} - 用户名称或默认值
85
+ */
86
+ function getUserDisplayName(user) {
87
+ // Non-Compliant: 如果 user 或 user.profile 为空,将导致程序崩溃
88
+ // return user.profile.name;
89
+
90
+ // Compliant: 使用可选链 (?.) 安全访问,并提供默认值 (??)
91
+ return user?.profile?.name ?? '未知用户';
92
+ }
93
+
94
+ /**
95
+ * 处理订单列表
96
+ * @param {Array} orders - 订单数组
97
+ */
98
+ function processOrders(orders) {
99
+ // Compliant: 确保 orders 存在且为数组后再进行遍历
100
+ if (Array.isArray(orders) && orders.length > 0) {
101
+ orders.forEach(order => {
102
+ console.log(`订单ID: ${order?.id}`);
103
+ });
104
+ }
105
+ }
106
+ ```
@@ -5,10 +5,27 @@
5
5
  * 严禁使用 `eval()`、`new Function()`。
6
6
  * 慎用 `v-html` (Vue) 或 `dangerouslySetInnerHTML` (React),必须确保内容已经过 DOMPurify 等库的清洗。
7
7
  * **敏感信息**:代码中禁止硬编码密码、Token、密钥(AK/SK)、内网 IP 等敏感信息,应通过环境变量或配置接口获取。
8
- * **日志安全**:禁止在生产环境日志中输出敏感信息(如密码、Token 等);**若变量名无明确语义化(如 `data`, `info`, `res`),视为潜在敏感信息禁止直接打印**;异常捕获时仅记录错误来源或通用提示,**严禁直接打印 `error.stack` 或完整的 `error` 对象**,防止堆栈信息泄露系统内部结构。
8
+ * **日志安全**:
9
+ * 禁止在生产环境日志中输出敏感信息(如密码、Token 等)。
10
+ * **变量命名**:若变量名无明确语义化(如 `data`, `info`, `res`),视为潜在敏感信息禁止直接打印。
11
+ * **异常捕获**:**严禁直接打印 `error.stack` 或完整的 `error` 对象**。如无法确定 `error` 结构则不打印 `error`,必须按照 **模块名 + 方法名 + 错误简述** 的格式输出,防止堆栈信息泄露系统内部结构。
9
12
  * **链接安全**:使用 `target="_blank"` 打开外部链接时,必须添加 `rel="noopener noreferrer"` 以防止钓鱼攻击。
10
13
  * **正则安全**:确保正则表达式不会导致拒绝服务攻击 (ReDoS)。
11
14
 
15
+ ## 示例:敏感信息处理
16
+
17
+ **场景**:Sonar 提示 "Hardcoded passwords/tokens/keys should not be used"。
18
+
19
+ **修复后代码**:
20
+ ```javascript
21
+ // Non-Compliant: 硬编码敏感信息
22
+ // const API_KEY = "sk-123456789";
23
+
24
+ // Compliant: 使用环境变量
25
+ // 说明:确保环境变量在构建或运行时已正确注入
26
+ const API_KEY = process.env.VUE_APP_API_KEY;
27
+ ```
28
+
12
29
  ## 示例:日志安全与异常处理
13
30
 
14
31
  **场景**:Sonar/安全扫描提示 "User credentials should not be printed" 或 "Stack traces should not be disclosed"。
@@ -34,7 +51,8 @@ async function handleLogin(username, password) {
34
51
  // Non-Compliant: console.error(error); 或 console.error(error.stack);
35
52
 
36
53
  // Compliant: 仅记录错误来源,不包含详细堆栈
37
- console.error('LoginService: 用户登录请求失败');
54
+ // 格式要求:模块名 + 方法名 + 错误简述
55
+ console.error('LoginService: handleLogin 方法报错/接口请求失败');
38
56
  }
39
57
  }
40
58
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "scan-debug-skill",
3
- "version": "1.0.2",
3
+ "version": "1.0.3",
4
4
  "description": "ScanDebugSkill for Trae IDE - Easily install debugging skills via npx",
5
5
  "bin": {
6
6
  "scan-debug-skill": "./bin/install.js"