@ohos-cpf/3rdloop 0.0.4 → 0.0.5

package/vendor/Server/Skills/arkts-code-use/references/CODE_PATTERNS.md

@@ -0,0 +1,431 @@
+# ArkTS 代码模式
+
+> 编写鸿蒙原生 ArkTS 代码时的标准实现模式：异步编程、并发、错误处理、事件、权限、资源生命周期、UI 状态管理。所有模式均已通过 ArkTS 严格模式编译验证。
+
+---
+
+## 一、异步编程模式
+
+### 1.1 Promise + async/await（默认选择）
+
+```typescript
+import fs from '@ohos.file.fs';
+import hilog from '@ohos.hilog';
+
+const DOMAIN: number = 0x0001;
+const TAG: string = 'MyApp_Async';
+
+/** 将回调式 API 封装为 Promise */
+function readTextAsync(filePath: string): Promise<string> {
+  return new Promise<string>((resolve: (value: string) => void,
+    reject: (reason: Error) => void) => {
+    fs.readText(filePath, (err: Error, data: string) => {
+      if (err) {
+        reject(err instanceof Error ? err : new Error(String(err)));
+        return;
+      }
+      resolve(data);
+    });
+  });
+}
+
+/** 调用方：async/await + try/catch/finally */
+async function processFile(filePath: string): Promise<string> {
+  try {
+    const content: string = await readTextAsync(filePath);
+    hilog.info(DOMAIN, TAG, 'read ok, length=%{public}d', content.length);
+    return content;
+  } catch (e) {
+    hilog.error(DOMAIN, TAG, 'read failed: %{public}s', (e as Error).message);
+    throw e instanceof Error ? e : new Error(String(e));
+  }
+}
+```
+
+### 1.2 超时控制（Promise.race）
+
+```typescript
+function withTimeout<T>(task: Promise<T>, timeoutMs: number): Promise<T> {
+  const timer: Promise<never> = new Promise<never>(
+    (_resolve: (value: never) => void, reject: (reason: Error) => void) => {
+      setTimeout(() => {
+        reject(new Error(`timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+    });
+  return Promise.race<T>([task, timer]);
+}
+```
+
+---
+
+## 二、并发模式（taskpool / worker）
+
+> 阻塞 IO、大量计算禁止在主线程执行。优先 taskpool（轻量任务池），长生命周期后台线程用 worker。
+
+### 2.1 taskpool 耗时计算
+
+```typescript
+import taskpool from '@ohos.taskpool';
+
+// @Concurrent 函数必须是独立函数，不能捕获外部变量（可序列化参数传入）
+@Concurrent
+function computeChecksum(input: number[]): number {
+  let sum: number = 0;
+  for (const value of input) {
+    sum += value * 31;
+  }
+  return sum;
+}
+
+async function runInBackground(input: number[]): Promise<number> {
+  const task: taskpool.Task = new taskpool.Task(computeChecksum, input);
+  return await taskpool.execute(task) as number;
+}
+```
+
+### 2.2 worker 生命周期（必须 terminate）
+
+```typescript
+import worker from '@ohos.worker';
+
+class WorkerHost {
+  private threadWorker: worker.ThreadWorker | null = null;
+
+  start(): void {
+    // 脚本路径相对模块 src/main/ets
+    this.threadWorker = new worker.ThreadWorker('entry/ets/workers/MyWorker.ets');
+    this.threadWorker.onmessage = (event: MessageEvents): void => {
+      // 处理子线程结果
+    };
+    this.threadWorker.postMessage({ type: 'start' });
+  }
+
+  /** 必须在确定生命周期节点调用，防止线程泄露 */
+  stop(): void {
+    if (this.threadWorker !== null) {
+      this.threadWorker.terminate();
+      this.threadWorker = null;
+    }
+  }
+}
+```
+
+---
+
+## 三、错误处理模式
+
+### 3.1 BusinessError（系统 API 标准错误）
+
+```typescript
+import { BusinessError } from '@ohos.base';
+
+async function callSystemApi(): Promise<void> {
+  try {
+    // await someSystemApi();
+  } catch (error) {
+    // 系统 API 错误统一转型为 BusinessError 读取 code
+    const err: BusinessError = error as BusinessError;
+    hilog.error(0x0001, 'MyApp', 'code=%{public}d, msg=%{public}s', err.code, err.message);
+    throw err instanceof Error ? err : new Error(String(err));
+  }
+}
+```
+
+### 3.2 参数防御性校验
+
+```typescript
+class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+  }
+}
+
+function validateInput(value: string | null | undefined, fieldName: string,
+  maxLen: number = 256): string {
+  if (value === null || value === undefined || value.length === 0) {
+    throw new ValidationError(`${fieldName} must not be empty`);
+  }
+  if (value.length > maxLen) {
+    throw new ValidationError(`${fieldName} exceeds max length ${maxLen}`);
+  }
+  return value;
+}
+```
+
+### 3.3 统一 Result 类型（避免异常控制流蔓延）
+
+```typescript
+export interface Result<T> {
+  success: boolean;
+  value?: T;
+  error?: string;
+}
+
+export class Ok<T> implements Result<T> {
+  success: boolean = true;
+  constructor(public value: T) {}
+}
+
+export class Fail<T> implements Result<T> {
+  success: boolean = false;
+  constructor(public error: string) {}
+}
+```
+
+---
+
+## 四、事件模式（emitter）
+
+```typescript
+import emitter from '@ohos.events.emitter';
+
+// 事件常量集中定义
+export const enum AppEvent {
+  DATA_UPDATED = 1001,
+  SYNC_FAILED = 1002,
+}
+
+class EventBus {
+  private static subscriptionCount: number = 0;
+
+  static subscribe(eventId: number, callback: (data: emitter.EventData) => void): void {
+    emitter.on({ eventId: eventId }, callback);
+    EventBus.subscriptionCount += 1;
+  }
+
+  static emit(eventId: number, data: Record<string, Object>): void {
+    emitter.emit({ eventId: eventId }, { data: data });
+  }
+
+  /** 取消订阅必须与 on 配对 */
+  static unsubscribe(eventId: number): void {
+    emitter.off(eventId);
+  }
+}
+```
+
+---
+
+## 五、权限申请模式
+
+```typescript
+import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl';
+import { common } from '@kit.AbilityKit';
+
+async function requestPermissions(context: common.UIAbilityContext,
+  permissions: Permissions[]): Promise<boolean> {
+  const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
+  const result: abilityAccessCtrl.PermissionRequestResult =
+    await atManager.requestPermissionsFromUser(context, permissions);
+  return result.authResults.every((status: number) =>
+    status === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED);
+}
+```
+
+> normal 级权限仅声明即生效；user_grant 级权限须声明 + 运行时申请两步缺一不可。
+
+---
+
+## 六、资源生命周期管理（防泄露）
+
+> **规则**：凡是 `create/open/on/connect` 获取的资源，必须存在对称的 `destroy/close/off/disconnect` 释放路径，置于 `try/finally` 或组件销毁回调中。
+
+| 资源 | 获取 | 释放 | 位置 |
+|------|------|------|------|
+| HTTP 连接 | `http.createHttp()` | `httpRequest.destroy()` | `try/finally` |
+| 文件句柄 | `fs.openSync()` | `fs.closeSync(fd)` | `try/finally` |
+| RDB 存储 | `getRdbStore()` | `close()` | 模块卸载 |
+| Worker | `new ThreadWorker()` | `terminate()` | 任务完成/销毁 |
+| Timer | `setInterval()` | `clearInterval(id)` | `aboutToDisappear` |
+| emitter 订阅 | `emitter.on()` | `emitter.off(id)` | `aboutToDisappear` |
+| 传感器 | `sensor.on()` | `sensor.off(type)` | 页面隐藏/销毁 |
+| AVPlayer | `createAVPlayer()` | `release()` | 播放结束/销毁 |
+
+### 6.1 HTTP 请求标准范式（最常见泄露点）
+
+```typescript
+import { http } from '@kit.NetworkKit';
+
+const MAX_RESPONSE_BYTES: number = 5 * 1024 * 1024;
+
+async function httpGet(url: string): Promise<string> {
+  const httpRequest: http.HttpRequest = http.createHttp();
+  try {
+    const response: http.HttpResponse = await httpRequest.request(url, {
+      method: http.RequestMethod.GET,
+      connectTimeout: 10_000,
+      readTimeout: 15_000,
+      expectMaxDuration: 20_000,
+    });
+    if (typeof response.result !== 'string') {
+      throw new Error('unexpected response type');
+    }
+    if (response.result.length > MAX_RESPONSE_BYTES) {
+      throw new Error(`response too large: ${response.result.length}`);
+    }
+    return response.result;
+  } finally {
+    // ✅ 成功失败均释放
+    httpRequest.destroy();
+  }
+}
+```
+
+### 6.2 文件读写标准范式
+
+```typescript
+import fs from '@ohos.file.fs';
+
+function readFileSafely(filePath: string): string {
+  let fd: number = -1;
+  try {
+    const file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
+    fd = file.fd;
+    const stat: fs.Stat = fs.statSync(filePath);
+    const buffer: ArrayBuffer = new ArrayBuffer(stat.size);
+    fs.readSync(fd, buffer);
+    return String.fromCharCode(...new Uint8Array(buffer));
+  } finally {
+    if (fd >= 0) {
+      fs.closeSync(fd);
+    }
+  }
+}
+```
+
+### 6.3 组件内订阅/Timer 清理
+
+```typescript
+@Component
+struct PollingComponent {
+  @State message: string = '';
+  private timerId: number = -1;
+
+  aboutToAppear(): void {
+    this.timerId = setInterval(() => {
+      this.message = `tick ${Date.now()}`;
+    }, 1000);
+  }
+
+  aboutToDisappear(): void {
+    if (this.timerId >= 0) {
+      clearInterval(this.timerId);
+      this.timerId = -1;
+    }
+  }
+
+  build() {
+    Text(this.message)
+  }
+}
+```
+
+---
+
+## 七、UI 状态管理模式
+
+### 7.1 父子组件通信
+
+```typescript
+// 子组件：单向输入 @Prop，双向绑定 @Link
+@Component
+struct CounterCard {
+  @Prop title: string = '';
+  @Link count: number;
+
+  build() {
+    Column({ space: 8 }) {
+      Text(this.title)
+        .fontSize(16)
+      Text(`count: ${this.count}`)
+        .fontSize(20)
+      Button('+1')
+        .onClick(() => {
+          this.count += 1;
+        })
+    }
+    .padding(12)
+  }
+}
+
+@Entry
+@Component
+struct Index {
+  @State count: number = 0;
+
+  build() {
+    Column({ space: 12 }) {
+      CounterCard({ title: 'demo', count: $count })  // @Link 用 $ 传引用
+    }
+  }
+}
+```
+
+### 7.2 @Provide/@Consume 跨层级
+
+```typescript
+// 祖先组件
+@Entry
+@Component
+struct GrandParent {
+  @Provide themeColor: string = '#007DFF';
+
+  build() { /* 包含后代组件 */ }
+}
+
+// 任意后代组件（无需逐层传递）
+@Component
+struct DeepChild {
+  @Consume themeColor: string;
+
+  build() {
+    Text('themed').fontColor(this.themeColor)
+  }
+}
+```
+
+### 7.3 @Builder 复用 + @BuilderParam 插槽
+
+```typescript
+@Builder
+function LoadingView(text: string) {
+  Column({ space: 8 }) {
+    LoadingProgress().width(48).height(48)
+    Text(text).fontSize(14)
+  }
+  .width('100%')
+  .justifyContent(FlexAlign.Center)
+}
+```
+
+---
+
+## 八、兼容性守卫模式
+
+```typescript
+import deviceInfo from '@ohos.deviceInfo';
+
+// 硬件能力检测：调用蓝牙/NFC/摄像头前必须
+function ensureBluetooth(): boolean {
+  return canIUse('SystemCapability.Communication.Bluetooth.Core');
+}
+
+// API Level 守卫：使用 since 高于目标版本的接口前必须
+function getSdkApiLevel(): number {
+  return deviceInfo.sdkApiVersion;
+}
+```
+
+---
+
+## 九、典型平台陷阱速查
+
+| 陷阱 | 正确做法 |
+|------|---------|
+| 沙箱路径 | 用 `context.filesDir` / `context.cacheDir`；禁止硬编码 `/data/local/tmp` |
+| rawfile 资源 | 不可直接路径访问；用 `resourceManager.getRawFileContentSync()` / `getRawFdSync()` |
+| `file://` 前缀 | 拼接为 `file://` + 绝对路径（两斜杠），媒体 URL 不用三斜杠 |
+| fs.writeSync 传 Uint8Array | 必须传 `uint8array.buffer`（ArrayBuffer） |
+| 高频 hilog.debug | 禁止每帧/每秒多次打印，影响性能 |
+| 阻塞主线程 | `Thread.sleep` 类同步等待不存在；用 `await new Promise` + setTimeout 或 taskpool |

