@ohos-cpf/3rdloop 0.0.1

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

@@ -0,0 +1,174 @@
+---
+name: arkts-library-demo-coverage
+description: 分析鸿蒙ArkTs原生库现有 Demo 对接口的覆盖情况。读取接口规格，扫描 entry/src/main/ets/ 下所有 .ets 文件，通过 AST/正则双层匹配识别已调用的接口，计算接口覆盖率百分比，输出已覆盖和未覆盖接口清单。当需要对鸿蒙原生库进行 demo 接口覆盖率缺口填补、未覆盖接口测试规划时调用。
+license: Apache-2.0
+compatibility: 需要 Node.js 运行环境
+metadata:
+  version: "1.1.0"
+  category: harmonyos-development
+  language: ArkTS/ETS
+  useWhen: 分析鸿蒙原生库 Demo 对接口的覆盖情况
+---
+
+# 鸿蒙ArkTs原生库 Demo 接口覆盖率分析
+
+本 Skill 直接调用本地脚本分析 Demo 源码对库导出接口的覆盖情况，直接输出最终 Markdown 覆盖率报告。
+
+> ⚠️ **核心约束**：基于静态 import 分析，动态调用（`obj[methodName]()`）无法识别，报告中需标注此限制。
+
+---
+## 脚本依赖
+
+本 Skill 直接调用以下本地脚本完成全部分析工作：
+
+```
+3rdLibraryLoop/MCP/scripts/analyze-demo-coverage.cjs
+```
+
+**调用方式**：通过 `node` 命令行直接执行，使用 `--` 参数传参。
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `libroot` | string | ✅ | 库源码根目录绝对路径（包含 `library/` 和 `entry/` 子目录） |
+
+**可选参数**：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `spec` | — | 已有的 `interface-spec.json` 路径（由 `extract-interfaces.cjs` 生成）。提供时从 JSON 读取接口规格；未提供时自动从 `libroot` 源码提取 |
+| `output` | `02-{库名}-Demo覆盖率报告.md` | 输出 Markdown 报告路径 |
+| `mode` | `auto` | 匹配模式：`auto`（AST 优先，降级正则）\| `ast`（强制 AST）\| `regex`（强制正则） |
+| `title` | `{库名} Demo 覆盖率分析报告` | 报告标题 |
+| `lib` | 从 spec/libroot 自动提取 | 库名覆盖 |
+| `src` | `{libroot}/entry/src/main/ets` | Demo 源码目录覆盖 |
+
+**派生变量**：
+- `skillDir`：本 Skill 所在目录
+- `scriptPath`：分析脚本路径 = `{{skillDir}}/../../../MCP/scripts/analyze-demo-coverage.cjs`
+
+---
+
+## 输入依赖
+
+- **前置SKILL**: ArkTsLibraryInterfaceSpecSkill（可选；若提供 `spec` 参数则使用其生成的 JSON，否则脚本自动从源码提取）
+- **输入文件**: 库源码目录（含 `library/` 和 `entry/src/main/ets/`）
+- **输出文件**: Markdown 覆盖率报告（脚本直接生成）
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 运行 analyze-demo-coverage.cjs → Phase 2: 确认报告输出 → Phase 3: 结果合理性校验
+```
+
+> 全程只有一条 `node` 命令，脚本直接输出最终 Markdown 报告，无中间文件，无需清理。
+
+---
+
+## Phase 1：运行 Demo 覆盖率分析脚本
+
+> ⚠️ **脚本一步完成：提取/读取接口规格 + 扫描 Demo 源码 + AST/正则双层匹配 + 生成 Markdown 报告。无中间 JSON 文件。**
+
+运行脚本：
+
+```bash
+node "{{skillDir}}/../../../MCP/scripts/analyze-demo-coverage.cjs" \
+  --libroot "{{libroot}}" \
+  --output "{{outputDir}}/02-{{libName}}-Demo覆盖率报告.md"
+```
+
+其中：
+- `{{skillDir}}` = SKILL.md 所在目录
+- `{{libroot}}` = 库源码根目录（包含 `library/` 和 `entry/` 子目录）
+- `{{outputDir}}` = 输出目录（通常与接口规格文档同目录）
+- 库名从 `oh-package.json5` 或 spec JSON 自动提取，无需 `--lib` 参数
+
+若已有 `interface-spec.json`，可通过 `--spec` 参数传入避免重复提取：
+
+```bash
+node "{{skillDir}}/../../../MCP/scripts/analyze-demo-coverage.cjs" \
+  --libroot "{{libroot}}" \
+  --spec "{{outputDir}}/{{libName}}-interface-spec.json" \
+  --output "{{outputDir}}/02-{{libName}}-Demo覆盖率报告.md"
+```
+
+**脚本自动完成**：
+1. 获取接口规格（从 `spec` JSON 读取，或从 `libroot` 源码自动提取）
+2. 递归扫描 `entry/src/main/ets/` 下的 `.ets` 文件（排除 `entryability/`、`entrybackupability/`、`model/`、`util/`、`ohosTest/` 等非 demo 目录）
+3. 提取 import（单行+多行+默认+混合+别名，兼容尾斜杠与子路径写法）并追踪实例变量
+4. AST 优先匹配（TS Compiler API 语义分析，含库入口文件大小写校准），失败自动降级正则匹配
+5. 匹配方法调用、检测对象字面量属性、默认导入命名空间宽松兜底
+6. **过滤低价值常量与类型声明**（对齐 XTS 覆盖率口径）：跳过 `lowValue === true` 的静态只读常量与 `kind === 'type'` 的类型别名，不计入统计分母，报告中标注过滤数量
+7. **直接生成最终 Markdown 报告**（含覆盖率统计、按类/按类型分组、已覆盖/未覆盖清单、文件覆盖详情、提升建议）
+
+> ⚠️ **Demo 范围界定**：扫描范围默认 `entry/src/main/ets/`，仅指主工程 demo 页面代码。绝不扩展到 `ohosTest/`、`test/`、`tests/`、`__tests__/`、`testability/` 等测试目录。
+
+**退出码处理**：
+- `0` → 成功
+- 其他 → 失败，终止流程并标注 `状态: 失败`
+- 脚本输出的 `⚠️ [警告]/[提示]`（stderr）不改变退出码，但指示结果可信度问题，必须在 Phase 3 处理
+
+---
+
+## Phase 2：确认报告输出
+
+脚本执行完毕后，Markdown 报告已直接生成在 `output` 指定路径（默认为 `02-{库名}-Demo覆盖率报告.md`）。
+
+报告包含以下章节：
+1. **基本信息** — 库名、源文件数、生成时间；若存在过滤，额外标注「过滤低价值常量」「过滤类型声明」「实际统计接口」三项（与 XTS 覆盖率报告口径一致）
+2. **覆盖率总览** — 方法级覆盖率百分比 + 进度条 + S/N/M 统计
+3. **按接口类型统计** — method/property/field/function/variable/enumValue/constructor 分组覆盖率
+4. **类级覆盖率** — 每个类/接口的覆盖统计（按覆盖率升序排列）
+5. **未覆盖接口详情** — 按类分组，含参数、返回类型、说明
+6. **已覆盖接口详情** — 按类分组，含签名和覆盖来源文件
+7. **文件覆盖详情** — 每个 Demo 文件覆盖的接口列表
+8. **覆盖率提升建议** — 按优先级排列的未覆盖接口补充清单
+
+---
+
+## Phase 3：结果合理性校验
+
+> ⚠️ 覆盖率脚本曾有静默失败历史（import 尾斜杠曾导致 0% 误报、入口文件大小写曾导致 ~11 个百分点低估），即使脚本已内置防护，交付前仍须完成本环节校验，禁止直接采信首轮结果。
+
+### 3.1 检查脚本告警
+
+- 控制台出现 `⚠️ [警告]/[提示]/[分析可信度警告]`，或报告头部出现「⚠️ 分析可信度警告」章节时，先按提示排查再采信结果
+- 库模块解析失败时脚本会自动放弃 AST 结果、降级正则模式（控制台有明确提示）。正则模式精度低于 AST，交付时应在报告中注明实际匹配模式
+
+### 3.2 覆盖率异常时交叉验证
+
+覆盖率 < 10% 或为 0%，且 Demo 源码确实存在 `import ... from '<库名>'` 时：
+
+1. **抽样 grep 交叉验证**：对报告中「未覆盖」的接口，在 Demo 源码目录统计真实调用数，与报告比对：
+   ```bash
+   grep -rh "\.方法名(" entry/src/main/ets/ --include="*.ets" | wc -l
+   ```
+2. **快速诊断口诀**："import 有、覆盖无 → 查 import 尾斜杠；部分漏、变量 any → 查入口文件大小写"
+3. **已知历史缺陷与 workaround**（脚本 v1.1 已修复，旧版本脚本仍会触发）：
+   - **import 尾斜杠**：Demo 写 `from '@ohos/xxx/'`（尾部带 `/`）曾被全部静默跳过 → 0% 误报。Workaround：复制 `entry/src/main/ets` 到临时目录，sed 去除尾斜杠后通过 `--src` 指向副本
+   - **入口文件大小写**：仓库入口为小写 `index.ets` 时，macOS（大小写不敏感文件系统）上 AST 模块解析曾静默失败、库类型坍缩为 `any` → 部分接口漏判。Workaround：复制 libroot（排除 .git）将 `library/index.ets` 重命名为 `Index.ets`，`--libroot` 指向副本。Linux（大小写敏感）上症状不同（existsSync 直接失败走降级逻辑），两者同源
+
+### 3.3 统计口径说明
+
+报告默认排除 `entryability/` 等非 Demo 目录（见 Phase 1 扫描范围）。`EntryAbility` 中的库调用（如 `GlobalContext.setValue` 在 `EntryAbility` 中触发）计入「未覆盖」属口径内合理行为，交付报告时应主动注明，避免读者误判为功能缺失。
+
+**低价值常量与类型声明过滤**：脚本自动过滤 `public static readonly` 常量（`lowValue === true`）与类型别名（`kind === 'type'`），不计入覆盖率分母，与 `analyze-xts-coverage.cjs` 口径完全一致。报告「基本信息」章节标注过滤数量与实际统计接口数。下游 Demo 场景规划 SKILL 消费的未覆盖清单中不会出现这些低价值常量，避免为纯常量类生成无意义的「常量展示页」。
+
+---
+
+## 注意事项
+
+核心要点：
+1. **脚本本地调用** — 全部分析工作由 `node` 直接执行 `analyze-demo-coverage.cjs` 一步完成，禁止 AI 手工解析源码或编写报告表格
+2. **AST/正则双模式** — `mode=auto` 时优先使用 TS Compiler API AST 语义分析，TypeScript 模块不可用时自动降级正则匹配
+3. **Demo 范围** — 仅 `entry/src/main/ets/`，测试目录自动排除
+4. **动态调用限制** — `obj[method]()` 无法识别，报告中标注此限制
+5. **无中间文件** — 脚本直接输出最终 Markdown 报告，无需清理
+6. **接口规格来源灵活** — 可通过 `--spec` 参数传入已有 JSON，也可不传 `--spec` 让脚本自动从源码提取
+7. **库名自动提取** — 默认从 `oh-package.json5` 或 spec JSON 读取，无需手工指定
+8. **结果合理性校验** — 覆盖率异常低/为 0 时先做 grep 抽样交叉验证再采信（见 Phase 3）；关注脚本 `⚠️` 告警与报告「分析可信度警告」章节

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

@@ -0,0 +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`，输出至覆盖率报告所在目录

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

