scan-debug-skill 1.0.7 → 1.0.8

package/README.md

@@ -20,8 +20,8 @@ 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`)
+1.  **Trae**：安装到 `.trae/skills/scan-debug-skill` (Install to `.trae/skills/scan-debug-skill`)
+2.  **Cursor**：安装到 `.cursor/skills/scan-debug-skill` (Install to `.cursor/skills/scan-debug-skill`)
 3.  **Custom**：安装到指定目录 (Install to a specified directory)
 
 ### 包含的内容 / Contents

package/SKILL.md

@@ -1,68 +1,58 @@
----
-name: 扫描问题
-description: SonarQube和安全扫描的时候触发。分析并修复 SonarQube 扫描出的代码问题，确保符合安全与质量规范。当用户要求修复 Sonar 问题时调用。
-triggers:
-  - sonar问题修复
-  - 奇安信问题修复
-  - sonar问题扫描
-  - 奇安信问题扫描
-  - 扫描问题修复
-  - 扫描代码问题
-  - scan-debug-skill扫描
-  - scan-debug-skill
-  - scan-debug
-license: MIT
-author: [scan-debug-skill](https://github.com/k73333333/ScanDebugSkill)
----
-
-# Sonar 代码质量与安全修复技能集
-
-本项目包含针对前端不同技术栈（JS/TS, CSS, HTML）的 SonarQube 修复技能指南。
-
-## 目录结构
-
-*   **[JS/TS 修复技能](./js/SKILL.md)**
-    *   包含 JavaScript、TypeScript 的修复规则。
-    *   涉及：注释规范、最佳实践、安全合规。
-
-*   **[CSS 修复技能](./css/SKILL.md)**
-    *   包含 CSS、SASS、LESS 的样式修复规则。
-    *   涉及：注释规范、通用实践、字体回退、重复属性。
-
-*   **[HTML 修复技能](./html/SKILL.md)**
-    *   包含 HTML 结构、语义化及可访问性修复规则。
-    *   涉及：注释规范、图片/表单/语义化结构、安全合规。
-
-## 使用说明
-对指定代码/文件/目录进行扫描问题然后根据扫描结果概览进行修复。
-
-请点击上述链接进入相应的技能目录查看详细指南。
-
-### 引用指南
-
-在编辑器中使用 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."
-
-## 扫描结果概览输出规则
-
-当用户提供扫描报告或提及多个代码问题时，应首先以表格形式输出扫描结果概览，遵循以下规范：
-
-- **表格列**：必须包含 类别、严重程度、问题描述、涉及文件。
-- **严重程度标识**：使用 🔴 高危、🟡 中、🔵 低、⚪ 建议 进行视觉区分。
-- **示例格式**：
-
-| 类别 | 严重程度 | 问题描述 | 涉及文件 |
-| :--- | :--- | :--- | :--- |
-| JS/TS 安全 | 🔴 高危 | window.open 缺少 noopener (反向 Tabnabbing 漏洞) | src/views/Assistant.vue |
-| 代码质量 | 🔴 高危 | 遗留 debugger 调试断点 | vite.config.ts |
-| 代码质量 | 🟡 中 | 遗留 console.log 调试日志 | vite.config.ts |
-| CSS 规范 | 🟡 中 | 滥用 !important 破坏级联规则 | src/assets/assistant.css |
-| JS/TS 规范 | 🟡 中 | 使用原生 confirm 阻塞交互 | src/views/Assistant.vue |
-| Vue 规范 | 🔵 低 | v-for 使用 index 作为 key (潜在渲染风险) | src/views/Assistant.vue |
-| 代码风格 | ⚪ 建议 | 变量命名可优化为更具语义化的名称 | src/utils/format.js |
+---
+name: scan-debug-skill
+description: "分析并修复 SonarQube 和奇安信扫描出的代码问题，确保符合安全与质量规范。Invoke when user asks to fix Sonar/Qianxin issues, scan code, or mentions scan-debug-skill."
+license: MIT
+author: [scan-debug-skill](https://github.com/k73333333/ScanDebugSkill)
+---
+
+# Sonar 代码质量与安全修复技能集
+
+本项目包含针对前端不同技术栈（JS/TS, CSS, HTML）的 SonarQube 修复技能指南。
+
+## 目录结构
+
+*   **[JS/TS 修复技能](./js/SKILL.md)**
+    *   包含 JavaScript、TypeScript 的修复规则。
+    *   涉及：注释规范、最佳实践、安全合规。
+
+*   **[CSS 修复技能](./css/SKILL.md)**
+    *   包含 CSS、SASS、LESS 的样式修复规则。
+    *   涉及：注释规范、通用实践、字体回退、重复属性。
+
+*   **[HTML 修复技能](./html/SKILL.md)**
+    *   包含 HTML 结构、语义化及可访问性修复规则。
+    *   涉及：注释规范、图片/表单/语义化结构、安全合规。
+
+## 使用说明
+对指定代码/文件/目录进行扫描问题然后根据扫描结果概览进行修复。
+
+请点击上述链接进入相应的技能目录查看详细指南。
+
+### 引用指南
+
+在编辑器中使用 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."
+
+## 扫描结果概览输出规则
+
+当用户提供扫描报告或提及多个代码问题时，应首先以表格形式输出扫描结果概览，遵循以下规范：
+
+- **表格列**：必须包含 类别、严重程度、问题描述、涉及文件。
+- **严重程度标识**：使用 🔴 高危、🟡 中、🔵 低、⚪ 建议 进行视觉区分。
+- **示例格式**：
+
+| 类别 | 严重程度 | 问题描述 | 涉及文件 |
+| :--- | :--- | :--- | :--- |
+| JS/TS 安全 | 🔴 高危 | window.open 缺少 noopener (反向 Tabnabbing 漏洞) | src/views/Assistant.vue |
+| 代码质量 | 🔴 高危 | 遗留 debugger 调试断点 | vite.config.ts |
+| 代码质量 | 🟡 中 | 遗留 console.log 调试日志 | vite.config.ts |
+| CSS 规范 | 🟡 中 | 滥用 !important 破坏级联规则 | src/assets/assistant.css |
+| JS/TS 规范 | 🟡 中 | 使用原生 confirm 阻塞交互 | src/views/Assistant.vue |
+| Vue 规范 | 🔵 低 | v-for 使用 index 作为 key (潜在渲染风险) | src/views/Assistant.vue |
+| 代码风格 | ⚪ 建议 | 变量命名可优化为更具语义化的名称 | src/utils/format.js |

package/bin/install.js

@@ -4,7 +4,7 @@
  * @Author: fukaidong
  * @Date: 2026-02-25 15:50:10
  * @LastEditors: fukaidong qiji777@yeah.net
- * @LastEditTime: 2026-02-26 18:33:02
+ * @LastEditTime: 2026-04-14 14:35:17
  * @Description: scan-debug-skill 安装脚本 (ScanDebugSkill Install Script)
  *               包含更新处理逻辑：安装前清理旧版本核心目录，确保无残留文件。
  */
@@ -133,8 +133,8 @@ if (hasCursor && !hasTrae) {
 // 若两者都存在，默认保持为 1 (Trae)
 
 console.log('请选择要安装的目标 IDE (Please select target IDE):');
-console.log(`1. Trae   (.trae/scan-debug-skill)   ${hasTrae ? '[Detected]' : ''}`);
-console.log(`2. Cursor (.cursor/scan-debug-skill) ${hasCursor ? '[Detected]' : ''}`);
+console.log(`1. Trae   (.trae/skills/scan-debug-skill)   ${hasTrae ? '[Detected]' : ''}`);
+console.log(`2. Cursor (.cursor/skills/scan-debug-skill) ${hasCursor ? '[Detected]' : ''}`);
 console.log('3. Custom (指定目录/Custom Directory)');
 
 rl.question(`请输入选项 (1/2/3) [默认: ${defaultChoice} (${defaultText})]: `, (answer) => {
@@ -161,20 +161,20 @@ rl.question(`请输入选项 (1/2/3) [默认: ${defaultChoice} (${defaultText})]
   
   // 选项 1：安装到 Trae
   if (choice === '1') {
-    targets.push(path.join(cwd, '.trae', 'scan-debug-skill'));
+    targets.push(path.join(cwd, '.trae', 'skills', 'scan-debug-skill'));
   }
   
   // 选项 2：安装到 Cursor
   if (choice === '2') {
-    targets.push(path.join(cwd, '.cursor', 'scan-debug-skill'));
+    targets.push(path.join(cwd, '.cursor', 'skills', 'scan-debug-skill'));
   }
 
   // 如果没有有效选择（且不是3），回退到默认
   if (targets.length === 0) {
     if (defaultChoice === '2') {
-        targets.push(path.join(cwd, '.cursor', 'scan-debug-skill'));
+        targets.push(path.join(cwd, '.cursor', 'skills', 'scan-debug-skill'));
     } else {
-        targets.push(path.join(cwd, '.trae', 'scan-debug-skill'));
+        targets.push(path.join(cwd, '.trae', 'skills', 'scan-debug-skill'));
     }
   }
 

