@ohos-graphics/stability-code-review 0.1.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.
Files changed (70) hide show
  1. package/README.md +169 -0
  2. package/SKILL.md +518 -0
  3. package/bin/install.js +165 -0
  4. package/config/rules.yaml +445 -0
  5. package/config/whitelist.yaml +52 -0
  6. package/package.json +40 -0
  7. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_001.md +275 -0
  8. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_002.md +273 -0
  9. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_003.md +305 -0
  10. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_004.md +350 -0
  11. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_005.md +301 -0
  12. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_006.md +320 -0
  13. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_007.md +432 -0
  14. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_008.md +394 -0
  15. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_009.md +425 -0
  16. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_010.md +472 -0
  17. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_011.md +204 -0
  18. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_012.md +210 -0
  19. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_013.md +226 -0
  20. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_014.md +222 -0
  21. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_015.md +256 -0
  22. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_016.md +269 -0
  23. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_017.md +222 -0
  24. package/references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_018.md +336 -0
  25. package/references/ConcurrencyStability/StabilityCodeReview_ConcurrencyStability_001.md +414 -0
  26. package/references/ConcurrencyStability/StabilityCodeReview_ConcurrencyStability_002.md +335 -0
  27. package/references/ConcurrencyStability/StabilityCodeReview_ConcurrencyStability_003.md +284 -0
  28. package/references/ConcurrencyStability/StabilityCodeReview_ConcurrencyStability_004.md +313 -0
  29. package/references/ConcurrencyStability/StabilityCodeReview_ConcurrencyStability_005.md +364 -0
  30. package/references/ExceptionHandling/StabilityCodeReview_ExceptionHandling_001.md +142 -0
  31. package/references/ExceptionHandling/StabilityCodeReview_ExceptionHandling_002.md +222 -0
  32. package/references/ExceptionHandling/StabilityCodeReview_ExceptionHandling_003.md +383 -0
  33. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_001.md +258 -0
  34. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_002.md +131 -0
  35. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_003.md +220 -0
  36. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_004.md +224 -0
  37. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_005.md +250 -0
  38. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_006.md +153 -0
  39. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_007.md +169 -0
  40. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_008.md +153 -0
  41. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_009.md +144 -0
  42. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_010.md +152 -0
  43. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_011.md +221 -0
  44. package/references/GraphicsStability/StabilityCodeReview_GraphicsStability_012.md +318 -0
  45. package/references/InitializationOrder/StabilityCodeReview_InitializationOrder_001.md +411 -0
  46. package/references/Lifecycle/StabilityCodeReview_Lifecycle_001.md +255 -0
  47. package/references/Lifecycle/StabilityCodeReview_Lifecycle_002.md +177 -0
  48. package/references/MemoryStability/StabilityCodeReview_MemoryStability_001.md +332 -0
  49. package/references/MemoryStability/StabilityCodeReview_MemoryStability_002.md +261 -0
  50. package/references/MemoryStability/StabilityCodeReview_MemoryStability_003.md +428 -0
  51. package/references/MemoryStability/StabilityCodeReview_MemoryStability_004.md +400 -0
  52. package/references/MemoryStability/StabilityCodeReview_MemoryStability_005.md +364 -0
  53. package/references/MemoryStability/StabilityCodeReview_MemoryStability_006.md +359 -0
  54. package/references/MemoryStability/StabilityCodeReview_MemoryStability_007.md +279 -0
  55. package/references/PROBLEM_TEMPLATE.md +65 -0
  56. package/references/PerformanceStability/StabilityCodeReview_PerformanceStability_001.md +380 -0
  57. package/references/PerformanceStability/StabilityCodeReview_PerformanceStability_002.md +437 -0
  58. package/references/REPORT_TEMPLATE.csv +5 -0
  59. package/references/REPORT_TEMPLATE.md +132 -0
  60. package/references/RULE_DEVELOPMENT_GUIDE.md +711 -0
  61. package/references/RULE_INDEX.md +101 -0
  62. package/references/RULE_TEMPLATE.md +192 -0
  63. package/references/ResourceManagement/StabilityCodeReview_ResourceManagement_001.md +334 -0
  64. package/references/ResourceManagement/StabilityCodeReview_ResourceManagement_002.md +425 -0
  65. package/references/ResourceManagement/StabilityCodeReview_ResourceManagement_003.md +420 -0
  66. package/references/ResourceManagement/StabilityCodeReview_ResourceManagement_004.md +409 -0
  67. package/references/ResourceManagement/StabilityCodeReview_ResourceManagement_005.md +445 -0
  68. package/references/ResourceManagement/StabilityCodeReview_ResourceManagement_006.md +384 -0
  69. package/references/ResourceManagement/StabilityCodeReview_ResourceManagement_007.md +395 -0
  70. package/scripts/add-rule.py +423 -0
