@ohos-cpf/3rdloop 0.0.2 → 0.0.4

package/vendor/Server/Skills/arkts-library-demo-scenario/SKILL.md

@@ -1,321 +1,321 @@
----
-name: arkts-library-demo-scenario
-description: 基于覆盖率报告，为未覆盖接口生成 ArkTS 测试 Demo 描述文档。读取覆盖率报告中的未覆盖接口清单（含签名和功能描述），以接口为单位生成测试 Demo 描述（名称、描述、步骤、预期结果），并以表格形式汇总输出。允许将存在直接调用关系或属于同一功能模块的接口合并到同一个 Demo 中。当需要对鸿蒙原生库进行 Demo 覆盖率缺口填补、未覆盖接口场景规划时调用。
-license: Apache-2.0
-metadata:
-  version: "1.0.0"
-  category: harmonyos-development
-  language: ArkTS/ETS
----
-
-# 鸿蒙ArkTs原生库未覆盖接口 Demo 场景生成
-
-本 Skill 读取覆盖率报告中的未覆盖接口清单，以接口为单位自动生成测试 Demo 描述，输出为标准 Markdown 表格文档，使接口覆盖率达到 100%。
-
-> ⚠️ **核心约束**：
-> 1. 只生成覆盖率报告"未覆盖接口清单"中列出的接口场景
-> 2. 所有内容必须基于覆盖率报告中真实存在的接口签名和功能描述
-> 3. 严禁捏造不存在的接口、参数或行为
-
----
-
-## 文档模式选择
-
-**选择规则（按顺序判断）：**
-
-1. **统计未覆盖接口数量和 Demo 预估数量**
-2. **判断模式**：若未覆盖接口 ≤ 25 个 **且** Demo ≤ 8 个 → 使用单文档模式
-3. **否则** → 使用多文档拆分模式
-
-| 模式 | 文件命名 | 适用条件 |
-|-----|---------|---------|
-| 单文档 | `{库名}未覆盖接口Demo场景.md` | 未覆盖接口 ≤ 25 个且 Demo ≤ 8 个 |
-| 多文档拆分 | `{库名}未覆盖接口Demo场景（一）{模块主题}.md`、`（二）...` | 接口 > 25 个或 Demo > 8 个 |
-
-> ⚠️ **多文档模式注意**：Demo 序号和接口覆盖矩阵序号在所有文档间保持全局连续。
-
-## 核心约束概览
-
-| 约束类别 | 关键规则 |
-|---------|---------|
-| **内容真实性** | 所有内容必须基于覆盖率报告中真实存在的接口签名和功能描述，严禁凭空捏造 |
-| **接口覆盖** | 每个未覆盖接口必须被至少一个 Demo 覆盖，补充后覆盖率达到 100% |
-| **Demo 分组** | 存在直接调用关系或属于同一功能模块的接口可合并；不同功能方向、无调用关系的接口禁止强行合并 |
-| **可验证性** | 每个按钮/步骤必须对应至少一条设备可观测的预期结果；依赖平台事件且已知不触发的接口改为平台限制说明 |
-| **ArkUI 响应式** | 计数器、状态标志变量必须声明为 `@State`；异步回调链须规划双计数器 |
-| **命名规范** | Demo 名称格式：`[功能动词][操作对象][特征/场景]Demo`，不超过 20 字 |
-| **输出格式** | 步骤和预期结果为编号列表；接口签名格式：`` `函数名(参数类型): 返回类型` `` |
-
----
-
-## 适用场景
-
-- 为已 ohos 化鸿蒙原生库填补 Demo 覆盖率缺口
-- 生成开发者可直接参考的测试 Demo 描述文档
-- 为 QA / 开发团队提供可执行的 Demo 实现指导
-- 配合 ArkTsLibraryInterfaceSpecSkill + ArkTsLibraryDemoCoverageSkill 实现"接口分析 → 覆盖率分析 → 缺口场景规划"完整链路
-
----
-
-## 任务参数
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `coverageReportPath` | ✅ | 覆盖率报告绝对路径（由 ArkTsLibraryDemoCoverageSkill 生成，含未覆盖接口清单及签名） |
-| `sourcePath` | 可选 | 源码根目录（提供后可探查现有 demo 风格作为参考） |
-| `outputDir` | 可选 | 输出目录，默认放置在覆盖率报告所在目录 |
-
-### 输入异常处理
-
-| 异常情况 | 处理方式 |
-|---------|---------|
-| 覆盖率报告不存在或无法读取 | 停止执行，向用户提示错误并请求提供有效文档路径 |
-| 覆盖率报告格式异常（非 Markdown 或无法解析） | 停止执行，向用户说明问题并请求提供正确格式的文档 |
-| 未覆盖接口清单为空（覆盖率 100%） | 生成空场景文档，标注"所有接口已覆盖，无需补充" |
-| 无法确定库名称 | 使用默认命名 `Unknown未覆盖接口Demo场景.md`，并向用户说明情况 |
-
----
-
----
-
-## 工作流程
-
-### 阶段一：读取覆盖率报告并提取未覆盖接口
-
-#### 1.1 读取覆盖率报告
-
-```
-执行步骤：
-1. 使用 read_file 读取 {{coverageReportPath}} 全文
-2. 提取库名称（用于输出文件命名）
-3. 提取当前覆盖率（用于概述中标注补充前后对比）
-```
-
-#### 1.2 提取未覆盖接口清单
-
-定位覆盖率报告「## 5. 未覆盖接口清单」章节，提取每个未覆盖接口：
-
-| 提取字段 | 来源列 | 用途 |
-|---------|--------|------|
-| 接口名称 | `方法/属性` 列 | Demo 命名和步骤描述 |
-| 完整签名 | `签名` 列 | 步骤中标注精确调用方式 |
-| 接口类型 | `类型` 列 | 确定调用方式（method/property/field） |
-| 功能描述 | `功能描述` 列 | Demo 描述和预期结果的依据 |
-| 所属类 | `### {ClassName}` 子标题 | 分组依据 |
-
-覆盖率报告本身已按类分组，同一类下的未覆盖接口天然属于同一功能模块。
-
-> ⚠️ **低价值常量跳过规则（强制）**：覆盖率报告已过滤 `public static readonly` 常量（`lowValue === true`）与类型别名（`kind === 'type'`），这些不会出现在未覆盖清单中。若覆盖率报告的「基本信息」章节标注了「过滤低价值常量 > 0」，说明库含纯常量类（如 `BleMsg`、`BluetoothGattCharacteristic`），**禁止为这些类规划独立的"常量展示页"Demo**。常量无行为逻辑、无运行时回归价值，仅作 `import` 引用即可，不纳入 Demo 覆盖目标。
-
-#### 1.3 建立未覆盖接口能力清单（内部工作记录）
-
-```
-未覆盖接口清单示例（不写入输出文件）：
-┌─────────────────────────────────────────────────────┐
-│ 类 ImageKnife                                        │
-│   - 方法 preload(loadSrc: ...): ImageKnifeRequest   │
-│     功能: 图片预加载                                  │
-│   - 方法 cancel(request: ImageKnifeRequest)          │
-│     功能: 取消预加载请求                               │
-│ 类 ImageKnifeOption                                  │
-│   - 属性 onlyRetrieveFromCache: boolean              │
-│     功能: 仅从缓存加载图片                              │
-│ ...                                                  │
-│                                                      │
-│ 未覆盖接口总数: N                                     │
-│ 当前覆盖率: X%                                       │
-│ 补充后预期覆盖率: 100%                                │
-└─────────────────────────────────────────────────────┘
-```
-
----
-
-### 阶段二：生成测试 Demo 描述
-
-#### 2.1 Demo 分组原则
-
-**原则一：一接口至少一个 Demo**
-每个未覆盖接口必须被至少一个 Demo 覆盖。
-
-**原则二：关联接口可合并**
-满足以下任一条件的接口可合并到同一 Demo：
-- 存在明确的调用依赖关系（如 `init()` → `execute()` → `destroy()`）
-- 共同完成一个完整的业务场景（如"创建 → 配置 → 执行 → 获取结果"）
-- 属于同一主题功能簇（如所有图像处理相关方法）
-- 一个接口的输出是另一个接口的输入
-
-**原则三：禁止无关合并**
-不同功能方向、无调用关系的接口不得强行合并到同一 Demo。
-
-#### 2.2 Demo 描述要素
-
-每个测试 Demo 包含以下五个要素：
-
-**① 测试 Demo 名称**
-- 以功能描述为基础简要命名
-- 命名格式：`[功能动词][操作对象][特征/场景]Demo`
-- 示例：`图片模糊处理Demo`、`配置初始化与销毁Demo`、`异步任务执行Demo`
-
-**② 测试 Demo 描述**
-- 对该 Demo 的功能和目的进行详细描述
-- 说明该 Demo 展示了哪些接口能力
-- 说明开发者通过该 Demo 能理解什么
-
-**③ 测试 Demo 步骤**
-- 以 Demo 页面为载体，列出具体可执行步骤
-- 步骤需包含：页面构建、UI 交互操作、接口调用时机、结果展示方式
-- 示例格式：
-  ```
-  1. 创建 Demo 页面，添加 [操作按钮] 和 [结果展示区域]
-  2. 点击按钮触发 xxx() 调用，传入参数 ...
-  3. 在结果区域展示返回值 / 状态变化
-  4. 验证 ...
-  ```
-
-**④ 测试 Demo 预期结果**
-- 列出验证该 Demo 是否成功的具体可观测指标
-- 包括：UI 展示内容、返回值格式、状态变化、无异常崩溃等
-
-**⑤ 对应函数接口**
-- 列出该 Demo 涉及的所有未覆盖接口的完整签名
-- 签名来源于覆盖率报告的"签名"列
-- 格式：`` `函数名(参数类型): 返回类型` ``
-
-> ⚠️ **可验证性前置规则（强制）**：在为任何接口编写步骤和预期结果之前，必须先判断：**该接口在目标设备上能否产生可被用户观测到的输出？**
->
-> | 情况 | 处理方式 |
-> |-----|----------|
-> | 接口有直接返回值、状态变更或 UI 更新 | 正常作为主步骤，预期结果描述可观测指标 |
-> | 接口依赖平台事件回调，且该事件在测试设备上已知不触发 | **禁止**作为主步骤；在 Demo 步骤中标注「平台限制」，建议通过 `dispatchXxx` 桥接方法间接验证 |
-> | 接口无任何可观测输出（无返回值、无回调、无 UI 变更） | 合并到相关流程 Demo 中，通过其他接口的状态变化间接验证 |
->
-> **禁止「死按钮」**：Demo 中每个按钮（每个步骤中调用的接口）必须对应至少一条 UI 上可观测的预期结果。若无法提供，该按钮/步骤必须删除或改为平台限制说明。
->
-> 🎯 **ArkUI `@State` 强制规则**：Demo 步骤中包含「计数器（如回调次数、调用次数）」或「状态标志（如是否已初始化）」等运行时变化量时，在步骤或预期结果描述中必须注明：**该变量须声明为 `@State`**，否则 ArkUI 不会触发重渲染，计数器将始终显示初始值（如永远显示 0），导致 Demo 验证逻辑完全失效。
-
-#### 2.3 生成策略
-
-按以下优先级顺序生成 Demo：
-
-1. **核心功能 Demo**（P0）：覆盖库最主要的功能接口，每个核心功能至少一个 Demo
-2. **完整流程 Demo**（P1）：展示"初始化 → 核心操作 → 销毁"完整生命周期
-3. **参数变体 Demo**（P2）：对同一接口的不同参数组合进行展示（可选）
-4. **组合能力 Demo**（P1）：将相关联接口合并，展示完整使用链路
-
-#### 2.4 异步回调链双计数器诊断模式（强制）
-
-对任何 Demo 中涉及「调用库函数 → 等待回调」的异步链路，**必须**在 Demo 设计中规划双计数器：
-
-| 计数器位置 | 变量名建议 | 含义 |
-|-----------|----------|------|
-| 调用/分发前（在触发代码中） | `xxxDispatchCount` | 调用/触发动作的执行次数 |
-| 回调内部（在 `onXxx` 回调方法中） | `xxxCallbackCount` | 回调实际被触发的次数 |
-
-两个计数器都必须在 Demo 页面的**验证区域**中展示（Text 组件），且**必须声明为 `@State`**。
-
-诊断规则：
-- `dispatchCount > 0` 且 `callbackCount = 0` → 调用成功但回调未触发，问题在回调注册或平台事件链
-- `dispatchCount = 0` → 触发代码未执行，问题在 Demo 的触发逻辑
-- `dispatchCount = callbackCount > 0` → 链路完全正常
-
----
-
-### 阶段三：生成输出文档
-
-#### 3.1 文档拆分执行
-
-根据"文档模式选择"部分的规则已确定输出模式，执行以下步骤：
-
-**多文档拆分原则（仅在多文档模式下执行）：**
-
-1. **按功能模块拆分**：每个文档对应一个或几个功能内聚的模块
-2. **全局连续编号（强制）**：Demo 序号和接口覆盖矩阵序号在所有文档中保持全局唯一且连续
-3. **每个文档独立完整**：每个拆分文档都包含完整的"概述 → Demo 总览 → 测试 Demo 描述列表 → 接口覆盖矩阵"结构
-4. **概述中标注分册信息**：注明当前文档是第几部分、覆盖哪些模块，以及其他部分的文件名
-
-#### 3.2 输出文件结构
-
-**单文档模式文件名**：`{库名}未覆盖接口Demo场景.md`（与覆盖率报告同目录）
-
-**多文档模式文件名**：`{库名}未覆盖接口Demo场景（{中文数字}）{模块主题}.md`
-
-**文档结构（每个文档均遵循）：**
-
-```markdown
-# {库名} 未覆盖接口 Demo 场景[（{分册编号}）{模块主题}]
-
-## 概述
-
-简要说明本文档基于覆盖率报告（{覆盖率报告文件名}，当前覆盖率 {X}%）生成，
-规划 {N} 个未覆盖接口的 Demo 场景，补充后覆盖率达到 100%。
-[多文档模式] 注明：本文档为第 X 部分，共 Y 部分，覆盖 {模块名} 模块。
-
-## Demo 总览
-
-| Demo 数量 | 覆盖接口数量 | 补充前覆盖率 | 补充后覆盖率 | 生成日期 |
-|----------|------------|------------|------------|---------|
-| N 个      | M 个        | {X}%       | 100%        | YYYY-MM-DD |
-
-## 测试 Demo 描述列表
-
-| 序号 | 测试 Demo 名称 | 测试 Demo 描述 | 测试 Demo 步骤 | 测试 Demo 预期结果 | 对应函数接口 |
-|-----|--------------|--------------|--------------|-----------------|------------|
-| {全局起始序号} | ... | ... | ... | ... | ... |
-
-## 接口覆盖矩阵
-
-| 序号 | 接口签名 | 接口类型 | 所在 Demo | 覆盖状态 |
-|-----|---------|---------|----------|---------|
-| {全局起始序号} | `{签名}` | {类型} | {Demo名称} | ✅ 已规划Demo |
-```
-
-#### 3.3 表格内容规范
-
-- **序号**：全局自增整数，单文档模式从 1 开始；多文档模式保持全局唯一且连续
-- **测试 Demo 名称**：简洁明了，不超过 20 字
-- **测试 Demo 描述**：2-4 句话，说明功能、目的和覆盖接口
-- **测试 Demo 步骤**：编号列表，每步骤一行，具体可执行，含接口调用位置
-- **测试 Demo 预期结果**：编号列表，具体可验证的观测指标
-- **对应函数接口**：列出所有相关接口的完整签名（来自覆盖率报告"签名"列）
-
-#### 3.4 步骤写作规范
-
-步骤描述必须以"Demo 页面"为视角，包含以下维度：
-
-```
-- 页面构建：构建什么样的页面（按钮、输入框、展示区）
-- 交互触发：点击什么触发哪个接口调用
-- 参数传递：传入什么参数
-- 结果展示：如何在页面上展示接口返回结果
-- 验证方式：如何判断接口行为符合预期
-```
-
----
-
-### 阶段四：质量校验
-
-生成文档前完成以下检查：
-
-| 检查项 | 标准 |
-|-------|------|
-| 接口覆盖完整性 | 覆盖率报告中每个未覆盖接口至少被一个 Demo 覆盖，补充后覆盖率达到 100% |
-| 内容真实性 | 所有接口签名、功能描述与覆盖率报告严格一致 |
-| 步骤可执行性 | 步骤描述足够具体，开发者可按步骤实现 |
-| 预期结果可验证 | 每条预期结果可观测、可判断 |
-| 无死按钮 | Demo 中每个可触发接口调用的按钮都有设备可观测的预期结果 |
-| @State 完整性 | 所有计数器、状态标志变量都注明须声明为 `@State`；异步回调链已规划双计数器 |
-| Demo 名称清晰 | 名称能准确反映 Demo 的核心目的 |
-| 无遗漏未覆盖接口 | 接口覆盖矩阵中所有未覆盖接口均已标记「✅ 已规划Demo」 |
-
----
-
-## 注意事项
-
-1. **只覆盖未覆盖接口**：严格对照覆盖率报告中的"未覆盖接口清单"，不重复设计已有 demo 覆盖的接口
-2. **签名准确**：涉及的功能点中接口签名必须与覆盖率报告"签名"列完全一致，不自行推断参数
-3. **场景可执行**：每个 Demo 的步骤描述必须能转化为可运行的 ArkTS 代码
-4. **合并合理**：存在明确调用依赖关系的接口可合并到一个场景；不同功能方向的接口必须独立场景
-5. **Native 跳过**：`lib*.so` 导出的 Native 模块接口不纳入场景生成范围
-6. **常量类不规划独立 Demo**：纯常量类（如 `BleMsg`、`BluetoothGattCharacteristic` 等 `public static readonly` 常量集合）已被覆盖率报告过滤，禁止为其规划"常量展示页"Demo。常量无行为逻辑、无运行时回归价值，开发者通过 `import` 引用即可，不纳入 Demo 覆盖目标
-7. **覆盖率报告自包含**：覆盖率报告的未覆盖清单已包含签名和功能描述，无需额外读取接口规格文档
-8. **输出目录默认**：若未指定 `outputDir`，输出至覆盖率报告所在目录
+---
+name: arkts-library-demo-scenario
+description: 基于覆盖率报告，为未覆盖接口生成 ArkTS 测试 Demo 描述文档。读取覆盖率报告中的未覆盖接口清单（含签名和功能描述），以接口为单位生成测试 Demo 描述（名称、描述、步骤、预期结果），并以表格形式汇总输出。允许将存在直接调用关系或属于同一功能模块的接口合并到同一个 Demo 中。当需要对鸿蒙原生库进行 Demo 覆盖率缺口填补、未覆盖接口场景规划时调用。
+license: Apache-2.0
+metadata:
+  version: "1.0.0"
+  category: harmonyos-development
+  language: ArkTS/ETS
+---
+
+# 鸿蒙ArkTs原生库未覆盖接口 Demo 场景生成
+
+本 Skill 读取覆盖率报告中的未覆盖接口清单，以接口为单位自动生成测试 Demo 描述，输出为标准 Markdown 表格文档，使接口覆盖率达到 100%。
+
+> ⚠️ **核心约束**：
+> 1. 只生成覆盖率报告"未覆盖接口清单"中列出的接口场景
+> 2. 所有内容必须基于覆盖率报告中真实存在的接口签名和功能描述
+> 3. 严禁捏造不存在的接口、参数或行为
+
+---
+
+## 文档模式选择
+
+**选择规则（按顺序判断）：**
+
+1. **统计未覆盖接口数量和 Demo 预估数量**
+2. **判断模式**：若未覆盖接口 ≤ 25 个 **且** Demo ≤ 8 个 → 使用单文档模式
+3. **否则** → 使用多文档拆分模式
+
+| 模式 | 文件命名 | 适用条件 |
+|-----|---------|---------|
+| 单文档 | `{库名}未覆盖接口Demo场景.md` | 未覆盖接口 ≤ 25 个且 Demo ≤ 8 个 |
+| 多文档拆分 | `{库名}未覆盖接口Demo场景（一）{模块主题}.md`、`（二）...` | 接口 > 25 个或 Demo > 8 个 |
+
+> ⚠️ **多文档模式注意**：Demo 序号和接口覆盖矩阵序号在所有文档间保持全局连续。
+
+## 核心约束概览
+
+| 约束类别 | 关键规则 |
+|---------|---------|
+| **内容真实性** | 所有内容必须基于覆盖率报告中真实存在的接口签名和功能描述，严禁凭空捏造 |
+| **接口覆盖** | 每个未覆盖接口必须被至少一个 Demo 覆盖，补充后覆盖率达到 100% |
+| **Demo 分组** | 存在直接调用关系或属于同一功能模块的接口可合并；不同功能方向、无调用关系的接口禁止强行合并 |
+| **可验证性** | 每个按钮/步骤必须对应至少一条设备可观测的预期结果；依赖平台事件且已知不触发的接口改为平台限制说明 |
+| **ArkUI 响应式** | 计数器、状态标志变量必须声明为 `@State`；异步回调链须规划双计数器 |
+| **命名规范** | Demo 名称格式：`[功能动词][操作对象][特征/场景]Demo`，不超过 20 字 |
+| **输出格式** | 步骤和预期结果为编号列表；接口签名格式：`` `函数名(参数类型): 返回类型` `` |
+
+---
+
+## 适用场景
+
+- 为已 ohos 化鸿蒙原生库填补 Demo 覆盖率缺口
+- 生成开发者可直接参考的测试 Demo 描述文档
+- 为 QA / 开发团队提供可执行的 Demo 实现指导
+- 配合 ArkTsLibraryInterfaceSpecSkill + ArkTsLibraryDemoCoverageSkill 实现"接口分析 → 覆盖率分析 → 缺口场景规划"完整链路
+
+---
+
+## 任务参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `coverageReportPath` | ✅ | 覆盖率报告绝对路径（由 ArkTsLibraryDemoCoverageSkill 生成，含未覆盖接口清单及签名） |
+| `sourcePath` | 可选 | 源码根目录（提供后可探查现有 demo 风格作为参考） |
+| `outputDir` | 可选 | 输出目录，默认放置在覆盖率报告所在目录 |
+
+### 输入异常处理
+
+| 异常情况 | 处理方式 |
+|---------|---------|
+| 覆盖率报告不存在或无法读取 | 停止执行，向用户提示错误并请求提供有效文档路径 |
+| 覆盖率报告格式异常（非 Markdown 或无法解析） | 停止执行，向用户说明问题并请求提供正确格式的文档 |
+| 未覆盖接口清单为空（覆盖率 100%） | 生成空场景文档，标注"所有接口已覆盖，无需补充" |
+| 无法确定库名称 | 使用默认命名 `Unknown未覆盖接口Demo场景.md`，并向用户说明情况 |
+
+---
+
+---
+
+## 工作流程
+
+### 阶段一：读取覆盖率报告并提取未覆盖接口
+
+#### 1.1 读取覆盖率报告
+
+```
+执行步骤：
+1. 使用 read_file 读取 {{coverageReportPath}} 全文
+2. 提取库名称（用于输出文件命名）
+3. 提取当前覆盖率（用于概述中标注补充前后对比）
+```
+
+#### 1.2 提取未覆盖接口清单
+
+定位覆盖率报告「## 5. 未覆盖接口清单」章节，提取每个未覆盖接口：
+
+| 提取字段 | 来源列 | 用途 |
+|---------|--------|------|
+| 接口名称 | `方法/属性` 列 | Demo 命名和步骤描述 |
+| 完整签名 | `签名` 列 | 步骤中标注精确调用方式 |
+| 接口类型 | `类型` 列 | 确定调用方式（method/property/field） |
+| 功能描述 | `功能描述` 列 | Demo 描述和预期结果的依据 |
+| 所属类 | `### {ClassName}` 子标题 | 分组依据 |
+
+覆盖率报告本身已按类分组，同一类下的未覆盖接口天然属于同一功能模块。
+
+> ⚠️ **低价值常量跳过规则（强制）**：覆盖率报告已过滤 `public static readonly` 常量（`lowValue === true`）与类型别名（`kind === 'type'`），这些不会出现在未覆盖清单中。若覆盖率报告的「基本信息」章节标注了「过滤低价值常量 > 0」，说明库含纯常量类（如 `BleMsg`、`BluetoothGattCharacteristic`），**禁止为这些类规划独立的"常量展示页"Demo**。常量无行为逻辑、无运行时回归价值，仅作 `import` 引用即可，不纳入 Demo 覆盖目标。
+
+#### 1.3 建立未覆盖接口能力清单（内部工作记录）
+
+```
+未覆盖接口清单示例（不写入输出文件）：
+┌─────────────────────────────────────────────────────┐
+│ 类 ImageKnife                                        │
+│   - 方法 preload(loadSrc: ...): ImageKnifeRequest   │
+│     功能: 图片预加载                                  │
+│   - 方法 cancel(request: ImageKnifeRequest)          │
+│     功能: 取消预加载请求                               │
+│ 类 ImageKnifeOption                                  │
+│   - 属性 onlyRetrieveFromCache: boolean              │
+│     功能: 仅从缓存加载图片                              │
+│ ...                                                  │
+│                                                      │
+│ 未覆盖接口总数: N                                     │
+│ 当前覆盖率: X%                                       │
+│ 补充后预期覆盖率: 100%                                │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+### 阶段二：生成测试 Demo 描述
+
+#### 2.1 Demo 分组原则
+
+**原则一：一接口至少一个 Demo**
+每个未覆盖接口必须被至少一个 Demo 覆盖。
+
+**原则二：关联接口可合并**
+满足以下任一条件的接口可合并到同一 Demo：
+- 存在明确的调用依赖关系（如 `init()` → `execute()` → `destroy()`）
+- 共同完成一个完整的业务场景（如"创建 → 配置 → 执行 → 获取结果"）
+- 属于同一主题功能簇（如所有图像处理相关方法）
+- 一个接口的输出是另一个接口的输入
+
+**原则三：禁止无关合并**
+不同功能方向、无调用关系的接口不得强行合并到同一 Demo。
+
+#### 2.2 Demo 描述要素
+
+每个测试 Demo 包含以下五个要素：
+
+**① 测试 Demo 名称**
+- 以功能描述为基础简要命名
+- 命名格式：`[功能动词][操作对象][特征/场景]Demo`
+- 示例：`图片模糊处理Demo`、`配置初始化与销毁Demo`、`异步任务执行Demo`
+
+**② 测试 Demo 描述**
+- 对该 Demo 的功能和目的进行详细描述
+- 说明该 Demo 展示了哪些接口能力
+- 说明开发者通过该 Demo 能理解什么
+
+**③ 测试 Demo 步骤**
+- 以 Demo 页面为载体，列出具体可执行步骤
+- 步骤需包含：页面构建、UI 交互操作、接口调用时机、结果展示方式
+- 示例格式：
+  ```
+  1. 创建 Demo 页面，添加 [操作按钮] 和 [结果展示区域]
+  2. 点击按钮触发 xxx() 调用，传入参数 ...
+  3. 在结果区域展示返回值 / 状态变化
+  4. 验证 ...
+  ```
+
+**④ 测试 Demo 预期结果**
+- 列出验证该 Demo 是否成功的具体可观测指标
+- 包括：UI 展示内容、返回值格式、状态变化、无异常崩溃等
+
+**⑤ 对应函数接口**
+- 列出该 Demo 涉及的所有未覆盖接口的完整签名
+- 签名来源于覆盖率报告的"签名"列
+- 格式：`` `函数名(参数类型): 返回类型` ``
+
+> ⚠️ **可验证性前置规则（强制）**：在为任何接口编写步骤和预期结果之前，必须先判断：**该接口在目标设备上能否产生可被用户观测到的输出？**
+>
+> | 情况 | 处理方式 |
+> |-----|----------|
+> | 接口有直接返回值、状态变更或 UI 更新 | 正常作为主步骤，预期结果描述可观测指标 |
+> | 接口依赖平台事件回调，且该事件在测试设备上已知不触发 | **禁止**作为主步骤；在 Demo 步骤中标注「平台限制」，建议通过 `dispatchXxx` 桥接方法间接验证 |
+> | 接口无任何可观测输出（无返回值、无回调、无 UI 变更） | 合并到相关流程 Demo 中，通过其他接口的状态变化间接验证 |
+>
+> **禁止「死按钮」**：Demo 中每个按钮（每个步骤中调用的接口）必须对应至少一条 UI 上可观测的预期结果。若无法提供，该按钮/步骤必须删除或改为平台限制说明。
+>
+> 🎯 **ArkUI `@State` 强制规则**：Demo 步骤中包含「计数器（如回调次数、调用次数）」或「状态标志（如是否已初始化）」等运行时变化量时，在步骤或预期结果描述中必须注明：**该变量须声明为 `@State`**，否则 ArkUI 不会触发重渲染，计数器将始终显示初始值（如永远显示 0），导致 Demo 验证逻辑完全失效。
+
+#### 2.3 生成策略
+
+按以下优先级顺序生成 Demo：
+
+1. **核心功能 Demo**（P0）：覆盖库最主要的功能接口，每个核心功能至少一个 Demo
+2. **完整流程 Demo**（P1）：展示"初始化 → 核心操作 → 销毁"完整生命周期
+3. **参数变体 Demo**（P2）：对同一接口的不同参数组合进行展示（可选）
+4. **组合能力 Demo**（P1）：将相关联接口合并，展示完整使用链路
+
+#### 2.4 异步回调链双计数器诊断模式（强制）
+
+对任何 Demo 中涉及「调用库函数 → 等待回调」的异步链路，**必须**在 Demo 设计中规划双计数器：
+
+| 计数器位置 | 变量名建议 | 含义 |
+|-----------|----------|------|
+| 调用/分发前（在触发代码中） | `xxxDispatchCount` | 调用/触发动作的执行次数 |
+| 回调内部（在 `onXxx` 回调方法中） | `xxxCallbackCount` | 回调实际被触发的次数 |
+
+两个计数器都必须在 Demo 页面的**验证区域**中展示（Text 组件），且**必须声明为 `@State`**。
+
+诊断规则：
+- `dispatchCount > 0` 且 `callbackCount = 0` → 调用成功但回调未触发，问题在回调注册或平台事件链
+- `dispatchCount = 0` → 触发代码未执行，问题在 Demo 的触发逻辑
+- `dispatchCount = callbackCount > 0` → 链路完全正常
+
+---
+
+### 阶段三：生成输出文档
+
+#### 3.1 文档拆分执行
+
+根据"文档模式选择"部分的规则已确定输出模式，执行以下步骤：
+
+**多文档拆分原则（仅在多文档模式下执行）：**
+
+1. **按功能模块拆分**：每个文档对应一个或几个功能内聚的模块
+2. **全局连续编号（强制）**：Demo 序号和接口覆盖矩阵序号在所有文档中保持全局唯一且连续
+3. **每个文档独立完整**：每个拆分文档都包含完整的"概述 → Demo 总览 → 测试 Demo 描述列表 → 接口覆盖矩阵"结构
+4. **概述中标注分册信息**：注明当前文档是第几部分、覆盖哪些模块，以及其他部分的文件名
+
+#### 3.2 输出文件结构
+
+**单文档模式文件名**：`{库名}未覆盖接口Demo场景.md`（与覆盖率报告同目录）
+
+**多文档模式文件名**：`{库名}未覆盖接口Demo场景（{中文数字}）{模块主题}.md`
+
+**文档结构（每个文档均遵循）：**
+
+```markdown
+# {库名} 未覆盖接口 Demo 场景[（{分册编号}）{模块主题}]
+
+## 概述
+
+简要说明本文档基于覆盖率报告（{覆盖率报告文件名}，当前覆盖率 {X}%）生成，
+规划 {N} 个未覆盖接口的 Demo 场景，补充后覆盖率达到 100%。
+[多文档模式] 注明：本文档为第 X 部分，共 Y 部分，覆盖 {模块名} 模块。
+
+## Demo 总览
+
+| Demo 数量 | 覆盖接口数量 | 补充前覆盖率 | 补充后覆盖率 | 生成日期 |
+|----------|------------|------------|------------|---------|
+| N 个      | M 个        | {X}%       | 100%        | YYYY-MM-DD |
+
+## 测试 Demo 描述列表
+
+| 序号 | 测试 Demo 名称 | 测试 Demo 描述 | 测试 Demo 步骤 | 测试 Demo 预期结果 | 对应函数接口 |
+|-----|--------------|--------------|--------------|-----------------|------------|
+| {全局起始序号} | ... | ... | ... | ... | ... |
+
+## 接口覆盖矩阵
+
+| 序号 | 接口签名 | 接口类型 | 所在 Demo | 覆盖状态 |
+|-----|---------|---------|----------|---------|
+| {全局起始序号} | `{签名}` | {类型} | {Demo名称} | ✅ 已规划Demo |
+```
+
+#### 3.3 表格内容规范
+
+- **序号**：全局自增整数，单文档模式从 1 开始；多文档模式保持全局唯一且连续
+- **测试 Demo 名称**：简洁明了，不超过 20 字
+- **测试 Demo 描述**：2-4 句话，说明功能、目的和覆盖接口
+- **测试 Demo 步骤**：编号列表，每步骤一行，具体可执行，含接口调用位置
+- **测试 Demo 预期结果**：编号列表，具体可验证的观测指标
+- **对应函数接口**：列出所有相关接口的完整签名（来自覆盖率报告"签名"列）
+
+#### 3.4 步骤写作规范
+
+步骤描述必须以"Demo 页面"为视角，包含以下维度：
+
+```
+- 页面构建：构建什么样的页面（按钮、输入框、展示区）
+- 交互触发：点击什么触发哪个接口调用
+- 参数传递：传入什么参数
+- 结果展示：如何在页面上展示接口返回结果
+- 验证方式：如何判断接口行为符合预期
+```
+
+---
+
+### 阶段四：质量校验
+
+生成文档前完成以下检查：
+
+| 检查项 | 标准 |
+|-------|------|
+| 接口覆盖完整性 | 覆盖率报告中每个未覆盖接口至少被一个 Demo 覆盖，补充后覆盖率达到 100% |
+| 内容真实性 | 所有接口签名、功能描述与覆盖率报告严格一致 |
+| 步骤可执行性 | 步骤描述足够具体，开发者可按步骤实现 |
+| 预期结果可验证 | 每条预期结果可观测、可判断 |
+| 无死按钮 | Demo 中每个可触发接口调用的按钮都有设备可观测的预期结果 |
+| @State 完整性 | 所有计数器、状态标志变量都注明须声明为 `@State`；异步回调链已规划双计数器 |
+| Demo 名称清晰 | 名称能准确反映 Demo 的核心目的 |
+| 无遗漏未覆盖接口 | 接口覆盖矩阵中所有未覆盖接口均已标记「✅ 已规划Demo」 |
+
+---
+
+## 注意事项
+
+1. **只覆盖未覆盖接口**：严格对照覆盖率报告中的"未覆盖接口清单"，不重复设计已有 demo 覆盖的接口
+2. **签名准确**：涉及的功能点中接口签名必须与覆盖率报告"签名"列完全一致，不自行推断参数
+3. **场景可执行**：每个 Demo 的步骤描述必须能转化为可运行的 ArkTS 代码
+4. **合并合理**：存在明确调用依赖关系的接口可合并到一个场景；不同功能方向的接口必须独立场景
+5. **Native 跳过**：`lib*.so` 导出的 Native 模块接口不纳入场景生成范围
+6. **常量类不规划独立 Demo**：纯常量类（如 `BleMsg`、`BluetoothGattCharacteristic` 等 `public static readonly` 常量集合）已被覆盖率报告过滤，禁止为其规划"常量展示页"Demo。常量无行为逻辑、无运行时回归价值，开发者通过 `import` 引用即可，不纳入 Demo 覆盖目标
+7. **覆盖率报告自包含**：覆盖率报告的未覆盖清单已包含签名和功能描述，无需额外读取接口规格文档
+8. **输出目录默认**：若未指定 `outputDir`，输出至覆盖率报告所在目录