package/css/reference/best-practices.md

@@ -1,38 +1,38 @@
-# CSS 通用最佳实践
-
-## 规则详情
-*   **ID 选择器**：尽量避免使用 ID 选择器定义样式（高优先级难以覆盖），推荐使用 Class 选择器。
-*   **!important**：慎用 `!important`，除非用于覆盖内联样式或第三方库样式，且需添加注释说明。
-*   **单位统一**：
-    *   当值为 `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"。
-
-**修复后代码**：
-```css
-div {
-  /* Compliant: 0 不需要单位 */
-  margin: 0;
-  padding: 10px;
-}
-```
+# CSS 通用最佳实践
+
+## 规则详情
+*   **ID 选择器**：尽量避免使用 ID 选择器定义样式（高优先级难以覆盖），推荐使用 Class 选择器。
+*   **!important**：慎用 `!important`，除非用于覆盖内联样式或第三方库样式，且需添加注释说明。
+*   **单位统一**：
+    *   当值为 `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"。
+
+**修复后代码**：
+```css
+div {
+  /* Compliant: 0 不需要单位 */
+  margin: 0;
+  padding: 10px;
+}
+```

package/css/reference/comments-documentation.md

@@ -1,15 +1,15 @@
-# 注释与文档规范
-
-## 规则详情
-*   **语言**：所有注释必须使用 **中文**。
-*   **复杂逻辑**：对于使用了复杂 CSS Hack 或特定浏览器兼容性写法的样式，必须在上方添加注释说明原因。
-
-## 示例
-```css
-/* 针对 IE11 的 Flexbox 兼容性修复 */
-@media all and (-ms-high-contrast: none), (-ms-high-contrast: active) {
-  .container {
-    display: block; 
-  }
-}
-```
+# 注释与文档规范
+
+## 规则详情
+*   **语言**：所有注释必须使用 **中文**。
+*   **复杂逻辑**：对于使用了复杂 CSS Hack 或特定浏览器兼容性写法的样式，必须在上方添加注释说明原因。
+
+## 示例
+```css
+/* 针对 IE11 的 Flexbox 兼容性修复 */
+@media all and (-ms-high-contrast: none), (-ms-high-contrast: active) {
+  .container {
+    display: block; 
+  }
+}
+```

