@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rn-library-known-issue-check/references/INSPECTION_GUIDE.md

@@ -0,0 +1,99 @@
+# 规则检视指南
+
+> 本文档为 Phase 3「逐条规则检视」的详细操作指南，覆盖规则文件读取、源码对照检查、判定规则、few-shot 参考四个环节。
+
+---
+
+## 1. 规则文件结构
+
+读取 `rules/R-XX-*.md`，获取以下字段：
+
+| 字段 | 用途 |
+|------|------|
+| **状态** | `draft` / `active`。只消费 `active` 状态规则（见 SKILL.md 核心定位 #3） |
+| **严重级别** | high / medium / low，及判定依据 |
+| **适用范围** | 含预筛特征（Phase 2 使用） |
+| **问题本质** | 机制层描述，理解这类问题为什么会发生 |
+| **检查点** | 逐条可判定的源码检查动作（2-5 条） |
+| **错误特征** | 命中此类问题的典型代码形态 |
+| **正确特征** | 修复后的代码形态 |
+| **来源案例** | 案例索引（编号/库/现象/案例文件） |
+
+---
+
+## 2. 对照源码检查
+
+按规则文件的**检查点**逐条对照 `{outputDir}/source/ohos/` 源码检查。
+
+### 2.1 检查点判定
+
+每条检查点给出 **是/否/疑似** 判定：
+
+| 判定 | 含义 | 处理 |
+|------|------|------|
+| **是**（命中） | 源码存在规则描述的**错误特征** | 记录为命中问题，引用案例作为修复指引 |
+| **否**（通过） | 源码符合**正确特征** | 记录为通过 |
+| **疑似** | 无法确定，需进一步确认 | 记录为疑似命中，报告中标注"需人工复核" |
+
+### 2.2 检查点判定技巧
+
+| 检查点类型 | 判定方法 |
+|------------|----------|
+| 存在性检查（是否存在某文件/某调用） | 全量扫描源码目录，grep 关键词 |
+| 顺序检查（析构顺序/注册时序） | 阅读相关函数/析构函数，分析成员声明顺序与销毁顺序 |
+| 完整性检查（接口是否全部实现） | 对照接口声明与实现文件，逐一核对 |
+| 健壮性检查（异常处理/空判） | 阅读异常分支代码，检查 try-catch / null 判断 |
+
+### 2.3 证据记录
+
+命中检查点时，必须记录**证据**：
+- 文件路径 + 行号（如 `ReanimatedModuleProxy.cpp:192-200`）
+- 关键代码片段（≤15 行，用 `// ←` 标注缺陷点）
+- 判定依据（为什么判定为命中）
+
+> 证据是报告「命中问题详情」的核心内容，缺失证据的命中判定视为无效。
+
+---
+
+## 3. 规则命中判定
+
+- 规则中**任一检查点命中错误特征** → 该规则**命中**（记 1 个问题）
+- 所有检查点均通过 → 该规则**通过**
+- 疑似命中 → 按命中处理（报告中标注"疑似"），避免漏报
+
+---
+
+## 4. few-shot 参考
+
+判定困难时，读取规则文件引用的案例文件（`cases/KI-XXX-*.md`），对照"错误代码/正确代码"片段辅助判定。
+
+### 4.1 案例文件结构
+
+| 字段 | 用途 |
+|------|------|
+| 库与现象 | 原始具体信息 |
+| 根因 | 机制层根因（与规则"问题本质"呼应） |
+| 错误代码 | 修复前代码片段（`verified: diff` 时必填） |
+| 正确代码 | 修复后代码片段（`verified: diff` 时必填） |
+| 修复方式 | 可迁移的修复模式 |
+| PR 链接 | 修复 PR 完整 URL |
+| diff 材料 | 链接到 `pr-info/{repo}-{number}.md` |
+
+### 4.2 使用场景
+
+| 场景 | 用法 |
+|------|------|
+| 判定困难 | 对照案例错误/正确代码，确认当前库代码形态属于哪一类 |
+| 修复指引 | 从案例「修复方式」提炼可迁移的修复建议 |
+| 证据补充 | 案例 diff 材料可作为命中判定的佐证 |
+
+---
+
+## 5. 常见判定陷阱
+
+| 陷阱 | 规避方法 |
+|------|----------|
+| 只看 ArkTS 层，忽略 C++ 层 | 同时检索 `.cpp` / `.h` 文件 |
+| 只看 `source/ohos/`，忽略 `source/RN/` 对比 | 命中判定需与上游对比，确认是鸿蒙化引入的问题还是上游遗留 |
+| 凭印象判定，不记录证据 | 每条命中必须记录文件路径 + 行号 + 代码片段 |
+| 疑似命中直接跳过 | 疑似按命中处理，报告中标注"需人工复核" |

