@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/arkts-library-stability-check/references/CODE_EXAMPLES.md

@@ -0,0 +1,309 @@
+# 代码示例参考
+
+> 本文件收录 `arkts-library-stability-check` 各检视维度的代码示例，供检视时对照参考。
+
+---
+
+## 1. 异常处理完整性
+
+### 1.1 关键路径无异常处理（E-01）
+
+```typescript
+// ❌ 关键路径无异常处理（E-01，扣 10 分）
+async connect(deviceId: string): Promise<void> {
+  await bluetooth.connect(deviceId); // 可能抛出 PermissionError
+  return; // 异常未传播
+}
+
+// ✅ 正确实现
+async connect(deviceId: string): Promise<void> {
+  try {
+    if (!deviceId || deviceId.length === 0) {
+      throw new Error('Invalid deviceId'); // 参数验证 (E-04)
+    }
+    await bluetooth.connect(deviceId);
+  } catch (e) {
+    throw new Error(`Connect failed: ${e.message}`); // 异常传播而非吞没
+  }
+}
+```
+
+### 1.2 Promise rejection 未处理（E-02）
+
+```typescript
+// ❌ Promise rejection 未处理（E-02，扣 8 分）
+bluetooth.startScanning()
+  .then((devices) => { /* 处理设备 */ });
+  // 缺少 .catch() 处理 rejection
+
+// ✅ 正确实现
+bluetooth.startScanning()
+  .then((devices) => { /* 处理设备 */ })
+  .catch((error) => {
+    console.error('Scan failed:', error);
+    throw error; // 重新抛出或上报
+  });
+```
+
+### 1.3 异常吞没（E-03）
+
+```typescript
+// ❌ 异常吞没（E-03，扣 7 分）
+try {
+  await sensor.subscribe();
+} catch (e) {
+  // 空 catch 块，异常被吞没
+}
+
+// ❌ 仅日志输出，未恢复/上报/重新抛出
+try {
+  await sensor.subscribe();
+} catch (e) {
+  console.log('error'); // 仅打印，未处理
+}
+
+// ✅ 正确实现
+try {
+  await sensor.subscribe();
+} catch (e) {
+  console.error('Sensor subscribe failed:', e);
+  // 恢复到安全状态或重新抛出
+  throw new Error(`Sensor error: ${e.message}`);
+}
+```
+
+### 1.4 参数验证缺失（E-04）
+
+```typescript
+// ❌ 参数验证缺失（E-04，扣 5 分）
+async writeData(data: string): Promise<void> {
+  await fileIo.writeText(this.fd, data);
+  // 未检查 data 是否为空或超出长度限制
+}
+
+// ✅ 正确实现
+async writeData(data: string): Promise<void> {
+  if (!data || data.length === 0) {
+    throw new Error('Data cannot be empty');
+  }
+  if (data.length > MAX_DATA_SIZE) {
+    throw new Error('Data exceeds maximum size');
+  }
+  await fileIo.writeText(this.fd, data);
+}
+```
+
+### 1.5 finally 缺失（E-06）
+
+```typescript
+// ❌ finally 缺失（E-06，扣 2 分）
+try {
+  await this.lock.acquire();
+  await this.processData();
+  this.lock.release();
+} catch (e) {
+  this.lock.release(); // 异常路径也释放，但重复代码
+  throw e;
+}
+// 如果 processData 之后的代码也抛出异常，lock 不会释放
+
+// ✅ 正确实现
+try {
+  await this.lock.acquire();
+  await this.processData();
+} catch (e) {
+  throw e; // 异常传播
+} finally {
+  this.lock.release(); // 无论异常与否都释放
+}
+```
+
+---
+
+## 2. 资源释放安全性
+
+### 2.1 事件订阅未取消（R-02）
+
+```typescript
+// ❌ 事件订阅未取消（R-02，扣 8 分）
+export class LocationPlugin {
+  startListening(): void {
+    geoLocationManager.on('locationChange', this.callback);
+    // 缺少 off() 调用！
+  }
+}
+
+// ✅ 正确实现
+export class LocationPlugin {
+  private isListening: boolean = false;
+
+  startListening(): void {
+    geoLocationManager.on('locationChange', this.callback);
+    this.isListening = true;
+  }
+
+  stopListening(): void {
+    if (this.isListening) {
+      geoLocationManager.off('locationChange', this.callback);
+      this.isListening = false;
+    }
+  }
+
+  aboutToDisappear(): void {
+    this.stopListening(); // 必须取消订阅
+  }
+}
+```
+
+### 2.2 Timer 未清理（R-04）
+
+```typescript
+// ❌ Timer 未清理（R-04，扣 5 分）
+export class PollingService {
+  startPolling(): void {
+    this.timer = setInterval(() => {
+      this.checkStatus();
+    }, 1000);
+    // 缺少 clearInterval 调用
+  }
+}
+
+// ✅ 正确实现
+export class PollingService {
+  private timer: number | null = null;
+
+  startPolling(): void {
+    this.timer = setInterval(() => {
+      this.checkStatus();
+    }, 1000);
+  }
+
+  stopPolling(): void {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  aboutToDisappear(): void {
+    this.stopPolling();
+  }
+}
+```
+
+---
+
+## 3. NAPI 跨语言调用
+
+### 3.1 Handle Scope 未清理（N-02）
+
+```cpp
+// ❌ Handle Scope 未清理（N-02，扣 8 分）
+static napi_value GetInfo(napi_env env, napi_callback_info info) {
+  napi_handle_scope scope;
+  napi_open_handle_scope(env, &scope);
+  // ... 业务逻辑 ...
+  // 缺少 napi_close_handle_scope！
+  return result;
+}
+
+// ✅ 正确实现
+static napi_value GetInfo(napi_env env, napi_callback_info info) {
+  napi_handle_scope scope;
+  napi_open_handle_scope(env, &scope);
+  napi_value result;
+  // ... 业务逻辑 ...
+  napi_close_handle_scope(env, scope); // 必须清理
+  return result;
+}
+```
+
+### 3.2 napi_ref 创建/释放不匹配（N-01）
+
+```cpp
+// ❌ napi_ref 创建后未释放（N-01，扣 10 分）
+static napi_value SetCallback(napi_env env, napi_callback_info info) {
+  napi_value callback;
+  napi_ref callbackRef;
+  napi_get_cb_info(env, info, ...);
+  napi_create_reference(env, callback, 1, &callbackRef);
+  // callbackRef 存储到全局，但从未调用 napi_delete_reference
+  return nullptr;
+}
+
+// ✅ 正确实现
+static napi_value SetCallback(napi_env env, napi_callback_info info) {
+  napi_value callback;
+  napi_ref callbackRef;
+  napi_get_cb_info(env, info, ...);
+  napi_create_reference(env, callback, 1, &callbackRef);
+  this->callbackRef = callbackRef;
+  return nullptr;
+}
+
+// 在适当时机释放
+void Cleanup() {
+  if (this->callbackRef != nullptr) {
+    napi_delete_reference(env, this->callbackRef);
+    this->callbackRef = nullptr;
+  }
+}
+```
+
+---
+
+## 4. 调用链完整性
+
+### 4.1 跨层级调用链追踪
+
+```
+调用链结构示例：
+ArkTS 层                      Native (C++) 层
+│                              │
+├─ publicAPI.method()          │
+│  ├─ try-catch ✅/❌          │
+│  └─ invokeNative()           │
+│                               ├─ NativeImpl::execute()
+│                               │  ├─ napi_handle_scope ✅/❌
+│                               │  ├─ napi_ref 管理 ✅/❌
+│                               │  └─ return result
+│                               │
+├─ callback/result             │
+│  ├─ 异常检查 ✅/❌           │
+│  └─ return to caller         │
+```
+
+### 4.2 异常传播链检查示例
+
+```typescript
+// ❌ ArkTS → Native 异常传播断裂（CH-01，扣 10 分）
+// Native 层：
+static napi_value Execute(napi_env env, napi_callback_info info) {
+  // 执行失败，但未通过 napi_throw 传播异常
+  return nullptr; // ArkTS 层收到 null 但不知原因
+}
+
+// ArkTS 层：
+const result = nativeModule.execute();
+if (result === null) {
+  // 无法判断是执行失败还是正常返回 null
+}
+
+// ✅ 正确实现
+// Native 层：
+static napi_value Execute(napi_env env, napi_callback_info info) {
+  if (executionFailed) {
+    napi_throw_error(env, nullptr, "Execution failed: timeout");
+    return nullptr;
+  }
+  return result;
+}
+
+// ArkTS 层：
+try {
+  const result = nativeModule.execute();
+} catch (e) {
+  console.error('Native execution error:', e);
+  // 异常已正确传播到 ArkTS 层
+}
+```