package/css/reference/duplicate-properties.md

@@ -1,16 +1,16 @@
-# 重复属性 (Duplicate Properties)
-
-## 规则详情
-*   **规则**：避免在同一选择器块中重复定义相同的属性（除非用于浏览器兼容性 fallback）。重复的属性只有最后一次声明生效，多余的声明应被移除。
-
-## 示例
-**场景**：Sonar 提示 "Duplicate property names" (重复的属性名)。
-
-**修复后代码**：
-```css
-a {
-  color: pink;
-  /* Compliant: 移除了重复定义的 color: orange */
-  background: orange;
-}
-```
+# 重复属性 (Duplicate Properties)
+
+## 规则详情
+*   **规则**：避免在同一选择器块中重复定义相同的属性（除非用于浏览器兼容性 fallback）。重复的属性只有最后一次声明生效，多余的声明应被移除。
+
+## 示例
+**场景**：Sonar 提示 "Duplicate property names" (重复的属性名)。
+
+**修复后代码**：
+```css
+a {
+  color: pink;
+  /* Compliant: 移除了重复定义的 color: orange */
+  background: orange;
+}
+```

package/css/reference/font-family-fallback.md

@@ -1,15 +1,15 @@
-# 字体族回退 (Font Family Fallback)
-
-## 规则详情
-*   **规则**：在定义 `font` 或 `font-family` 时，必须在末尾指定一个通用字体族，**优先使用 `sans-serif`**（除非业务明确要求使用 `serif` 或 `monospace`），以防止特定字体不可用时浏览器回退到默认字体导致样式崩坏。
-
-## 示例
-**场景**：Sonar 提示 "font-family" 缺少通用字体族声明。
-
-**修复后代码**：
-```css
-body {
-  /* Compliant: 末尾添加 sans-serif 作为通用回退字体 */
-  font-family: "PingFang SC", "Microsoft YaHei", Arial, sans-serif;
-}
-```
+# 字体族回退 (Font Family Fallback)
+
+## 规则详情
+*   **规则**：在定义 `font` 或 `font-family` 时，必须在末尾指定一个通用字体族，**优先使用 `sans-serif`**（除非业务明确要求使用 `serif` 或 `monospace`），以防止特定字体不可用时浏览器回退到默认字体导致样式崩坏。
+
+## 示例
+**场景**：Sonar 提示 "font-family" 缺少通用字体族声明。
+
+**修复后代码**：
+```css
+body {
+  /* Compliant: 末尾添加 sans-serif 作为通用回退字体 */
+  font-family: "PingFang SC", "Microsoft YaHei", Arial, sans-serif;
+}
+```

