scan-debug-skill 1.0.0

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 ADDED
@@ -0,0 +1,26 @@
1
+ # scan-debug-skill
2
+
3
+ 这个包包含了一套用于 IDE 的代码扫描与调试技能(Scan & Debug Skill)。
4
+ 支持 **Trae** 和 **Cursor** 两种 IDE。
5
+
6
+ ## 使用方法
7
+
8
+ ### 通过 npx 安装
9
+
10
+ 在您的项目根目录下运行以下命令:
11
+
12
+ ```bash
13
+ npx scan-debug-skill
14
+ ```
15
+
16
+ 运行后,脚本会提示您选择安装目标:
17
+
18
+ 1. **Trae**:安装到 `.trae/scan-debug-skill`
19
+ 2. **Cursor**:安装到 `.cursor/scan-debug-skill`
20
+ 3. **Both**:同时安装到上述两个位置
21
+
22
+ ### 包含的内容
23
+
24
+ - CSS 最佳实践与规范
25
+ - HTML 语义化与安全规范
26
+ - JS/TS 编码规范与安全指南
package/SKILL.md ADDED
@@ -0,0 +1,20 @@
1
+ # Sonar 代码质量与安全修复技能集
2
+
3
+ 本项目包含针对前端不同技术栈(JS/TS, CSS, HTML)的 SonarQube 修复技能指南。
4
+
5
+ ## 目录结构
6
+
7
+ * **[JS/TS 修复技能](./js/SKILL.md)**
8
+ * 包含 JavaScript、TypeScript、Vue、React 的修复规则。
9
+ * 涉及:注释规范、最佳实践、框架规范、安全合规。
10
+
11
+ * **[CSS 修复技能](./css/SKILL.md)**
12
+ * 包含 CSS、SASS、LESS 的样式修复规则。
13
+ * 涉及:注释规范、通用实践、字体回退、重复属性。
14
+
15
+ * **[HTML 修复技能](./html/SKILL.md)**
16
+ * 包含 HTML 结构、语义化及可访问性修复规则。
17
+ * 涉及:注释规范、图片/表单/语义化结构、安全合规。
18
+
19
+ ## 使用说明
20
+ 请点击上述链接进入相应的技能目录查看详细指南。
package/bin/install.js ADDED
@@ -0,0 +1,171 @@
1
+ #!/usr/bin/env node
2
+
3
+ /*
4
+ * @Author: fukaidong fukaidong@aspirecn.com
5
+ * @Date: 2026-02-25 15:50:10
6
+ * @LastEditors: fukaidong fukaidong@aspirecn.com
7
+ * @LastEditTime: 2026-02-25 16:15:00
8
+ * @Description: scan-debug-skill 安装脚本 (ScanDebugSkill Install Script)
9
+ * 包含更新处理逻辑:安装前清理旧版本核心目录,确保无残留文件。
10
+ */
11
+
12
+ const fs = require('fs');
13
+ const path = require('path');
14
+ const readline = require('readline');
15
+
16
+ /**
17
+ * 递归复制目录或文件
18
+ * @param {string} src - 源路径
19
+ * @param {string} dest - 目标路径
20
+ */
21
+ function copyRecursiveSync(src, dest) {
22
+ const stats = fs.statSync(src);
23
+ const isDirectory = stats.isDirectory();
24
+
25
+ if (isDirectory) {
26
+ // 如果目标目录不存在,则创建
27
+ if (!fs.existsSync(dest)) {
28
+ fs.mkdirSync(dest, { recursive: true });
29
+ }
30
+ // 遍历源目录下的所有文件和子目录
31
+ fs.readdirSync(src).forEach((childItemName) => {
32
+ copyRecursiveSync(path.join(src, childItemName), path.join(dest, childItemName));
33
+ });
34
+ } else {
35
+ // 如果是文件,确保目标文件的父目录存在
36
+ const destDir = path.dirname(dest);
37
+ if (!fs.existsSync(destDir)) {
38
+ fs.mkdirSync(destDir, { recursive: true });
39
+ }
40
+ // 复制文件 (fs.copyFileSync 默认会覆盖已存在的同名文件)
41
+ fs.copyFileSync(src, dest);
42
+ }
43
+ }
44
+
45
+ /**
46
+ * 执行安装操作,将资源复制到目标目录
47
+ * 包含更新逻辑:先清理旧目录,再复制新目录
48
+ * @param {string} targetDir - 目标安装目录
49
+ */
50
+ function install(targetDir) {
51
+ // 源目录:当前脚本所在目录的上级目录 (package root)
52
+ const sourceDir = path.resolve(__dirname, '..');
53
+
54
+ console.log(`\n🚀 开始安装/更新 scan-debug-skill...`);
55
+ console.log(`📂 源路径 (Source): ${sourceDir}`);
56
+ console.log(`🎯 目标路径 (Target): ${targetDir}\n`);
57
+
58
+ try {
59
+ // 确保目标根目录存在
60
+ if (!fs.existsSync(targetDir)) {
61
+ console.log(`Creating target directory: ${targetDir}`);
62
+ fs.mkdirSync(targetDir, { recursive: true });
63
+ } else {
64
+ console.log(`ℹ️ 目标目录已存在,准备进行更新... (Target exists, preparing to update)`);
65
+ }
66
+
67
+ // 需要复制的文件和文件夹列表
68
+ // 包含 css, html, js 目录以及 SKILL.md 说明文件
69
+ const itemsToCopy = ['css', 'html', 'js', 'SKILL.md'];
70
+
71
+ itemsToCopy.forEach(item => {
72
+ const srcPath = path.join(sourceDir, item);
73
+ const destPath = path.join(targetDir, item);
74
+
75
+ if (fs.existsSync(srcPath)) {
76
+ // --- 更新处理逻辑 START ---
77
+ // 如果目标是一个已存在的目录,先将其删除。
78
+ // 这样做是为了确保新版本删除了某些文件时,目标目录也能同步删除这些废弃文件(避免脏数据)。
79
+ // 仅对我们明确管理的子目录执行此操作,避免误删用户在根目录下放的其他文件。
80
+ if (fs.existsSync(destPath)) {
81
+ const destStats = fs.statSync(destPath);
82
+ if (destStats.isDirectory()) {
83
+ // Node.js 14.14.0+ 支持 fs.rmSync
84
+ // 如果是旧版本 Node,这里可能需要回退方案,但一般现代开发环境都支持
85
+ try {
86
+ process.stdout.write(`Cleaning old ${item}... `);
87
+ fs.rmSync(destPath, { recursive: true, force: true });
88
+ console.log('✅ Cleaned');
89
+ } catch (rmError) {
90
+ console.warn(`⚠️ 无法清理旧目录 ${item}: ${rmError.message},将尝试直接覆盖。`);
91
+ }
92
+ }
93
+ }
94
+ // --- 更新处理逻辑 END ---
95
+
96
+ process.stdout.write(`Writing ${item}... `);
97
+ copyRecursiveSync(srcPath, destPath);
98
+ console.log('✅ Done');
99
+ } else {
100
+ console.warn(`⚠️ 警告: 源文件/目录 ${item} 未找到,跳过 (Source not found, skipping)。`);
101
+ }
102
+ });
103
+
104
+ console.log(`\n✨ scan-debug-skill 安装/更新成功!(Installation/Update Successful)`);
105
+ console.log(`👉 当前位置: ${targetDir}\n`);
106
+
107
+ } catch (error) {
108
+ console.error(`\n❌ 安装失败 (Installation Failed): ${error.message}`);
109
+ // 发生错误时退出进程
110
+ process.exit(1);
111
+ }
112
+ }
113
+
114
+ // 主程序入口
115
+ const rl = readline.createInterface({
116
+ input: process.stdin,
117
+ output: process.stdout
118
+ });
119
+
120
+ const cwd = process.cwd();
121
+
122
+ // 检测当前目录下是否存在 .trae 或 .cursor 目录,以便提供智能默认选项
123
+ const hasTrae = fs.existsSync(path.join(cwd, '.trae'));
124
+ const hasCursor = fs.existsSync(path.join(cwd, '.cursor'));
125
+
126
+ let defaultChoice = '1'; // 默认 Trae
127
+ let defaultText = 'Trae';
128
+
129
+ if (hasCursor && !hasTrae) {
130
+ defaultChoice = '2';
131
+ defaultText = 'Cursor';
132
+ } else if (hasTrae && hasCursor) {
133
+ defaultChoice = '3';
134
+ defaultText = 'Both';
135
+ }
136
+
137
+ console.log('请选择要安装的目标 IDE (Please select target IDE):');
138
+ console.log(`1. Trae (.trae/scan-debug-skill) ${hasTrae ? '[Detected]' : ''}`);
139
+ console.log(`2. Cursor (.cursor/scan-debug-skill) ${hasCursor ? '[Detected]' : ''}`);
140
+ console.log('3. Both (同时安装/Install Both)');
141
+
142
+ rl.question(`请输入选项 (1/2/3) [默认: ${defaultChoice} (${defaultText})]: `, (answer) => {
143
+ const choice = answer.trim() || defaultChoice;
144
+
145
+ // 映射选择到目标目录
146
+ const targets = [];
147
+
148
+ // 选项 1 或 3:安装到 Trae
149
+ if (choice === '1' || choice === '3') {
150
+ targets.push(path.join(cwd, '.trae', 'scan-debug-skill'));
151
+ }
152
+
153
+ // 选项 2 或 3:安装到 Cursor
154
+ if (choice === '2' || choice === '3') {
155
+ targets.push(path.join(cwd, '.cursor', 'scan-debug-skill'));
156
+ }
157
+
158
+ // 如果没有有效选择(虽然有默认值保护),回退到默认
159
+ if (targets.length === 0) {
160
+ if (defaultChoice === '2') {
161
+ targets.push(path.join(cwd, '.cursor', 'scan-debug-skill'));
162
+ } else {
163
+ targets.push(path.join(cwd, '.trae', 'scan-debug-skill'));
164
+ }
165
+ }
166
+
167
+ // 执行安装
168
+ targets.forEach(dir => install(dir));
169
+
170
+ rl.close();
171
+ });
package/css/SKILL.md ADDED
@@ -0,0 +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)
@@ -0,0 +1,20 @@
1
+ # CSS 通用最佳实践
2
+
3
+ ## 规则详情
4
+ * **ID 选择器**:尽量避免使用 ID 选择器定义样式(高优先级难以覆盖),推荐使用 Class 选择器。
5
+ * **!important**:慎用 `!important`,除非用于覆盖内联样式或第三方库样式,且需添加注释说明。
6
+ * **单位统一**:
7
+ * 当值为 `0` 时,省略单位(如 `0px` -> `0`)。
8
+ * 避免使用绝对单位(如 `cm`, `in`),除非在打印样式表中。
9
+
10
+ ## 示例:省略零值单位
11
+ **场景**:Sonar 提示 "Unexpected unit"。
12
+
13
+ **修复后代码**:
14
+ ```css
15
+ div {
16
+ /* Compliant: 0 不需要单位 */
17
+ margin: 0;
18
+ padding: 10px;
19
+ }
20
+ ```
@@ -0,0 +1,15 @@
1
+ # 注释与文档规范
2
+
3
+ ## 规则详情
4
+ * **语言**:所有注释必须使用 **中文**。
5
+ * **复杂逻辑**:对于使用了复杂 CSS Hack 或特定浏览器兼容性写法的样式,必须在上方添加注释说明原因。
6
+
7
+ ## 示例
8
+ ```css
9
+ /* 针对 IE11 的 Flexbox 兼容性修复 */
10
+ @media all and (-ms-high-contrast: none), (-ms-high-contrast: active) {
11
+ .container {
12
+ display: block;
13
+ }
14
+ }
15
+ ```
@@ -0,0 +1,16 @@
1
+ # 重复属性 (Duplicate Properties)
2
+
3
+ ## 规则详情
4
+ * **规则**:避免在同一选择器块中重复定义相同的属性(除非用于浏览器兼容性 fallback)。重复的属性只有最后一次声明生效,多余的声明应被移除。
5
+
6
+ ## 示例
7
+ **场景**:Sonar 提示 "Duplicate property names" (重复的属性名)。
8
+
9
+ **修复后代码**:
10
+ ```css
11
+ a {
12
+ color: pink;
13
+ /* Compliant: 移除了重复定义的 color: orange */
14
+ background: orange;
15
+ }
16
+ ```
@@ -0,0 +1,15 @@
1
+ # 字体族回退 (Font Family Fallback)
2
+
3
+ ## 规则详情
4
+ * **规则**:在定义 `font` 或 `font-family` 时,必须在末尾指定一个通用字体族,**优先使用 `sans-serif`**(除非业务明确要求使用 `serif` 或 `monospace`),以防止特定字体不可用时浏览器回退到默认字体导致样式崩坏。
5
+
6
+ ## 示例
7
+ **场景**:Sonar 提示 "font-family" 缺少通用字体族声明。
8
+
9
+ **修复后代码**:
10
+ ```css
11
+ body {
12
+ /* Compliant: 末尾添加 sans-serif 作为通用回退字体 */
13
+ font-family: "PingFang SC", "Microsoft YaHei", Arial, sans-serif;
14
+ }
15
+ ```
package/html/SKILL.md ADDED
@@ -0,0 +1,26 @@
1
+ ---
2
+ name: html-sonar-repair
3
+ description: HTML/Template 代码 SonarQube 扫描问题修复指南,涵盖可访问性、语义化及安全漏洞修复。
4
+ ---
5
+
6
+ # Sonar HTML 代码质量与安全修复技能
7
+
8
+ 此技能用于指导 AI 助手协助用户修复 SonarQube 及奇安信安全扫描发现的 HTML/Template 代码问题。
9
+
10
+ ## 核心原则
11
+ 1. **直接高效**:直接给出修复后的完整代码片段,**始终保持中文输出**。
12
+ 2. **可访问性 (A11y)**:确保 HTML 结构符合 WCAG 标准。
13
+ 3. **语义化**:优先使用语义化标签。
14
+
15
+ ## 技能索引
16
+
17
+ ### 基础规范
18
+ - 注释与文档规范 (中文注释) → 详见 [comments-documentation](reference/comments-documentation.md)
19
+ - HTML 语义化结构 (Lang, Doctype, Table) → 详见 [semantic-structure](reference/semantic-structure.md)
20
+
21
+ ### 元素规范
22
+ - 图片替代文本 (Image Alt Text) → 详见 [image-alt-text](reference/image-alt-text.md)
23
+ - 表单标签关联 (Form Labels) → 详见 [form-labels](reference/form-labels.md)
24
+
25
+ ### 安全合规
26
+ - 外链安全与事件 (Noopener, Inline Events) → 详见 [security-compliance](reference/security-compliance.md)
@@ -0,0 +1,16 @@
1
+ # 注释与文档规范
2
+
3
+ ## 规则详情
4
+ * **语言**:所有注释必须使用 **中文**。
5
+ * **结构说明**:对于复杂的 DOM 结构或模板逻辑,需添加注释说明用途。
6
+
7
+ ## 示例
8
+ ```html
9
+ <!--
10
+ 主要内容区域
11
+ 包含了文章列表和侧边栏
12
+ -->
13
+ <main class="main-content">
14
+ ...
15
+ </main>
16
+ ```
@@ -0,0 +1,20 @@
1
+ # 表单标签关联 (Form Labels)
2
+
3
+ ## 规则详情
4
+ * **规则**:所有 `<input>`, `<textarea>`, `<select>` 等表单元素必须有关联的 `<label>`,可以通过 `for` 属性关联 ID,或将 input 包裹在 label 中。
5
+
6
+ ## 示例
7
+ **场景**:Sonar 提示 "Form elements should have labels"。
8
+
9
+ **修复后代码**:
10
+ ```html
11
+ <!-- Compliant: 使用 for 属性关联 -->
12
+ <label for="username">用户名</label>
13
+ <input type="text" id="username" name="username">
14
+
15
+ <!-- Compliant: 隐式关联 (Nest) -->
16
+ <label>
17
+ 密码
18
+ <input type="password" name="password">
19
+ </label>
20
+ ```
@@ -0,0 +1,18 @@
1
+ # 图片替代文本 (Image Alt Text)
2
+
3
+ ## 规则详情
4
+ * **规则**:所有 `<img>` 标签必须包含 `alt` 属性。
5
+ * 如果图片仅用于装饰,应设置 `alt=""`。
6
+ * 如果图片包含信息,应提供有意义的描述文本。
7
+
8
+ ## 示例
9
+ **场景**:Sonar 提示 "<img> elements should have an 'alt' attribute"。
10
+
11
+ **修复后代码**:
12
+ ```html
13
+ <!-- Compliant: 装饰性图片,alt 为空 -->
14
+ <img src="bg-pattern.png" alt="">
15
+
16
+ <!-- Compliant: 信息性图片,提供描述 -->
17
+ <img src="logo.png" alt="公司 Logo">
18
+ ```
@@ -0,0 +1,16 @@
1
+ # 安全合规规范 (Security)
2
+
3
+ ## 规则详情
4
+ * **外链安全**:`<a>` 标签使用 `target="_blank"` 时,必须添加 `rel="noopener noreferrer"`。
5
+ * **内联事件**:避免使用内联 JS 事件(如 `onclick="..."`),应通过脚本绑定事件。
6
+
7
+ ## 示例:外链安全
8
+ **场景**:Sonar 提示 "Links with target='_blank' should have rel='noopener noreferrer'"。
9
+
10
+ **修复后代码**:
11
+ ```html
12
+ <!-- Compliant: 防止新窗口通过 window.opener 访问原页面 -->
13
+ <a href="https://example.com" target="_blank" rel="noopener noreferrer">
14
+ 外部链接
15
+ </a>
16
+ ```
@@ -0,0 +1,21 @@
1
+ # HTML 语义化结构
2
+
3
+ ## 规则详情
4
+ * **链接文本**:`<a>` 标签必须包含有意义的文本内容,避免仅包含图标或空内容(如果是图标链接,应使用 `aria-label`)。
5
+ * **Doctype**:每个 HTML 文档必须声明 `<!DOCTYPE html>`。
6
+ * **Lang 属性**:`<html>` 标签必须包含 `lang` 属性,声明页面语言(如 `lang="zh-CN"`)。
7
+ * **表格结构**:`<table>` 必须包含 `<caption>` (标题) 或 `summary` 属性(虽已废弃但部分旧标准仍用),以及正确使用 `<thead>`, `<tbody>`, `<tfoot>`。
8
+
9
+ ## 示例:链接文本为空
10
+ **场景**:Sonar 提示 "Links must have discernible text"。
11
+
12
+ **修复后代码**:
13
+ ```html
14
+ <!-- Compliant: 提供文本内容 -->
15
+ <a href="/home">返回首页</a>
16
+
17
+ <!-- Compliant: 图标链接使用 aria-label -->
18
+ <a href="/settings" aria-label="设置">
19
+ <i class="icon-settings"></i>
20
+ </a>
21
+ ```
package/js/SKILL.md ADDED
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: js-sonar-repair
3
+ description: JavaScript/TypeScript 代码 SonarQube 扫描问题修复指南,涵盖代码规范、框架最佳实践及安全漏洞修复。
4
+ ---
5
+
6
+ # Sonar JS/TS 代码质量与安全修复技能
7
+
8
+ 此技能用于指导 AI 助手协助用户修复 SonarQube 及奇安信安全扫描发现的 JavaScript/TypeScript 代码问题。
9
+
10
+ ## 核心原则
11
+ 1. **直接高效**:直接给出修复后的完整代码片段,**始终保持中文输出**。
12
+ 2. **安全优先**:严格遵循 SonarQube 安全热点和奇安信漏洞扫描标准。
13
+ 3. **规范统一**:严格遵守项目的代码风格与注释规范。
14
+
15
+ ## 技能索引
16
+
17
+ ### 基础规范
18
+ - 注释与文档规范 (JSDoc, 中文注释) → 详见 [comments-documentation](reference/comments-documentation.md)
19
+ - JS/TS 通用最佳实践 (类型判断, 变量声明, 复杂度) → 详见 [js-ts-best-practices](reference/js-ts-best-practices.md)
20
+
21
+ ### 框架规范
22
+ - Vue/React 框架特定规范 (List Key, Props, Side Effects) → 详见 [framework-vue-react](reference/framework-vue-react.md)
23
+
24
+ ### 安全合规
25
+ - 安全漏洞与合规性 (XSS, 敏感信息, 堆栈泄露) → 详见 [security-compliance](reference/security-compliance.md)
@@ -0,0 +1,22 @@
1
+ # 注释与文档规范
2
+
3
+ ## 规则详情
4
+ * **语言**:所有注释必须使用 **中文**。
5
+ * **JSDoc**:导出的函数、类、接口必须包含 JSDoc 注释,说明 `@param` (参数)、`@returns` (返回值) 和 `@throws` (异常)。
6
+ * **逻辑解释**:关键的业务逻辑判断、复杂的正则表达式、非显而易见的修复原因,需在代码上方添加单行注释 `//`。
7
+
8
+ ## 示例
9
+ ```javascript
10
+ /**
11
+ * 计算两个日期之间的天数差
12
+ * @param {Date} startDate - 开始日期
13
+ * @param {Date} endDate - 结束日期
14
+ * @returns {number} - 天数差(绝对值)
15
+ */
16
+ function getDaysDiff(startDate, endDate) {
17
+ // 校验参数是否有效
18
+ if (!startDate || !endDate) return 0;
19
+
20
+ // ...
21
+ }
22
+ ```
@@ -0,0 +1,19 @@
1
+ # 前端框架规范 (Vue/React)
2
+
3
+ ## 规则详情
4
+ * **列表渲染**:`v-for` (Vue) 或 `map` (React) 循环渲染时,必须提供唯一的 `key`,且**避免使用数组索引 (index) 作为 key**(除非列表是静态且不排序的)。
5
+ * **Props 验证**:组件接收的 Props 必须定义类型验证和默认值。
6
+ * **副作用清理**:在组件销毁生命周期(`beforeUnmount`, `useEffect cleanup`)中,必须清理定时器、事件监听器等副作用。
7
+
8
+ ## 示例:Vue/React 列表 Key 问题
9
+
10
+ **场景**:Sonar 提示 "Use a unique value for the key attribute"。
11
+
12
+ **修复后代码**:
13
+ ```html
14
+ <!-- Compliant: 使用数据的唯一 ID 作为 key -->
15
+ <div v-for="item in list" :key="item.id">
16
+ <!-- 显示用户名称 -->
17
+ {{ item.name }}
18
+ </div>
19
+ ```
@@ -0,0 +1,49 @@
1
+ # JS/TS 通用最佳实践
2
+
3
+ ## 规则详情
4
+ * **强类型判断**:始终使用 `===` 和 `!==` 代替 `==` 和 `!=`,避免隐式类型转换带来的 Bug。
5
+ * **变量声明**:优先使用 `const`,其次使用 `let`,**严禁使用 `var`**。
6
+ * **认知复杂度 (Cognitive Complexity)**:当 Sonar 提示函数复杂度过高(通常 > 15)时,必须将逻辑拆分为多个职责单一的子函数。
7
+ * **魔法数字 (Magic Numbers)**:避免直接使用无意义的数字(0 和 1 除外),应将其定义为具名常量。
8
+ * **异步处理**:
9
+ * 优先使用 `async/await`。
10
+ * 所有 Promise 链必须以 `.catch()` 结束,或在 `try...catch` 块中处理错误。
11
+
12
+ ## 示例:认知复杂度与魔法数字
13
+
14
+ **场景**:Sonar 提示 "Refactor this function to reduce its Cognitive Complexity" 及 "Replace this constant value 86400000 with a name"。
15
+
16
+ **修复后代码**:
17
+ ```javascript
18
+ // 定义常量,消除魔法数字
19
+ const ONE_DAY_MS = 24 * 60 * 60 * 1000;
20
+
21
+ /**
22
+ * 检查日期是否在明天之后
23
+ * @param {Date} date - 待检查的日期对象
24
+ * @returns {boolean} - 如果日期有效且在一天之后,返回 true
25
+ */
26
+ function isDateFuture(date) {
27
+ // 1. 参数校验:确保日期对象存在
28
+ if (!date) {
29
+ return false;
30
+ }
31
+
32
+ // 2. 逻辑判断:计算时间差
33
+ const thresholdTime = Date.now() + ONE_DAY_MS;
34
+
35
+ // 3. 返回结果:判断是否超过阈值
36
+ return date.getTime() > thresholdTime;
37
+ }
38
+ ```
39
+
40
+ ## 示例:正则表达式安全 (ReDoS)
41
+
42
+ **场景**:Sonar 提示 "Make sure the regex used here... cannot lead to denial of service"。
43
+
44
+ **修复后代码**:
45
+ ```javascript
46
+ // Compliant: 优化正则结构,避免嵌套量词,防止 ReDoS 攻击
47
+ // 说明:匹配一个或多个 'a' 后跟一个 'b'
48
+ const regex = /a+b/;
49
+ ```
@@ -0,0 +1,26 @@
1
+ # 安全合规规范 (Security)
2
+
3
+ ## 规则详情
4
+ * **XSS 防范**:
5
+ * 严禁使用 `eval()`、`new Function()`。
6
+ * 慎用 `v-html` (Vue) 或 `dangerouslySetInnerHTML` (React),必须确保内容已经过 DOMPurify 等库的清洗。
7
+ * **敏感信息**:代码中禁止硬编码密码、Token、密钥(AK/SK)、内网 IP 等敏感信息,应通过环境变量或配置接口获取。
8
+ * **链接安全**:使用 `target="_blank"` 打开外部链接时,必须添加 `rel="noopener noreferrer"` 以防止钓鱼攻击。
9
+ * **禁止打印敏感堆栈**:在 `.catch()` 中禁止直接打印整个 Error 对象。
10
+
11
+ ## 示例:禁止打印敏感堆栈
12
+
13
+ **场景**:Sonar 提示 "Define and throw a dedicated exception instead of using a generic one" 或敏感日志泄露。
14
+
15
+ **修复后代码**:
16
+ ```javascript
17
+ try {
18
+ await getUserInfo();
19
+ } catch (error) {
20
+ // Compliant: 仅打印必要的错误摘要,隐藏堆栈详情
21
+ console.error('获取用户信息失败:', error.message || '未知错误');
22
+
23
+ // 可选:上报监控系统
24
+ // logger.report(error);
25
+ }
26
+ ```
package/package.json ADDED
@@ -0,0 +1,26 @@
1
+ {
2
+ "name": "scan-debug-skill",
3
+ "version": "1.0.0",
4
+ "description": "ScanDebugSkill for Trae IDE - Easily install debugging skills via npx",
5
+ "bin": {
6
+ "scan-debug-skill": "./bin/install.js"
7
+ },
8
+ "scripts": {
9
+ "test": "echo \"Error: no test specified\" && exit 1"
10
+ },
11
+ "keywords": [
12
+ "trae",
13
+ "skill",
14
+ "debug",
15
+ "scan"
16
+ ],
17
+ "author": "",
18
+ "license": "ISC",
19
+ "files": [
20
+ "bin",
21
+ "css",
22
+ "html",
23
+ "js",
24
+ "SKILL.md"
25
+ ]
26
+ }