package/vendor/Server/Skills/arkts-library-stability-check/references/SCORING_RULES.md

@@ -0,0 +1,90 @@
+# 评分规则参考
+
+> 本文件为 `arkts-library-stability-check` 的评分规则详细参考，供评分计算时按规则执行。
+
+---
+
+## 1. 维度评分规则
+
+采用**严苛扣分制**，每个维度独立计算扣分后汇总：
+
+| 维度 | 基础分 | 扣分上限 | 说明 |
+|------|--------|----------|------|
+| 异常处理完整性 | 25 | -25 | E-01~E-06 各项扣分叠加 |
+| 资源释放安全性 | 25 | -25 | R-01~R-05 各项扣分叠加 |
+| 并发安全 | 20 | -20 | C-01~C-03 各项扣分叠加 |
+| ArkTS 生命周期 | 10 | -10 | L-01~L-02 各项扣分叠加 |
+| NAPI 跨语言调用 | 15 | -15 | N-01~N-05 各项扣分叠加 |
+| C++ 内存管理 | 10 | -10 | M-01~M-03 各项扣分叠加 |
+| 调用链完整性 | 5 | -5 | CH-01~CH-03 各项扣分叠加 |
+
+**维度得分** = max(0, 基础分 - 该维度累计扣分)
+
+**综合评分** = Σ(各维度得分)，范围 0-100
+
+---
+
+## 2. 特殊归零规则（叠加于维度扣分之上）
+
+| 规则 | 条件 | 结果 |
+|------|------|------|
+| 归零规则 1 | Critical 级别问题 ≥ 5 个 | **直接评 0 分** |
+| 归零规则 2 | Critical ≥ 3 个 + Major ≥ 4 个 | **直接评 0 分** |
+| 归零规则 3 | 核心公共 API 异常处理完全缺失（≥ 3 个核心 API 调用无 try-catch，不含 example/demo 代码） | **直接评 0 分** |
+| 归零规则 4 | NAPI 引用管理完全不匹配（创建远多于释放） | **直接评 0 分** |
+| 归零规则 5 | 未发现鸿蒙化核心实现代码 | **0 分** |
+| 归零规则 6 | 源码目录不可访问 | **0 分** |
+
+---
+
+## 3. 严重度映射
+
+问题严重度按扣分值映射：
+
+| 严重度 | 扣分范围 | 说明 |
+|--------|----------|------|
+| **Critical** | ≥ 8 分 | 致命问题，可能导致崩溃或严重资源泄露 |
+| **Major** | 5-7 分 | 严重问题，影响系统稳定性 |
+| **Minor** | ≤ 3 分 | 轻微问题，建议改进 |
+
+---
+
+## 4. 评分等级说明
+
+| 分数段 | 等级 | 说明 |
+|--------|------|------|
+| 90-100 | 优秀 | 异常处理完善，资源管理规范，无稳定性风险 |
+| 80-89 | 良好 | 存在少量 Minor 问题，不影响核心稳定性 |
+| 70-79 | 一般 | 存在 Major 级别问题需关注，有一定风险 |
+| 60-69 | 较差 | 存在 Critical 级别问题，稳定性堪忧 |
+| <60 | 严重不足 | 多个 Critical 问题，崩溃/泄露风险极高 |
+| 0 | 不可用 | 触发归零规则或完全缺失稳定性设计 |
+
+---
+
+## 5. 评分计算示例
+
+### 示例 1：正常评分
+
+某库核心代码发现：
+- E-01（-10）+ E-04（-5）→ 异常处理维度扣 15 分 → 得分 10/25
+- R-02（-8）→ 资源释放维度扣 8 分 → 得分 17/25
+- C-01（-10）→ 并发安全维度扣 10 分 → 得分 10/20
+- 其余维度无扣分
+
+**综合评分** = 10 + 17 + 10 + 10 + 15 + 10 + 5 = **77/100**（一般）
+
+### 示例 2：触发归零规则
+
+某库核心代码发现 5 个 Critical 问题（如 E-01×2、R-01、N-01、CH-01）：
+- 触发**归零规则 1**（Critical ≥ 5）
+- **综合评分直接为 0 分**，即使维度扣分未扣满
+
+---
+
+## 6. 评分执行要点
+
+1. **先判定归零规则**：在计算维度扣分前，先检查是否触发归零规则。触发则直接 0 分，无需逐项扣分。
+2. **仅对核心代码评分**：example/demo/sample/test 代码不参与评分，但可作为参考。
+3. **扣分不叠加到负**：每个维度得分下限为 0，不出现负分。
+4. **报告格式**：报告必须包含 `**综合评分：XX/100**` 格式（粗体标记、中文冒号），以便后端 `_parseArktsLibraryScore` 函数正确解析评分。

