@ohos-cpf/3rdloop 0.0.4 → 0.0.5

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

@@ -0,0 +1,144 @@
+# API 查证指南
+
+> 编写 ArkTS 代码前，所有系统 API 的 import 路径、方法签名、权限、API Level 必须通过官方文档查证。本文档说明查证工具的使用方法与领域关键词速查。
+
+---
+
+## 一、查证工具
+
+### 1.1 首选：MCP Gateway `script_deveco_docs`
+
+MCP Gateway 运行时，`script_deveco_docs` 工具封装了 `devecocli docs`，可直接检索与精读 HarmonyOS 官方 API 文档。
+
+**按关键词检索（action=search）**：
+
+```json
+{
+  "action": "search",
+  "keywords": "http createHttp request",
+  "catalog": "harmonyos-references",
+  "limit": 5
+}
+```
+
+| 参数 | 说明 |
+|------|------|
+| `action` | `search`（检索）或 `read`（读全文） |
+| `keywords` | 空格分隔的关键词，建议 2-4 个（API 名 + 模块名 + 功能词） |
+| `catalog` | 默认 `harmonyos-references`（API 参考）；指南类用 `harmonyos-guides` |
+| `limit` | 返回条数，默认 10 |
+
+返回字段：`title`（文档标题）、`documentId`（用于 read）、`sectionTitle`（命中小节）、`snippet`（摘要）。
+
+**按 documentId 精读（action=read）**：
+
+```json
+{
+  "action": "read",
+  "documentId": "API参考/网络/Network_Kit_网络服务/ArkTS_API/ohos_net_http_数据请求_/js-apis-http",
+  "section": "HttpRequest"
+}
+```
+
+`section` 可选，指定后只返回该小节（推荐，节省 token）。文档正文包含：方法签名、参数表、返回值、`权限`、`系统能力`（SystemCapability）、`起始版本`（since）、`废弃`（deprecated）标注、错误码。
+
+### 1.2 备选：`devecocli docs`（终端）
+
+MCP 不可用时直接使用 CLI：
+
+```bash
+# 检索（匹配任一关键词）
+devecocli docs search "http createHttp" --limit 5
+
+# 按文档 ID 精读
+devecocli docs read "API参考/网络/Network_Kit_网络服务/ArkTS_API/ohos_net_http_数据请求_/js-apis-http"
+
+# 查看可用文档目录
+devecocli docs catalog
+```
+
+### 1.3 补充：知识库（最佳实践/平台陷阱）
+
+MCP Gateway 的 `kb_search`（内置）或 `kb-server_search_knowledge`（下游）可检索鸿蒙知识库中的最佳实践与实战经验（如平台陷阱、性能优化），适合在方案设计阶段补充查询，不适合替代官方 API 参考。
+
+---
+
+## 二、三步查询法
+
+对每个涉及的系统 API 依次执行：
+
+```
+Step 1 宽泛定位：用功能关键词检索，确认可用的模块/类
+        例：keywords = "video player"
+Step 2 精确签名：read 文档定位到具体类/方法小节，记录完整签名
+        例：documentId = "...js-apis-media", section = "createAVPlayer"
+Step 3 权限与版本：确认该 API 的「权限」「起始版本」「废弃」标注
+        - 权限 → 记入 module.json5 声明清单
+        - since > 目标 API Level → 加 canIUse()/sdkApiVersion 守卫或换旧接口
+        - deprecated → 检索替代接口（keywords 加 "alternative" 或直接搜新接口名）
+```
+
+---
+
+## 三、领域关键词速查
+
+| 领域 | 功能 | 检索关键词 |
+|------|------|-----------|
+| 网络 | HTTP 请求 | `http createHttp request` |
+| 网络 | WebSocket | `webSocket connect` |
+| 网络 | 网络状态 | `network connection` |
+| 存储 | KV 偏好 | `preferences data` |
+| 存储 | 关系型数据库 | `relationalStore` |
+| 存储 | 文件读写 | `file fs openSync readSync` |
+| 存储 | 用户文件选择 | `file picker` |
+| UI | 页面路由 | `Navigation NavDestination router` |
+| UI | 列表懒加载 | `LazyForEach IDataSource` |
+| UI | 动画 | `animateTo animation` |
+| UI | 弹窗 | `CustomDialog AlertDialog` |
+| 多媒体 | 视频播放 | `AVPlayer media` |
+| 多媒体 | 音频播放/录制 | `AudioRenderer AudioCapturer` |
+| 多媒体 | 图片处理 | `ImageSource PixelMap` |
+| 设备 | 定位 | `geoLocationManager` |
+| 设备 | 蓝牙 BLE | `bluetooth ble` |
+| 设备 | 传感器 | `sensor accelerometer` |
+| 设备 | 振动 | `vibrator` |
+| 安全 | 对称加密 | `cryptoFramework AES Cipher` |
+| 安全 | 摘要/HMAC | `cryptoFramework hash hmac` |
+| 安全 | 密钥管理 | `huks` |
+| 并发 | 任务池 | `taskpool execute Concurrent` |
+| 并发 | Worker | `worker ThreadWorker` |
+| 事件 | 事件总线 | `emitter on emit off` |
+| 权限 | 运行时申请 | `requestPermissionsFromUser abilityAccessCtrl` |
+| 应用 | 应用上下文 | `common UIAbilityContext` |
+| 应用 | 弹框申请 | `requestPermissionsFromUser` |
+
+---
+
+## 四、API Level 对照
+
+| API Level | 系统版本 | 说明 |
+|-----------|---------|------|
+| 9 | HarmonyOS 3.2 | 基础 API |
+| 10 | HarmonyOS 4.0 | — |
+| 11 | HarmonyOS 4.1 | Stage 模型完善 |
+| 12 | HarmonyOS 5.0 (NEXT) | NEXT 正式版本 |
+| 13+ | 5.x 后续 | 持续演进 |
+
+**规则**：
+- 工程模式：目标 API Level 以目标工程 `build-profile.json5` 的 `compatibleSdkVersion` 为准（先读取再写代码）
+- 独立模式：默认按 API 12+ 编写；`since` > 12 的接口必须加版本守卫
+- 优先使用非废弃接口；文档明确标注 `废弃` 的禁止使用
+
+---
+
+## 五、查证结论记录格式
+
+每个功能点查证后立即记录，作为 Phase 3 编码依据：
+
+| 功能点 | import 路径 | 关键 API 与签名 | 权限 | since | 结论 |
+|--------|------------|----------------|------|-------|------|
+| 发起 GET 请求 | `@kit.NetworkKit` (`http`) | `http.createHttp(): HttpRequest`、`request(url, options): Promise<HttpResponse>` | `ohos.permission.INTERNET` | 8 | ✅ |
+| 后台计算校验和 | `@ohos.taskpool` | `@Concurrent` 函数 + `taskpool.execute(task)` | 无 | 9 | ✅ |
+| 蓝牙扫描 | `@ohos.bluetooth.ble` | `startScan(filters)` | `ohos.permission.ACCESS_BLUETOOTH` | 10 | ⚠️ 需 canIUse 守卫 |
+
+> 未出现在该表中的系统 API 不允许出现在最终代码里。

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