@@ -0,0 +1,100 @@
+# 示例：测试 Demo 描述文档
+
+本文档展示使用 `ohos-arkts-demo-doc-generator` 技能针对一个虚构的图像处理鸿蒙原生库（`ohos-blur-kit`）生成的测试 Demo 描述文档示例。
+
+> 📌 注意：以下所有接口均为示范用途，实际生成时应严格依据真实规格文档。
+
+---
+
+## 假设的接口规格文档（输入）
+
+```typescript
+// Index.ets - 导出接口清单
+
+// 图像模糊处理管理类
+export class BlurManager {
+  constructor(radius: number)
+  blur(pixelMap: PixelMap): Promise<PixelMap>
+  blurSync(pixelMap: PixelMap): PixelMap
+  setRadius(radius: number): void
+  getRadius(): number
+  release(): void
+}
+
+// 工具函数
+export function createBlurConfig(radius: number, mode: BlurMode): BlurConfig
+export function isSupported(): boolean
+
+// 枚举
+export enum BlurMode {
+  GAUSSIAN = 'gaussian',
+  STACK = 'stack',
+  BOX = 'box'
+}
+
+// 接口
+export interface BlurConfig {
+  radius: number
+  mode: BlurMode
+  quality?: number
+}
+
+// 常量
+export const VERSION: string
+```
+
+---
+
+## 生成的输出文档示例
+
+以下为技能输出的 `ohos-blur-kit测试demo描述.md` 内容：
+
+---
+
+# ohos-blur-kit 测试 Demo 描述文档
+
+## 概述
+
+本文档基于 `ohos-blur-kit` 库的接口规格说明文档自动生成，提供该库各接口的 ArkTS 测试 Demo 描述，供开发者参考实现功能验证页面。文档按功能相关性对接口进行分组，每组接口对应一个 Demo 页面描述。
+
+## Demo 总览
+
+| Demo 数量 | 覆盖接口数量 | 生成日期 |
+|----------|------------|---------|
+| 4 个      | 8 个        | 2026-03-11 |
+
+## 测试 Demo 描述列表
+
+| 序号 | 测试 Demo 名称 | 测试 Demo 描述 | 测试 Demo 步骤 | 测试 Demo 预期结果 | 对应函数接口 |
+|-----|--------------|--------------|--------------|-----------------|------------|
+| 1 | 环境检测与配置创建 Demo | 展示如何在使用 BlurManager 前检测当前设备是否支持模糊能力，以及如何通过 `createBlurConfig()` 创建合法的模糊配置对象。帮助开发者理解使用前置条件检查和配置初始化的标准流程。 | 1. 创建 Demo 页面，包含"检测支持"按钮、BlurMode 选择器（Gaussian/Stack/Box）、radius 输入框和"创建配置"按钮，以及 JSON 展示区域。<br>2. 点击"检测支持"按钮，调用 `isSupported()`，将返回的布尔值显示在页面上（"当前设备支持模糊 ✅" 或 "当前设备不支持 ❌"）。<br>3. 选择 BlurMode 并输入 radius 值，点击"创建配置"按钮，调用 `createBlurConfig(radius, mode)`。<br>4. 在 JSON 展示区域展示返回的 `BlurConfig` 对象，格式化显示 radius、mode、quality 字段。 | 1. 页面加载完成，按钮与选择器可正常操作。<br>2. 调用 `isSupported()` 返回布尔值，页面相应显示支持/不支持状态。<br>3. 调用 `createBlurConfig()` 后成功返回 `BlurConfig` 对象，页面格式化展示该对象的 radius 和 mode 字段，无抛出异常。 | `isSupported(): boolean`<br>`createBlurConfig(radius: number, mode: BlurMode): BlurConfig` |
+| 2 | BlurManager 生命周期管理 Demo | 展示 `BlurManager` 的完整生命周期：构造（传入 radius）、设置/获取 radius、最终释放资源。帮助开发者理解 BlurManager 对象的创建方式、radius 属性的读写机制，以及释放资源的时机。 | 1. 创建 Demo 页面，包含 radius 输入框、"创建 BlurManager"按钮、新 radius 输入框、"更新 radius"按钮、"获取 radius"按钮和"释放"按钮，以及状态日志区域。<br>2. 填写 radius 值（如 15），点击"创建 BlurManager"，调用 `new BlurManager(15)`，在日志区域显示"BlurManager 已创建，初始 radius=15"。<br>3. 修改 radius 值（如 25），点击"更新 radius"，调用 `setRadius(25)`，日志显示"radius 已更新为 25"。<br>4. 点击"获取 radius"，调用 `getRadius()`，日志显示"当前 radius=25"，验证与上一步设置一致。<br>5. 点击"释放"，调用 `release()`，日志显示"BlurManager 已释放"，此后操作按钮禁用。 | 1. `new BlurManager(radius)` 成功创建实例，无异常。<br>2. `setRadius(newValue)` 调用后，再次 `getRadius()` 返回与设置值一致，验证读写一致性。<br>3. `release()` 调用后页面日志提示释放成功，后续调用不再可用（按钮变灰）。<br>4. 整个生命周期无内存泄漏提示，无崩溃。 | `new BlurManager(radius: number)`<br>`setRadius(radius: number): void`<br>`getRadius(): number`<br>`release(): void` |
+| 3 | 同步图像模糊处理 Demo | 展示使用 `blurSync()` 对 PixelMap 进行同步模糊处理的完整流程，帮助开发者理解同步调用方式、传参规范及处理后图像的获取与展示。 | 1. 创建 Demo 页面，包含"选择图片"按钮（调用图库选择器）、原图展示区域、radius 滑动条、"执行同步模糊"按钮和模糊后图片展示区域。<br>2. 点击"选择图片"，从图库选取一张图片，在原图展示区域预览。<br>3. 拖动 radius 滑动条调整模糊半径（范围 1-50）。<br>4. 点击"执行同步模糊"，创建 `BlurManager(radius)`，调用 `blurSync(pixelMap)`，传入原图 PixelMap。<br>5. 将返回的 PixelMap 在模糊后图片展示区域显示，并在图片下方标注"模糊半径: {radius}"。 | 1. 选图后原图在页面正常预览。<br>2. `blurSync()` 同步返回处理后的 PixelMap，页面立即更新展示模糊后图片。<br>3. 模糊后图片的尺寸（宽高像素数）与原图一致，仅视觉效果有模糊。<br>4. 调整不同 radius 值后重复操作，模糊程度随 radius 增大而加深。<br>5. 无异常抛出，UI 线程无卡顿超过 3 秒的提示。 | `new BlurManager(radius: number)`<br>`blurSync(pixelMap: PixelMap): PixelMap` |
+| 4 | 异步图像模糊处理 Demo | 展示使用 `blur()` 对 PixelMap 进行异步模糊处理的完整流程，以及与同步方式的对比体验。帮助开发者理解 Promise 异步调用方式、await 使用规范，以及如何在 ArkTS 中处理异步返回结果。 | 1. 创建 Demo 页面，包含"选择图片"按钮、原图展示区域、radius 输入框、"执行异步模糊"按钮、Loading 指示器和模糊后图片展示区域。<br>2. 选取一张图片，在原图区域预览。<br>3. 输入 radius 值，点击"执行异步模糊"，按钮变为禁用状态，显示 Loading 指示器。<br>4. 调用 `await blurManager.blur(pixelMap)`，等待 Promise resolve。<br>5. Promise 完成后，隐藏 Loading、启用按钮，将返回的 PixelMap 在结果区域显示，下方标注"异步模糊完成，耗时: {ms}ms"。 | 1. 点击"执行异步模糊"后，按钮立即变为禁用，Loading 指示器显示，表明异步任务已开始。<br>2. `blur()` 返回的 Promise 正常 resolve，Loading 消失，模糊后图片显示在结果区域。<br>3. 模糊后图片尺寸与原图一致，视觉上出现模糊效果。<br>4. UI 线程在等待期间不冻结（可滚动页面或切换其他控件）。<br>5. 页面正确展示异步耗时，无 Promise reject 或未捕获异常。 | `new BlurManager(radius: number)`<br>`blur(pixelMap: PixelMap): Promise<PixelMap>` |
+
+## 接口覆盖矩阵
+
+| 序号 | 接口名称 | 所在 Demo | 覆盖状态 |
+|-----|---------|----------|---------|
+| 1 | `isSupported(): boolean` | 环境检测与配置创建 Demo | ✅ 已覆盖 |
+| 2 | `createBlurConfig(radius, mode): BlurConfig` | 环境检测与配置创建 Demo | ✅ 已覆盖 |
+| 3 | `new BlurManager(radius: number)` | BlurManager 生命周期管理 Demo / 同步模糊 Demo / 异步模糊 Demo | ✅ 已覆盖 |
+| 4 | `setRadius(radius: number): void` | BlurManager 生命周期管理 Demo | ✅ 已覆盖 |
+| 5 | `getRadius(): number` | BlurManager 生命周期管理 Demo | ✅ 已覆盖 |
+| 6 | `release(): void` | BlurManager 生命周期管理 Demo | ✅ 已覆盖 |
+| 7 | `blurSync(pixelMap: PixelMap): PixelMap` | 同步图像模糊处理 Demo | ✅ 已覆盖 |
+| 8 | `blur(pixelMap: PixelMap): Promise<PixelMap>` | 异步图像模糊处理 Demo | ✅ 已覆盖 |
+
+---
+
+## 关键生成规则说明
+
+上述示例展示了以下技能规则的应用：
+
+1. **生命周期合并**：`constructor`、`setRadius`、`getRadius`、`release` 四个接口合并到一个 Demo，因为它们共同描述 `BlurManager` 的完整生命周期管理流程。
+
+2. **前置条件合并**：`isSupported()` 与 `createBlurConfig()` 合并到一个 Demo，因为它们都属于"使用前准备"阶段，且 `createBlurConfig` 的结果可作为构造函数的配置依据。
+
+3. **异步/同步分开**：`blur()` 和 `blurSync()` 虽然功能类似，但因调用方式（异步 vs 同步）差异明显，分别在独立 Demo 中展示，便于开发者对比。
+
+4. **以页面为载体**：每个步骤都明确描述了对应的 UI 组件（按钮、展示区、日志区等）和用户操作，使开发者可直接按步骤实现 Demo 页面。