package/vendor/Server/Skills/arkts-library-stability-check/scripts/validate-skill.cjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+/**
+ * @tool validate-skill
+ * @description 校验 arkts-library-stability-check SKILL 目录是否符合 Agent Skills 规范，检查 frontmatter、结构、渐进式披露、报告模板完整性。跨平台（Windows/macOS/Linux），仅需 Node.js。
+ * @param skillDir: string - SKILL目录绝对路径
+ * @hidden
+ * validate-skill.cjs
+ *
+ * 用法:
+ *   # CLI 模式
+ *   node validate-skill.cjs /path/to/skill
+ *
+ *   # MCP Gateway 模式（第一个参数为 JSON 字符串）
+ *   node validate-skill.cjs '{"skillDir":"/path/to/skill"}'
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── 参数解析（兼容 MCP Gateway JSON 模式与 CLI 模式） ──────
+
+function parseArgs(argv) {
+  if (argv.length === 0) return {};
+  const first = argv[0];
+  if (typeof first === 'string' && first.startsWith('{')) {
+    try { return JSON.parse(first); } catch (e) { return {}; }
+  }
+  return { skillDir: first };
+}
+
+// ── 输出统计 ─────────────────────────────────────────────
+
+let PASS = 0;
+let FAIL = 0;
+let WARNINGS = 0;
+
+function checkPass(msg) { console.log(`  ✅ ${msg}`); PASS += 1; }
+function checkFail(msg) { console.log(`  ❌ ${msg}`); FAIL += 1; }
+function checkWarn(msg) { console.log(`  ⚠️  ${msg}`); WARNINGS += 1; }
+
+// ── Frontmatter 解析 ─────────────────────────────────────
+
+/**
+ * 解析 SKILL.md 的 frontmatter 与 body。
+ * 返回 { frontmatter: object|null, bodyLines: string[] }
+ */
+function parseFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (!lines[0] || lines[0].trim() !== '---') {
+    return { frontmatter: null, bodyLines: lines };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    return { frontmatter: null, bodyLines: lines };
+  }
+  const fmLines = lines.slice(1, end);
+  const fm = {};
+  let currentKey = null;
+  for (const line of fmLines) {
+    const m = line.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
+    if (m) {
+      currentKey = m[1];
+      fm[currentKey] = m[2].trim();
+    } else if (currentKey && /^\s+\S/.test(line)) {
+      fm[currentKey] += '\n' + line.trim();
+    }
+  }
+  return { frontmatter: fm, bodyLines: lines.slice(end + 1) };
+}
+
+// ── 主流程 ───────────────────────────────────────────────
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const skillDir = args.skillDir || '';
+
+  if (!skillDir) {
+    console.log('Usage: node validate-skill.cjs <skillDir>');
+    console.log('Error: skillDir parameter is required');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    console.log(`Error: Directory does not exist: ${skillDir}`);
+    process.exit(1);
+  }
+
+  console.log('=== SKILL 规范校验 ===');
+  console.log(`目录: ${skillDir}`);
+  console.log('');
+
+  // ─── 1. SKILL.md 存在性 ───
+  console.log('--- 1. 文件结构检查 ---');
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillFile) && fs.statSync(skillFile).isFile()) {
+    checkPass('SKILL.md 存在');
+  } else {
+    checkFail('SKILL.md 不存在');
+    console.log('无法继续校验，SKILL.md 是必需文件');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf-8');
+  const { frontmatter, bodyLines } = parseFrontmatter(content);
+
+  // ─── 2. Frontmatter 检查 ───
+  console.log('');
+  console.log('--- 2. Frontmatter 检查 ---');
+
+  if (frontmatter) {
+    checkPass('YAML frontmatter 存在');
+  } else {
+    checkFail('缺少 YAML frontmatter（文件应以 --- 开头并以 --- 结束头部）');
+  }
+
+  const nameField = frontmatter ? String(frontmatter.name || '') : '';
+  if (nameField) {
+    checkPass(`name 字段存在: ${nameField}`);
+
+    // name 字符集校验
+    if (/^[a-z0-9]+(-[a-z0-9]+)*$/.test(nameField)) {
+      checkPass('name 字符集合规（仅小写字母/数字/连字符）');
+    } else {
+      checkFail('name 字符集不合规：应仅含 a-z/0-9/-，不能首尾连字符或连续连字符');
+    }
+
+    // name 长度校验
+    const nameLen = nameField.length;
+    if (nameLen >= 1 && nameLen <= 64) {
+      checkPass(`name 长度合规 (${nameLen} 字符)`);
+    } else {
+      checkFail(`name 长度不合规：应在 1-64 字符之间（当前 ${nameLen}）`);
+    }
+
+    // name 匹配目录名
+    const dirName = path.basename(path.resolve(skillDir));
+    if (nameField === dirName) {
+      checkPass(`name 匹配父目录名 (${dirName})`);
+    } else {
+      checkFail(`name 不匹配父目录名：name='${nameField}' vs 目录='${dirName}'`);
+    }
+  } else {
+    checkFail('name 字段缺失');
+  }
+
+  const descField = frontmatter ? String(frontmatter.description || '') : '';
+  if (descField) {
+    const descLen = descField.length;
+    if (descLen <= 1024) {
+      checkPass(`description 长度合规 (${descLen} 字符)`);
+    } else {
+      checkFail(`description 过长：应 ≤1024 字符（当前 ${descLen}）`);
+    }
+  } else {
+    checkFail('description 字段缺失或为空');
+  }
+
+  if (frontmatter && frontmatter.license) {
+    checkPass('license 字段存在');
+  } else {
+    checkWarn('license 字段缺失（推荐添加）');
+  }
+
+  if (frontmatter && frontmatter.metadata) {
+    checkPass('metadata 字段存在');
+  } else {
+    checkWarn('metadata 字段缺失（推荐添加 author/version）');
+  }
+
+  // ─── 3. Body 检查 ───
+  console.log('');
+  console.log('--- 3. Body 内容检查 ---');
+
+  const bodyLineCount = bodyLines.length;
+  if (bodyLineCount <= 500) {
+    checkPass(`body 行数合规 (${bodyLineCount} 行, ≤500)`);
+  } else {
+    checkWarn(`body 行数较多 (${bodyLineCount} 行，推荐 < 500，考虑拆分到 references/)`);
+  }
+
+  if (/任务参数|## .*参数|\|\s*参数/.test(content)) {
+    checkPass('包含任务参数说明');
+  } else {
+    checkWarn('未找到任务参数表（推荐添加）');
+  }
+
+  if (/工作流程|Phase|## Phase/.test(content)) {
+    checkPass('包含工作流程概览');
+  } else {
+    checkWarn('未找到工作流程概览（推荐添加）');
+  }
+
+  // ─── 4. 渐进式披露检查 ───
+  console.log('');
+  console.log('--- 4. 渐进式披露检查 ---');
+
+  const refsDir = path.join(skillDir, 'references');
+  if (fs.existsSync(refsDir) && fs.statSync(refsDir).isDirectory()) {
+    const refFiles = fs.readdirSync(refsDir)
+      .filter((f) => f.endsWith('.md') && fs.statSync(path.join(refsDir, f)).isFile());
+    checkPass(`references/ 目录存在 (${refFiles.length} 个文档)`);
+
+    // 检查引用深度（一层）
+    const nestedDirs = fs.readdirSync(refsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory()).length;
+    if (nestedDirs === 0) {
+      checkPass('references 保持一层深度');
+    } else {
+      checkFail(`references 存在嵌套子目录 (${nestedDirs} 个)，应保持一层深度`);
+    }
+  } else {
+    checkWarn('无 references/ 目录（详细内容建议拆分到此目录）');
+  }
+
+  const assetsDir = path.join(skillDir, 'assets');
+  if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
+    checkPass('assets/ 目录存在');
+  } else {
+    checkWarn('无 assets/ 目录（如需模板/资源可添加）');
+  }
+
+  const scriptsDir = path.join(skillDir, 'scripts');
+  if (fs.existsSync(scriptsDir) && fs.statSync(scriptsDir).isDirectory()) {
+    checkPass('scripts/ 目录存在');
+  } else {
+    checkWarn('无 scripts/ 目录（如需可执行脚本可添加）');
+  }
+
+  // 检查文件引用使用相对路径
+  const absRefs = (content.match(/\]\(\/[^)]+\)/g) || []).length;
+  if (absRefs === 0) {
+    checkPass('文件引用使用相对路径');
+  } else {
+    checkFail(`发现 ${absRefs} 个绝对路径引用，应使用相对路径`);
+  }
+
+  // ─── 5. 报告模板完整性检查（本 SKILL 特有） ───
+  console.log('');
+  console.log('--- 5. 报告模板完整性检查 ---');
+
+  const reportTemplate = path.join(skillDir, 'assets', 'REPORT_TEMPLATE.md');
+  if (fs.existsSync(reportTemplate)) {
+    checkPass('assets/REPORT_TEMPLATE.md 存在');
+    const templateContent = fs.readFileSync(reportTemplate, 'utf-8');
+    // 检查关键格式标记
+    if (templateContent.includes('**综合评分：{score}/100**')) {
+      checkPass('报告模板包含综合评分格式标记');
+    } else {
+      checkFail('报告模板缺少 `**综合评分：{score}/100**` 格式标记');
+    }
+    if (templateContent.includes('_parseArktsLibraryScore')) {
+      checkPass('报告模板包含后端解析依赖说明');
+    } else {
+      checkWarn('报告模板缺少后端解析依赖说明');
+    }
+  } else {
+    checkWarn('无 assets/REPORT_TEMPLATE.md（报告模板建议放置于此）');
+  }
+
+  // ─── 6. 总结 ───
+  console.log('');
+  console.log('=== 校验总结 ===');
+  console.log(`  ✅ 通过: ${PASS}`);
+  console.log(`  ❌ 失败: ${FAIL}`);
+  console.log(`  ⚠️  警告: ${WARNINGS}`);
+  console.log('');
+
+  if (FAIL === 0) {
+    console.log('ALL CHECKS PASSED');
+    process.exit(0);
+  } else {
+    console.log(`VALIDATION FAILED: ${FAIL} 个必须修复的问题`);
+    process.exit(1);
+  }
+}
+
+main();