package/html/SKILL.md

@@ -1,26 +1,26 @@
----
-name: html-sonar-repair
-description: HTML/Template 代码 SonarQube 扫描问题修复指南，涵盖可访问性、语义化及安全漏洞修复。
----
-
-# Sonar HTML 代码质量与安全修复技能
-
-此技能用于指导 AI 助手协助用户修复 SonarQube 及奇安信安全扫描发现的 HTML/Template 代码问题。
-
-## 核心原则
-1.  **直接高效**：直接给出修复后的完整代码片段，**始终保持中文输出**。
-2.  **可访问性 (A11y)**：确保 HTML 结构符合 WCAG 标准。
-3.  **语义化**：优先使用语义化标签。
-
-## 技能索引
-
-### 基础规范
-- 注释与文档规范 (中文注释) → 详见 [comments-documentation](reference/comments-documentation.md)
-- HTML 语义化结构 (Lang, Doctype, Table, Nesting) → 详见 [semantic-structure](reference/semantic-structure.md)
-
-### 元素规范
-- 图片替代文本 (Image Alt Text) → 详见 [image-alt-text](reference/image-alt-text.md)
-- 表单标签关联 (Form Labels) → 详见 [form-labels](reference/form-labels.md)
-
-### 安全合规
-- 外链安全与事件 (Noopener, Inline Events) → 详见 [security-compliance](reference/security-compliance.md)
+---
+name: html-sonar-repair
+description: HTML/Template 代码 SonarQube 扫描问题修复指南，涵盖可访问性、语义化及安全漏洞修复。
+---
+
+# Sonar HTML 代码质量与安全修复技能
+
+此技能用于指导 AI 助手协助用户修复 SonarQube 及奇安信安全扫描发现的 HTML/Template 代码问题。
+
+## 核心原则
+1.  **直接高效**：直接给出修复后的完整代码片段，**始终保持中文输出**。
+2.  **可访问性 (A11y)**：确保 HTML 结构符合 WCAG 标准。
+3.  **语义化**：优先使用语义化标签。
+
+## 技能索引
+
+### 基础规范
+- 注释与文档规范 (中文注释) → 详见 [comments-documentation](reference/comments-documentation.md)
+- HTML 语义化结构 (Lang, Doctype, Table, Nesting) → 详见 [semantic-structure](reference/semantic-structure.md)
+
+### 元素规范
+- 图片替代文本 (Image Alt Text) → 详见 [image-alt-text](reference/image-alt-text.md)
+- 表单标签关联 (Form Labels) → 详见 [form-labels](reference/form-labels.md)
+
+### 安全合规
+- 外链安全与事件 (Noopener, Inline Events) → 详见 [security-compliance](reference/security-compliance.md)

package/html/reference/comments-documentation.md

@@ -1,16 +1,16 @@
-# 注释与文档规范
-
-## 规则详情
-*   **语言**：所有注释必须使用 **中文**。
-*   **结构说明**：对于复杂的 DOM 结构或模板逻辑，需添加注释说明用途。
-
-## 示例
-```html
-<!-- 
-  主要内容区域
-  包含了文章列表和侧边栏
--->
-<main class="main-content">
-  ...
-</main>
-```
+# 注释与文档规范
+
+## 规则详情
+*   **语言**：所有注释必须使用 **中文**。
+*   **结构说明**：对于复杂的 DOM 结构或模板逻辑，需添加注释说明用途。
+
+## 示例
+```html
+<!-- 
+  主要内容区域
+  包含了文章列表和侧边栏
+-->
+<main class="main-content">
+  ...
+</main>
+```

package/html/reference/form-labels.md

