@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/arkts-library-demo-code/references/TEMPLATE.md

@@ -0,0 +1,544 @@
+# Demo 代码模板
+
+本文档提供 `arkts-library-demo-code` 技能生成 Demo 代码时使用的标准模板，包含 Demo 页面模板、主导航页面模板、原始 Demo 入口保留模板、路由配置模板和 module.json5 权限段模板。
+
+---
+
+## 一、Demo 页面模板（无权限版）
+
+适用场景：Demo 不需要任何用户授权权限，仅使用库接口或系统自动授权功能。
+
+```typescript
+/**
+ * Demo {SEQ}: {ENGLISH_TITLE}
+ *
+ * 功能说明：{DESCRIPTION}
+ * 对应接口：{INTERFACES}
+ *
+ * @author {AUTHOR}
+ */
+
+import hilog from '@ohos.hilog';
+import { {ImportedSymbols} } from '{LIBRARY_PACKAGE}';
+
+// ─── 日志常量 ──────────────────────────────────────────────────────────────
+const DOMAIN: number = 0xD001;
+const TAG: string = '{LIBRARY_TAG}_{PAGE_NAME}';
+
+// ─── 类型定义（根据接口需要填写） ──────────────────────────────────────────
+interface {ModelName} {
+  // 根据接口返回值类型定义
+}
+
+/**
+ * {ComponentName} - {中文功能说明}
+ *
+ * 展示 {LIBRARY_NAME} 的 {核心功能} 使用方法。
+ */
+@Entry
+@Component
+struct {ComponentName} {
+  // ─── 状态变量 ────────────────────────────────────────────────────────────
+  @State private resultText: string = '';
+  @State private isLoading: boolean = false;
+  @State private isError: boolean = false;
+
+  // ─── 非响应式成员（库实例、Timer 等） ─────────────────────────────────────
+  // private instance: {LibraryClass} | null = null;
+
+  // ─── 生命周期 ──────────────────────────────────────────────────────────────
+
+  aboutToAppear(): void {
+    hilog.info(DOMAIN, TAG, '{ComponentName} appeared');
+  }
+
+  aboutToDisappear(): void {
+    hilog.info(DOMAIN, TAG, '{ComponentName} disappeared');
+    // TODO: 释放持有的资源（库实例、订阅、Timer 等）
+  }
+
+  // ─── 核心功能方法 ─────────────────────────────────────────────────────────
+
+  /**
+   * {方法功能说明}
+   */
+  private async {actionMethod}(): Promise<void> {
+    hilog.debug(DOMAIN, TAG, '{actionMethod} called');
+    this.isLoading = true;
+    this.isError = false;
+    try {
+      // TODO: 调用鸿蒙原生库接口
+      // const result = await {libraryCall};
+      // this.resultText = `成功：${String(result)}`;
+      hilog.info(DOMAIN, TAG, '{actionMethod} succeeded');
+    } catch (err) {
+      const msg: string = (err as Error).message ?? String(err);
+      hilog.error(DOMAIN, TAG, '{actionMethod} failed: %{public}s', msg);
+      this.resultText = `错误：${msg}`;
+      this.isError = true;
+    } finally {
+      this.isLoading = false;
+    }
+  }
+
+  // ─── UI 构建 ──────────────────────────────────────────────────────────────
+
+  build() {
+    Scroll() {
+      Column({ space: 16 }) {
+        // 页面标题（通过 $r() 引用国际化字符串，禁止硬编码）
+        Text($r('app.string.demo_{seq}_title'))
+          .fontSize(20)
+          .fontWeight(FontWeight.Bold)
+          .width('100%')
+          .textAlign(TextAlign.Center)
+          .padding({ top: 16 })
+
+        Divider()
+
+        // TODO: 根据 Demo 步骤描述填写操作控件（输入框、按钮、选择器等）
+
+        // 执行按钮（按钮文本必须通过 $r() 引用）
+        Button($r('app.string.demo_{seq}_{action}_btn'))
+          .width('100%')
+          .enabled(!this.isLoading)
+          .onClick(() => this.{actionMethod}())
+
+        // 加载指示器
+        if (this.isLoading) {
+          LoadingProgress().width(40).height(40)
+        }
+
+        // 结果/错误展示区域
+        if (this.resultText.length > 0) {
+          Text(this.resultText)
+            .fontSize(14)
+            .width('100%')
+            .padding(12)
+            .backgroundColor(this.isError ? '#FFEBEE' : '#F5F5F5')
+            .fontColor(this.isError ? '#C62828' : '#212121')
+            .borderRadius(8)
+        }
+      }
+      .width('100%')
+      .padding(16)
+    }
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+---
+
+## 二、Demo 页面模板（含动态权限申请版）
+
+适用场景：Demo 需要申请用户授权权限（如相机、媒体文件访问、位置等）。
+
+```typescript
+/**
+ * Demo {SEQ}: {ENGLISH_TITLE}
+ *
+ * 功能说明：{DESCRIPTION}
+ * 对应接口：{INTERFACES}
+ * 所需权限：{PERMISSIONS}
+ *
+ * @author {AUTHOR}
+ */
+
+import hilog from '@ohos.hilog';
+import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl';
+import common from '@ohos.app.ability.common';
+import { {ImportedSymbols} } from '{LIBRARY_PACKAGE}';
+
+// ─── 日志常量 ──────────────────────────────────────────────────────────────
+const DOMAIN: number = 0xD001;
+const TAG: string = '{LIBRARY_TAG}_{PAGE_NAME}';
+
+// ─── 权限列表（填写此 Demo 实际需要的权限） ────────────────────────────────
+const REQUIRED_PERMISSIONS: Permissions[] = [
+  'ohos.permission.{PERMISSION_NAME}' as Permissions,
+];
+
+@Entry
+@Component
+struct {ComponentName} {
+  @State private resultText: string = '';
+  @State private isLoading: boolean = false;
+  @State private isError: boolean = false;
+  @State private hasPermission: boolean = false;
+
+  aboutToAppear(): void {
+    hilog.info(DOMAIN, TAG, '{ComponentName} appeared');
+    // 页面加载时主动申请权限
+    this.requestNeededPermissions();
+  }
+
+  aboutToDisappear(): void {
+    hilog.info(DOMAIN, TAG, '{ComponentName} disappeared');
+    // 释放持有资源
+  }
+
+  // ─── 权限申请 ─────────────────────────────────────────────────────────────
+
+  /**
+   * 申请 Demo 所需的运行时权限。
+   * 须在使用权限保护接口前调用。
+   */
+  private async requestNeededPermissions(): Promise<void> {
+    hilog.debug(DOMAIN, TAG, 'requestNeededPermissions called');
+    const context = getContext(this) as common.UIAbilityContext;
+    const atManager = abilityAccessCtrl.createAtManager();
+    try {
+      const result = await atManager.requestPermissionsFromUser(context, REQUIRED_PERMISSIONS);
+      this.hasPermission = result.authResults.every((r: number) => r === 0);
+      hilog.info(DOMAIN, TAG, 'Permission result: %{public}s',
+                 this.hasPermission ? 'granted' : 'denied');
+      if (!this.hasPermission) {
+        this.resultText = '提示：需要授予权限才能运行此 Demo';
+        this.isError = true;
+      }
+    } catch (err) {
+      const msg: string = (err as Error).message ?? String(err);
+      hilog.error(DOMAIN, TAG, 'requestNeededPermissions failed: %{public}s', msg);
+      this.resultText = `权限申请失败：${msg}`;
+      this.isError = true;
+    }
+  }
+
+  // ─── 核心功能方法 ─────────────────────────────────────────────────────────
+
+  private async {actionMethod}(): Promise<void> {
+    if (!this.hasPermission) {
+      hilog.warn(DOMAIN, TAG, '{actionMethod} skipped: permission not granted');
+      this.resultText = '请先授予所需权限';
+      return;
+    }
+    hilog.debug(DOMAIN, TAG, '{actionMethod} called');
+    this.isLoading = true;
+    this.isError = false;
+    try {
+      // TODO: 调用需要权限的接口
+      hilog.info(DOMAIN, TAG, '{actionMethod} succeeded');
+    } catch (err) {
+      const msg: string = (err as Error).message ?? String(err);
+      hilog.error(DOMAIN, TAG, '{actionMethod} failed: %{public}s', msg);
+      this.resultText = `错误：${msg}`;
+      this.isError = true;
+    } finally {
+      this.isLoading = false;
+    }
+  }
+
+  build() {
+    Scroll() {
+      Column({ space: 16 }) {
+        Text($r('app.string.demo_{seq}_title'))
+          .fontSize(20)
+          .fontWeight(FontWeight.Bold)
+          .width('100%')
+          .textAlign(TextAlign.Center)
+          .padding({ top: 16 })
+
+        Divider()
+
+        // 权限状态提示
+        if (!this.hasPermission) {
+          Text('⚠️ 权限未授予，部分功能不可用')
+            .fontSize(13)
+            .fontColor('#E65100')
+            .width('100%')
+            .padding(8)
+            .backgroundColor('#FFF3E0')
+            .borderRadius(6)
+        }
+
+        // TODO: 操作控件
+
+        Button($r('app.string.demo_{seq}_{action}_btn'))
+          .width('100%')
+          .enabled(!this.isLoading && this.hasPermission)
+          .onClick(() => this.{actionMethod}())
+
+        if (this.isLoading) {
+          LoadingProgress().width(40).height(40)
+        }
+
+        if (this.resultText.length > 0) {
+          Text(this.resultText)
+            .fontSize(14)
+            .width('100%')
+            .padding(12)
+            .backgroundColor(this.isError ? '#FFEBEE' : '#F5F5F5')
+            .fontColor(this.isError ? '#C62828' : '#212121')
+            .borderRadius(8)
+        }
+      }
+      .width('100%')
+      .padding(16)
+    }
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+---
+
+## 三、主导航页面模板（DemoIndex.ets）
+
+> ⚠️ `DemoEntry.title/description` 必须声明为 `Resource` 类型并由 `$r()` 赋值（禁止硬编码字符串）；路由为 `pages/{序号}_{PascalCaseName}Page`（**无子目录**）。
+
+```typescript
+/**
+ * {LIBRARY_NAME} Demo 主导航页面
+ *
+ * 提供所有 Demo 的入口列表，通过 router 跳转到各 Demo 页面。
+ *
+ * @author {AUTHOR}
+ */
+
+import hilog from '@ohos.hilog';
+
+const DOMAIN: number = 0xD001;
+const TAG: string = '{LIBRARY_TAG}_DemoIndex';
+
+// Demo 条目数据结构（title/description 使用 Resource 类型，支持国际化）
+interface DemoEntry {
+  id: string;          // Demo 编号，如 "001"
+  title: Resource;     // Demo 名称，通过 $r('app.string.demo_NNN_title') 引用
+  description: Resource; // Demo 简要描述，通过 $r('app.string.demo_NNN_index_desc') 引用
+  route: string;       // 路由路径（无子目录，如 'pages/001_XxxPage'）
+}
+
+// Demo 列表配置（按序号排列；title/description 必须用 $r() 引用，禁止硬编码字符串）
+const DEMO_LIST: DemoEntry[] = [
+  {
+    id: '001',
+    title: $r('app.string.demo_001_title'),
+    description: $r('app.string.demo_001_index_desc'),
+    route: 'pages/001_{PascalCaseName}Page'
+  },
+  // ... 其他 Demo（数量必须与场景文档一致）
+];
+
+@Entry
+@Component
+struct DemoIndex {
+  aboutToAppear(): void {
+    hilog.info(DOMAIN, TAG, 'DemoIndex appeared, total demos: %{public}d', DEMO_LIST.length);
+  }
+
+  build() {
+    Column() {
+      // 页面标题（$r() 引用）
+      Text($r('app.string.demo_index_title'))
+        .fontSize(22)
+        .fontWeight(FontWeight.Bold)
+        .width('100%')
+        .textAlign(TextAlign.Center)
+        .padding({ top: 24, bottom: 4 })
+
+      // 动态计数文本：运行时数据，无需 $r()
+      Text(`共 ${DEMO_LIST.length} 个测试 Demo`)
+        .fontSize(13)
+        .fontColor('#888888')
+        .width('100%')
+        .textAlign(TextAlign.Center)
+        .margin({ bottom: 16 })
+
+      List({ space: 8 }) {
+        ForEach(DEMO_LIST, (demo: DemoEntry) => {
+          ListItem() {
+            this.DemoCard(demo)
+          }
+        }, (demo: DemoEntry) => demo.id)
+      }
+      .width('100%')
+      .layoutWeight(1)
+      .padding({ left: 16, right: 16, bottom: 16 })
+    }
+    .width('100%')
+    .height('100%')
+    .backgroundColor('#F0F2F5')
+  }
+
+  // @Builder 传入静态数据对象，属合法用法（不依赖 @State）
+  @Builder
+  DemoCard(demo: DemoEntry): void {
+    Row({ space: 12 }) {
+      // 序号徽章（纯动态字符串，直接插入 demo.id 即可）
+      Text(demo.id)
+        .fontSize(14)
+        .fontWeight(FontWeight.Bold)
+        .fontColor('#FFFFFF')
+        .width(44).height(44)
+        .textAlign(TextAlign.Center)
+        .backgroundColor('#3478F6')
+        .borderRadius(22)
+
+      // 标题 + 描述（Resource 类型，直接传入 Text，不可用模板字符串插入）
+      Column({ space: 4 }) {
+        Text(demo.title)
+          .fontSize(14)
+          .fontWeight(FontWeight.Medium)
+          .width('100%')
+        Text(demo.description)
+          .fontSize(11)
+          .fontColor('#888888')
+          .width('100%')
+          .maxLines(2)
+          .textOverflow({ overflow: TextOverflow.Ellipsis })
+      }
+      .layoutWeight(1)
+      .alignItems(HorizontalAlign.Start)
+
+      // 箭头
+      Text('›')
+        .fontSize(20)
+        .fontColor('#BBBBBB')
+    }
+    .width('100%')
+    .padding({ left: 16, right: 16, top: 12, bottom: 12 })
+    .backgroundColor(Color.White)
+    .onClick(() => {
+      hilog.info(DOMAIN, TAG, 'Navigate to demo: %{public}s', demo.id);
+      this.getUIContext().getRouter().pushUrl({ url: demo.route })
+        .catch((err: Error) => {
+          hilog.error(DOMAIN, TAG, 'Navigation failed: %{public}s', err.message);
+        });
+    })
+  }
+}
+```
+
+---
+
+## 四、main_pages.json 路由配置模板
+
+```json
+{
+  "src": [
+    "pages/DemoIndex",
+    "pages/001_{PascalCaseName1}Page",
+    "pages/002_{PascalCaseName2}Page"
+  ]
+}
+```
+
+**更新规则**：
+- 主页面 `DemoIndex` 必须列在第一位
+- 其余 Demo 页面按序号顺序排列，路径格式 `pages/{序号}_{PascalCaseName}Page`（**不含子目录**）
+- 路径与 Demo 页面文件所在位置一致（不含 `.ets` 后缀）
+
+---
+
+## 五、module.json5 权限声明模板
+
+在 `module.json5` 的 `"module"` 节点下添加 `"requestPermissions"` 字段：
+
+```json5
+{
+  "module": {
+    // ...其他字段...
+    "requestPermissions": [
+      {
+        // 网络权限（系统自动授权，无需 usedScene）
+        "name": "ohos.permission.INTERNET"
+      },
+      {
+        // 读取媒体文件（需用户授权）
+        "name": "ohos.permission.READ_MEDIA",
+        "reason": "$string:permission_read_media_reason",
+        "usedScene": {
+          "abilities": ["EntryAbility"],
+          "when": "inuse"
+        }
+      },
+      {
+        // 相机（需用户授权）
+        "name": "ohos.permission.CAMERA",
+        "reason": "$string:permission_camera_reason",
+        "usedScene": {
+          "abilities": ["EntryAbility"],
+          "when": "inuse"
+        }
+      }
+    ]
+  }
+}
+```
+
+> ⚠️ `reason` 字段必须引用 `$string:xxx` 资源，不得硬编码字符串。需在 `resources/base/element/string.json`（及 zh_CN/en_US）中添加对应字符串资源。
+
+---
+
+## 六、原始库 Demo 入口保留模板（OriginalDemoCard）
+
+若工程中已有原始的鸿蒙原生库功能演示页面（如 `pages/Tab`，通过 `pages/Index` 跳转进入），**必须**在 `DemoIndex.ets` 中以视觉区分的方式保留其跳转入口，确保原有 Demo 不被覆盖。
+
+1. 在 `DemoIndex.ets` 顶层常量区声明原始 Demo 路由：
+
+```typescript
+// 原始库 Demo 路由（保留原有演示，不纳入序号列表）
+const ORIGINAL_DEMO_ROUTE: string = 'pages/Tab';
+```
+
+2. 在 `struct DemoIndex` 中添加 `@Builder OriginalDemoCard()` 方法（静态布局，无 `@State`）：
+
+```typescript
+@Builder
+OriginalDemoCard(): void {
+  Row({ space: 12 }) {
+    Text('↗')
+      .fontSize(14).fontWeight(FontWeight.Bold).fontColor('#FFFFFF')
+      .width(44).height(44).textAlign(TextAlign.Center)
+      .backgroundColor('#FF8C00')  // 橙色，与蓝色序号徽章区分
+      .borderRadius(22)
+
+    Column({ space: 4 }) {
+      Text($r('app.string.demo_original_title'))
+        .fontSize(14).fontWeight(FontWeight.Medium).width('100%')
+      Text($r('app.string.demo_original_index_desc'))
+        .fontSize(11).fontColor('#888888').width('100%')
+        .maxLines(2).textOverflow({ overflow: TextOverflow.Ellipsis })
+    }
+    .layoutWeight(1).alignItems(HorizontalAlign.Start)
+
+    Text('›').fontSize(24).fontColor('#BBBBBB')
+  }
+  .width('100%')
+  .padding({ left: 16, right: 16, top: 12, bottom: 12 })
+  .backgroundColor('#FFF8EE')
+  .borderRadius(8)
+  .border({ width: 1, color: '#FFD580', style: BorderStyle.Solid })
+  .onClick(() => {
+    this.getUIContext().getRouter().pushUrl({ url: ORIGINAL_DEMO_ROUTE })
+      .catch((err: Error) => {
+        hilog.error(DOMAIN, TAG, 'Original demo navigation failed: %{public}s', err.message);
+      });
+  })
+}
+```
+
+3. 在 `build()` 的 Divider 下方、序号 Demo List 上方插入原始 Demo 卡片（用 Column 包裹确保水平边距一致）：
+
+```typescript
+Column() {
+  this.OriginalDemoCard()
+}
+.width('100%')
+.padding({ left: 16, right: 16 })
+```
+
+4. 在 **base / zh_CN / en_US 三个** `string.json` 中添加对应字符串键：
+
+```json
+// base 与 zh_CN
+{ "name": "demo_original_title", "value": "原始鸿蒙原生库示例" },
+{ "name": "demo_original_index_desc", "value": "原有鸿蒙原生库功能演示页面（保留入口）" }
+
+// en_US
+{ "name": "demo_original_title", "value": "Original Library Demo" },
+{ "name": "demo_original_index_desc", "value": "Original library feature showcase page (preserved entry)" }
+```

package/vendor/Server/Skills/arkts-library-demo-code/scripts/build.ps1

@@ -0,0 +1,93 @@
+<#
+.SYNOPSIS
+    Run devecocli build with timeout and daemon cleanup.
+.DESCRIPTION
+    Use .NET Process class to avoid PS 5.1 Start-Process limitations.
+    Redirect via cmd.exe built-in redirection (> file 2>&1), daemon inherits
+    FILE handles from cmd.exe (not pipe handles), WaitForExit only waits cmd.exe.
+    On timeout or build failure, force-kills the process tree and sweeps
+    residual hvigor node/java daemons so pipes are released.
+#>
+param([string]$Cmd, [switch]$JavaHome)
+
+$DevEco = "D:\software\ide\DevEco Studio"  # fallback
+try {
+    $hdcPath = (cmd /c "where.exe hdc 2>nul" 2>&1) -split "`r`n" | Select-Object -First 1
+    if ($hdcPath) {
+        $hdcPath = $hdcPath.Trim()
+        $idx = $hdcPath.IndexOf('\sdk')
+        if ($idx -gt 0) { $DevEco = $hdcPath.Substring(0, $idx) }
+    }
+} catch {}
+
+# Auto-set JAVA_HOME for test HAP builds
+if ($JavaHome) {
+    $Cmd = "set JAVA_HOME=$DevEco\jbr && set PATH=%JAVA_HOME%\bin;%PATH% && $Cmd"
+}
+
+$TimeoutMs = 300000
+$ErrorActionPreference = "Continue"
+
+Write-Host "[build.ps1] DevEco:  $DevEco"
+Write-Host "[build.ps1] Cmd:     $Cmd"
+Write-Host "[build.ps1] Timeout: $($TimeoutMs/1000)s"
+
+# Write command to temp .cmd file
+$guid = [System.Guid]::NewGuid().ToString("N")
+$cmdFile = "$env:TEMP\devecocli_cmd_$guid.cmd"
+$logFile = "$env:TEMP\devecocli_log_$guid.log"
+Set-Content -Path $cmdFile -Value "@echo off`r`n$Cmd > `"$logFile`" 2>&1"
+
+# Use .NET Process class (avoids PS 5.1 Start-Process -NoNewWindow + Redirect conflict)
+$psi = New-Object System.Diagnostics.ProcessStartInfo
+$psi.FileName = "cmd.exe"
+$psi.Arguments = "/c `"$cmdFile`""
+$psi.UseShellExecute = $false
+$psi.CreateNoWindow = $true
+# Don't set RedirectStandardOutput/RedirectStandardError - cmd.exe handles redirection internally
+$proc = [System.Diagnostics.Process]::Start($psi)
+
+# Wait for cmd.exe only (daemon stays alive with FILE handles, not pipe handles)
+$finished = $proc.WaitForExit($TimeoutMs)
+
+if (-not $finished) {
+    Write-Host "[build.ps1] TIMEOUT after $($TimeoutMs/1000)s"
+    $proc.Kill()
+    taskkill /PID $proc.Id /T /F 2>$null | Out-Null
+    $exitCode = 1
+} else {
+    $exitCode = $proc.ExitCode
+}
+
+# Output build results from file
+if (Test-Path $logFile) {
+    Get-Content $logFile
+}
+Write-Host ""
+
+# Daemon cleanup (prevents session blocking via inherited handles)
+Write-Host "[build.ps1] Stopping daemon..."
+& "$DevEco\tools\node\node.exe" "$DevEco\tools\hvigor\bin\hvigorw.js" --stop-daemon *>$null
+
+# Residual daemon force-kill fallback on failure (success path keeps graceful stop only)
+if ($exitCode -ne 0) {
+    Write-Host "[build.ps1] Build failed - sweeping residual hvigor daemons..."
+    $residual = Get-CimInstance Win32_Process -ErrorAction SilentlyContinue |
+        Where-Object {
+            ($_.Name -eq 'node.exe' -or $_.Name -eq 'java.exe') -and
+            $_.CommandLine -and
+            $_.CommandLine -match 'hvigor' -and
+            $_.CommandLine -match [regex]::Escape($DevEco) -and
+            $_.CommandLine -notmatch '--stop-daemon'
+        }
+    foreach ($p in $residual) {
+        Write-Host "[build.ps1] Force-kill residual daemon PID $($p.ProcessId)"
+        taskkill /PID $p.ProcessId /T /F 2>$null | Out-Null
+    }
+}
+
+# Cleanup temp files
+Remove-Item $logFile, $cmdFile -Force -ErrorAction SilentlyContinue
+
+Write-Host "[build.ps1] DONE exit=$exitCode"
+[Environment]::Exit($exitCode)