@ohos-cpf/3rdloop 0.0.2 → 0.0.4

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

@@ -1,97 +1,97 @@
----
-name: arkts-library-xts-coverage
-description: 分析鸿蒙ArkTs原生库现有 XTS 测试用例对接口的覆盖情况。通过 analyze-xts-coverage.cjs 脚本一步完成接口提取、覆盖率匹配和 Markdown 报告生成。当需要对鸿蒙ArkTs原生库的 XTS 测试用例进行接口覆盖率分析时调用。
-license: Apache-2.0
-compatibility: 需要Node.js运行环境
-metadata:
-  version: "1.1.0"
-  category: ohos-testing
-  language: ArkTS/ETS
----
-
-# 鸿蒙ArkTs原生库 XTS 接口覆盖率分析
-
-通过 `analyze-xts-coverage.cjs` 脚本一步完成接口提取、XTS 覆盖率匹配和 Markdown 报告生成，无需中间文件。
-
-> ⚠️ **核心约束**：基于静态 import 和接口调用分析，动态调用（`obj[methodName]()`）无法识别。
-
----
-
-## 任务参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `libroot` | string | ✅* | 库源码根目录路径（含 `library/` 和 `entry/src/ohosTest/`） |
-| `spec` | string | ✅* | 已有的 interface-spec.json 路径（与 `libroot` 二选一） |
-| `output` | string | ❌ | 输出 Markdown 报告路径，默认 `03-{库名}-XTS覆盖率报告.md` |
-| `title` | string | ❌ | 报告标题 |
-| `mode` | string | ❌ | 匹配模式: `auto`(默认) \| `ast` \| `regex` |
-| `lib` | string | ❌ | 库名覆盖，默认从 spec 或源码中读取 |
-
-> `libroot` 与 `spec` 至少提供一个。提供 `spec` 时跳过接口提取步骤直接使用；仅提供 `libroot` 时脚本自动从源码提取接口。
-
----
-
-## 执行命令
-
-```bash
-node "{{workspaceRoot}}/MCP/scripts/analyze-xts-coverage.cjs" --libroot "{{libroot}}" [--output "{{output}}"] [--title "{{title}}"] [--mode auto|ast|regex] [--lib "{{库名}}"]
-```
-
-或从已有 interface-spec.json 生成：
-
-```bash
-node "{{workspaceRoot}}/MCP/scripts/analyze-xts-coverage.cjs" --spec "{{spec}}" --libroot "{{libroot}}" [--output "{{output}}"]
-```
-
-其中 `{{workspaceRoot}}` = `3rdLibraryLoop` 工作区根目录。
-
----
-
-## 脚本自动完成
-
-1. 从 `library/` 源码提取接口规格（或读取 `--spec` 指定的 JSON）
-2. 递归扫描 `entry/src/ohosTest/` 下所有 `.ets` 和 `.ts` 测试文件
-3. 提取 `import { ... } from 'lib'` 语句（单行/多行/别名/混合导入，兼容深层路径导入 `@pkg/name/src/main/ets/.../ClassName`）
-4. AST/正则双层匹配：静态方法、实例方法（追踪变量声明）、链式调用、对象字面量属性
-5. 直接渲染输出 Markdown 覆盖率报告
-
----
-
-## 库源码目录结构约定
-
-```
-{{libroot}}/
-  ├── library/                           ← 库源码（Index.ets 入口）
-  │   ├── Index.ets
-  │   ├── src/main/ets/
-  │   └── src/main/cpp/types/.../Index.d.ts   ← Native .so 声明
-  └── entry/src/ohosTest/                ← XTS 测试源码（被分析的目录）
-```
-
----
-
-## 输出
-
-生成 Markdown 报告，包含以下章节：
-- **基本信息**：库名、源文件数、生成时间
-- **覆盖率总览**：方法级覆盖率百分比、S/N/M 统计、进度条
-- **按接口类型统计**：method/property/field/function/variable 分类别覆盖率
-- **类级覆盖率**：按类分组的覆盖明细
-- **未覆盖接口详情**：按类分组的未覆盖接口清单
-- **已覆盖接口详情**：按类分组的已覆盖接口清单（含覆盖来源文件）
-- **文件覆盖详情**：每个 XTS 测试文件覆盖的接口数和接口列表
-
----
-
-## 注意事项
-
-1. **确定性**：所有计数和匹配由脚本完成，同一组输入必定产生相同输出
-2. **子目录排除**：自动排除扫描目录第一层的 `entryability/`、`model/`、`util/` 等子目录
-3. **构造函数和枚举**：已在接口提取阶段排除
-4. **动态调用限制**：`obj[methodName]()` 无法识别
-5. **模式选择**：`auto` 优先 AST 匹配（需 TypeScript 模块），失败时降级正则；`ast` 强制 AST；`regex` 强制正则
-6. **深层路径导入**：测试文件可能通过深层路径导入类（`import { X } from '@ohos/pkg/src/main/ets/.../X'`）而非包名导入，AST/正则匹配引擎与 AST 模块解析均已兼容
-7. **入口文件大小写**：macOS/Windows 大小写不敏感文件系统上库入口文件可能为 `Index.ets` 或 `index.ets`，脚本已做大小写归一；否则模块解析会静默失败，导致类型推断全面失效、实例方法类覆盖率全部为 0
-8. **结果合理性检查**：覆盖率 <5% 且测试代码总量 >500 行时脚本输出告警；此时必须先用 grep 盘点实例方法调用（`变量名.方法名(`）与静态方法调用（`类名.方法名(`）并按类对账，确认无匹配缺陷后再写入正式报告
-9. **`--lib` 慎用**：传入短名（如 `mp3agic`）会覆盖 spec/oh-package.json5 推断的真实包名（`@ohos/mp3agic`），导致 import 匹配条件全部失效；无特殊需要不要覆盖库名
+---
+name: arkts-library-xts-coverage
+description: 分析鸿蒙ArkTs原生库现有 XTS 测试用例对接口的覆盖情况。通过 analyze-xts-coverage.cjs 脚本一步完成接口提取、覆盖率匹配和 Markdown 报告生成。当需要对鸿蒙ArkTs原生库的 XTS 测试用例进行接口覆盖率分析时调用。
+license: Apache-2.0
+compatibility: 需要Node.js运行环境
+metadata:
+  version: "1.1.0"
+  category: ohos-testing
+  language: ArkTS/ETS
+---
+
+# 鸿蒙ArkTs原生库 XTS 接口覆盖率分析
+
+通过 `analyze-xts-coverage.cjs` 脚本一步完成接口提取、XTS 覆盖率匹配和 Markdown 报告生成，无需中间文件。
+
+> ⚠️ **核心约束**：基于静态 import 和接口调用分析，动态调用（`obj[methodName]()`）无法识别。
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `libroot` | string | ✅* | 库源码根目录路径（含 `library/` 和 `entry/src/ohosTest/`） |
+| `spec` | string | ✅* | 已有的 interface-spec.json 路径（与 `libroot` 二选一） |
+| `output` | string | ❌ | 输出 Markdown 报告路径，默认 `03-{库名}-XTS覆盖率报告.md` |
+| `title` | string | ❌ | 报告标题 |
+| `mode` | string | ❌ | 匹配模式: `auto`(默认) \| `ast` \| `regex` |
+| `lib` | string | ❌ | 库名覆盖，默认从 spec 或源码中读取 |
+
+> `libroot` 与 `spec` 至少提供一个。提供 `spec` 时跳过接口提取步骤直接使用；仅提供 `libroot` 时脚本自动从源码提取接口。
+
+---
+
+## 执行命令
+
+```bash
+node "{{workspaceRoot}}/MCP/scripts/analyze-xts-coverage.cjs" --libroot "{{libroot}}" [--output "{{output}}"] [--title "{{title}}"] [--mode auto|ast|regex] [--lib "{{库名}}"]
+```
+
+或从已有 interface-spec.json 生成：
+
+```bash
+node "{{workspaceRoot}}/MCP/scripts/analyze-xts-coverage.cjs" --spec "{{spec}}" --libroot "{{libroot}}" [--output "{{output}}"]
+```
+
+其中 `{{workspaceRoot}}` = `3rdLibraryLoop` 工作区根目录。
+
+---
+
+## 脚本自动完成
+
+1. 从 `library/` 源码提取接口规格（或读取 `--spec` 指定的 JSON）
+2. 递归扫描 `entry/src/ohosTest/` 下所有 `.ets` 和 `.ts` 测试文件
+3. 提取 `import { ... } from 'lib'` 语句（单行/多行/别名/混合导入，兼容深层路径导入 `@pkg/name/src/main/ets/.../ClassName`）
+4. AST/正则双层匹配：静态方法、实例方法（追踪变量声明）、链式调用、对象字面量属性
+5. 直接渲染输出 Markdown 覆盖率报告
+
+---
+
+## 库源码目录结构约定
+
+```
+{{libroot}}/
+  ├── library/                           ← 库源码（Index.ets 入口）
+  │   ├── Index.ets
+  │   ├── src/main/ets/
+  │   └── src/main/cpp/types/.../Index.d.ts   ← Native .so 声明
+  └── entry/src/ohosTest/                ← XTS 测试源码（被分析的目录）
+```
+
+---
+
+## 输出
+
+生成 Markdown 报告，包含以下章节：
+- **基本信息**：库名、源文件数、生成时间
+- **覆盖率总览**：方法级覆盖率百分比、S/N/M 统计、进度条
+- **按接口类型统计**：method/property/field/function/variable 分类别覆盖率
+- **类级覆盖率**：按类分组的覆盖明细
+- **未覆盖接口详情**：按类分组的未覆盖接口清单
+- **已覆盖接口详情**：按类分组的已覆盖接口清单（含覆盖来源文件）
+- **文件覆盖详情**：每个 XTS 测试文件覆盖的接口数和接口列表
+
+---
+
+## 注意事项
+
+1. **确定性**：所有计数和匹配由脚本完成，同一组输入必定产生相同输出
+2. **子目录排除**：自动排除扫描目录第一层的 `entryability/`、`model/`、`util/` 等子目录
+3. **构造函数和枚举**：已在接口提取阶段排除
+4. **动态调用限制**：`obj[methodName]()` 无法识别
+5. **模式选择**：`auto` 优先 AST 匹配（需 TypeScript 模块），失败时降级正则；`ast` 强制 AST；`regex` 强制正则
+6. **深层路径导入**：测试文件可能通过深层路径导入类（`import { X } from '@ohos/pkg/src/main/ets/.../X'`）而非包名导入，AST/正则匹配引擎与 AST 模块解析均已兼容
+7. **入口文件大小写**：macOS/Windows 大小写不敏感文件系统上库入口文件可能为 `Index.ets` 或 `index.ets`，脚本已做大小写归一；否则模块解析会静默失败，导致类型推断全面失效、实例方法类覆盖率全部为 0
+8. **结果合理性检查**：覆盖率 <5% 且测试代码总量 >500 行时脚本输出告警；此时必须先用 grep 盘点实例方法调用（`变量名.方法名(`）与静态方法调用（`类名.方法名(`）并按类对账，确认无匹配缺陷后再写入正式报告
+9. **`--lib` 慎用**：传入短名（如 `mp3agic`）会覆盖 spec/oh-package.json5 推断的真实包名（`@ohos/mp3agic`），导致 import 匹配条件全部失效；无特殊需要不要覆盖库名