@@ -0,0 +1,240 @@
+# ArkTS 规范与约束速查
+
+> ArkTS 是 TypeScript 的扩展集，在 TS 基础上施加了更严格的静态类型约束（强制静态类型、禁止运行时改变对象布局），以获得更好的运行性能。本文档汇总编码时必须遵守的约束，**违反即编译报错**。
+
+---
+
+## 一、禁止项清单（编译必查）
+
+以下是 ArkTS 严格模式下最常见的编译阻断项，生成代码必须全部规避：
+
+| # | 禁止项 | 错误码/规则 | 正确替代方式 |
+|---|--------|------------|------------|
+| 1 | `any` / `unknown` 类型 | `arkts-no-any-unknown` | 使用具体类型或泛型 `T` |
+| 2 | `ESObject` / `Object` 通用类型 | `arkts-no-esobj` | 使用 `interface` 或具体类型 |
+| 3 | 动态属性访问 `obj['key']` | `arkts-no-dynamic-property` | `obj.key` 类型安全访问 |
+| 4 | 未类型化对象字面量 `let o = {}` | `arkts-no-untyped-obj-literals` | 先声明 class/interface 再赋值 |
+| 5 | 内联匿名对象类型参数 | `arkts-no-obj-literals-as-types` | 定义命名 `interface` |
+| 6 | `prototype` 扩展 | `arkts-no-prototype-assignment` | 类继承或组合 |
+| 7 | `delete` 操作符 | `arkts-no-delete` | 将属性设为 `undefined` 或重构数据结构 |
+| 8 | `arguments` 对象 | `arkts-no-arguments` | 使用展开参数 `...args: T[]` |
+| 9 | 双重类型转换 `as unknown as T` | `arkts-no-unsafe-cast` | 定义正确的类型，单次合法转型 |
+| 10 | `for...in` 遍历 | `arkts-no-for-in` | `Object.keys()` + `for...of` / `forEach` |
+| 11 | `eval()` / `new Function()` | `arkts-no-eval` | 禁止使用，无合法替代 |
+| 12 | catch 块直接 `throw e` | `arkts-limited-throw` | `throw e instanceof Error ? e : new Error(String(e))` |
+| 13 | 结构型类型（鸭子类型）匹配 | `arkts-no-structural-typing` | 显式 `extends` / `implements` |
+| 14 | 函数类型不一致赋值 | `arkts-strict-function-types` | 参数/返回值类型完全一致 |
+| 15 | 泛型函数非箭头定义 | `arkts-no-functional-constructors` | 使用 `function` 声明或箭头函数 |
+| 16 | `Object.assign` 修改对象布局 | `arkts-no-object-assign` | 逐属性赋值（类型已声明） |
+| 17 | 运行时修改 class 布局 | `arkts-no-runtime-change-layout` | 类型声明保持静态 |
+| 18 | `Symbol()` API | `arkts-no-symbol` | 不使用 Symbol |
+| 19 | `as any` / 类型断言到 any | `arkts-no-any` | 明确的目标类型断言 |
+| 20 | `void` 返回值以外使用 `undefined` 检查歧义 | — | 显式 `T \| undefined` |
+
+> 完整规则见官方文档 [从 TypeScript 到 ArkTS 的适配规则](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/typescript-to-arkts-migration-guide)。
+
+---
+
+## 二、高频错误正误对照
+
+### 2.1 类型安全（规则 1/2/4/5）
+
+```typescript
+// ❌ 错误：any + 未类型化字面量
+function parse(json: string): any {
+  return JSON.parse(json);
+}
+let config = { timeout: 5000, retries: 3 };
+
+// ✅ 正确：显式类型
+interface Config {
+  timeout: number;
+  retries: number;
+}
+function parseConfig(json: string): Config {
+  return JSON.parse(json) as Config;  // 单次断言到具体类型是允许的
+}
+const config: Config = { timeout: 5000, retries: 3 };
+```
+
+### 2.2 catch 重抛（规则 12，最高频报错之一）
+
+```typescript
+// ❌ 错误：e 为 unknown，直接 throw 违反 arkts-limited-throw
+try {
+  await doWork();
+} catch (e) {
+  throw e;
+}
+
+// ✅ 正确：确保抛出 Error 实例
+try {
+  await doWork();
+} catch (e) {
+  throw e instanceof Error ? e : new Error(String(e));
+}
+```
+
+### 2.3 对象字面量必须对应显式类型（规则 4/5）
+
+```typescript
+// ❌ 错误：内联匿名类型 + 裸字面量
+function fetchData(url: string, cb: (resp: { code: number }) => void): void {}
+let resp = { code: 200 };
+
+// ✅ 正确：命名 interface
+interface Response {
+  code: number;
+}
+function fetchData(url: string, cb: (resp: Response) => void): void {}
+const resp: Response = { code: 200 };
+```
+
+### 2.4 结构型类型禁用（规则 13）
+
+```typescript
+// ❌ 错误：鸭子类型赋值（字段相同也不能赋值）
+interface A { x: number }
+class B { x: number = 1 }
+const a: A = new B();  // 编译报错 arkts-no-structural-typing
+
+// ✅ 正确：显式实现
+class C implements A { x: number = 1 }
+const a2: A = new C();
+```
+
+### 2.5 遍历（规则 10）
+
+```typescript
+// ❌ 错误
+for (const key in obj) { console.log(key); }
+
+// ✅ 正确
+const keys: string[] = Object.keys(obj);
+for (const key of keys) {
+  console.log(key);
+}
+```
+
+---
+
+## 三、类型系统约束
+
+| 约束 | 说明 |
+|------|------|
+| 显式类型标注 | 所有变量、参数、返回值建议显式标注；字面量初始化可省略 |
+| 联合类型 | `string \| null` 合法；禁止用 `any` 模拟联合 |
+| 泛型 | 完整支持；优先泛型而非 any/Object 传参 |
+| 字面量联合 | `mode: 'sync' \| 'async'` 合法，简单场景优先于枚举 |
+| 可选属性 | `timeout?: number` 合法；访问时用 `?.` 或显式判空 |
+| Record 类型 | `Record<string, string>` 用于键值对场景 |
+| 函数类型 | 箭头函数与 function 声明均可；回调参数类型必须显式 |
+
+---
+
+## 四、命名与格式规范（华为 ArkTS 编程规范）
+
+### 4.1 命名约定
+
+| 元素 | 风格 | 示例 |
+|------|------|------|
+| 类 / 接口 / 枚举 / struct / 装饰器类 | PascalCase | `HttpClient`、`RetryPolicy`、`LoadState` |
+| 方法 / 变量 / 参数 | camelCase | `sendRequest`、`maxRetries` |
+| 常量 | UPPER_SNAKE_CASE | `const MAX_SIZE: number = 1024` |
+| 枚举成员 | UPPER_SNAKE_CASE 或 PascalCase（全工程统一） | `enum Status { IDLE, RUNNING }` |
+| 布尔变量/方法 | is/has/can 前缀 | `isValid`、`hasData` |
+| 私有成员 | `private` 修饰符（不加 `_` 前缀） | `private count: number` |
+| 文件名 | PascalCase.ets | `HttpClient.ets`、`Index.ets` |
+
+### 4.2 代码格式
+
+- 缩进 **2 空格**，禁止 Tab
+- 语句行尾**分号**（`.ets` 源文件中必写）
+- 单行长度建议 ≤ 120 字符
+- 单文件 ≤ 400 行，超出按职责拆分
+- import 顺序：`@ohos.*` / `@kit.*` → 第三方库 → 相对路径模块
+
+### 4.3 注释规范
+
+- 公共接口必须有 JSDoc：功能、`@param`、`@returns`
+- 复杂逻辑块行内注释说明"为什么"而非"是什么"
+- 禁止提交注释掉的死代码
+
+```typescript
+/**
+ * 重试策略配置
+ */
+export interface RetryPolicy {
+  /** 最大重试次数，默认 3 */
+  maxRetries: number;
+  /** 重试间隔基数（毫秒），按指数退避递增 */
+  baseIntervalMs: number;
+}
+
+/**
+ * 按指数退避执行重试
+ * @param fn - 要执行的异步操作
+ * @param policy - 重试策略
+ * @returns 操作结果
+ */
+async function withRetry<T>(fn: () => Promise<T>, policy: RetryPolicy): Promise<T> {
+  // ...实现
+}
+```
+
+---
+
+## 五、日志规范
+
+### 5.1 初始化
+
+```typescript
+import hilog from '@ohos.hilog';
+
+// 域值 0x0000~0xFFFF，按模块分配
+const DOMAIN: number = 0x0001;
+// 标签 ≤ 31 字符，格式：模块名_功能名
+const TAG: string = 'MyApp_HttpClient';
+```
+
+### 5.2 级别使用
+
+| 级别 | 场景 |
+|------|------|
+| `debug` | 方法进出、中间状态（禁止用于高频循环） |
+| `info` | 关键流程节点、状态变更、操作成功 |
+| `warn` | 可恢复异常、参数降级处理 |
+| `error` | 操作失败、异常捕获 |
+
+### 5.3 隐私保护（强制）
+
+```typescript
+// ✅ 敏感数据使用 %{private}s
+hilog.info(DOMAIN, TAG, 'login, account: %{private}s', account);
+
+// ❌ 禁止密码/Token/手机号使用 %{public}s
+```
+
+---
+
+## 六、ArkUI 声明式 UI 约束
+
+| 约束 | 说明 |
+|------|------|
+| 状态变量必须加装饰器 | `@State` / `@Prop` / `@Link` / `@Provide` / `@Consume` 等 |
+| 组件内状态修改触发刷新 | 只能通过状态变量驱动 UI，禁止命令式操作 |
+| build() 内禁止修改状态 | 只做声明；状态修改放事件回调和生命周期 |
+| 尺寸单位 | 布局用 `vp`、字体用 `fp`，禁止硬编码 px 假设 |
+| 资源引用 | `$r('app.string.xxx')`；string 避免硬编码 |
+| 条件渲染 | `if/else` 分支中组件结构须完整闭合 |
+| 列表性能 | 大数据量列表用 `LazyForEach` + `IDataSource` |
+
+---
+
+## 七、依赖与导入约束
+
+- `@ohos.*` 模块导入：`import http from '@ohos.net.http';`
+- Kit 聚合导入（优先）：`import { http } from '@kit.NetworkKit';`
+- 相对导入必须带文件名（无扩展名）：`import { Config } from './Config';`
+- import 路径大小写敏感（macOS 不敏感、构建机 Linux 敏感，必须按实际文件名大小写书写）
+- 三方依赖通过 `oh-package.json5` 声明，`ohpm install` 安装，禁止直接引用未声明依赖