@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/rn-library-consistency-check/references/SCORING_STANDARD.md

@@ -0,0 +1,220 @@
+# 严苛评分标准与计算规则
+
+本文件定义 RN 鸿蒙化一致性检视的完整评分体系，包括扣分类型、豁免规则、归零规则、维度加权计算方法。
+
+> 📖 **引用来源**：SKILL.md Phase 6 评分计算 + 严苛评分标准节的详细内容。
+
+---
+
+## 1. 严苛扣分制
+
+采用**严苛扣分制**，从 100 分开始扣减，每个函数的对比结果**独立计算扣分**：
+
+```
+初始分数：100 分
+
+扣分类型（函数级独立扣分）：
+├── 致命问题：-15 分（最多扣 60 分）
+│   ├── **原生注册缺失（JS/TS Spec注册的TM或Component在ArkTS Factory中未注册）** -15/实体名 ⛔跳过内部逐项检查
+│   ├── 参数类型致命错误（如 boolean→string）............... -15/处
+│   ├── OHOS 方法缺失（Android 有但 OHOS 无方法）.......... -15/方法（仅限已注册TM内部）
+│   ├── OHOS 方法为 Stub（返回固定值无实际操作）........... -8/方法
+│   ├── OHOS 方法返回错误而非实现.......................... -10/方法
+│   ├── 返回值类型/语义完全错误........................... -10/处
+│   ├── 函数行为致命不一致（核心逻辑完全不同）............. -15/方法
+│   ├── 无文档说明的副作用（OHOS Prop影响额外功能点，Android/iOS无此影响且无文档解释）-15/处
+│   └── 错误码硬编码固定值............................... -8/处
+│
+├── 严重问题：-12 分
+│   ├── 函数行为严重不一致（核心逻辑部分不同）............. -12/方法
+│   ├── 异常传播不完整................................... -6/方法
+│   ├── 核心方法部分功能缺失............................. -12/方法
+│   ├── 参数数量不匹配................................... -8/方法
+│   ├── 有文档但不合理的副作用（文档标注了但理由不成立）.. -12/处
+│   ├── 非rawProps核心属性默认值不一致且无文档（vs Android/iOS）-12/处
+│   └── 返回值格式不标准................................. -6/方法
+│
+├── 中等问题：-8 分
+│   ├── 边界处理不一致................................... -8/方法
+│   ├── 错误消息缺少诊断信息............................. -4/处
+│   ├── 类型精度丢失（int/double 精度问题）............... -5/处
+│   ├── 空值处理不完整................................... -8/处
+│   ├── 非rawProps次要属性默认值不一致且无文档（vs Android/iOS）-8/处
+│   └── 事件数据格式不一致............................... -6/处
+│
+├── 轻微问题：-3 分
+│   ├── 方法命名不一致（无合理理由）..................... -3/方法
+│   ├── 术语/常量命名不一致............................. -2/处
+│   ├── 默认值差异....................................... -4/处
+│   ├── 有文档说明的合理副作用（归入平台适配合理性维度）.. -3/处
+│   ├── 非rawProps属性默认值不一致但有文档合理差异........ -3/处
+│   └── 平台差异未文档化................................. -3/处
+```
+
+---
+
+## 2. 文档标注不支持豁免规则
+
+🟢 **豁免规则**（文档标注不支持→不扣分）：
+
+| 项目 | 说明 |
+|------|------|
+| 适用条件 | OHOS 仓库的 README、接口规格说明、或源码注释中明确标注该接口/属性/函数/组件不支持（如 "HarmonyOS Support: No"、"Android only"、"(不支持)" 等） |
+| 豁免对象 | 属性、接口、函数、方法、Command、事件、组件等所有检视项 |
+| 豁免效果 | 标记为"🟢 文档标注不支持，豁免不扣分"，0分，不计入致命/严重问题计数 |
+| 文档来源优先级 | 接口规格说明 > OHOS README > 源码注释 > 上游文档 |
+| 验证要求 | 必须在报告中引用文档标注的具体位置（文件:行号 + 标注原文） |
+
+### 判定流程
+
+1. **识别缺失项**：在逐项检视中发现 OHOS 未实现某项
+2. **检查文档标注**：依次查找以下文档来源，判断是否标注为不支持：
+   - **接口规格说明**（如 `接口规格说明.md`）：查找该接口行，检查是否有 `(Android only)`、`(iOS only)`、`(不支持)` 等标注
+   - **OHOS README**（如 `harmony/README.md` 或仓库根目录 README）：查找 "HarmonyOS Support" 列，值为 "No" 或空；查找 "Platform" 列，值非 "All" 且非 "HarmonyOS"
+   - **源码注释**（如 `.ets`/`.ts`/`.cpp` 文件中的注释）：查找 `// not supported`、`// Android only`、`// TODO: 鸿蒙不支持` 等
+   - **上游文档**（如 RN 库的 `docs/Reference.md`）：查找平台限制标注
+3. **判定规则**：
+   - 🟢 **文档已标注不支持** → 豁免，0分，报告中标注"🟢 文档标注不支持，豁免不扣分（来源：文件:行号）"，**不计入致命/严重问题计数**
+   - ❌ **文档未标注不支持** → 按原扣分规则扣分
+
+> ⚠️ **重要**：此豁免规则适用于所有检视维度（方法缺失、Command缺失、Prop缺失、事件缺失等），不仅限于特定的检查点。
+
+### 豁免项输出格式
+
+```markdown
+| # | 检视项 | 缺失描述 | 文档标注 | 文档来源 | 豁免判定 | 扣分 |
+|---|--------|---------|---------|---------|---------|------|
+| 1 | `clearFormData` Command | ArkTS未注册 | ✅ Android only, HarmonyOS Support: No | README.md:380 + 接口规格说明.md:46 | 🟢 豁免不扣分 | 0 |
+| 2 | `allowFileAccess` Prop | ArkTS未实现 | ❌ 无标注 | — | ❌ 按规则扣分 | -15 |
+```
+
+---
+
+## 3. 归零规则
+
+| 条件 | 结果 |
+|------|------|
+| 不存在鸿蒙代码 | 0 分 |
+| 鸿蒙代码无实际实现（全部 Stub） | 0 分 |
+| 致命问题 ≥ 4 个 | 0 分 |
+| 致命问题 ≥ 3 个 + 严重问题 ≥ 2 个 | 0 分 |
+| 累计扣分超过 60 分 | 0 分 |
+
+最低分数：0 分
+
+---
+
+## 4. 评分等级
+
+| 分数区间 | 等级 | 含义 |
+|----------|------|------|
+| 90-100 | 优秀 | 鸿蒙化实现与原库高度一致，无致命/严重问题 |
+| 80-89 | 良好 | 存在少量中等问题，核心功能完整 |
+| 70-79 | 一般 | 存在严重问题，部分方法实现偏差 |
+| 60-69 | 较差 | 多个严重问题，功能缺失明显 |
+| 50-59 | 严重不足 | 致命问题存在，核心功能不可用 |
+| <50 | 极差 | 实现一致性严重不足，需全面重新实现 |
+
+---
+
+## 5. 检视维度与权重
+
+| 维度编号 | 维度 | 权重 | 满分 | 说明 |
+|----------|------|------|------|------|
+| 维度1 | API 契约一致性 | 35% | 35 | 方法签名、参数类型、返回值、事件/回调对比 |
+| 维度2 | 平台实现一致性 | 30% | 30 | Android vs OHOS、iOS vs OHOS 函数级功能对比；副作用&关联影响（无文档/不合理部分）；非rawProps属性默认值（无文档/不合理部分） |
+| 维度3 | RN 架构一致性 | 20% | 20 | TurboModule/NativeModule/NAPI 桥接一致性 |
+| 维度4 | 平台适配合理性 | 15% | 15 | 合理差异判定、平台特有场景处理；副作用&关联影响（有文档且合理部分）；非rawProps属性默认值（有文档且合理部分） |
+
+---
+
+## 6. 维度加权扣分计算
+
+```
+基础分 = 100
+
+维度编号与权重：
+| 维度编号 | 维度名称 | 权重 | 扣分上限 |
+|----------|---------|------|---------|
+| 维度1 | API 契约一致性 | 35% | -35 |
+| 维度2 | 平台实现一致性 | 30% | -30 |
+| 维度3 | RN 架构一致性 | 20% | -20 |
+| 维度4 | 平台适配合理性 | 15% | -15 |
+
+维度扣分来源映射（按检查项维度标签 + 条件路由规则）：
+
+维度1（API 契约一致性，35%）：
+  → 四类型所有 ①契约一致性 检查项（无条件路由）
+
+维度2（平台实现一致性，30%）：
+  → 四类型所有 ②平台实现差异 检查项（主映射逻辑不一致、函数行为不一致等）
+  → Props 副作用&关联影响：无文档说明的副作用（-15）、有文档但不合理的副作用（-12）
+  → 非 rawProps 属性默认值：无文档说明的不一致（核心 -12、次要 -8）、有文档但不合理的差异
+  → Phase 5.3 平台差异记录中不合理差异
+
+维度4（平台适配合理性，15%）：
+  → Props 副作用&关联影响：有文档说明且合理的副作用（-3，归入此维度）
+  → 非 rawProps 属性默认值：有文档说明且合理的差异（-3，归入此维度）
+  → Phase 5.3 平台差异记录中合理差异
+  → 平台差异未文档化（-3）
+
+维度3（RN 架构一致性，20%）：
+  → 四类型所有 ③架构桥接一致性 检查项
+  → Phase 5.1 NAPI/C++ 桥接 + Phase 5.2 NativeModule 架构
+```
+
+### 条件路由规则（核心）
+
+副作用&关联影响、非rawProps属性默认值两个检查项的扣分，不按①②③标签硬绑定维度，而根据判定结果路由：
+
+| 判定结果 | 归入维度 |
+|----------|----------|
+| 无文档说明 → | 维度2（平台实现一致性） |
+| 有文档但不合理 → | 维度2（平台实现一致性） |
+| 有文档且合理 → | 维度4（平台适配合理性） |
+
+### 维度内扣分规则
+
+| 问题等级 | 扣分 |
+|----------|------|
+| 致命问题 | -15 分/处 |
+| 严重问题 | -12 分/处 |
+| 中等问题 | -8 分/处 |
+| 轻微问题 | -3 分/处 |
+
+```
+维度实际扣分 = min(扣分上限, 致命扣分 + 严重扣分 + 中等扣分 + 轻微扣分)
+
+归零检查：
+- 致命问题累计 ≥ 4 个 → 最终分 = 0
+- 致命问题 ≥ 3 个 + 严重问题 ≥ 2 个 → 最终分 = 0
+- 累计扣分超过 60 分 → 最终分 = 0
+- 无鸿蒙代码或全部 Stub → 最终分 = 0
+
+最终分 = max(0, 100 - 各维度实际扣分之和)
+```
+
+---
+
+## 7. 扣分维度标注规则
+
+所有检视表格的扣分列，必须在分数后标注维度编号，格式为 **`-X（维度N）`**：
+
+| 检查项标签 | 对应维度 |
+|------------|----------|
+| ①契约一致性检查项 | 维度1（API 契约一致性） |
+| ②平台实现差异检查项（主映射逻辑、函数行为） | 维度2（平台实现一致性） |
+| ③架构桥接一致性检查项 | 维度3（RN 架构一致性） |
+| 副作用&关联影响：**条件路由** | 无文档/不合理→维度2，有文档且合理→维度4 |
+| 非 rawProps 属性默认值：**条件路由** | 无文档/不合理→维度2，有文档且合理→维度4 |
+| 平台差异记录：合理差异→维度4，不合理差异→维度2 | |
+
+示例：`-15（维度2）`、`-3（维度4）`、`-8（维度1）`
+
+---
+
+## 8. 评分格式要求
+
+报告必须包含 `**综合评分：XX/100**`（粗体标记，中文冒号），确保 `_parseRNLibraryScore` 函数的 `/\*?\*?综合评分[：:\s]*(\d{1,3})\s*\/\s*100/i` 正则匹配。
+
+评分正则匹配优先级为 `综合评分` > `总体评分/评分` > `得分`。

