@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +1,400 @@
+# 示例：ohos-blur-kit Demo 代码生成
+
+本文档展示使用 `arkts-library-demo-code` 技能，基于 `ohos-blur-kit` 库的测试 Demo 描述文档，生成实际 ArkTS 页面代码的完整示例。
+
+---
+
+## 输入：Demo 描述文档片段（来自 ohos-arkts-demo-doc-generator）
+
+| 序号 | 测试 Demo 名称 | 对应函数接口 |
+|-----|--------------|------------|
+| 1 | 环境检测与配置创建 Demo | `isSupported(): boolean`、`createBlurConfig(radius, mode): BlurConfig` |
+| 2 | BlurManager 生命周期管理 Demo | `new BlurManager(radius)`、`setRadius()`、`getRadius()`、`release()` |
+
+---
+
+## 输出示例一：Demo 01 页面代码
+
+**文件路径**：`entry/src/main/ets/pages/001_CheckSupportAndConfigPage.ets`
+
+```typescript
+/**
+ * Demo 001: Check Support And Config
+ *
+ * 功能说明：展示如何在使用 BlurManager 前检测当前设备是否支持模糊能力，
+ *           以及如何通过 createBlurConfig() 创建合法的模糊配置对象。
+ * 对应接口：isSupported(): boolean
+ *           createBlurConfig(radius: number, mode: BlurMode): BlurConfig
+ *
+ */
+
+import hilog from '@ohos.hilog';
+import { isSupported, createBlurConfig, BlurMode, BlurConfig } from '@ohos/blur-kit';
+
+// ─── 日志常量 ──────────────────────────────────────────────────────────────
+const DOMAIN: number = 0xD001;
+const TAG: string = 'BlurKit_CheckSupportPage';
+
+// ─── 类型定义 ──────────────────────────────────────────────────────────────
+
+/** 模糊模式选项，与 UI 选择器绑定 */
+interface BlurModeOption {
+  label: string;
+  value: BlurMode;
+}
+
+const BLUR_MODE_OPTIONS: BlurModeOption[] = [
+  { label: 'Gaussian', value: BlurMode.GAUSSIAN },
+  { label: 'Stack',    value: BlurMode.STACK },
+  { label: 'Box',      value: BlurMode.BOX },
+];
+
+/**
+ * CheckSupportAndConfigPage - 环境检测与配置创建示例
+ *
+ * 展示 ohos-blur-kit 的设备能力检测和配置对象创建流程。
+ */
+@Entry
+@Component
+struct CheckSupportAndConfigPage {
+  // ─── 状态变量 ────────────────────────────────────────────────────────────
+  @State private supportStatus: string = '未检测';
+  @State private isSupported: boolean = false;
+  @State private selectedMode: BlurMode = BlurMode.GAUSSIAN;
+  @State private radiusInputVal: string = '15';
+  @State private configResult: string = '';
+  @State private isCheckLoading: boolean = false;
+  @State private isConfigLoading: boolean = false;
+
+  aboutToAppear(): void {
+    hilog.info(DOMAIN, TAG, 'CheckSupportAndConfigPage appeared');
+  }
+
+  aboutToDisappear(): void {
+    hilog.info(DOMAIN, TAG, 'CheckSupportAndConfigPage disappeared');
+  }
+
+  // ─── 核心功能方法 ─────────────────────────────────────────────────────────
+
+  /**
+   * 检测当前设备是否支持模糊功能。
+   * 调用 isSupported() 并将结果显示在页面上。
+   */
+  private async checkDeviceSupport(): Promise<void> {
+    hilog.debug(DOMAIN, TAG, 'checkDeviceSupport called');
+    this.isCheckLoading = true;
+    try {
+      // ✅ 验证点 1: isSupported() 返回布尔值，页面显示支持/不支持状态
+      const supported: boolean = isSupported();
+      this.isSupported = supported;
+      this.supportStatus = supported ? '当前设备支持模糊 ✅' : '当前设备不支持模糊 ❌';
+      hilog.info(DOMAIN, TAG, 'Device blur support: %{public}s', String(supported));
+    } catch (err) {
+      const msg: string = (err as Error).message ?? String(err);
+      hilog.error(DOMAIN, TAG, 'checkDeviceSupport failed: %{public}s', msg);
+      this.supportStatus = `检测失败：${msg}`;
+    } finally {
+      this.isCheckLoading = false;
+    }
+  }
+
+  /**
+   * 根据当前选择的 BlurMode 和输入的 radius 创建 BlurConfig 对象。
+   * 调用 createBlurConfig(radius, mode) 并将结果 JSON 展示在页面上。
+   */
+  private async createConfig(): Promise<void> {
+    hilog.debug(DOMAIN, TAG, 'createConfig called, mode: %{public}s, radius: %{public}s',
+                this.selectedMode, this.radiusInputVal);
+    this.isConfigLoading = true;
+    try {
+      const radius: number = Number(this.radiusInputVal);
+      if (isNaN(radius) || radius <= 0) {
+        this.configResult = '错误：radius 必须为正数';
+        hilog.warn(DOMAIN, TAG, 'Invalid radius input: %{public}s', this.radiusInputVal);
+        return;
+      }
+
+      // ✅ 验证点 2: createBlurConfig() 返回 BlurConfig 对象，页面格式化展示
+      const config: BlurConfig = createBlurConfig(radius, this.selectedMode);
+      this.configResult = JSON.stringify({
+        radius: config.radius,
+        mode: config.mode,
+        quality: config.quality ?? '(默认)'
+      }, null, 2);
+      hilog.info(DOMAIN, TAG, 'BlurConfig created successfully, radius: %{public}d, mode: %{public}s',
+                 config.radius, config.mode);
+    } catch (err) {
+      const msg: string = (err as Error).message ?? String(err);
+      hilog.error(DOMAIN, TAG, 'createConfig failed: %{public}s', msg);
+      this.configResult = `错误：${msg}`;
+    } finally {
+      this.isConfigLoading = false;
+    }
+  }
+
+  // ─── UI 构建 ──────────────────────────────────────────────────────────────
+
+  build() {
+    Scroll() {
+      Column({ space: 16 }) {
+        // 页面标题（通过 $r() 引用国际化字符串，禁止硬编码）
+        Text($r('app.string.demo_001_title'))
+          .fontSize(20)
+          .fontWeight(FontWeight.Bold)
+          .width('100%')
+          .textAlign(TextAlign.Center)
+          .padding({ top: 16 })
+
+        Divider()
+
+        // ── 区块一：设备支持检测 ──────────────────────────────
+        Text($r('app.string.demo_001_check_section_label'))
+          .fontSize(16).fontWeight(FontWeight.Medium)
+
+        Text(this.supportStatus)
+          .fontSize(14)
+          .fontColor(this.isSupported ? '#2E7D32' : '#C62828')
+          .padding(8)
+
+        Button($r('app.string.demo_001_check_btn'))
+          .width('100%')
+          .onClick(() => this.checkDeviceSupport())
+          .enabled(!this.isCheckLoading)
+
+        if (this.isCheckLoading) {
+          LoadingProgress().width(32).height(32)
+        }
+
+        Divider()
+
+        // ── 区块二：创建模糊配置 ──────────────────────────────
+        Text($r('app.string.demo_001_create_config_section_label'))
+          .fontSize(16).fontWeight(FontWeight.Medium)
+
+        // Radius 输入框（placeholder 为辅助提示，动态内容可不经 $r()）
+        Row({ space: 8 }) {
+          Text($r('app.string.demo_001_radius_label')).fontSize(14).width(60)
+          TextInput({ placeholder: '> 0', text: this.radiusInputVal })
+            .type(InputType.Number)
+            .layoutWeight(1)
+            .onChange((val: string) => { this.radiusInputVal = val; })
+        }.width('100%')
+
+        // BlurMode 选择
+        Row({ space: 8 }) {
+          Text($r('app.string.demo_001_mode_label')).fontSize(14).width(60)
+          Select(BLUR_MODE_OPTIONS.map(o => ({ value: o.label })))
+            .selected(0)
+            .onSelect((idx: number) => {
+              this.selectedMode = BLUR_MODE_OPTIONS[idx].value;
+              hilog.debug(DOMAIN, TAG, 'BlurMode selected: %{public}s', BLUR_MODE_OPTIONS[idx].label);
+            })
+            .layoutWeight(1)
+        }.width('100%')
+
+        Button($r('app.string.demo_001_create_config_btn'))
+          .width('100%')
+          .onClick(() => this.createConfig())
+          .enabled(!this.isConfigLoading)
+
+        if (this.isConfigLoading) {
+          LoadingProgress().width(32).height(32)
+        }
+
+        // 结果展示（this.configResult 为运行时动态文本，无需 $r()）
+        if (this.configResult.length > 0) {
+          Text($r('app.string.demo_001_config_result_label'))
+            .fontSize(14)
+            .fontWeight(FontWeight.Medium)
+          Text(this.configResult)
+            .fontSize(13)
+            .fontFamily('monospace')
+            .width('100%')
+            .padding(12)
+            .backgroundColor('#F5F5F5')
+            .borderRadius(8)
+        }
+      }
+      .width('100%')
+      .padding(16)
+    }
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+---
+
+## 输出示例二：主导航页面代码
+
+**文件路径**：`entry/src/main/ets/pages/DemoIndex.ets`
+
+```typescript
+/**
+ * ohos-blur-kit Demo 主导航页面
+ *
+ * 提供所有 Demo 的入口列表，通过 router.pushUrl 跳转到各 Demo 页面。
+ */
+
+import hilog from '@ohos.hilog';
+
+const DOMAIN: number = 0xD001;
+const TAG: string = 'BlurKit_DemoIndex';
+
+// ✅ title/description 必须声明为 Resource，由 $r() 赋值，禁止直接写字符串字面量
+interface DemoEntry {
+  id: string;
+  title: Resource;       // 通过 $r('app.string.demo_NNN_title') 引用
+  description: Resource; // 通过 $r('app.string.demo_NNN_index_desc') 引用
+  route: string;
+}
+
+const DEMO_LIST: DemoEntry[] = [
+  {
+    id: '001',
+    title: $r('app.string.demo_001_title'),
+    description: $r('app.string.demo_001_index_desc'),
+    route: 'pages/001_CheckSupportAndConfigPage'   // 无子目录
+  },
+  {
+    id: '002',
+    title: $r('app.string.demo_002_title'),
+    description: $r('app.string.demo_002_index_desc'),
+    route: 'pages/002_BlurManagerLifecyclePage'
+  },
+  {
+    id: '003',
+    title: $r('app.string.demo_003_title'),
+    description: $r('app.string.demo_003_index_desc'),
+    route: 'pages/003_SyncBlurImagePage'
+  },
+  {
+    id: '004',
+    title: $r('app.string.demo_004_title'),
+    description: $r('app.string.demo_004_index_desc'),
+    route: 'pages/004_AsyncBlurImagePage'
+  },
+];
+
+@Entry
+@Component
+struct DemoIndex {
+  aboutToAppear(): void {
+    hilog.info(DOMAIN, TAG, 'DemoIndex appeared, total demos: %{public}d', DEMO_LIST.length);
+  }
+
+  build() {
+    Column() {
+      Text($r('app.string.demo_index_title'))
+        .fontSize(22)
+        .fontWeight(FontWeight.Bold)
+        .width('100%')
+        .textAlign(TextAlign.Center)
+        .padding({ top: 24, bottom: 8 })
+
+      // 动态计数文本：运行时数据，无需 $r()
+      Text(`共 ${DEMO_LIST.length} 个 Demo`)
+        .fontSize(14)
+        .fontColor('#666666')
+        .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
+  DemoCard(demo: DemoEntry): void {
+    Row({ space: 12 }) {
+      // 序号标签
+      Text(demo.id)
+        .fontSize(14)
+        .fontWeight(FontWeight.Bold)
+        .fontColor(Color.White)
+        .width(40)
+        .height(40)
+        .textAlign(TextAlign.Center)
+        .backgroundColor('#1976D2')
+        .borderRadius(20)
+
+      // 标题和描述
+      Column({ space: 4 }) {
+        Text(demo.title)
+          .fontSize(15)
+          .fontWeight(FontWeight.Medium)
+        Text(demo.description)
+          .fontSize(12)
+          .fontColor('#888888')
+          .maxLines(2)
+          .textOverflow({ overflow: TextOverflow.Ellipsis })
+      }
+      .layoutWeight(1)
+      .alignItems(HorizontalAlign.Start)
+    }
+    .width('100%')
+    .padding(12)
+    .backgroundColor(Color.White)
+    .borderRadius(10)
+    .onClick(() => {
+      hilog.info(DOMAIN, TAG, 'Navigate to demo %{public}s: %{public}s', demo.id, demo.route);
+      this.getUIContext().getRouter().pushUrl({ url: demo.route }).catch((err: Error) => {
+        hilog.error(DOMAIN, TAG, 'Navigation to %{public}s failed: %{public}s',
+                    demo.id, err.message);
+      });
+    })
+  }
+}
+```
+
+---
+
+## 对应的 main_pages.json 更新
+
+```json
+{
+  "src": [
+    "pages/DemoIndex",
+    "pages/001_CheckSupportAndConfigPage",
+    "pages/002_BlurManagerLifecyclePage",
+    "pages/003_SyncBlurImagePage",
+    "pages/004_AsyncBlurImagePage"
+  ]
+}
+```
+
+## 对应的字符串资源（zh_CN/element/string.json 追加片段）
+
+```json
+{ "name": "demo_index_title", "value": "ohos-blur-kit 功能演示" },
+{ "name": "demo_001_title", "value": "【001】环境检测与配置创建" },
+{ "name": "demo_001_check_section_label", "value": "1. 设备支持检测" },
+{ "name": "demo_001_check_btn", "value": "检测设备支持" },
+{ "name": "demo_001_create_config_section_label", "value": "2. 创建模糊配置" },
+{ "name": "demo_001_radius_label", "value": "Radius:" },
+{ "name": "demo_001_mode_label", "value": "Mode:" },
+{ "name": "demo_001_create_config_btn", "value": "创建 BlurConfig" },
+{ "name": "demo_001_config_result_label", "value": "BlurConfig 对象：" },
+{ "name": "demo_001_index_desc", "value": "检测设备模糊能力，创建 BlurConfig 配置对象" },
+{ "name": "demo_002_title", "value": "【002】BlurManager 生命周期管理" },
+{ "name": "demo_002_index_desc", "value": "创建、配置、释放 BlurManager 实例" },
+{ "name": "demo_003_title", "value": "【003】同步图像模糊处理" },
+{ "name": "demo_003_index_desc", "value": "blurSync() 对 PixelMap 同步模糊处理" },
+{ "name": "demo_004_title", "value": "【004】异步图像模糊处理" },
+{ "name": "demo_004_index_desc", "value": "blur() 对 PixelMap 异步模糊处理" }
+```
+
+> 同名键须在 **三个** 资源文件中同步添加：`base/element/string.json`（默认值，建议与 zh_CN 相同）、`en_US/element/string.json`（英文 Title Case，键名完全一致）。

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

@@ -0,0 +1,99 @@
+# 系统 API 检索指南（SYSTEM_API_LOOKUP）
+
+> 编写 ArkTS Demo 代码时，查证 HarmonyOS 系统 API（`@kit.*` / `@ohos.*` / `@hms.*`）的权威途径。
+> 通过 MCP 工具 `script_deveco_docs` 调用，语料为 HarmonyOS 官方 API 参考文档（本地离线）。
+
+---
+
+## 1. 检索工具 `script_deveco_docs`
+
+> 由 MCP Gateway 的 `MCP/scripts/deveco_docs.js` 脚本提供，封装 `devecocli docs`，**内置降噪排序与小节精确定位**。opencode 通过 MCP 协议自动发现并主动调用，无需手动执行 shell 命令。
+
+### 1.1 参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `action` | string | 是 | `search`（检索）\| `read`（读取文档） |
+| `keywords` | string | search 必填 | 检索关键词，多个用空格分隔（如 `"ImageFit"`、`"BorderStyle"`） |
+| `catalog` | string | 否 | 文档类别，默认 `harmonyos-references`（API 参考） |
+| `limit` | number | 否 | 返回条数上限，默认 10 |
+| `documentId` | string | read 必填 | 文档 ID（来自 search 结果的 `documentId` 字段） |
+| `section` | string | read 可选 | 按小节名精确定位（如 `ImageFit`），返回该小节而非全文 |
+
+### 1.2 调用示例
+
+> 工具实际名称以 MCP 工具列表为准（opencode 中可能带 server 前缀，实际为 `mcp-gateway_script_deveco_docs`）。下述以无前缀名 `script_deveco_docs` 说明。
+
+```
+工具: script_deveco_docs
+参数: { "action": "search", "keywords": "ImageFit", "catalog": "harmonyos-references", "limit": 8 }
+
+工具: script_deveco_docs
+参数: { "action": "read", "documentId": "API参考/.../ts-appendix-enums", "section": "ImageFit" }
+```
+
+### 1.3 返回结构
+
+**search** 返回 `{ tool, action, query, total, results: [{ title, documentId, sectionTitle, snippet }] }`，结果已按标题相关性从高到低排序（命中 title > 命中 sectionTitle > 内容匹配）。
+
+**read** 返回 `{ tool, action, documentId, section, contentLength, content }`；提供 `section` 时 `content` 仅含该小节（如单个枚举定义），否则为全文（截断保护 20000 字符）。
+
+### 1.4 环境依赖
+
+- `devecocli` 需已全局安装（`npm install -g @deveco/deveco-cli`）
+- 脚本自动定位 `@deveco/deveco-cli/dist/cli.js` 并用 node 直接运行，规避 Windows 下 `.cmd` 的中文编码问题（documentId 含中文时也可正常 read）
+- 可用 `DEVECO_CLI_PATH` 环境变量显式指定 cli.js 路径
+- 若 MCP Gateway 已启动（`hotReload: true`），脚本放入 `MCP/scripts/` 后自动注册，无需重启
+
+---
+
+## 2. 常用系统 API 速查
+
+Demo 页面代码中高频出现的系统 API 依赖及其典型 import 路径（以 `script_deveco_docs` 检索结果为准，下表为常见形态）：
+
+| 系统 API | 典型 import | 用途 | 检索关键词 |
+|---------|------------|------|-----------|
+| `hilog` | `import { hilog } from '@kit.PerformanceAnalysisKit'` | 日志输出 | `hilog` |
+| `router`（页面路由） | `import { router } from '@kit.ArkUI'` | 页面跳转 | `router` |
+| `common.UIAbilityContext` | `import { common } from '@kit.AbilityKit'` | 应用上下文 | `UIAbilityContext` |
+| `common.Context` | `import { common } from '@kit.AbilityKit'` | 通用上下文 | `common Context` |
+| `abilityAccessCtrl` | `import { abilityAccessCtrl } from '@kit.AbilityKit'` | 动态权限申请 | `abilityAccessCtrl` |
+| `ImageFit` | ArkUI 全局枚举，无需 import | 图片填充效果 | `ImageFit` |
+| `BorderStyle` | ArkUI 全局枚举 | 边框样式 | `BorderStyle` |
+| `FontWeight` | ArkUI 全局枚举 | 字体粗细 | `FontWeight` |
+| `TextAlign` | ArkUI 全局枚举 | 文本对齐 | `TextAlign` |
+| `TextOverflow` | ArkUI 全局枚举 | 文本溢出处理 | `TextOverflow` |
+| `TextDecorationType` | ArkUI 全局枚举 | 文本装饰线 | `TextDecorationType` |
+| 被测库自身 API | —（非系统 API） | 库功能调用 | **不在系统语料，不检索** |
+
+> ⚠️ **检索边界**：**被测库自身 API** 不在 HarmonyOS 系统 API 语料中，`script_deveco_docs` 会返回"未找到相关文档"。这类 API 直接按接口规格文档/库源码编写，不要检索。
+
+---
+
+## 3. 降噪策略
+
+`devecocli docs search` 原生返回含噪声（如搜 `ImageFit` 会命中 `ImageParticleParameters`、`RichEditorImageSpanStyleResult` 等含 "Image" 的无关文档）。`script_deveco_docs` 已内置以下降噪手段：
+
+1. **相关性排序**：命中结果 `title` 的排在 `sectionTitle` 命中之前，多关键词全命中优先
+2. **取第一条**：排序后第一条通常即目标；若首条 `title`/`sectionTitle` 与目标不符，逐条检查 `sectionTitle` 匹配项
+3. **`--catalog harmonyos-references`**：限定在 API 参考语料内检索（默认），排除 FAQ/指南/最佳实践等非签名文档
+4. **多关键词组合**：用"模块名 + 接口名"（如 `TextOverflow` 在 `ts-universal-attributes` 下）可显著提升精确度
+
+---
+
+## 4. 大文档精确定位
+
+- 聚合文档（`Enums`、`Types`、`公共定义` 等）可达数十 KB（如 `ts-appendix-enums` 47 KB）
+- **read 必须带 `section=<目标名>`**：脚本会从文档中定位 `#### <section>` 小节并只返回该小节（如 `ImageFit` 枚举定义约 2 KB），避免浪费 token
+- 若 `section` 未命中（返回 `section: null`），再考虑全文读取或换关键词
+
+---
+
+## 5. 常见问题
+
+| 问题 | 原因 | 处理 |
+|------|------|------|
+| `search` 返回空 | API 不是系统 API（库自身 API）、或关键词不准确 | 按接口规格文档/库源码编写，不检索 |
+| `read` 提示 Document not found | documentId 被截断或路径不完整 | 从最新 `search` 结果的 `documentId` 完整复制 |
+| `search` 结果第一条不相关 | 关键词过泛 | 用"模块名 + 接口名"多关键词重试 |
+| 工具不可用（tools 列表无 `script_deveco_docs`） | MCP Gateway 未重启 | 重启 opencode / 检查 `MCP/scripts/` 脚本存在且带 `@tool` 注释 |