package/vendor/Server/Skills/rn-library-known-issue-check/references/PRESCREEN_GUIDE.md

@@ -0,0 +1,64 @@
+# 预筛指南
+
+> 本文档为 Phase 2「预筛适用规则」的详细操作指南。预筛是**核心环节**：知识库 19+ 条规则不可能全部适用于每个库，预筛决定哪些规则进入深度检查，直接影响检视效率与评分准确性。
+
+---
+
+## 1. 预筛特征四维度
+
+对每条规则，读取其规则文件（`rules/R-XX-*.md`）的**适用范围 + 预筛特征**，从四个维度判定是否适用：
+
+| 维度 | 判定依据 | 检索位置 |
+|------|----------|----------|
+| **依赖特征** | 当前库的 `oh-package.json5` / `package.json` 依赖中是否包含规则描述的依赖类型 | `{outputDir}/source/ohos/oh-package.json5`、`package.json` |
+| **文件特征** | 源码中是否存在规则描述的文件类型（`.ets` / `.cpp` / `module.json5` 等） | `{outputDir}/source/ohos/` 全量文件扫描 |
+| **API 特征** | 源码中是否调用规则描述的 API（`sensor.on` / `.gesture()` / `window` API 等） | `{outputDir}/source/ohos/` 代码内容检索 |
+| **能力声明** | 接口规格说明.md / README 中是否声明规则描述的能力（全屏/横屏/传感器等） | `{outputDir}/接口规格说明.md`、README |
+
+---
+
+## 2. 判定规则
+
+| 判定 | 条件 | 处理 |
+|------|------|------|
+| **适用** | 命中任一预筛特征 | 进入 Phase 3 深度检查 |
+| **不适用** | 未命中任何预筛特征 | 跳过，记录跳过原因 |
+
+> ⚠️ **预筛不适用规则不计入评分分母**。评分只基于「适用规则」计算。
+
+---
+
+## 3. 常见预筛误判与规避
+
+### 3.1 误判为「适用」（过度预筛）
+
+| 场景 | 规避方法 |
+|------|----------|
+| 库的 `example/` 目录含某能力，但库本体没有 | 预筛只看库本体源码，排除 `example/` |
+| 依赖中声明了某 SDK，但代码从未调用 | 依赖特征需**结合 API 特征**确认，仅依赖声明不足以判定适用 |
+| 上游 RN 原库有某能力，但鸿蒙化实现未移植 | 预筛针对**鸿蒙化实现**（`source/ohos/`），不看上游 `source/RN/` |
+
+### 3.2 误判为「不适用」（漏筛）
+
+| 场景 | 规避方法 |
+|------|----------|
+| 能力通过 C++ 层实现，ArkTS 层无痕迹 | 同时检索 `.cpp` / `.h` 文件中的 API 特征 |
+| 能力声明在 README 但代码中命名不同 | 以「能力声明」维度兜底，README/接口文档声明即视为候选 |
+| 规则描述的能力是「间接依赖」（如手势库被本库依赖） | 检查 `oh-package.json5` 的 dependencies 是否含相关库 |
+
+### 3.3 判定技巧
+
+- **先读 INDEX.md 分类**：媒体与窗口类规则（R-01/R-09/R-10）只对媒体/窗口类库可能适用；C++ 内存类规则（R-07/R-12）只对含 C++ 层的库可能适用。分类可快速缩小候选集。
+- **能力声明优先**：接口规格说明.md 是预筛的最快入口，先读它了解库对外声明的能力，再对照规则分类。
+- **记录跳过原因**：不适用规则必须记录具体原因（如「库无全屏/视频/Web 媒体能力声明，ArkTS 层无窗口状态 API」），供报告「不适用规则清单」使用。
+
+---
+
+## 4. 预筛输出
+
+预筛完成后，输出两类清单：
+
+1. **适用规则清单**：规则编号 + 规则名 + 命中预筛特征（进入 Phase 3）
+2. **不适用规则清单**：规则编号 + 规则名 + 不适用原因（写入报告）
+
+> 预筛结果示例参见 [报告模板](assets/REPORT_TEMPLATE.md) 的「二、规则命中清单」。

