@ohos-graphics/stability-code-review 0.1.0

package/SKILL.md

@@ -0,0 +1,518 @@
+---
+name: ohos-dev-graphics-stability-code-review
+description: >
+  C/C++ 稳定性代码审查框架，包含可扩展规则体系，覆盖 9 个稳定性分类：
+  异常处理、并发稳定性、性能稳定性、资源管理、初始化顺序、边界条件、生命周期、内存稳定性、图形稳定性。
+  触发场景：稳定性专项全仓扫描、代码上库前本地检视、稳定性审计、故障预防检视、代码审查、OpenHarmony 稳定性扫描、
+  以及用户要求检查 C/C++ 代码稳定性风险时均应使用此技能。
+metadata:
+  author: openharmony
+  scope: domain
+  stage: development
+  domain: graphics
+  capability: stability-code-review
+  version: 0.1.0
+  status: trial
+  tags:
+    - cpp
+    - stability
+    - review
+---
+
+# OpenHarmony Stability Code Review
+
+这是一个**可扩展的稳定性规则检视框架**，用于对 C/C++ 代码库（特别是 OpenHarmony 组件）执行稳定性风险检视并生成结构化报告。框架采用"规则即文档"设计，所有规则以 Markdown 文档形式存放在 `references/` 目录，AI 模型直接读取规则文档进行代码检视，输出中文检视报告到 `./report/` 目录。
+
+当前框架包含 **57 条稳定性规则**，覆盖 **9 个稳定性分类**，后续可持续扩展新规则。
+
+## 触发场景
+
+当用户需要进行以下操作时，应使用此技能：
+
+- **稳定性专项全仓扫描**：对 C/C++ 代码库执行**稳定性审计**或**风险检视**
+- **指定规则扫描**：用户明确指定规则 ID 或分类进行针对性检视（如"用 ExceptionHandling_001 规则检视"、"只检视 HIGH 级别规则"）
+- **代码上库前本地检视**：在代码提交前进行稳定性检视，确保上库代码的可靠性
+- 检测稳定性风险（异常处理不当、并发死锁、性能退化、资源泄漏等）
+- 审查生命周期管理（对象生命周期、异步任务管理）
+- 对代码库进行批量稳定性检视并生成结构化报告
+- 用户明确要求检查代码稳定性时
+
+**触发示例**：
+
+```
+# 全量扫描（遍历所有规则）
+稳定性全量扫描 ./rosen/
+代码稳定性检视 ./src/
+
+# 指定规则扫描（遍历指定的所有规则）
+用 ExceptionHandling_001 规则检视 ./src/
+用 ExceptionHandling_001,ExceptionHandling_002,ConcurrencyStability_001 规则检视 ./rosen/
+
+# 按级别过滤扫描（遍历指定级别的所有规则）
+对 ./rosen/ 做稳定性扫描，只检视 HIGH 级别的规则
+对 ./src/ 进行稳定性扫描，检视 CRITICAL 和 HIGH 级别规则
+
+# 指定分类扫描（遍历该分类下的所有规则）
+对 ./src/ 做稳定性扫描，只检视异常处理分类的规则
+用ConcurrencyStability和MemoryStability分类的规则检视 ./rosen/
+```
+
+## 绝不能做
+
+在使用此技能时：
+
+1. **永远不要修改被扫描的源代码**
+   - 你的工作只是检视代码，识别稳定性风险
+   - 禁止对源代码文件进行任何修改操作
+
+2. **不要输出非必要的过程中间件**
+   - 除了目标输出的中文检视报告之外，请不要输出其它非必要的过程中间文件或临时文件
+   - 保持输出目录的整洁，只在 `./report/` 目录下输出最终报告
+
+## 项目结构
+
+```
+├── SKILL.md                       # skill 技能说明（本文件）
+├── README.md                      # 项目说明
+├── config/
+│   ├── rules.yaml                 # 规则配置
+│   └── whitelist.yaml             # 白名单配置
+├── references/                    # 规则参考文档（核心）和报告输出格式示例
+│   ├── RULE_INDEX.md              # 规则总索引
+│   ├── RULE_DEVELOPMENT_GUIDE.md  # 规则开发完整指南
+│   ├── RULE_TEMPLATE.md           # 规则文档模板
+│   ├── PROBLEM_TEMPLATE.md        # 检出问题格式模板
+│   ├── REPORT_TEMPLATE.md         # 报告输出格式模板（Markdown格式）
+│   ├── REPORT_TEMPLATE.csv        # 报告输出格式模板（CSV格式）
+│   ├── ExceptionHandling/         # 异常处理 规则目录（3条）
+│   ├── ConcurrencyStability/      # 并发稳定性 规则目录（5条）
+│   ├── PerformanceStability/      # 性能稳定性 规则目录（2条）
+│   ├── ResourceManagement/        # 资源管理 规则目录（7条）
+│   ├── InitializationOrder/       # 初始化顺序 规则目录（1条）
+│   ├── BoundaryCondition/         # 边界条件 规则目录（18条）
+│   ├── Lifecycle/                 # 生命周期 规则目录（2条）
+│   ├── MemoryStability/           # 内存稳定性 规则目录（7条）
+│   └── GraphicsStability/         # 图形稳定性 规则目录（12条）
+└── scripts/
+    └── add-rule.py                # 规则脚手架工具
+```
+
+## 工作流程
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                            用户输入 (opencode)                       │
+│                                                                      │
+│     "稳定性全量扫描 ./rosen/"  /  "用 ExceptionHandling_001 检视 ./src/" │
+└───────────────────────────────────┬──────────────────────────────────┘
+                                    │
+                                    ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                       步骤 1：规则加载与遍历准备                      │
+│                                                                      │
+│  加载 config/rules.yaml ──→ 确定启用的规则列表                       │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │ 规则遍历策略：                                                 │ │
+│  │                                                                │ │
+│  │ 情况 1：用户指定检测规则                                       │ │
+│  │   - 解析用户指定的规则 ID 列表或规则级别过滤条件               │ │
+│  │   - 遍历用户指定的所有规则，确保无遗漏                         │ │
+│  │   - 验证指定的规则 ID 是否存在                                 │ │
+│  │                                                                │ │
+│  │ 情况 2：用户未指定检测规则                                     │ │
+│  │   - 加载 config/rules.yaml 中所有启用的规则                    │ │
+│  │   - 遍历所有启用的规则，确保无遗漏                             │ │
+│  │   - 默认包含所有 57 条规则（覆盖 9 个稳定性分类）              │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                                                      │
+│  根据规则 reference 字段 ──→ 加载 references/ 下对应的规则文档       │
+│  按稳定性分类组织规则 ──→ 准备分发给对应的 subagent                 │
+│                                                                      │
+│  示例：加载 references/ExceptionHandling/StabilityCodeReview_ExceptionHandling_001.md │
+└───────────────────────────────────┬──────────────────────────────────┘
+                                    │
+                                    ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                         步骤 2：白名单配置加载                        │
+│                                                                      │
+│  加载 config/whitelist.yaml ──→ 初始化白名单过滤规则                 │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │ 白名单类型：                                                   │ │
+│  │                                                                │ │
+│  │ 1. 全局路径白名单（global.paths）                              │ │
+│  │    - test/, tests/, unittest/, mock/, build/, out/, .git/ 等   │ │
+│  │    - 包含这些路径的文件将被跳过                                │ │
+│  │                                                                │ │
+│  │ 2. 全局文件模式白名单（global.patterns）                       │ │
+│  │    - *_test.cpp, *_unittest.h, *_fuzztest.cpp, *.pb.cc 等      │ │
+│  │    - 匹配这些模式的文件将被跳过                                │ │
+│  │                                                                │ │
+│  │ 3. 规则级白名单（rules.RULE_ID.patterns）                      │ │
+│  │    - 针对特定规则的误报排除模式                                │ │
+│  │    - 仅对该规则生效，不影响其他规则检视                       │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+└───────────────────────────────────┬──────────────────────────────────┘
+                                    │
+                                    ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                步骤 3：并行分类型代码检视（Subagent 模式）            │
+│                                                                      │
+│  主 Agent 根据稳定性分类启动多个 Subagent，每个 Subagent 负责一个分类 │
+│  **重要：每个 Subagent 必须遍历该分类下的所有规则，不得遗漏**        │
+│  **重要：每个 Subagent 必须按照 references/PROBLEM_TEMPLATE.md 格式输出问题** │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │ Subagent 1: 异常处理分类检视                                   │ │
+│  │   - 遍历 ExceptionHandling_001~003 所有规则（共 3 条）         │ │
+│  │   - 根据规则文档执行代码检视                                   │ │
+│  │   - 按照检出问题格式模板输出该分类的 issues 列表               │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │ Subagent 2: 并发稳定性分类检视                                 │ │
+│  │   - 遍历 ConcurrencyStability_001~005 所有规则（共 5 条）      │ │
+│  │   - 根据规则文档执行代码检视                                   │ │
+│  │   - 按照检出问题格式模板输出该分类的 issues 列表               │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │ Subagent 3: 性能稳定性分类检视                                 │ │
+│  │   - 遍历 PerformanceStability_001~002 所有规则（共 2 条）      │ │
+│  │   - 根据规则文档执行代码检视                                   │ │
+│  │   - 按照检出问题格式模板输出该分类的 issues 列表               │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│  ... （其他分类：资源管理、初始化顺序、边界条件、生命周期、          │
+│        内存稳定性、图形稳定性）                                      │
+│                                                                      │
+│  每个分类对应的 Subagent 数量：共 9 个 Subagent（覆盖 9 个稳定性分类） │
+│  每个 Subagent 的检视流程：                                          │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │ 对每个代码文件，按规则文档要求执行检视：                       │ │
+│  │                                                                │ │
+│  │ 1. 白名单过滤（优先执行）                                      │ │
+│  │    检查文件路径是否匹配白名单配置：                            │ │
+│  │    - 全局路径白名单：test/, unittest/, build/ 等               │ │
+│  │    - 全局文件模式白名单：*_test.cpp, *.pb.cc 等                │ │
+│  │    - 规则级白名单：特定规则的排除模式                          │ │
+│  │    匹配则跳过该文件，不进行后续检视                            │ │
+│  │         │                                                      │ │
+│  │         ▼                                                      │ │
+│  │ 2. 遍历该分类下的所有规则（必须遍历，不得遗漏）                 │ │
+│  │    按顺序检查每一条规则：                                      │ │
+│  │    - 规则 1 → 规则 2 → 规则 3 → ... → 规则 N                   │ │
+│  │         │                                                      │ │
+│  │         ▼                                                      │ │
+│  │ 3. 识别 RISK_PATTERN（稳定性风险模式）                         │ │
+│  │    根据规则文档中的检测范围和检测要点                          │ │
+│  │         │                                                      │ │
+│  │         ▼                                                      │ │
+│  │ 4. 分析 CONTEXT（上下文：异常处理、资源管理、并发等）           │ │
+│  │    判断是否存在安全防护                                        │ │
+│  │         │                                                      │ │
+│  │         ▼                                                      │ │
+│  │ 5. 评估 IMPACT（稳定性影响：服务中断、性能退化、资源耗尽等）    │ │
+│  │    根据规则文档中的 RiskFlow 和 ImpactAnalysis                  │ │
+│  │         │                                                      │ │
+│  │         ▼                                                      │ │
+│  │ 6. 安全写法排除                                                │ │
+│  │    参考规则文档中的误报排除表格                                │ │
+│  │    NOPROTECT 标记、安全防护代码等                               │ │
+│  │         │                                                      │ │
+│  │         ▼                                                      │ │
+│  │ 7. 构建检出结果（严格按照 references/PROBLEM_TEMPLATE.md 格式）│ │
+│  │    - 问题标题、分类、规则、位置、函数名、严重程度              │ │
+│  │    - 关键源码片段（5-20行）                                    │ │
+│  │    - 问题描述（说明违反的规则和存在的风险）                    │ │
+│  │    - 风险流分析（RiskFlow）                                    │ │
+│  │    - 影响分析（ImpactAnalysis）                                │ │
+│  │    - 修复建议（描述+代码示例）                                 │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                                                      │
+│  每个 Subagent 输出：符合 references/PROBLEM_TEMPLATE.md 格式的 issues 列表 │
+└───────────────────────────────────┬──────────────────────────────────┘
+                                    │
+                                    ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                     步骤 4：主 Agent 汇总检测结果                     │
+│                                                                      │
+│  主 Agent 收集所有 Subagent 的检测结果并进行汇总整理：               │
+│  **重要：所有 Subagent 输出必须符合 references/PROBLEM_TEMPLATE.md 格式** │
+│                                                                      │
+│  ┌────────────────────────────────────────────────────────────────┐ │
+│  │ 汇总流程：                                                     │ │
+│  │                                                                │ │
+│  │ 1. 收集所有 Subagent 的输出                                    │ │
+│  │    - Subagent 1 (异常处理) issues 列表                         │ │
+│  │    - Subagent 2 (并发稳定性) issues 列表                       │ │
+│  │    - ... (其他 7 个分类)                                       │ │
+│  │    - Subagent 9 (图形稳定性) issues 列表                       │ │
+│  │                                                                │ │
+│  │ 2. 验证规则遍历完整性                                          │ │
+│  │    - 检查用户指定的规则是否全部遍历                            │ │
+│  │    - 或检查所有启用的规则是否全部遍历                          │ │
+│  │                                                                │ │
+│  │ 3. 格式验证                                                    │ │
+│  │    - 验证每个检出问题是否符合 references/PROBLEM_TEMPLATE.md 格式 │
+│  │    - 验证问题格式的完整性和规范性                              │ │
+│  │    - 确保包含问题标题、分类、规则、位置、函数名、严重程度等必需字段 │
+│  │                                                                │ │
+│  │ 4. 去重合并                                                    │ │
+│  │    - 合并所有 issues 列表                                      │ │
+│  │    - 按分类组织检测结果                                        │ │
+│  │    - 同位置问题去重合并                                        │ │
+│  │                                                                │ │
+│  │ 5. 分组排序                                                    │ │
+│  │    - 按 references/REPORT_TEMPLATE.md **检出问题详情**章节格式组织报告结构 │
+│  │    - 按严重程度分组排序：CRITICAL → HIGH → MEDIUM → LOW        │ │
+│  │    - 统计问题数量、分类分布、严重程度分布                      │ │
+│  └────────────────────────────────────────────────────────────────┘ │
+│                                                                      │
+│  汇总输出：符合 references/REPORT_TEMPLATE.md **检出问题详情**章节格式要求的问题列表 │
+└───────────────────────────────────┬──────────────────────────────────┘
+                                    │
+                                    ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│                          步骤 5：报告生成                             │
+│                                                                      │
+│  **重要：报告必须输出到 ./report/ 目录**                             │
+│  **禁止输出到其他路径**（如 .opencode/tmp/、./output/ 等）           │
+│                                                                      │
+│  **重要：必须按照 references/REPORT_TEMPLATE.md 格式生成Markdown报告** │
+│  **重要：必须按照 references/REPORT_TEMPLATE.csv 格式生成CSV报告**    │
+│  **禁止偏离模板定义的格式**                                          │
+│                                                                      │
+│  **必须执行的输出流程**：                                            │
+│                                                                      │
+│  1. 检查 ./report/ 目录是否存在                                      │
+│     使用 Bash 工具执行：ls ./report/                                 │
+│     或使用 Glob 工具检查：pattern="./report/*"                       │
+│                                                                      │
+│  2. 如果 ./report/ 不存在，必须先创建目录                           │
+│     使用 Bash 工具执行：mkdir ./report                               │
+│     **禁止在目录不存在时直接输出**                                   │
+│                                                                      │
+│  3. 严格按 references/REPORT_TEMPLATE.md 格式生成Markdown报告       │
+│     严格按 references/REPORT_TEMPLATE.csv 格式生成CSV报告           │
+│     **禁止增减报告章节或修改报告格式**                               │
+│                                                                      │
+│  4. 输出报告到 ./report/ 目录（必须使用 Write 工具）                 │
+│     ├── ./report/report_{target}_{timestamp}.md     ← 详细报告      │
+│     └── ./report/report_{target}_{timestamp}.csv    ← 表格报告      │
+│     **target**: 检视目标名称（如文件名、目录名）                     │
+│     **timestamp**: 时间戳格式 `YYYYMMDD_HHMMSS`                     │
+│                                                                      │
+│  5. 验证报告已成功输出                                               │
+│     使用 Bash 工具执行：ls ./report/                                 │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## 工作流说明
+
+### 关键原则
+
+1. **规则遍历完整性**：
+   - 用户指定检测规则时：必须遍历用户指定的所有规则，不得遗漏任何一条规则
+   - 用户未指定检测规则时：必须遍历所有启用的规则，不得遗漏任何一条规则
+   - 主 Agent 必须验证所有指定或启用的规则已全部遍历
+
+2. **模板格式严格遵守**：
+   - Subagent 输出：每个 Subagent 必须严格按照 `references/PROBLEM_TEMPLATE.md` 格式输出问题
+   - 主 Agent 输出：主 Agent 必须严格按照 `references/REPORT_TEMPLATE.md` 和 `references/REPORT_TEMPLATE.csv` 格式生成报告
+   - 格式验证：主 Agent 在汇总时验证每个问题的格式完整性和规范性
+   - 禁止偏离：任何输出不得偏离模板定义的格式和章节结构
+
+3. **Subagent 并行检视**：
+   - 针对每个稳定性分类，必须启动独立的 Subagent 进行检视
+   - 共 9 个稳定性分类，对应 9 个 Subagent 并行工作
+   - 每个 Subagent 负责遍历该分类下的所有规则，不得遗漏
+   - 所有 Subagent 完成后，由主 Agent 汇总检测结果
+
+### 详细流程
+
+1. **规则加载与遍历准备**：
+   - 根据 config/rules.yaml 加载启用的规则列表
+   - **用户指定规则时**：解析用户指定的规则 ID 或过滤条件，确保遍历所有指定规则
+   - **用户未指定规则时**：加载所有启用的规则，确保遍历所有规则
+   - 验证规则 ID 的有效性，按稳定性分类组织规则
+
+2. **白名单配置加载**：
+   - 加载 config/whitelist.yaml，初始化全局路径白名单、文件模式白名单和规则级白名单
+   - 将白名单配置传递给所有 Subagent
+
+3. **并行分类型代码检视（Subagent 模式）**：
+   - 主 Agent 根据稳定性分类启动 9 个 Subagent（覆盖 9 个分类）
+   - 每个 Subagent 的职责：
+     - 遍历该分类下的所有规则（例如：异常处理分类遍历 ExceptionHandling_001~003 共 3 条规则）
+     - 根据规则文档执行代码检视，应用白名单过滤
+     - 输出该分类的 issues 列表
+   - **重要**：每个 Subagent 必须遍历该分类下的所有规则，不得遗漏任何一条规则
+   - Subagent 分类列表：
+     - Subagent 1: 异常处理（ExceptionHandling，3 条规则）
+     - Subagent 2: 并发稳定性（ConcurrencyStability，5 条规则）
+     - Subagent 3: 性能稳定性（PerformanceStability，2 条规则）
+     - Subagent 4: 资源管理（ResourceManagement，7 条规则）
+     - Subagent 5: 初始化顺序（InitializationOrder，1 条规则）
+     - Subagent 6: 边界条件（BoundaryCondition，18 条规则）
+     - Subagent 7: 生命周期（Lifecycle，2 条规则）
+     - Subagent 8: 内存稳定性（MemoryStability，7 条规则）
+     - Subagent 9: 图形稳定性（GraphicsStability，12 条规则）
+
+4. **主 Agent 汇总检测结果**：
+    - 收集所有 9 个 Subagent 的输出
+    - 格式验证：验证每个问题的格式完整性和规范性
+    - 去重合并：合并所有 issues 列表，同位置问题合并
+    - 分组排序：按分类组织，按严重程度分组（CRITICAL → HIGH → MEDIUM → LOW）
+    - 验证规则遍历完整性：
+      - 检查用户指定的规则是否全部遍历
+      - 或检查所有启用的规则是否全部遍历
+      - 记录每条规则的检查状态作为内部验证
+
+5. **报告输出（强制要求）**：
+   - **必须**先检查 `./report/` 目录是否存在
+   - 如果不存在，**必须**先使用 Bash 工具执行 `mkdir ./report` 创建目录
+   - **必须**使用 Write 工具输出 Markdown 和 CSV 报告到 `./report/` 目录
+   - **必须**严格按照 `references/REPORT_TEMPLATE.md` 格式生成Markdown报告
+   - **必须**同时按照 `references/REPORT_TEMPLATE.csv` 格式生成CSV报告
+   - Markdown报告必须包含以下章节：
+     - 检视概览（代码信息、问题统计、分类问题分布）
+     - 检出问题详情（按严重程度分组，每个问题严格遵循 `references/PROBLEM_TEMPLATE.md`）
+     - 修复优先级建议
+     - 附录（白名单过滤、检视工具版本）
+   - CSV报告必须包含以下内容：
+     - 首行标题包含：问题序号、稳定性类别、规则名称、规则ID、问题描述、文件路径
+     - 后续每行列出一个检出问题
+     - 问题描述和文件路径**禁止**包含 `,` 字符
+   - **禁止**输出到其他路径（如 `.opencode/tmp/` 等）
+   - **禁止**偏离模板定义的格式
+   - 如果报告未输出到 `./report/` 目录或格式不符合模板，视为**检视流程不完整**，需要重新执行输出步骤
+
+## 核心概念
+
+### 稳定性分类
+
+框架包含 9 个稳定性分类，总计 57 条规则：
+
+| 分类 | 英文名 | 规则数量 | 描述 | 规则ID范围 |
+|------|--------|----------|------|------------|
+| 异常处理 | ExceptionHandling | 3条 | 检测异常未捕获、空catch块、异常处理不当等 | ExceptionHandling_001~003 |
+| 并发稳定性 | ConcurrencyStability | 5条 | 检测死锁风险、线程池耗尽、任务堆积等 | ConcurrencyStability_001~005 |
+| 性能稳定性 | PerformanceStability | 2条 | 检测无限循环风险、大循环、递归深度等 | PerformanceStability_001~002 |
+| 资源管理 | ResourceManagement | 7条 | 检测文件句柄泄漏、数据库连接泄漏等 | ResourceManagement_001~007 |
+| 初始化顺序 | InitializationOrder | 1条 | 检测静态初始化顺序问题、未初始化使用等 | InitializationOrder_001 |
+| 边界条件 | BoundaryCondition | 18条 | 检测空容器操作、极端输入处理等 | BoundaryCondition_001~018 |
+| 生命周期 | Lifecycle | 2条 | 检测对象生命周期管理、异步任务生命周期等 | Lifecycle_001~002 |
+| 内存稳定性 | MemoryStability | 7条 | 检测内存泄漏、OOM风险、内存碎片化等 | MemoryStability_001~007 |
+| 图形稳定性 | GraphicsStability | 12条 | 检测图形资源泄漏、渲染异常、UI线程阻塞等 | GraphicsStability_001~012 |
+
+所有规则以 Markdown 文档形式存放在 `references/` 目录，按文件夹分类
+
+### 严重程度等级
+
+| 等级 | 定义 | 适用场景 | 典型后果 |
+|------|------|----------|----------|
+| **CRITICAL** | 极高风险，可能导致系统崩溃、安全漏洞，必须立即修复 | 空指针解引用、use-after-free、double-free、内存越界访问、Parcel数据安全风险、除零崩溃 | 程序崩溃（SIGSEGV）、安全漏洞、内存损坏 |
+| **HIGH** | 高风险，可能导致服务中断、资源耗尽、严重稳定性问题 | 内存泄漏、资源泄漏、线程安全问题、并发死锁、递归栈溢出、GPU资源管理问题 | OOM、资源耗尽、服务中断、性能严重退化 |
+| **MEDIUM** | 中等风险，可能导致功能异常、数据错误，但不直接导致崩溃 | 编码规范违规、类型转换问题、初始化顺序问题、JSON处理不当、std::atomic时序问题 | 功能异常、数据错误、性能轻微退化 |
+
+### 规则文档结构
+
+每条规则文档包含以下核心内容：
+- **问题描述**：稳定性风险的具体描述和危害
+- **检测示例**：问题代码和修复方案对比
+- **检测范围**：需要检查的 API、函数、模式
+- **检测要点**：具体的检测步骤
+- **风险流分析（RiskFlow）**：风险来源、风险类型、传播路径、影响点
+- **影响分析（ImpactAnalysis）**：触发条件、传播方式、后果、缓解建议
+- **误报排除**：安全场景识别表格
+- **测试用例**：包含触发用例（错误写法）和安全用例（正确写法）
+
+规则文档格式详见示例[references/RULE_TEMPLATE.md](references/RULE_TEMPLATE.md)
+
+### 规则遍历机制
+
+框架采用**严格遍历机制**，确保规则检视的完整性：
+
+1. **用户指定规则时**：
+   - 解析用户指定的规则 ID 列表或过滤条件
+   - 按列表顺序遍历所有指定规则，不得遗漏
+   - 验证规则 ID 的有效性
+   - 内部验证所有指定规则已遍历
+
+2. **用户未指定规则时**：
+    - 加载 config/rules.yaml 中所有启用的规则
+    - 默认遍历所有启用的规则
+    - 按分类组织规则遍历流程
+    - 内部验证所有启用规则已遍历
+
+### Subagent 并行检视机制
+
+框架采用**分类并行检视**机制，提升检视效率：
+
+1. **分类型并行**：
+   - 主 Agent 根据 9 个稳定性分类启动 9 个 Subagent
+   - 每个 Subagent 负责一个稳定性分类的规则检视
+   - Subagent 之间并行工作，互不干扰
+
+2. **Subagent 职责**：
+   - 接收主 Agent 分配的稳定性分类
+   - 遍历该分类下的所有规则（例如：异常处理分类遍历 3 条规则）
+   - 对每个代码文件执行规则检视
+   - 应用白名单过滤
+   - 输出该分类的 issues 列表
+
+3. **主 Agent 汇总**：
+    - 收集所有 9 个 Subagent 的检测结果
+    - 格式验证：验证每个问题的格式完整性和规范性
+    - 去重合并：合并 issues 列表，同位置问题合并
+    - 分组排序：按分类组织，按严重程度分组
+    - 验证规则遍历完整性
+    - 生成最终报告
+
+### 规则遍历完整性验证
+
+为确保规则遍历不遗漏，框架要求以下验证机制：
+
+1. **检视前验证**：
+   - 用户指定规则时：验证所有指定规则 ID 是否存在
+   - 用户未指定规则时：加载所有启用的规则 ID 列表
+   - 按分类统计规则数量，准备分发给 Subagent
+
+2. **检视中验证**：
+   - 每个 Subagent 必须遍历该分类下的所有规则，不得遗漏
+   - Subagent 输出应包含已遍历的规则 ID 列表
+
+3. **检视后验证**：
+   - 主 Agent 验证每个分类的规则遍历完整性
+   - 标注每条规则的遍历状态作为过程验证
+   - **不要**单开章节输出完整性验证到报告中
+
+### 报告输出
+
+1. **模板文件**：
+   - **Subagent 输出格式**：[检出问题格式模板](references/PROBLEM_TEMPLATE.md)
+     - 每个 Subagent 必须严格按照此模板格式输出检出的每个问题
+     - 包含：问题标题、分类、规则、位置、函数、严重程度、关键源码片段、问题描述、风险流分析、影响分析、修复建议
+   - **主 Agent 输出格式**：[报告输出格式模板(Markdown)](references/REPORT_TEMPLATE.md)
+     - 主 Agent 必须严格按照此模板格式生成最终稳定性代码审查报告（Markdown格式）
+     - 包含：检视概览、检出问题详情（按严重程度分组）、修复优先级建议、附录
+   - **主 Agent 输出格式**：[报告输出格式模板(CSV)](references/REPORT_TEMPLATE.csv)
+     - 主 Agent 必须严格按照此模板格式生成检出问题列表报告（CSV格式）
+     - 首行标题包含：问题序号、稳定性类别、规则名称、规则ID、问题描述、文件路径
+     - 问题描述和文件路径**禁止**包含 `,` 字符
+   
+2. **格式遵守要求**：
+   - Subagent 输出问题前，必须参考 `references/PROBLEM_TEMPLATE.md` 确保格式完整
+   - 主 Agent 汇总问题时，必须验证每个问题的格式完整性和规范性
+   - 主 Agent 生成报告前，必须参考 `references/REPORT_TEMPLATE.md` 和 `references/REPORT_TEMPLATE.csv` 确保格式完整
+   - 禁止偏离模板定义的格式和章节结构
+
+## 添加新规则
+
+1. **定义规则信息**：确定规则 ID、名称、分类、严重程度
+2. **创建规则文档**：按 [references/RULE_TEMPLATE.md](references/RULE_TEMPLATE.md) 格式编写规则文档
+3. **更新配置**：在 [config/rules.yaml](config/rules.yaml) 中添加规则配置
+4. **更新文档**：新增规则后，需同步更新 [README.md](README.md)、[SKILL.md](SKILL.md)、[references/RULE_INDEX.md](references/RULE_INDEX.md) 中的相关说明
+5. **验证规则有效性**：使用 Agent 检视代码验证规则检出准确性，根据结果优化规则文档
+
+更多规则开发指导详见 [references/RULE_DEVELOPMENT_GUIDE.md](references/RULE_DEVELOPMENT_GUIDE.md)