package/vendor/Server/Skills/arkts-code-use/references/SYNTAX_CHECK_GUIDE.md

@@ -0,0 +1,164 @@
+# 语法验证指南（deveco-cli）
+
+> 生成的 ArkTS 代码必须通过编译验证（`BUILD SUCCESSFUL`）才可交付。本文档说明验证机制、工具用法与错误修复。
+
+---
+
+## 一、核心机制：构建图可达性
+
+hvigor 编译器只编译**构建图可达**的 .ets 文件：
+
+```
+entry/src/main/ets/pages/Index.ets（页面，注册于 main_pages.json）
+    └── import → 组件/工具类
+            └── import → 更深层模块
+```
+
+- 被页面/入口 import 链引用的文件 → 参与编译，语法/约束错误全部暴露
+- **未被引用的孤立 .ets 文件 → 完全不编译，错误不会暴露**
+
+因此验证前必须确保新代码已接入构建图。两种方式：
+
+| 方式 | 操作 | 适用 |
+|------|------|------|
+| 工程内接线 | 新页面注册 `main_pages.json`；新类被页面/`index.ets` import | 有目标工程 |
+| 自动接线 | `verify-arkts.cjs` 脚本在临时工程入口页生成 side-effect import（`import '../verify/Xxx';`） | 独立代码验证 |
+
+> side-effect import（无绑定导入）足以让目标文件参与编译并暴露全部错误，无需知道文件内导出符号名。
+
+---
+
+## 二、工程模式验证
+
+```bash
+# 在目标工程根目录执行
+devecocli build
+
+# 指定模块/产物
+devecocli build --modules entry
+devecocli build --product default --build-mode debug
+
+# 清理后构建（怀疑缓存问题时）
+devecocli build clean && devecocli build
+```
+
+**前置检查**：新代码已按 Phase 3.5 接线（页面注册 / import 可达），否则构建通过不代表语法正确。
+
+**结果判定**：只认 `BUILD SUCCESSFUL`；`ERROR` 必须清零，`WARNING` 记录但不阻断。
+
+---
+
+## 三、独立模式验证（verify-arkts.cjs）
+
+无目标工程时，使用本SKILL自带脚本自动完成"脚手架 → 接线 → 编译 → 回显错误"：
+
+```bash
+node {本SKILL目录}/scripts/verify-arkts.cjs --files <文件1.ets> [文件2.ets ...] [选项]
+```
+
+| 选项 | 说明 |
+|------|------|
+| `--files <f.ets>...` | 待验证的 .ets 文件（至少 1 个；多文件间相对导入按原目录结构保留） |
+| `--work-dir <目录>` | 临时工程所在目录（默认系统临时目录，验证后删除；指定后工程保留可复用加速下次验证） |
+| `--keep` | 保留临时工程（默认自动删除） |
+| `--api-level <n>` | 指定脚手架 API Level（默认用 devecocli 默认值） |
+| `--timeout <ms>` | 构建超时（默认 600000） |
+
+**MCP Gateway 调用**（JSON 参数）：
+
+```json
+{ "files": ["/abs/path/Foo.ets", "/abs/path/Bar.ets"], "workDir": "/tmp/arkts-verify", "keep": false }
+```
+
+**退出码**：`0` 验证通过；`1` 存在编译错误（输出结构化错误列表）；`2` 环境/参数错误。
+
+**输出示例（失败）**：
+
+```
+=== ArkTS 编译验证失败（3 个错误） ===
+  [arkts-no-any-unknown]        /abs/path/Foo.ets:2:17
+    Use explicit types instead of "any", "unknown"
+  ...
+```
+
+**注意**：
+- 引用了工程专属资源（`$r('app.string.xxx')`、rawfile、自定义 so 库）的代码无法在临时工程验证，须用工程模式
+- 首次运行需脚手架（约 10-60s）；指定 `--work-dir` 复用可加速
+- 需要本机已安装 DevEco Studio + SDK + devecocli 可用
+
+---
+
+## 四、错误输出解析
+
+`devecocli build` 的 ArkTS 编译错误格式（用于定位）：
+
+```
+N ERROR: 10605008 ArkTS Compiler Error
+Error Message: <人读信息> (arkts-规则名) At File: <绝对路径>:<行>:<列>
+```
+
+解析要点：
+- 规则名在**圆括号**内，如 `(arkts-no-any-unknown)`
+- 位置为 `文件:行:列`，列指向违规 token 起点
+- 同一文件多个错误一次全部修复再重跑，避免逐个循环
+
+---
+
+## 五、错误修复速查表
+
+| 错误关键词 / 规则 | 修复方案 |
+|-----------------|---------|
+| `arkts-no-any-unknown` | `any`/`unknown` → 具体类型或泛型 `T`；`as any` → `as 具体类型` |
+| `arkts-no-esobj` | `ESObject`/`Object` → `interface` 或具体类型 |
+| `arkts-no-untyped-obj-literals` | `let o = {...}` → 先声明 `interface`/`class`，再 `const o: T = {...}` |
+| `arkts-no-obj-literals-as-types` | 匿名对象类型参数 → 命名 `interface` |
+| `arkts-limited-throw` | `throw e` → `throw e instanceof Error ? e : new Error(String(e))` |
+| `arkts-no-dynamic-property` | `obj['key']` → `obj.key` |
+| `arkts-no-structural-typing` | 鸭子类型赋值 → 显式 `implements` / `extends` |
+| `arkts-no-unsafe-cast` | `as unknown as T` → 修正类型定义，单次断言 |
+| `arkts-no-delete` | `delete obj.x` → `obj.x = undefined` 或重构结构 |
+| `arkts-no-for-in` | `for...in` → `Object.keys()` + `for...of` |
+| `arkts-no-prototype-assignment` | 原型扩展 → 类继承/组合 |
+| `arkts-no-arguments` | `arguments` → `...args: T[]` |
+| `Cannot find module 'xxx'` | import 路径拼写/大小写；相对层级；`@ohos.*` 模块名以文档为准 |
+| `xxx has been deprecated` | 查官方文档替代 API，禁止保留 |
+| `Page 'xxx' does not exist` | `main_pages.json` 与实际页面文件对齐 |
+| `Permission denied` / 权限类 | `module.json5` `requestPermissions` 声明（对照 Phase 2 查证表） |
+| `undefined property` / 资源类 | `$r` 资源需存在于 `resources/base/element`；rawfile 走 resourceManager |
+| 装饰器报错 | `@Component` struct 不能继承；`@Concurrent` 函数不能捕获外部变量 |
+| ArkUI 状态更新不生效 | build() 内禁止修改状态变量；修改放事件回调 |
+
+---
+
+## 六、辅助检查（可选补充）
+
+### 6.1 Code Linter（代码风格/安全规则）
+
+```bash
+devecocli check lint <文件或目录> [--fix] [--format json]
+```
+
+- 检查 TS/ArkTS 风格问题（`@performance/recommended`、`@typescript-eslint/recommended`、`@security/*`）
+- 依赖工程上下文（`build-profile.json5`），且部分环境需工程完成同步后才识别文件（`Files checked: 0` 说明未识别到目标）
+- **lint 通过 ≠ 语法正确**，仅作为风格/安全补充；最终以 `devecocli build` 为准
+
+### 6.2 版本兼容检查
+
+```bash
+devecocli check compat versions                        # 列出可用 SDK 版本
+devecocli check compat --source-version "<V1>" --target-version "<V2>"
+devecocli check compat --source-version "<V1>" --target-version "<V2>" <文件...>
+```
+
+检查代码使用的 API 在目标 SDK 版本是否存在/已变更，适合交付前核对 API Level 兼容性。
+
+> zsh 下版本号含括号，务必加引号；先用 `compat versions` 复制真实版本串。
+
+---
+
+## 七、验证纪律
+
+1. **一次性修复**：收集全部 ERROR 后统一修复，再重新构建
+2. **修复循环上限 5 轮**：超过后停止，向用户报告错误清单与已尝试方案
+3. **禁止降低验证标准**：不允许通过注释掉代码、放宽 lint 配置等方式"绕过"错误
+4. **速查表未覆盖的错误**：用 `script_deveco_docs` 查证涉事 API 的正确用法，或查阅 [ArkTS 规范与约束](ARKTS_RULES.md) 对应条目