@@ -1,20 +1,20 @@
-# 表单标签关联 (Form Labels)
-
-## 规则详情
-*   **规则**：所有 `<input>`, `<textarea>`, `<select>` 等表单元素必须有关联的 `<label>`，可以通过 `for` 属性关联 ID，或将 input 包裹在 label 中。
-
-## 示例
-**场景**：Sonar 提示 "Form elements should have labels"。
-
-**修复后代码**：
-```html
-<!-- Compliant: 使用 for 属性关联 -->
-<label for="username">用户名</label>
-<input type="text" id="username" name="username">
-
-<!-- Compliant: 隐式关联 (Nest) -->
-<label>
-  密码
-  <input type="password" name="password">
-</label>
-```
+# 表单标签关联 (Form Labels)
+
+## 规则详情
+*   **规则**：所有 `<input>`, `<textarea>`, `<select>` 等表单元素必须有关联的 `<label>`，可以通过 `for` 属性关联 ID，或将 input 包裹在 label 中。
+
+## 示例
+**场景**：Sonar 提示 "Form elements should have labels"。
+
+**修复后代码**：
+```html
+<!-- Compliant: 使用 for 属性关联 -->
+<label for="username">用户名</label>
+<input type="text" id="username" name="username">
+
+<!-- Compliant: 隐式关联 (Nest) -->
+<label>
+  密码
+  <input type="password" name="password">
+</label>
+```

package/html/reference/image-alt-text.md

@@ -1,18 +1,18 @@
-# 图片替代文本 (Image Alt Text)
-
-## 规则详情
-*   **规则**：所有 `<img>` 标签必须包含 `alt` 属性。
-    *   如果图片仅用于装饰，应设置 `alt=""`。
-    *   如果图片包含信息，应提供有意义的描述文本。
-
-## 示例
-**场景**：Sonar 提示 "<img> elements should have an 'alt' attribute"。
-
-**修复后代码**：
-```html
-<!-- Compliant: 装饰性图片，alt 为空 -->
-<img src="bg-pattern.png" alt="">
-
-<!-- Compliant: 信息性图片，提供描述 -->
-<img src="logo.png" alt="公司 Logo">
-```
+# 图片替代文本 (Image Alt Text)
+
+## 规则详情
+*   **规则**：所有 `<img>` 标签必须包含 `alt` 属性。
+    *   如果图片仅用于装饰，应设置 `alt=""`。
+    *   如果图片包含信息，应提供有意义的描述文本。
+
+## 示例
+**场景**：Sonar 提示 "<img> elements should have an 'alt' attribute"。
+
+**修复后代码**：
+```html
+<!-- Compliant: 装饰性图片，alt 为空 -->
+<img src="bg-pattern.png" alt="">
+
+<!-- Compliant: 信息性图片，提供描述 -->
+<img src="logo.png" alt="公司 Logo">
+```

package/html/reference/security-compliance.md

@@ -1,16 +1,16 @@
-# 安全合规规范 (Security)
-
-## 规则详情
-*   **外链安全**：`<a>` 标签使用 `target="_blank"` 时，必须添加 `rel="noopener noreferrer"`。
-*   **内联事件**：避免使用内联 JS 事件（如 `onclick="..."`），应通过脚本绑定事件。
-
-## 示例：外链安全
-**场景**：Sonar 提示 "Links with target='_blank' should have rel='noopener noreferrer'"。
-
-**修复后代码**：
-```html
-<!-- Compliant: 防止新窗口通过 window.opener 访问原页面 -->
-<a href="https://example.com" target="_blank" rel="noopener noreferrer">
-  外部链接
-</a>
-```
+# 安全合规规范 (Security)
+
+## 规则详情
+*   **外链安全**：`<a>` 标签使用 `target="_blank"` 时，必须添加 `rel="noopener noreferrer"`。
+*   **内联事件**：避免使用内联 JS 事件（如 `onclick="..."`），应通过脚本绑定事件。
+
+## 示例：外链安全
+**场景**：Sonar 提示 "Links with target='_blank' should have rel='noopener noreferrer'"。
+
+**修复后代码**：
+```html
+<!-- Compliant: 防止新窗口通过 window.opener 访问原页面 -->
+<a href="https://example.com" target="_blank" rel="noopener noreferrer">
+  外部链接
+</a>
+```

package/html/reference/semantic-structure.md