package/vendor/Server/Skills/rn-library-consistency-check/scripts/validate-skill.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+# @tool validate-skill
+# @description 校验SKILL目录是否符合Agent Skills规范，检查frontmatter、结构、渐进式披露
+# @param skillDir: string - SKILL目录绝对路径
+
+import json
+import os
+import re
+import sys
+
+PASS = 0
+FAIL = 0
+WARNINGS = 0
+
+
+def check_pass(msg):
+    global PASS
+    print(f"  ✅ {msg}")
+    PASS += 1
+
+
+def check_fail(msg):
+    global FAIL
+    print(f"  ❌ {msg}")
+    FAIL += 1
+
+
+def check_warn(msg):
+    global WARNINGS
+    print(f"  ⚠️  {msg}")
+    WARNINGS += 1
+
+
+def main():
+    global PASS, FAIL, WARNINGS
+
+    # 解析参数：支持 JSON 字符串（MCP Gateway 调用）或直接路径（命令行调用）
+    if len(sys.argv) > 1:
+        arg = sys.argv[1]
+        try:
+            skill_dir = json.loads(arg).get("skillDir", "")
+        except (json.JSONDecodeError, AttributeError):
+            skill_dir = arg
+    else:
+        print("Usage: validate-skill.py <skillDir>")
+        print("Error: skillDir parameter is required")
+        sys.exit(1)
+
+    if not skill_dir:
+        print("Usage: validate-skill.py <skillDir>")
+        print("Error: skillDir parameter is required")
+        sys.exit(1)
+
+    if not os.path.isdir(skill_dir):
+        print(f"Error: Directory does not exist: {skill_dir}")
+        sys.exit(1)
+
+    print("=== SKILL 规范校验 ===")
+    print(f"目录: {skill_dir}")
+    print()
+
+    # ─── 1. SKILL.md 存在性 ───
+    print("--- 1. 文件结构检查 ---")
+    skill_file = os.path.join(skill_dir, "SKILL.md")
+    if os.path.isfile(skill_file):
+        check_pass("SKILL.md 存在")
+    else:
+        check_fail("SKILL.md 不存在")
+        print("无法继续校验，SKILL.md 是必需文件")
+        sys.exit(1)
+
+    with open(skill_file, "r", encoding="utf-8") as f:
+        content = f.read()
+    lines = content.splitlines()
+
+    # ─── 2. Frontmatter 检查 ───
+    print()
+    print("--- 2. Frontmatter 检查 ---")
+
+    # 检查 frontmatter 存在
+    if lines and lines[0].strip() == "---":
+        check_pass("YAML frontmatter 存在")
+    else:
+        check_fail("缺少 YAML frontmatter（文件应以 --- 开头）")
+
+    # 提取 name 字段
+    name_match = re.search(r"^name:\s*(.+)$", content, re.MULTILINE)
+    name_field = name_match.group(1).strip() if name_match else ""
+
+    if name_field:
+        check_pass(f"name 字段存在: {name_field}")
+
+        # name 字符集校验
+        if re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", name_field):
+            check_pass("name 字符集合规（仅小写字母/数字/连字符）")
+        else:
+            check_fail("name 字符集不合规：应仅含 a-z/0-9/-，不能首尾连字符或连续连字符")
+
+        # name 长度校验
+        name_len = len(name_field)
+        if 1 <= name_len <= 64:
+            check_pass(f"name 长度合规 ({name_len} 字符)")
+        else:
+            check_fail(f"name 长度不合规：应在 1-64 字符之间（当前 {name_len}）")
+
+        # name 匹配目录名
+        dir_name = os.path.basename(skill_dir.rstrip(os.sep))
+        if name_field == dir_name:
+            check_pass(f"name 匹配父目录名 ({dir_name})")
+        else:
+            check_warn(
+                f"name 与父目录名不一致：name='{name_field}' vs 目录='{dir_name}'"
+                "（项目可能使用PascalCase目录命名约定）"
+            )
+    else:
+        check_fail("name 字段缺失")
+
+    # 提取 description 字段
+    desc_match = re.search(
+        r"^description:\s*(.+?)(?=\n[a-z]|\n---|\Z)", content, re.MULTILINE | re.DOTALL
+    )
+    desc_field = desc_match.group(1).strip() if desc_match else ""
+
+    if desc_field:
+        desc_len = len(desc_field)
+        if desc_len <= 1024:
+            check_pass(f"description 长度合规 ({desc_len} 字符)")
+        else:
+            check_fail(f"description 过长：应 ≤1024 字符（当前 {desc_len}）")
+    else:
+        check_fail("description 字段缺失或为空")
+
+    # 检查 license
+    if re.search(r"^license:", content, re.MULTILINE):
+        check_pass("license 字段存在")
+    else:
+        check_warn("license 字段缺失（推荐添加）")
+
+    # 检查 metadata
+    if re.search(r"^metadata:", content, re.MULTILINE):
+        check_pass("metadata 字段存在")
+    else:
+        check_warn("metadata 字段缺失（推荐添加 author/version）")
+
+    # ─── 3. Body 检查 ───
+    print()
+    print("--- 3. Body 内容检查 ---")
+
+    # 统计 body 行数（frontmatter 之后的行）
+    start = 0
+    end_idx = 0
+    for i, line in enumerate(lines):
+        if line.strip() == "---":
+            if start == 0:
+                start = i + 1
+            else:
+                end_idx = i + 1
+                break
+    if end_idx == 0:
+        end_idx = start
+    body_lines = len(lines) - end_idx
+
+    if body_lines <= 500:
+        check_pass(f"body 行数合规 ({body_lines} 行, ≤500)")
+    else:
+        check_warn(
+            f"body 行数较多 ({body_lines} 行，推荐 < 500，考虑拆分到 references/)"
+        )
+
+    # 检查任务参数表
+    if re.search(r"任务参数|## .*参数\| 参数", content):
+        check_pass("包含任务参数说明")
+    else:
+        check_warn("未找到任务参数表（推荐添加）")
+
+    # 检查工作流程
+    if re.search(r"工作流程|Phase|## Phase", content):
+        check_pass("包含工作流程概览")
+    else:
+        check_warn("未找到工作流程概览（推荐添加）")
+
+    # ─── 4. 渐进式披露检查 ───
+    print()
+    print("--- 4. 渐进式披露检查 ---")
+
+    # 检查 references 目录
+    ref_dir = os.path.join(skill_dir, "references")
+    if os.path.isdir(ref_dir):
+        ref_files = [
+            f
+            for f in os.listdir(ref_dir)
+            if f.endswith(".md") and os.path.isfile(os.path.join(ref_dir, f))
+        ]
+        check_pass(f"references/ 目录存在 ({len(ref_files)} 个文档)")
+
+        # 检查引用深度（一层）
+        nested = False
+        for root, dirs, files in os.walk(ref_dir):
+            if root != ref_dir and dirs:
+                nested = True
+                break
+        if not nested:
+            check_pass("references 保持一层深度")
+        else:
+            check_fail("references 存在嵌套子目录，应保持一层深度")
+    else:
+        check_warn("无 references/ 目录（详细内容建议拆分到此目录）")
+
+    # 检查 assets 目录
+    if os.path.isdir(os.path.join(skill_dir, "assets")):
+        check_pass("assets/ 目录存在")
+    else:
+        check_warn("无 assets/ 目录（如需模板/资源可添加）")
+
+    # 检查 scripts 目录
+    if os.path.isdir(os.path.join(skill_dir, "scripts")):
+        check_pass("scripts/ 目录存在")
+    else:
+        check_warn("无 scripts/ 目录（如需可执行脚本可添加）")
+
+    # 检查文件引用使用相对路径
+    abs_refs = len(re.findall(r"\]\(/[^)]+\)", content))
+    if abs_refs == 0:
+        check_pass("文件引用使用相对路径")
+    else:
+        check_fail(f"发现 {abs_refs} 个绝对路径引用，应使用相对路径")
+
+    # ─── 5. 总结 ───
+    print()
+    print("=== 校验总结 ===")
+    print(f"  ✅ 通过: {PASS}")
+    print(f"  ❌ 失败: {FAIL}")
+    print(f"  ⚠️  警告: {WARNINGS}")
+    print()
+
+    if FAIL == 0:
+        print("ALL CHECKS PASSED")
+        sys.exit(0)
+    else:
+        print(f"VALIDATION FAILED: {FAIL} 个必须修复的问题")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()