package/vendor/Server/Skills/rn-library-known-issue-check/references/SOURCE_PREP_GUIDE.md

@@ -0,0 +1,75 @@
+# 源码准备指南
+
+> 本文档说明检视前如何准备源码目录，确保 Phase 1-3 的输入完整且正确。
+
+---
+
+## 1. 源码目录结构
+
+检视前，`{outputDir}` 下应包含以下结构：
+
+```
+{outputDir}/
+├── 接口规格说明.md                    # 前置 SKILL 产出（必需）
+├── source/
+│   ├── ohos/                          # 鸿蒙化实现代码（必需）
+│   │   ├── harmony/                   # 常见目录
+│   │   ├── src/main/cpp/              # C++ TurboModule 实现
+│   │   ├── oh-package.json5           # 鸿蒙依赖声明
+│   │   ├── package.json               # 补充依赖声明
+│   │   └── ...
+│   └── RN/                            # 上游原库代码（可选，用于对比）
+│       └── ...
+```
+
+---
+
+## 2. 获取源码
+
+### 2.1 克隆鸿蒙化仓库
+
+```bash
+git clone --depth=1 {ohosRepoUrl} {outputDir}/source/ohos/
+```
+
+### 2.2 克隆上游原库（可选）
+
+```bash
+git clone --depth=1 {upstreamRepoUrl} {outputDir}/source/RN/
+```
+
+> 上游原库用于对比：判断某问题是鸿蒙化引入的，还是上游遗留问题。
+
+---
+
+## 3. 源码目录检查
+
+### 3.1 必需文件检查
+
+| 文件 | 用途 | 缺失处理 |
+|------|------|----------|
+| `oh-package.json5` | 依赖特征预筛 | 跳过依赖维度预筛，使用 `package.json` 替代 |
+| `package.json` | 依赖特征预筛 | 跳过依赖维度预筛 |
+| 至少一个 `.ets`/`.ts` 文件 | 鸿蒙化实现 | 判定为「未实现鸿蒙化」，检视跳过 |
+| 至少一个 `.cpp`/`.h` 文件 | 可能含 C++ 层实现 | 跳过 C++ 相关规则（R-07/R-12） |
+
+### 3.2 文件命名约定
+
+检视 Agent 应识别以下常见鸿蒙化目录布局：
+
+| 目录 | 说明 |
+|------|------|
+| `harmony/` | 标准鸿蒙化目录（首选） |
+| `ohos/` | 早期鸿蒙化目录 |
+| `src/main/cpp/` | C++ TurboModule 实现 |
+| `src/main/ets/` | ArkTS 实现 |
+| `harmony/entry/src/main/ets/` | 鸿蒙工程入口 |
+
+### 3.3 排除规则
+
+以下目录/文件不纳入检视范围：
+- `example/` — 示例工程代码
+- `node_modules/` — 依赖包
+- `build/`、`builds/` — 构建产物
+- `.git/` — Git 元数据
+- `oh_modules/` — 鸿蒙依赖