@@ -0,0 +1,711 @@
1
+ # 规则开发指南
2
+
3
+ ## 核心流程
4
+
5
+ ```
6
+ 定义规则需求 → 创建规则文档 → 更新配置 → 测试验证 → 持续改进
7
+ ```
8
+
9
+ ---
10
+
11
+ ## 第一步:定义规则需求
12
+
13
+ 明确以下信息:
14
+
15
+ - **规则 ID**: `StabilityCodeReview_XXX_YYY`(XXX为分类英文缩写,YYY为序号)
16
+ - **规则名称**: 一句话描述稳定性问题,简洁明确
17
+ - **分类**: 异常处理/并发稳定性/性能稳定性/资源管理/初始化顺序/边界条件/生命周期/内存稳定性/图形稳定性
18
+ - **严重程度**: CRITICAL/HIGH/MEDIUM/LOW(详见下方严重程度定义)
19
+ - **检测需求**: 详细描述要检测的稳定性风险场景,包括:
20
+ - 问题触发条件
21
+ - 影响范围
22
+ - 实际项目中的常见错误模式
23
+ - 参考的实际代码函数/类名/常量值
24
+
25
+ ### 严重程度定义
26
+
27
+ | 等级 | 定义 | 适用场景 | 典型后果 |
28
+ |------|------|----------|----------|
29
+ | **CRITICAL** | 极高风险,可能导致系统崩溃、安全漏洞,必须立即修复 | 空指针解引用、use-after-free、double-free、内存越界访问、Parcel数据安全风险、除零崩溃、悬垂引用、返回局部变量引用 | 程序崩溃(SIGSEGV)、安全漏洞、内存损坏、未定义行为 |
30
+ | **HIGH** | 高风险,可能导致服务中断、资源耗尽、严重稳定性问题 | 内存泄漏、资源泄漏、线程安全问题、并发死锁、递归栈溢出、GPU资源管理问题、引用计数错误、容器find未检查、反序列化内存泄漏 | OOM、资源耗尽、服务中断、性能严重退化、GPU崩溃 |
31
+ | **MEDIUM** | 中等风险,可能导致功能异常、数据错误,但不直接导致崩溃 | 编码规范违规、类型转换问题、初始化顺序问题、JSON处理不当、std::atomic时序问题、异常处理机制、数据成员未初始化 | 功能异常、数据错误、性能轻微退化、未定义值 |
32
+ | **LOW** | 低风险,代码质量问题,建议改进 | 编码风格问题、性能优化建议、可维护性问题 | 代码可读性差、维护成本高 |
33
+
34
+ ---
35
+
36
+ ## 第二步:创建规则文档
37
+
38
+ 在 `references/分类名称/` 目录下创建规则文档:
39
+
40
+ ```
41
+ references/BoundaryCondition/StabilityCodeReview_BoundaryCondition_XXX.md
42
+ ```
43
+
44
+ 按 [RULE_TEMPLATE.md](RULE_TEMPLATE.md) 格式编写文档,必须包含以下章节:
45
+
46
+ ### 1. 基本信息(YAML Front Matter)
47
+
48
+ ```yaml
49
+ ---
50
+ rule_id: "StabilityCodeReview_BoundaryCondition_XXX"
51
+ name: "规则名称"
52
+ category: "边界条件"
53
+ severity: "CRITICAL" # 根据风险等级选择
54
+ language: ["cpp", "c++"]
55
+ author: "OH-Department7 Stability Team"
56
+ ---
57
+ ```
58
+
59
+ ### 2. 问题描述
60
+
61
+ **要求**:
62
+ - 第一句话描述问题及其危害(必须)
63
+ - 可选补充详细背景说明(如OpenHarmony特定要求)
64
+ - 可选补充实际项目中的常见错误模式
65
+
66
+ **示例**:
67
+ ```markdown
68
+ ## 问题描述
69
+
70
+ 从Parcel中读取的数据不可信,不能直接作为循环或递归的条件,必须进行上限保护处理。恶意构造的Parcel数据可能包含超大数值,导致死循环、栈溢出或拒绝服务攻击。
71
+
72
+ OpenHarmony禁止使用C++异常处理机制(try/catch/throw)。异常处理机制会引入运行时开销和代码膨胀,影响系统稳定性和性能。
73
+ ```
74
+
75
+ ### 3. 检测示例
76
+
77
+ **必须包含5-10个问题场景**:
78
+
79
+ - 每个场景用注释标注具体问题
80
+ - 覆盖常见变体和实际代码模式
81
+ - 使用实际项目中的函数名、常量值增强真实性
82
+
83
+ **示例结构**:
84
+ ```cpp
85
+ // ❌ 问题代码
86
+ // 场景1:{具体问题描述,如"Parcel数据直接作为循环条件"}
87
+ void ReadDataFromParcel(Parcel& parcel)
88
+ {
89
+ int count = parcel.ReadInt32(); // 不可信数据
90
+ for (int i = 0; i < count; i++) { // 危险:count可能为超大值
91
+ ProcessItem(parcel);
92
+ }
93
+ }
94
+
95
+ // 场景2:{具体问题描述}
96
+ // 场景3:{具体问题描述}
97
+ // ...提供5-10个场景
98
+ ```
99
+
100
+ **必须包含5-10个修复方案**:
101
+
102
+ - 包括最佳实践、RAII模式
103
+ - 参考实际代码中的标准写法
104
+ - 使用真实函数名、日志函数、常量值
105
+
106
+ **示例结构**:
107
+ ```cpp
108
+ // ✅ 修复方案
109
+ // 修复场景1:{修复方法说明,如"添加上限保护"}
110
+ constexpr int MAX_ITEM_COUNT = 1000; // 实际项目中常用的常量值
111
+
112
+ void ReadDataFromParcel(Parcel& parcel)
113
+ {
114
+ int count = parcel.ReadInt32();
115
+ if (count < 0 || count > MAX_ITEM_COUNT) { // 安全:有上限保护
116
+ ROSEN_LOGE("Invalid count: %d", count); // 实际项目使用的日志函数
117
+ return;
118
+ }
119
+ for (int i = 0; i < count; i++) {
120
+ ProcessItem(parcel);
121
+ }
122
+ }
123
+
124
+ // 修复场景2:使用RAII模式(推荐)
125
+ // 修复场景3:使用智能指针
126
+ // ...提供5-10个修复方案
127
+ ```
128
+
129
+ ### 4. 检测范围
130
+
131
+ **要求**:
132
+ - 清晰列出要检查的目标(API、函数、模式)
133
+ - 编号列表,便于理解
134
+ - 具体到函数名、关键字、模式
135
+
136
+ **示例**:
137
+ ```markdown
138
+ ## 检测范围
139
+
140
+ 检查以下模式:
141
+
142
+ 1. 从Parcel读取数据后直接用于`for`循环
143
+ 2. 从Parcel读取数据后直接用于`while`循环
144
+ 3. 从Parcel读取数据后直接用于递归终止条件
145
+ 4. 从Parcel读取数据后用于嵌套循环控制
146
+ 5. Parcel.ReadInt32/ReadInt64/ReadUint32/ReadUint64等读取函数
147
+ ```
148
+
149
+ ### 5. 检测要点
150
+
151
+ **必须包含**:
152
+ - 基本检测步骤(5条)
153
+ - 误报排除方法
154
+
155
+ **可选扩展章节**(根据规则特点添加):
156
+
157
+ #### 最佳实践说明
158
+
159
+ 针对复杂技术点提供最佳实践:
160
+
161
+ - **推荐方式1**:说明适用场景和示例
162
+ - **推荐方式2**:说明适用场景和示例
163
+
164
+ **示例**(ConcurrencyStability_001):
165
+ ```markdown
166
+ ### memory_order使用说明
167
+
168
+ 精确的内存序控制可以提高性能并确保正确的同步:
169
+
170
+ - **memory_order_relaxed**:仅保证原子性,无顺序约束
171
+ - 适用场景:纯统计计数、不需要同步的数据
172
+ - 示例:`counter.fetch_add(1, std::memory_order_relaxed)`
173
+
174
+ - **memory_order_release**:写操作,确保之前的写操作对其他线程可见
175
+ - 适用场景:发布数据、状态标记
176
+ - 示例:`dataReady_.store(true, std::memory_order_release)`
177
+ ```
178
+
179
+ #### 实际代码参考
180
+
181
+ 引用实际项目中的具体元素:
182
+
183
+ - **实际常量值**:MAX_NESTING_DEPTH = 800
184
+ - **实际函数名**:RSCanvasDrawingRenderNodeDrawable::CreateGpuSurface
185
+ - **实际日志函数**:ROSEN_LOGE(), RS_LOGE()
186
+ - **实际项目路径**:rosen/modules/render_service/
187
+
188
+ **示例**(BoundaryCondition_001):
189
+ ```markdown
190
+ ### 动态上限vs常量上限
191
+
192
+ 实际代码中常用两种上限保护方式:
193
+
194
+ - **动态上限**:使用Parcel.GetReadableBytes()获取实际可读大小
195
+ - 示例:`if (len > readableSize || len > payload_.max_size())`
196
+ - 适用场景:数据大小可变、需要精确控制
197
+
198
+ - **常量上限**:使用constexpr定义固定上限
199
+ - 示例:`constexpr int MAX_ITEM_COUNT = 1000;`
200
+ - 适用场景:固定大小限制、简单场景
201
+ ```
202
+
203
+ #### 特殊技术说明
204
+
205
+ 针对复杂技术提供详细说明:
206
+
207
+ - **memory_order详解**(并发稳定性)
208
+ - **thread_local最佳实践**(并发稳定性)
209
+ - **C++11/20特性**(容器find、初始化)
210
+ - **POD vs 非POD类型**(初始化顺序)
211
+ - **Visitor模式**(性能稳定性)
212
+ - **VulkanCleanupHelper引用计数**(图形稳定性)
213
+
214
+ **示例**(InitializationOrder_001):
215
+ ```markdown
216
+ ### POD类型与非POD类型的差异
217
+
218
+ #### POD类型(Plain Old Data)- 必须显式初始化
219
+
220
+ - **基本类型**:int, long, float, double, char, bool
221
+ - **指针类型**:int*, void*, char*, Logger*
222
+ - **未初始化后果**:值为随机值,可能产生未定义行为
223
+
224
+ #### 非POD类型 - 通常有默认构造函数
225
+
226
+ - **STL容器**:std::string, std::vector, std::map
227
+ - **智能指针**:std::unique_ptr, std::shared_ptr
228
+ - **可以不显式初始化**:调用默认构造函数
229
+ ```
230
+
231
+ #### 分类处理策略
232
+
233
+ 针对不同场景提供不同处理方式:
234
+
235
+ **示例**(ConcurrencyStability_001):
236
+ ```markdown
237
+ ### 全局变量分类处理
238
+
239
+ 根据用途选择不同的保护策略:
240
+
241
+ - **统计计数器**:使用 std::atomic + memory_order_relaxed
242
+ - **缓存数据**:使用 std::mutex 保护或读写锁
243
+ - **配置数据**:使用 std::call_once 初始化,只读访问
244
+ - **线程独立数据**:使用 thread_local,无需同步
245
+ ```
246
+
247
+ ### 6. 风险流分析(RiskFlow)
248
+
249
+ **必须包含完整的风险流**:
250
+
251
+ ```markdown
252
+ - RISK_SOURCE: {具体到代码元素,如"Parcel读取的不可信数据"}
253
+ - RISK_TYPE: {具体风险类型,如"边界条件缺失、空指针解引用"}
254
+ - RISK_PATH: {完整传播路径,如"不可信数据 -> 循环条件 -> 无限循环/栈溢出"}
255
+ - IMPACT_POINT: {最终影响,如"系统资源耗尽、拒绝服务"}
256
+ ```
257
+
258
+ **要求**:
259
+ - 具体到代码元素(函数、API、变量)
260
+ - 描述完整的传播路径
261
+ - 说明最终影响系统稳定性的点
262
+
263
+ ### 7. 影响分析(ImpactAnalysis)
264
+
265
+ **必须包含完整的影响分析**:
266
+
267
+ ```markdown
268
+ - Trigger: {具体触发条件,如"使用Parcel数据作为循环条件"}
269
+ - Propagation: {具体传播方式,如"恶意构造超大数值导致无限循环"}
270
+ - Consequence: {具体后果,如"CPU资源耗尽、栈溢出、系统崩溃"}
271
+ - Mitigation: {具体缓解方案,如"添加数值上限检查,限制循环次数"}
272
+ ```
273
+
274
+ **要求**:
275
+ - 触发条件要具体(什么代码、什么数据)
276
+ - 传播方式要说明机制
277
+ - 后果要具体(崩溃、资源耗尽、性能下降等)
278
+ - 缓解方案要具体可行
279
+
280
+ ### 8. 误报排除
281
+
282
+ **必须包含误报排除表格**:
283
+
284
+ | 场景 | 识别特征 | 处理方式 |
285
+ |------|----------|----------|
286
+ | NOPROTECT标记 | 有 // NOPROTECT 注释 | 不报 |
287
+ | 已有安全防护 | {具体识别方法} | 不报 |
288
+ | 使用最佳实践 | {具体识别方法} | 不报 |
289
+ | 第三方库 | 位于 third_party 目录 | 白名单排除 |
290
+ | 测试代码 | 位于 test 目录 | 自动跳过 |
291
+
292
+ **要求**:
293
+ - 至少包含NOPROTECT、第三方库、测试代码的排除
294
+ - 针对规则特点添加具体的误报场景
295
+ - 识别特征要明确(注释、路径、代码模式)
296
+
297
+ ### 9. 测试用例
298
+
299
+ **触发用例要求**:
300
+ - 提供5-10个触发用例
301
+ - 覆盖典型错误模式和边界情况
302
+ - 每个用例用注释标注应该触发的原因
303
+
304
+ **安全用例要求**:
305
+ - 提供5-10个安全用例
306
+ - 覆盖正确做法和误报排除场景
307
+ - 包含NOPROTECT标记的用例
308
+ - 包含最佳实践的用例
309
+
310
+ ---
311
+
312
+ ## 第三步:更新配置
313
+
314
+ 在 `config/rules.yaml` 中添加规则配置:
315
+
316
+ ```yaml
317
+ 边界条件:
318
+ name: 边界条件
319
+ description: 检测边界条件处理不当导致的稳定性风险
320
+ enabled: true
321
+ rules:
322
+ StabilityCodeReview_BoundaryCondition_XXX:
323
+ enabled: true
324
+ id: StabilityCodeReview_BoundaryCondition_XXX
325
+ name: Parcel数据不可作为循环条件
326
+ severity: HIGH # 根据实际严重程度设置
327
+ description: Parcel数据不可信,不能直接作为循环条件
328
+ reference: 边界条件/StabilityCodeReview_BoundaryCondition_XXX.md
329
+ ```
330
+
331
+ ---
332
+
333
+ ## 第四步:更新文档
334
+
335
+ 新增规则后,需同步更新以下文档:
336
+
337
+ - **README.md**:更新规则总数和分类统计
338
+ - **SKILL.md**:更新"核心概念-稳定性分类"表格中的规则数量
339
+ - **references/RULE_INDEX.md**:添加新规则到规则索引
340
+
341
+ ---
342
+
343
+ ## 第五步:验证规则有效性
344
+
345
+ 使用 Agent 检视代码验证规则有效性:
346
+
347
+ 1. 选择包含目标问题模式的代码文件或目录
348
+ 2. 使用新增规则对代码进行检视
349
+ 3. 验证规则是否能准确检出问题
350
+ 4. 检查是否存在误报或漏报
351
+ 5. 根据验证结果优化规则文档
352
+
353
+ ---
354
+
355
+ ## 第六步:持续改进
356
+
357
+ 根据实际使用反馈持续改进:
358
+
359
+ 1. 收集误报案例,完善误报排除表格
360
+ 2. 收集漏报案例,扩展检测范围和要点
361
+ 3. 更新实际代码参考,增强真实性
362
+ 4. 补充新发现的错误模式和修复方案
363
+
364
+ ---
365
+
366
+ ## 规则编写最佳实践
367
+
368
+ ### 1. 代码示例质量
369
+
370
+ **问题代码要求**:
371
+ - 每个场景用注释标注具体问题(`// 错误:xxx` 或 `// 危险:xxx`)
372
+ - 使用实际项目中的函数名、类名(如Parcel、Drawing::Surface)
373
+ - 覆盖常见变体和实际错误模式
374
+ - 提供5-10个场景,全面覆盖问题
375
+
376
+ **修复方案要求**:
377
+ - 参考实际项目中的标准写法
378
+ - 使用真实的常量值(如MAX_NESTING_DEPTH = 800)
379
+ - 使用真实的日志函数(如ROSEN_LOGE())
380
+ - 包含RAII、智能指针等最佳实践
381
+ - 提供5-10个修复方案
382
+
383
+ ### 2. 检测要点深度
384
+
385
+ **基本检测步骤**:
386
+ - 如何识别目标代码模式
387
+ - 如何检查问题
388
+ - 如何判断风险
389
+ - 如何排除误报
390
+ - 特殊情况处理
391
+
392
+ **扩展说明章节**(根据规则特点添加):
393
+ - 最佳实践说明(memory_order、thread_local等)
394
+ - 实际代码参考(函数名、常量值、项目路径)
395
+ - 特殊技术说明(C++11/20特性、POD类型等)
396
+ - 分类处理策略(不同场景不同处理)
397
+
398
+ ### 3. 风险流和影响分析
399
+
400
+ **风险流要求**:
401
+ - RISK_SOURCE具体到代码元素(函数、API、变量)
402
+ - RISK_TYPE使用标准术语(空指针解引用、UAF、数据竞争等)
403
+ - RISK_PATH描述完整传播路径
404
+ - IMPACT_POINT说明最终影响
405
+
406
+ **影响分析要求**:
407
+ - Trigger具体触发条件
408
+ - Propagation传播机制
409
+ - Consequence具体后果(崩溃、OOM等)
410
+ - Mitigation具体缓解方案
411
+
412
+ ### 4. 误报排除完善
413
+
414
+ **必须包含的排除场景**:
415
+ - NOPROTECT标记
416
+ - 第三方库路径
417
+ - 测试代码路径
418
+ - 已有安全防护
419
+
420
+ **规则特有的排除场景**:
421
+ - 使用最佳实践(智能指针、RAII等)
422
+ - 使用新特性(C++11/20)
423
+ - 特殊业务场景
424
+
425
+ ### 5. 实际性增强
426
+
427
+ **引用实际项目元素**:
428
+ - 实际函数名:RSCanvasDrawingRenderNodeDrawable::CreateGpuSurface
429
+ - 实际类名:NativeBufferUtils::VulkanCleanupHelper
430
+ - 实际常量:MAX_NESTING_DEPTH, RECORD_CMD_MAX_DEPTH
431
+ - 实际日志:ROSEN_LOGE(), RS_LOGE()
432
+ - 实际项目路径:rosen/modules/render_service/
433
+
434
+ **参考实际代码模式**:
435
+ - Marshalling/Unmarshalling深度检查模式
436
+ - Visitor模式替代传统递归
437
+ - memory_order精确控制
438
+ - 动态上限vs常量上限
439
+
440
+ ---
441
+
442
+ ## 分类规则编写要点
443
+
444
+ ### 异常处理 (ExceptionHandling)
445
+
446
+ **特点**:
447
+ - OpenHarmony禁止异常处理机制
448
+ - 使用错误码返回值替代
449
+ - 需说明编码规范要求
450
+
451
+ **检测重点**:
452
+ - try/catch/throw关键字检测
453
+ - 错误码返回值使用模式
454
+ - 异常分支处理正确性
455
+
456
+ ### 并发稳定性 (ConcurrencyStability)
457
+
458
+ **特点**:
459
+ - 线程安全、数据竞争、竞态条件
460
+ - 需要详细说明memory_order、thread_local
461
+ - 涉及mutex、atomic、condition_variable
462
+
463
+ **扩展说明**:
464
+ - memory_order使用说明(relaxed/release/acquire/acq_rel)
465
+ - thread_local最佳实践
466
+ - 全局变量分类处理
467
+ - 检查-执行(check-then-act)模式
468
+
469
+ ### 性能稳定性 (PerformanceStability)
470
+
471
+ **特点**:
472
+ - 递归栈溢出、无限循环
473
+ - 需要说明实际深度限制值
474
+ - Visitor模式替代传统递归
475
+
476
+ **扩展说明**:
477
+ - 实际深度限制值参考(MAX_NESTING_DEPTH = 800)
478
+ - Marshalling/Unmarshalling深度检查模式
479
+ - Visitor模式替代传统递归
480
+ - 多重终止条件保护
481
+
482
+ ### 资源管理 (ResourceManagement)
483
+
484
+ **特点**:
485
+ - 内存泄漏、资源泄漏
486
+ - 反序列化、动态库加载
487
+ - 需要强调RAII、智能指针
488
+
489
+ **最佳实践**:
490
+ - 使用std::unique_ptr、std::shared_ptr
491
+ - 使用std::make_unique、std::make_shared
492
+ - 构造函数初始化列表
493
+ - 异常分支清理
494
+
495
+ ### 初始化顺序 (InitializationOrder)
496
+
497
+ **特点**:
498
+ - 类成员未初始化
499
+ - POD vs 非POD类型差异
500
+ - 多种初始化方式优先级
501
+
502
+ **扩展说明**:
503
+ - 初始化方式的优先级(类内初始化 > 初始化列表 > 函数体赋值)
504
+ - POD类型与非POD类型的差异
505
+ - 结构体初始化列表(C++11)
506
+ - 默认构造函数的作用
507
+
508
+ ### 边界条件 (BoundaryCondition)
509
+
510
+ **特点**:
511
+ - Parcel数据安全、不可信数据
512
+ - 容器find未检查、数组越界
513
+ - 动态上限vs常量上限
514
+
515
+ **扩展说明**:
516
+ - 动态上限vs常量上限(GetReadableBytes() vs constexpr)
517
+ - 实际常量值(MAX_ITEM_COUNT = 1000)
518
+ - contains()替代find()(C++20)
519
+ - 链式find逐层检查
520
+
521
+ ### 生命周期 (Lifecycle)
522
+
523
+ **特点**:
524
+ - 悬垂引用、UAF
525
+ - 返回局部变量引用
526
+ - 成员变量引用安全性
527
+
528
+ **扩展说明**:
529
+ - Meyers单例模式(静态局部变量)
530
+ - 成员变量引用安全
531
+ - 智能指针管理的对象引用
532
+ - 返回参数引用
533
+
534
+ ### 内存稳定性 (MemoryStability)
535
+
536
+ **特点**:
537
+ - 空指针解引用、内存分配失败
538
+ - malloc/calloc/realloc/new(std::nothrow)
539
+ - 智能指针替代手动管理
540
+
541
+ **扩展说明**:
542
+ - malloc/calloc/realloc必须判空
543
+ - new(std::nothrow)必须判空,普通new不需判空(OpenHarmony禁止异常)
544
+ - 使用RAII替代手动管理
545
+ - realloc失败时的指针处理
546
+
547
+ ### 图形稳定性 (GraphicsStability)
548
+
549
+ **特点**:
550
+ - GPU资源管理、引用计数
551
+ - VulkanCleanupHelper、VkImage
552
+ - 线程角色混乱
553
+
554
+ **扩展说明**:
555
+ - VulkanCleanupHelper引用计数管理(首次vs后续)
556
+ - DeleteVkImage函数指针
557
+ - GPU资源UAF风险
558
+ - RS主线程限制
559
+
560
+ ---
561
+
562
+ ## 规则文档完整性检查清单
563
+
564
+ 创建规则文档后,使用以下清单验证完整性:
565
+
566
+ ### 基本信息检查
567
+ - [ ] YAML Front Matter包含所有必需字段
568
+ - [ ] 规则ID格式正确(StabilityCodeReview_XXX_YYY)
569
+ - [ ] 严重程度根据风险等级正确设置
570
+ - [ ] 分类正确
571
+
572
+ ### 问题描述检查
573
+ - [ ] 第一句话描述问题及危害
574
+ - [ ] 可选补充详细背景说明
575
+ - [ ] 可选补充实际项目常见错误模式
576
+
577
+ ### 检测示例检查
578
+ - [ ] 问题代码包含5-10个场景
579
+ - [ ] 每个场景用注释标注具体问题
580
+ - [ ] 使用实际项目函数名、类名
581
+ - [ ] 修复方案包含5-10个方案
582
+ - [ ] 参考实际项目标准写法
583
+ - [ ] 包含RAII、智能指针等最佳实践
584
+
585
+ ### 检测范围检查
586
+ - [ ] 清晰列出检测目标(编号列表)
587
+ - [ ] 具体到函数名、关键字、模式
588
+
589
+ ### 检测要点检查
590
+ - [ ] 包含基本检测步骤(5条)
591
+ - [ ] 包含误报排除方法
592
+ - [ ] 根据规则特点添加扩展说明章节:
593
+ - [ ] 最佳实践说明(memory_order、thread_local等)
594
+ - [ ] 实际代码参考(函数名、常量值)
595
+ - [ ] 特殊技术说明(C++11/20特性等)
596
+ - [ ] 分类处理策略
597
+
598
+ ### 风险流和影响分析检查
599
+ - [ ] RiskFlow包含4个必需字段
600
+ - [ ] 具体到代码元素,描述完整路径
601
+ - [ ] ImpactAnalysis包含4个必需字段
602
+ - [ ] 触发条件、传播机制、后果、缓解方案具体
603
+
604
+ ### 误报排除检查
605
+ - [ ] 包含误报排除表格
606
+ - [ ] 至少包含NOPROTECT、第三方库、测试代码
607
+ - [ ] 针对规则特点添加具体误报场景
608
+ - [ ] 识别特征明确
609
+
610
+ ### 测试用例检查
611
+ - [ ] 触发用例包含5-10个
612
+ - [ ] 覆盖典型错误模式和边界情况
613
+ - [ ] 安全用例包含5-10个
614
+ - [ ] 覆盖正确做法和误报排除
615
+ - [ ] 包含NOPROTECT标记用例
616
+ - [ ] 包含最佳实践用例
617
+
618
+ ---
619
+
620
+ ## 规则编写常见问题
621
+
622
+ ### 问题1:代码示例不够实际
623
+
624
+ **解决方案**:
625
+ - 参考实际项目代码,使用真实的函数名、类名
626
+ - 使用实际项目中的常量值(MAX_NESTING_DEPTH = 800)
627
+ - 使用实际项目的日志函数(ROSEN_LOGE())
628
+ - 添加"实际代码参考"章节
629
+
630
+ ### 问题2:检测要点不够深入
631
+
632
+ **解决方案**:
633
+ - 根据规则特点添加扩展说明章节
634
+ - 详细说明技术细节(memory_order、thread_local等)
635
+ - 提供分类处理策略
636
+ - 说明最佳实践模式
637
+
638
+ ### 问题3:风险流不够具体
639
+
640
+ **解决方案**:
641
+ - RISK_SOURCE具体到代码元素(函数、API、变量)
642
+ - RISK_TYPE使用标准术语
643
+ - RISK_PATH描述完整传播路径,不跳过中间步骤
644
+ - IMPACT_POINT说明最终影响(崩溃、OOM等)
645
+
646
+ ### 问题4:误报排除不够完善
647
+
648
+ **解决方案**:
649
+ - 至少包含NOPROTECT、第三方库、测试代码
650
+ - 添加规则特有的误报场景
651
+ - 明确识别特征(注释、路径、代码模式)
652
+ - 使用表格形式,便于AI理解
653
+
654
+ ### 问题5:缺少最佳实践说明
655
+
656
+ **解决方案**:
657
+ - 添加"最佳实践说明"章节
658
+ - 说明推荐方式和适用场景
659
+ - 提供代码片段示例
660
+ - 说明性能、安全性等方面的考虑
661
+
662
+ ---
663
+
664
+ ## 规则文档模板使用指南
665
+
666
+ ### 必需章节(不可省略)
667
+
668
+ 1. YAML Front Matter
669
+ 2. 问题描述(至少一句话)
670
+ 3. 检测示例(至少5个问题场景+5个修复方案)
671
+ 4. 检测范围
672
+ 5. 检测要点(至少5条)
673
+ 6. 风险流分析
674
+ 7. 影响分析
675
+ 8. 误报排除表格
676
+ 9. 测试用例(至少5个触发+5个安全)
677
+
678
+ ### 可选章节(根据规则特点添加)
679
+
680
+ 1. 问题描述中的详细背景说明
681
+ 2. 检测要点中的扩展说明章节:
682
+ - 最佳实践说明
683
+ - 实际代码参考
684
+ - 特殊技术说明
685
+ - 分类处理策略
686
+ 3. 更多的代码示例场景(10+)
687
+
688
+ ### 建议的代码示例数量
689
+
690
+ - **简单规则**:5个问题场景 + 5个修复方案
691
+ - **复杂规则**:10个问题场景 + 10个修复方案
692
+ - **涉及多场景的规则**:覆盖所有主要场景,每个场景至少1个示例
693
+
694
+ ---
695
+
696
+ ## 总结
697
+
698
+ 编写高质量规则文档的关键:
699
+
700
+ 1. **实际性**:使用真实的项目函数名、常量值、日志函数
701
+ 2. **完整性**:包含所有必需章节,不省略关键信息
702
+ 3. **深度性**:添加扩展说明章节,详细说明技术细节
703
+ 4. **准确性**:风险流和影响分析具体到代码元素
704
+ 5. **全面性**:提供足够的代码示例(5-10个场景)
705
+ 6. **实用性**:包含最佳实践、误报排除、测试用例
706
+
707
+ 遵循本指南,创建的规则文档将:
708
+ - 帮助AI模型准确识别问题
709
+ - 提供明确的修复指导
710
+ - 减少误报和漏报
711
+ - 提高稳定性检测质量