package/vendor/Server/Skills/arkts-library-xts-doc/SKILL.md

@@ -1,194 +1,194 @@
----
-name: arkts-library-xts-doc
-description: 基于XTS覆盖率报告，为未覆盖接口自动判断可测试性并生成XTS用例描述文档。仅生成纯函数（无UI操作、可通过执行结果验证）的XTS用例描述，包含用例序号、名称、描述、预期结果、对应函数接口。当需要对鸿蒙原生库进行XTS覆盖率缺口填补、未覆盖接口测试规划时调用。
-license: Apache-2.0
-compatibility: 需要XTS覆盖率报告（由ArkTsLibraryXTSCoverageSkill生成），需要文件写入权限到输出目录
-metadata:
-  version: "1.0.0"
-  category: ohos-testing
-  language: ArkTS/ETS
----
-
-# 鸿蒙ArkTs原生库未覆盖接口XTS用例生成
-
-读取XTS覆盖率报告中的未覆盖接口清单，自动判断接口可测试性，为可测试接口生成标准化XTS用例描述文档，100%覆盖所有未覆盖的可测试接口。
-
-> ⚠️ **核心约束**：
-> 1. 仅生成纯函数的XTS用例描述，不生成需要UI操作、无法通过执行结果验证的用例
-> 2. 所有用例内容基于覆盖率报告中真实存在的接口签名和功能描述，严禁捏造
-> 3. 100%覆盖所有未覆盖的可测试接口
-
----
-
-## 任务参数
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `xtsCoverageReportPath` | string | ✅ | XTS覆盖率报告绝对路径（由ArkTsLibraryXTSCoverageSkill生成，含未覆盖接口清单及签名） |
-| `outputDir` | string | ❌ | 输出目录，默认放置在覆盖率报告所在目录 |
-
-### 输入异常处理
-
-| 异常情况 | 处理方式 |
-|---------|---------|
-| 覆盖率报告不存在或无法读取 | 停止执行，向用户提示错误 |
-| 未覆盖接口清单为空（覆盖率100%） | 生成空文档，标注"所有接口已覆盖，无需补充" |
-| 无法确定库名称 | 使用默认命名 `Unknown未覆盖接口XTS用例描述.md` |
-
----
-
-## 输入依赖
-
-- **前置SKILL**: `arkts-library-xts-coverage`（生成XTS覆盖率报告）
-- **输入文件**: XTS覆盖率报告（`.md`格式，含未覆盖接口清单及签名）
-
----
-
-## 工作流程概览
-
-```
-Phase 1: 读取覆盖率报告并提取未覆盖接口
-    ↓
-Phase 2: 接口可测试性判断
-    ↓
-Phase 3: XTS用例规划（正向+空值+异常+大数据）
-    ↓
-Phase 4: 生成XTS用例描述文档
-    ↓
-Phase 5: 文档验证与输出
-```
-
----
-
-## Phase 1：读取覆盖率报告并提取未覆盖接口
-
-### 1.1 读取覆盖率报告
-
-1. 使用 `read_file` 读取 `xtsCoverageReportPath` 全文
-2. 提取库名称（用于输出文件命名）
-3. 提取当前XTS覆盖率（用于概述中标注补充前后对比）
-
-### 1.2 提取未覆盖接口清单
-
-定位覆盖率报告「未覆盖接口清单」章节，提取每个未覆盖接口：
-
-| 提取字段 | 来源列 | 用途 |
-|---------|--------|------|
-| 接口名称 | `方法/属性` 列 | 用例命名 |
-| 完整签名 | `签名` 列 | 用例预期结果中标注精确调用方式 |
-| 接口类型 | `类型` 列 | 可测试性判断依据 |
-| 功能描述 | `功能描述` 列 | 用例描述的依据 |
-| 所属类 | `### {ClassName}` 子标题 | 分组依据 |
-
-> 覆盖率报告的未覆盖清单用于**索引**（确定要补充的接口及分组）；报告中字段不完整或与规格不一致时，**精确参数类型/返回类型/枚举值一律以 `interface-spec.json` 为权威来源补全**，不得凭报告文本猜测或按函数名推断签名。
-
----
-
-## Phase 2：接口可测试性判断
-
-### 2.1 判断标准（摘要）
-
-- **✅ 可测试**：纯函数、无UI操作、结果可验证、无不可控外部依赖
-- **❌ 不可测试**：涉及UI操作、依赖不可控外部因素、结果不可验证、纯展示型、`private`/`protected` 成员、`public static readonly` 常量
-- **⚠️ 需额外条件**：依赖Mock/异步等待/前置状态的接口，可测但需在用例中标注前提条件
-
-> 完整判断标准、接口类型测试规则、分类示例参见 [可测试性判断指南](references/TESTABILITY_GUIDE.md)
-
-### 2.2 接口分类标记
-
-对每个未覆盖接口进行分类标记：`✅ 可测试`、`❌ 不可测试`、`⚠️ 可测试（需额外条件）`。
-
-对于 `⚠️ 可测试（需额外条件）` 的接口，在用例描述中注明测试前提条件（如需要Mock网络请求）。
-
----
-
-## Phase 3：XTS用例规划
-
-### 3.1 设计原则（摘要）
-
-- 每个可测试接口至少有1个**正向用例**
-- 每个可测试接口至少有1个**空值/null输入用例**
-- 每个可测试接口至少有1个**异常/边界值用例**
-- 集合类型参数接口至少有1个**大数据量用例**
-- 一个用例可包含多个关联接口（展示协同使用方式）
-
-### 3.2 多接口用例设计
-
-将多个接口放在同一用例中的条件：
-- 接口之间存在调用依赖关系（如 `init` → `execute` → `getResult`）
-- 接口协同完成一个完整功能流程（如 `create` → `configure` → `start`）
-- 接口之间存在状态变化关系（如 `setConfig` → `getConfig` 验证）
-
-### 3.3 跨接口综合场景设计
-
-正向/空值/异常/大数据之外，还应设计四类**跨接口综合场景**：
-1. **空值/异常边界综合**：将多个接口的空值、异常、边界输入组合进同一用例，验证错误处理的一致性
-2. **大数据综合**：对集合/字符串类接口的数据处理链路（输入→处理→输出）组合验证
-3. **端到端流程综合**：串联存在调用依赖的接口，模拟真实业务流程（初始化→配置→调用→清理）
-4. **状态机综合**：对存在状态流转的接口按状态顺序验证（未初始化→初始化→运行→停止→销毁）
-
-综合场景优先复用 3.2 中已建立关联的接口组，避免为每个接口单独堆叠低价值用例。
-
-### 3.4 用例编号规则
-
-- 用例序号采用三位补零格式：`001`、`002`、`003`...
-- 序号按模块分组递增，便于管理
-
-> 详细的场景设计规范（空值、异常、大数据、Mock、异步等待）参见 [可测试性判断指南](references/TESTABILITY_GUIDE.md) 和 [用例模板与编写规范](references/TEMPLATE.md)
-
-### 3.5 用例计数约束调和
-
-当下游存在「用例场景数 ≥ 接口覆盖数」的计数约束（即报告要求 `用例数 ≥ 已覆盖接口数`）时：
-- **setter/getter 配对接口不合并为单用例**（每个接口各计 1 条用例），以保证接口数与用例数匹配
-- 或通过 **3.3 跨接口综合场景**补足差额（综合场景一条用例计 1，便于补齐接口数）
-- 若接口数明显大于用例场景容量，优先拆分多接口用例，保证每接口至少 1 条用例
-
----
-
-## Phase 4：生成XTS用例描述文档
-
-### 4.1 文档结构
-
-生成的文档包含以下章节：
-
-1. **概述** — 库名称、生成时间、覆盖率前后对比、用例统计
-2. **接口可测试性分析** — 可测试/不可测试/需额外条件接口列表
-3. **用例索引表** — 全部用例的序号、名称、涉及接口、模块归属
-4. **XTS用例详细描述** — 每个用例的描述、预期结果、对应函数接口
-
-### 4.2 文件命名与存放
-
-```
-文件命名规则：{库名}未覆盖接口XTS用例描述.md
-存放位置：覆盖率报告所在目录（或指定 outputDir）
-```
-
-> 完整文档模板参见 [用例模板与编写规范](references/TEMPLATE.md)
-
----
-
-## Phase 5：文档验证与输出
-
-### 5.1 验证检查项
-
-1. **内容真实性**：所有接口签名、功能描述与覆盖率报告严格一致；报告中签名不完整或可疑时，对照 `interface-spec.json` 校验
-2. **可测试性判断准确性**：不可测试接口未生成用例
-3. **预期输出可验证性**：每个用例的预期输出具体、可验证
-4. **接口关联合理性**：多接口用例的接口间存在明确关联关系
-5. **签名补全校验**：涉及参数类型、返回类型（含 `| null`/`undefined` 联合）、枚举值时，均已按 `interface-spec.json` 的权威签名补全，无沿用报告缺省/简略签名的用例
-
-### 5.2 输出确认
-
-- 文档末尾标注 `状态: 成功` 或 `状态: 失败`
-- 确认可测试接口覆盖率达到100%
-- 每个用例预期结果必须具体、可验证
-
----
-
-## 参考资料
-
-- [可测试性判断指南](references/TESTABILITY_GUIDE.md) — 可测试性判断标准、接口类型测试规则、用例设计原则、空值/异常/大数据场景设计规范
-- [用例模板与编写规范](references/TEMPLATE.md) — 文档整体模板、各类用例模板（正向/多接口/反向/空值）、六段式用例结构规范
-- [完整生成示例](references/EXAMPLES.md) — 基于lodash的完整XTS用例描述生成示例
-
-> **接口签名权威来源**：`interface-spec.json` 的 `signature` 字段可能与同对象的 `returnType` 分叉（历史遗留）。二者冲突时以 `returnType` + `params` 为准（`returnType` 完整保留 `| null` / `undefined` 等联合类型细节）。
+---
+name: arkts-library-xts-doc
+description: 基于XTS覆盖率报告，为未覆盖接口自动判断可测试性并生成XTS用例描述文档。仅生成纯函数（无UI操作、可通过执行结果验证）的XTS用例描述，包含用例序号、名称、描述、预期结果、对应函数接口。当需要对鸿蒙原生库进行XTS覆盖率缺口填补、未覆盖接口测试规划时调用。
+license: Apache-2.0
+compatibility: 需要XTS覆盖率报告（由ArkTsLibraryXTSCoverageSkill生成），需要文件写入权限到输出目录
+metadata:
+  version: "1.0.0"
+  category: ohos-testing
+  language: ArkTS/ETS
+---
+
+# 鸿蒙ArkTs原生库未覆盖接口XTS用例生成
+
+读取XTS覆盖率报告中的未覆盖接口清单，自动判断接口可测试性，为可测试接口生成标准化XTS用例描述文档，100%覆盖所有未覆盖的可测试接口。
+
+> ⚠️ **核心约束**：
+> 1. 仅生成纯函数的XTS用例描述，不生成需要UI操作、无法通过执行结果验证的用例
+> 2. 所有用例内容基于覆盖率报告中真实存在的接口签名和功能描述，严禁捏造
+> 3. 100%覆盖所有未覆盖的可测试接口
+
+---
+
+## 任务参数
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `xtsCoverageReportPath` | string | ✅ | XTS覆盖率报告绝对路径（由ArkTsLibraryXTSCoverageSkill生成，含未覆盖接口清单及签名） |
+| `outputDir` | string | ❌ | 输出目录，默认放置在覆盖率报告所在目录 |
+
+### 输入异常处理
+
+| 异常情况 | 处理方式 |
+|---------|---------|
+| 覆盖率报告不存在或无法读取 | 停止执行，向用户提示错误 |
+| 未覆盖接口清单为空（覆盖率100%） | 生成空文档，标注"所有接口已覆盖，无需补充" |
+| 无法确定库名称 | 使用默认命名 `Unknown未覆盖接口XTS用例描述.md` |
+
+---
+
+## 输入依赖
+
+- **前置SKILL**: `arkts-library-xts-coverage`（生成XTS覆盖率报告）
+- **输入文件**: XTS覆盖率报告（`.md`格式，含未覆盖接口清单及签名）
+
+---
+
+## 工作流程概览
+
+```
+Phase 1: 读取覆盖率报告并提取未覆盖接口
+    ↓
+Phase 2: 接口可测试性判断
+    ↓
+Phase 3: XTS用例规划（正向+空值+异常+大数据）
+    ↓
+Phase 4: 生成XTS用例描述文档
+    ↓
+Phase 5: 文档验证与输出
+```
+
+---
+
+## Phase 1：读取覆盖率报告并提取未覆盖接口
+
+### 1.1 读取覆盖率报告
+
+1. 使用 `read_file` 读取 `xtsCoverageReportPath` 全文
+2. 提取库名称（用于输出文件命名）
+3. 提取当前XTS覆盖率（用于概述中标注补充前后对比）
+
+### 1.2 提取未覆盖接口清单
+
+定位覆盖率报告「未覆盖接口清单」章节，提取每个未覆盖接口：
+
+| 提取字段 | 来源列 | 用途 |
+|---------|--------|------|
+| 接口名称 | `方法/属性` 列 | 用例命名 |
+| 完整签名 | `签名` 列 | 用例预期结果中标注精确调用方式 |
+| 接口类型 | `类型` 列 | 可测试性判断依据 |
+| 功能描述 | `功能描述` 列 | 用例描述的依据 |
+| 所属类 | `### {ClassName}` 子标题 | 分组依据 |
+
+> 覆盖率报告的未覆盖清单用于**索引**（确定要补充的接口及分组）；报告中字段不完整或与规格不一致时，**精确参数类型/返回类型/枚举值一律以 `interface-spec.json` 为权威来源补全**，不得凭报告文本猜测或按函数名推断签名。
+
+---
+
+## Phase 2：接口可测试性判断
+
+### 2.1 判断标准（摘要）
+
+- **✅ 可测试**：纯函数、无UI操作、结果可验证、无不可控外部依赖
+- **❌ 不可测试**：涉及UI操作、依赖不可控外部因素、结果不可验证、纯展示型、`private`/`protected` 成员、`public static readonly` 常量
+- **⚠️ 需额外条件**：依赖Mock/异步等待/前置状态的接口，可测但需在用例中标注前提条件
+
+> 完整判断标准、接口类型测试规则、分类示例参见 [可测试性判断指南](references/TESTABILITY_GUIDE.md)
+
+### 2.2 接口分类标记
+
+对每个未覆盖接口进行分类标记：`✅ 可测试`、`❌ 不可测试`、`⚠️ 可测试（需额外条件）`。
+
+对于 `⚠️ 可测试（需额外条件）` 的接口，在用例描述中注明测试前提条件（如需要Mock网络请求）。
+
+---
+
+## Phase 3：XTS用例规划
+
+### 3.1 设计原则（摘要）
+
+- 每个可测试接口至少有1个**正向用例**
+- 每个可测试接口至少有1个**空值/null输入用例**
+- 每个可测试接口至少有1个**异常/边界值用例**
+- 集合类型参数接口至少有1个**大数据量用例**
+- 一个用例可包含多个关联接口（展示协同使用方式）
+
+### 3.2 多接口用例设计
+
+将多个接口放在同一用例中的条件：
+- 接口之间存在调用依赖关系（如 `init` → `execute` → `getResult`）
+- 接口协同完成一个完整功能流程（如 `create` → `configure` → `start`）
+- 接口之间存在状态变化关系（如 `setConfig` → `getConfig` 验证）
+
+### 3.3 跨接口综合场景设计
+
+正向/空值/异常/大数据之外，还应设计四类**跨接口综合场景**：
+1. **空值/异常边界综合**：将多个接口的空值、异常、边界输入组合进同一用例，验证错误处理的一致性
+2. **大数据综合**：对集合/字符串类接口的数据处理链路（输入→处理→输出）组合验证
+3. **端到端流程综合**：串联存在调用依赖的接口，模拟真实业务流程（初始化→配置→调用→清理）
+4. **状态机综合**：对存在状态流转的接口按状态顺序验证（未初始化→初始化→运行→停止→销毁）
+
+综合场景优先复用 3.2 中已建立关联的接口组，避免为每个接口单独堆叠低价值用例。
+
+### 3.4 用例编号规则
+
+- 用例序号采用三位补零格式：`001`、`002`、`003`...
+- 序号按模块分组递增，便于管理
+
+> 详细的场景设计规范（空值、异常、大数据、Mock、异步等待）参见 [可测试性判断指南](references/TESTABILITY_GUIDE.md) 和 [用例模板与编写规范](references/TEMPLATE.md)
+
+### 3.5 用例计数约束调和
+
+当下游存在「用例场景数 ≥ 接口覆盖数」的计数约束（即报告要求 `用例数 ≥ 已覆盖接口数`）时：
+- **setter/getter 配对接口不合并为单用例**（每个接口各计 1 条用例），以保证接口数与用例数匹配
+- 或通过 **3.3 跨接口综合场景**补足差额（综合场景一条用例计 1，便于补齐接口数）
+- 若接口数明显大于用例场景容量，优先拆分多接口用例，保证每接口至少 1 条用例
+
+---
+
+## Phase 4：生成XTS用例描述文档
+
+### 4.1 文档结构
+
+生成的文档包含以下章节：
+
+1. **概述** — 库名称、生成时间、覆盖率前后对比、用例统计
+2. **接口可测试性分析** — 可测试/不可测试/需额外条件接口列表
+3. **用例索引表** — 全部用例的序号、名称、涉及接口、模块归属
+4. **XTS用例详细描述** — 每个用例的描述、预期结果、对应函数接口
+
+### 4.2 文件命名与存放
+
+```
+文件命名规则：{库名}未覆盖接口XTS用例描述.md
+存放位置：覆盖率报告所在目录（或指定 outputDir）
+```
+
+> 完整文档模板参见 [用例模板与编写规范](references/TEMPLATE.md)
+
+---
+
+## Phase 5：文档验证与输出
+
+### 5.1 验证检查项
+
+1. **内容真实性**：所有接口签名、功能描述与覆盖率报告严格一致；报告中签名不完整或可疑时，对照 `interface-spec.json` 校验
+2. **可测试性判断准确性**：不可测试接口未生成用例
+3. **预期输出可验证性**：每个用例的预期输出具体、可验证
+4. **接口关联合理性**：多接口用例的接口间存在明确关联关系
+5. **签名补全校验**：涉及参数类型、返回类型（含 `| null`/`undefined` 联合）、枚举值时，均已按 `interface-spec.json` 的权威签名补全，无沿用报告缺省/简略签名的用例
+
+### 5.2 输出确认
+
+- 文档末尾标注 `状态: 成功` 或 `状态: 失败`
+- 确认可测试接口覆盖率达到100%
+- 每个用例预期结果必须具体、可验证
+
+---
+
+## 参考资料
+
+- [可测试性判断指南](references/TESTABILITY_GUIDE.md) — 可测试性判断标准、接口类型测试规则、用例设计原则、空值/异常/大数据场景设计规范
+- [用例模板与编写规范](references/TEMPLATE.md) — 文档整体模板、各类用例模板（正向/多接口/反向/空值）、六段式用例结构规范
+- [完整生成示例](references/EXAMPLES.md) — 基于lodash的完整XTS用例描述生成示例
+
+> **接口签名权威来源**：`interface-spec.json` 的 `signature` 字段可能与同对象的 `returnType` 分叉（历史遗留）。二者冲突时以 `returnType` + `params` 为准（`returnType` 完整保留 `| null` / `undefined` 等联合类型细节）。