package/vendor/Server/Skills/rn-library-known-issue-check/scripts/validate-known-issue-report.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+# @tool validate-known-issue-report
+# @description 校验已知问题检视报告是否完整，检查报告结构、评分公式、证据完整性（跨平台：Windows/macOS/Linux）
+# @param reportDir: string - 检视报告所在目录绝对路径
+
+import json
+import os
+import re
+import sys
+
+
+def parse_args():
+    """解析命令行参数：支持 JSON 字符串（MCP Gateway 约定）或直接传目录路径"""
+    if len(sys.argv) > 1:
+        raw = sys.argv[1]
+        # 尝试解析为 JSON（MCP Gateway 传参方式）
+        try:
+            return json.loads(raw).get("reportDir", "")
+        except json.JSONDecodeError:
+            # 非 JSON，视为直接传入的目录路径
+            return raw.strip()
+    return ""
+
+
+def main():
+    report_dir = parse_args()
+
+    if not report_dir:
+        print("Usage: validate-known-issue-report.py <reportDir>")
+        print("Error: reportDir parameter is required")
+        return 1
+
+    if not os.path.isdir(report_dir):
+        print(f"Error: Directory does not exist: {report_dir}")
+        return 1
+
+    report_file = os.path.join(report_dir, "已知问题检视报告.md")
+    if not os.path.isfile(report_file):
+        print(f"Error: Report file not found: {report_file}")
+        return 1
+
+    # 读取报告内容（UTF-8，兼容中文）
+    with open(report_file, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    passed = 0
+    failed = 0
+    warnings = 0
+
+    def check_pass(msg):
+        nonlocal passed
+        print(f"  ✅ {msg}")
+        passed += 1
+
+    def check_fail(msg):
+        nonlocal failed
+        print(f"  ❌ {msg}")
+        failed += 1
+
+    def check_warn(msg):
+        nonlocal warnings
+        print(f"  ⚠️  {msg}")
+        warnings += 1
+
+    print("=== 已知问题检视报告校验 ===")
+    print(f"目录: {report_dir}")
+    print("")
+
+    # ─── 1. 报告结构检查 ───
+    print("--- 1. 报告结构检查 ---")
+    for section in ["检视概览", "规则命中清单", "命中问题详情", "检视结论"]:
+        if section in content:
+            check_pass(f"包含「{section}」章节")
+        else:
+            check_fail(f"缺少「{section}」章节")
+
+    # ─── 2. 评分检查 ───
+    print("")
+    print("--- 2. 评分检查 ---")
+
+    # 提取评分（兼容 **评分** | {score}/100 或 **评分**：{score}/100 等格式）
+    score_match = re.search(r"\*\*评分\*\*[^\d]*(\d+)\s*/\s*100", content)
+    if score_match:
+        score = int(score_match.group(1))
+        if 0 <= score <= 100:
+            check_pass(f"评分在有效范围 (0-100): {score}")
+        else:
+            check_fail(f"评分超出有效范围: {score}")
+    else:
+        check_fail("未找到评分字段")
+
+    # 检查评分公式
+    if re.search(r"100\s*[−\-]\s*30", content):
+        check_pass("评分公式正确 (100 - 30×命中数)")
+    else:
+        check_warn("未找到评分公式说明")
+
+    # ─── 3. 命中规则检查 ───
+    print("")
+    print("--- 3. 命中规则检查 ---")
+
+    hit_rules = len(re.findall(r"\*\*命中\*\*", content))
+    if hit_rules > 0:
+        check_pass(f"包含 {hit_rules} 条命中规则")
+        # 检查是否有案例引用
+        if re.search(r"KI-\d+", content):
+            check_pass("命中规则引用了案例 (KI-XXX)")
+        else:
+            check_warn("命中规则未引用案例")
+        # 检查是否有修复指引
+        if re.search(r"修复指引|修复方案|正确特征", content):
+            check_pass("命中规则包含修复指引")
+        else:
+            check_warn("命中规则缺少修复指引")
+    else:
+        check_warn("无命中规则")
+
+    # ─── 4. 不适用规则清单 ───
+    print("")
+    print("--- 4. 不适用规则检查 ---")
+
+    if re.search(r"不适用规则清单|不适用规则", content):
+        check_pass("包含不适用规则清单")
+        # 检查是否有跳过原因
+        if re.search(r"不适用原因|预筛未命中", content):
+            check_pass("不适用规则记录了跳过原因")
+        else:
+            check_warn("不适用规则缺少跳过原因")
+    else:
+        check_warn("无不适用规则清单")
+
+    # ─── 5. 证据完整性 ───
+    print("")
+    print("--- 5. 证据完整性检查 ---")
+
+    if re.search(r"```(cpp|typescript|arkts|ts|java)", content):
+        check_pass("命中规则包含代码片段证据")
+    else:
+        check_warn("命中规则缺少代码片段证据")
+
+    # 检查文件路径引用
+    if re.search(r"\.(cpp|h|ets|ts|java):\d+", content):
+        check_pass("证据包含文件路径+行号")
+    else:
+        check_warn("证据未包含文件路径+行号")
+
+    # ─── 总结 ───
+    print("")
+    print("=== 校验总结 ===")
+    print(f"  ✅ 通过: {passed}")
+    print(f"  ❌ 失败: {failed}")
+    print(f"  ⚠️  警告: {warnings}")
+    print("")
+
+    if failed == 0:
+        print("ALL CHECKS PASSED")
+        return 0
+    else:
+        print(f"VALIDATION FAILED: {failed} 个必须修复的问题")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())