@@ -1,43 +1,43 @@
-# HTML 语义化结构
-
-## 规则详情
-*   **链接文本**：`<a>` 标签必须包含有意义的文本内容，避免仅包含图标或空内容（如果是图标链接，应使用 `aria-label`）。
-*   **Doctype**：每个 HTML 文档必须声明 `<!DOCTYPE html>`。
-*   **Lang 属性**：`<html>` 标签必须包含 `lang` 属性，声明页面语言（如 `lang="zh-CN"`）。
-*   **表格结构**：`<table>` 必须包含 `<caption>` (标题) 或 `summary` 属性（虽已废弃但部分旧标准仍用），以及正确使用 `<thead>`, `<tbody>`, `<tfoot>`。
-*   **标签嵌套**：严禁错误的标签嵌套，例如：
-    *   `<a>` 标签内禁止嵌套其他交互元素（如 `<button>`, `<input>`, `<a>`）。
-    *   `<p>` 标签内禁止嵌套块级元素（如 `<div>`, `<h1>`, `<ul>`）。
-    *   `<ul>`/`<ol>` 的直接子元素必须是 `<li>`。
-
-## 示例：链接文本为空
-**场景**：Sonar 提示 "Links must have discernible text"。
-
-**修复后代码**：
-```html
-<!-- Compliant: 提供文本内容 -->
-<a href="/home">返回首页</a>
-
-<!-- Compliant: 图标链接使用 aria-label -->
-<a href="/settings" aria-label="设置">
-  <i class="icon-settings"></i>
-</a>
-```
-
-## 示例：标签错误嵌套
-**场景**：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"。
-
-**修复后代码**：
-```html
-<!-- Non-Compliant: a 标签嵌套 button (非法交互元素嵌套) -->
-<!-- <a href="/login"><button>登录</button></a> -->
-
-<!-- Compliant: 使用样式将 a 标签伪装成按钮，或使用 JS 跳转 -->
-<a href="/login" class="btn">登录</a>
-
-<!-- Non-Compliant: p 标签嵌套 div (非法块级元素嵌套) -->
-<!-- <p>这是一个段落 <div>错误嵌套</div></p> -->
-
-<!-- Compliant: 将外层 p 改为 div -->
-<div>这是一个段落 <div>正确嵌套</div></div>
-```
+# HTML 语义化结构
+
+## 规则详情
+*   **链接文本**：`<a>` 标签必须包含有意义的文本内容，避免仅包含图标或空内容（如果是图标链接，应使用 `aria-label`）。
+*   **Doctype**：每个 HTML 文档必须声明 `<!DOCTYPE html>`。
+*   **Lang 属性**：`<html>` 标签必须包含 `lang` 属性，声明页面语言（如 `lang="zh-CN"`）。
+*   **表格结构**：`<table>` 必须包含 `<caption>` (标题) 或 `summary` 属性（虽已废弃但部分旧标准仍用），以及正确使用 `<thead>`, `<tbody>`, `<tfoot>`。
+*   **标签嵌套**：严禁错误的标签嵌套，例如：
+    *   `<a>` 标签内禁止嵌套其他交互元素（如 `<button>`, `<input>`, `<a>`）。
+    *   `<p>` 标签内禁止嵌套块级元素（如 `<div>`, `<h1>`, `<ul>`）。
+    *   `<ul>`/`<ol>` 的直接子元素必须是 `<li>`。
+
+## 示例：链接文本为空
+**场景**：Sonar 提示 "Links must have discernible text"。
+
+**修复后代码**：
+```html
+<!-- Compliant: 提供文本内容 -->
+<a href="/home">返回首页</a>
+
+<!-- Compliant: 图标链接使用 aria-label -->
+<a href="/settings" aria-label="设置">
+  <i class="icon-settings"></i>
+</a>
+```
+
+## 示例：标签错误嵌套
+**场景**：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"。
+
+**修复后代码**：
+```html
+<!-- Non-Compliant: a 标签嵌套 button (非法交互元素嵌套) -->
+<!-- <a href="/login"><button>登录</button></a> -->
+
+<!-- Compliant: 使用样式将 a 标签伪装成按钮，或使用 JS 跳转 -->
+<a href="/login" class="btn">登录</a>
+
+<!-- Non-Compliant: p 标签嵌套 div (非法块级元素嵌套) -->
+<!-- <p>这是一个段落 <div>错误嵌套</div></p> -->
+
+<!-- Compliant: 将外层 p 改为 div -->
+<div>这是一个段落 <div>正确嵌套</div></div>
+```