@ohos-cpf/3rdloop 0.0.2 → 0.0.4

package/vendor/Server/Skills/flutter-library-test-coverage-check/SKILL.md

@@ -1,414 +1,414 @@
----
-name: flutter-library-test-coverage-check
-description: 对 Flutter 三方库进行用例覆盖度检视，**核心聚焦 Dart 公开接口的覆盖程度**。通过 MCP/scripts 共享脚本自动提取接口规格、分析测试覆盖率和 Demo 覆盖率，基于脚本报告采用严苛扣分制生成检视报告（0-100分）。作为 Flutter 仓库检视流程的最后阶段，依赖接口规格说明和文档质量检视结果。
-license: Apache-2.0
-compatibility: 需要 Node.js 运行环境、Git 仓库访问、接口规格说明文档（可选，脚本可直接从源码提取）
-metadata:
-  version: "1.1.0"
----
-
-# FlutterLibraryTestCoverageCheckSkill
-
-对 Flutter 三方库进行用例覆盖度检视，**核心聚焦：测试用例和 demo 示例对 Dart 公开接口的覆盖程度**。通过共享脚本自动完成接口提取和覆盖率分析，基于脚本报告采用严苛扣分制评分。
-
-> ⚠️ **核心定位**：Flutter 三方库对外导出的接口是 **Dart 层定义的**（位于 `lib/` 目录），本 SKILL 聚焦于测试用例和 demo 对这些 **Dart 公开接口**的覆盖程度。接口提取和覆盖率分析由 `MCP/scripts/` 目录下的三个 Node.js 共享脚本自动完成（本 SKILL 通过相对路径引用，不保存脚本副本），检视者基于脚本报告进行评分和深度分析。
-
----
-
-## 任务参数
-
-| 参数 | 必需 | 说明 |
-|------|------|------|
-| `repoUrl` | ✅ | Git 仓库地址，支持分支 `?branch=xxx` |
-| `outputDir` | ✅ | 输出目录绝对路径，存放检视报告和脚本产出 |
-| `interfaceDocPath` | ❌ | 接口规格说明文档路径（如已有则作为参考，脚本可直接从源码提取） |
-| `repoName` | ✅ | 仓库名称（用于报告标识） |
-
----
-
-## 输入依赖
-
-本 SKILL 是 Flutter 仓库检视流程的**最后阶段**，依赖：
-
-- **前置 SKILL**: `library-interface-analyzer`（接口规格说明，可选 — 脚本可直接从源码提取）
-- **前置 SKILL**: `flutter-library-documentation-quality-check`（文档质量检视报告）
-- **输入文件**: `接口规格说明.md`（可选）、`文档质量检视报告.md`
-- **仓库源码**: 已克隆到 `{outputDir}/source/`
-- **运行环境**: Node.js（用于执行 `MCP/scripts/` 目录下的共享分析脚本）
-
----
-
-## 脚本依赖
-
-本 SKILL **不保存脚本副本**，直接调用 `MCP/scripts/` 目录下的三个共享 Node.js 脚本，**自动完成接口提取和覆盖率分析**：
-
-| 脚本 | 功能 | 输出 |
-|------|------|------|
-| `flutter-extract-interfaces.cjs` | 从 `lib/` 源码提取 Dart 公开接口规格 | `interface-spec.json` |
-| `flutter-analyze-xts-coverage.cjs` | 分析 test/ 目录测试用例覆盖率 | `03-xxx-XTS覆盖率报告.md` |
-| `flutter-analyze-demo-coverage.cjs` | 分析 example/lib 目录 Demo 覆盖率 | `02-xxx-Demo覆盖率报告.md` |
-
-**派生变量**：
-- `skillDir`：本 SKILL 所在目录（任务 prompt 中“SKILL 目录”下发的绝对路径）
-- `mcpScriptsDir`：共享脚本目录 = `{{skillDir}}/../../../MCP/scripts`（即 `3rdLibraryLoop/MCP/scripts`）
-
-> 详细脚本参数、用法和输出格式参见 [脚本使用指南](references/SCRIPT_USAGE.md)
-
----
-
-## 评分体系（严苛扣分制）
-
-**初始分数：100 分**，采用扣分制计算最终得分。
-
-| 维度 | 满分 | 扣分上限 | 核心检查内容 |
-|------|------|----------|--------------|
-| 测试结构完整性 | 15 | -15 | 测试目录、文件结构、框架使用 |
-| 公开接口覆盖率 | 40 | -40 | **核心：脚本报告的覆盖率数据** |
-| 测试场景覆盖 | 25 | -25 | 正常、异常、边界、并发场景 |
-| 测试代码质量 | 20 | -20 | 命名、独立性、可重复性、清理 |
-
-**特殊规则（直接 0 分）**：
-- 无任何测试文件 → **0 分**
-- **接口覆盖率未达 100% → 直接 0 分**（测试覆盖率或 Demo 覆盖率任意一个达到 100% 即可豁免）
-- 累计扣分超过 60 分 → **0 分**
-
-> 详细评分规则、扣分表和一票否决判定流程参见 [评分规则详解](references/SCORING_RULES.md)
-
----
-
-## 工作流程
-
-```
-Phase 0: 接口提取与覆盖率分析（脚本自动执行）
-    ↓
-Phase 1: 测试结构分析（15 分）
-    ↓
-Phase 2: 公开接口覆盖率评分（40 分，核心维度）
-    ↓
-Phase 3: 测试场景覆盖检查（25 分）
-    ↓
-Phase 4: 测试代码质量检查（20 分）
-    ↓
-Phase 5: 评分计算与报告生成
-```
-
----
-
-### Phase 0：接口提取与覆盖率分析（脚本自动执行）
-
-> ⚠️ **关键改进**：本阶段使用共享脚本（位于 `{{skillDir}}/../../../MCP/scripts/`，本 SKILL 不保存副本）自动完成接口提取和覆盖率分析，替代原有的人工读取接口规格说明和手动匹配覆盖率的流程。脚本基于 Dart 正则解析，支持 export 链追踪、monorepo、实例变量追踪等复杂场景。
-
-#### 0.1 提取接口规格
-
-从仓库源码目录提取 Dart 公开接口规格，生成 `interface-spec.json`：
-
-```bash
-node "{{skillDir}}/../../../MCP/scripts/flutter-extract-interfaces.cjs" \
-    --repoDir {outputDir}/source \
-    --output {outputDir}/interface-spec.json
-```
-
-脚本自动完成：
-- pubspec.yaml 解析 → 包名 → 入口文件定位
-- export 链递归追踪（src/ 相对路径 + package: 跨包路径）
-- export hide/show 过滤
-- 类/枚举/mixin/extension 成员提取（方法、属性、构造函数、字段）
-- 顶层函数/常量/变量/typedef 提取
-- `_` 前缀私有成员过滤
-- `///` 文档注释提取
-- monorepo 多子包支持
-
-> 如果已有前置 SKILL 生成的 `接口规格说明.md`，可作为参考对照，但**以脚本提取的 `interface-spec.json` 为准**（脚本提取更精确、更完整）。
-
-#### 0.2 分析测试覆盖率（XTS）
-
-使用 `interface-spec.json` 分析 test/ 目录的测试覆盖率：
-
-```bash
-node "{{skillDir}}/../../../MCP/scripts/flutter-analyze-xts-coverage.cjs" \
-    --spec {outputDir}/interface-spec.json \
-    --libroot {outputDir}/source \
-    --output {outputDir}/03-XTS覆盖率报告.md
-```
-
-脚本扫描目录：`test/` + `example/test/` + `example/integration_test/`
-
-报告输出关键数据：
-- **方法级覆盖率**（用于一票否决判定和扣分计算）
-- **类级覆盖率表**（每个类的覆盖数/未覆盖数/覆盖率）
-- **未覆盖接口详情**（按类分组，含签名、参数、说明）
-- **已覆盖接口详情**（含覆盖文件路径）
-- **文件覆盖详情**（每个测试文件覆盖的接口列表）
-
-#### 0.3 分析 Demo 覆盖率
-
-使用 `interface-spec.json` 分析 example/lib 目录的 Demo 覆盖率：
-
-```bash
-node "{{skillDir}}/../../../MCP/scripts/flutter-analyze-demo-coverage.cjs" \
-    --spec {outputDir}/interface-spec.json \
-    --libroot {outputDir}/source \
-    --output {outputDir}/02-Demo覆盖率报告.md
-```
-
-脚本扫描目录：`example/lib/`（支持 `examples/lib`、`demo/lib` 等 fallback）
-
-报告结构与 XTS 报告相同，区别在于扫描的是 Demo 源码而非测试源码。
-
-#### 0.4 读取脚本报告
-
-从两份 Markdown 报告中提取关键数据：
-
-| 数据项 | XTS 报告位置 | Demo 报告位置 | 用途 |
-|--------|-------------|-------------|------|
-| 方法级覆盖率 | "覆盖率总览"章节 | "覆盖率总览"章节 | 一票否决判定 + 扣分计算 |
-| 类级覆盖率表 | "类级覆盖率"章节 | "类级覆盖率"章节 | 覆盖核对表 |
-| 未覆盖接口 | "未覆盖接口详情"章节 | "未覆盖接口详情"章节 | 未覆盖接口清单 |
-| 已覆盖接口 | "已覆盖接口详情"章节 | "已覆盖接口详情"章节 | Demo 补充覆盖判定 |
-| 按类型统计 | "按接口类型统计"章节 | "按接口类型统计"章节 | 接口分类分析 |
-
-> **效率提示**：Step 0.1 提取的 `interface-spec.json` 被 Step 0.2 和 Step 0.3 共享，避免重复提取。若不关心中间 JSON，Step 0.2/0.3 也可直接使用 `--libroot` 参数一步到位（脚本内部自动提取接口）。
-
----
-
-### Phase 1：测试结构分析（满分 15 分）
-
-> 基于脚本报告和源码目录结构进行人工分析。
-
-#### 1.1 测试目录定位
-
-**Flutter 三方库的测试代码标准位置**：
-
-| 扫描优先级 | 目录路径 | 检查内容 |
-|------------|----------|----------|
-| ⭐⭐⭐ 最高 | `test/` | Flutter 标准测试目录（主测试代码） |
-| ⭐⭐ 高 | `example/` | 示例应用（demo 调用公开接口） |
-| ⭐ 中 | `example/integration_test/` | 集成测试（可选） |
-| ⭐ 低 | 根目录 `*_test.dart` | 非标准位置测试文件 |
-
-> 脚本报告中的"源文件数"可用于快速判断测试文件数量。
-
-#### 1.2 测试目录检查（严苛扣分）
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| 测试目录存在 | 至少存在一个测试目录 | **缺失扣 15 分（致命）** |
-| 测试文件数量 | ≥1 个测试文件 | **缺失扣 10 分** |
-| 测试文件命名 | 以 `_test.dart` 结尾 | 不规范扣 3 分/文件 |
-| 测试目录组织 | 有合理的子目录结构 | 无组织扣 2 分 |
-
-#### 1.3 测试框架使用检查
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| flutter_test 使用 | pubspec.yaml 配置 flutter_test | **缺失扣 5 分** |
-| mock 框架使用 | 使用 mockito 或 fake | 未使用扣 3 分 |
-| 测试覆盖率工具 | 配置 test_coverage 或 coverage | 未配置扣 2 分 |
-
-> 详细检查项参见 [检视清单](references/CHECKLIST.md)
-
----
-
-### Phase 2：公开接口覆盖率评分（满分 40 分，核心维度）
-
-> ⚠️ **这是本 SKILL 的核心检查项**，直接决定评分合理性。覆盖率数据**直接从脚本报告读取**，无需手动计算。
-
-#### 2.1 一票否决规则判定（优先检查）
-
-从脚本报告读取覆盖率数据，执行一票否决判定：
-
-```
-1. 读取 XTS 覆盖率（来自 flutter-analyze-xts-coverage.cjs 报告的"方法级覆盖率"）
-2. 读取 Demo 覆盖率（来自 flutter-analyze-demo-coverage.cjs 报告的"方法级覆盖率"）
-3. 判定：
-   - XTS 覆盖率 = 100% → ✅ 豁免一票否决，进入正常评分
-   - Demo 覆盖率 = 100% → ✅ 豁免一票否决，进入正常评分
-   - 两者均 < 100% → ❌ 触发一票否决，直接 0 分
-```
-
-> ⚠️ **覆盖率统计口径**：脚本排除 constant（常量）、enumValue（枚举值）、constructor（构造函数）类型，只计算 method/property/field/function/type/variable 的覆盖率。这些被排除的类型在报告中标注"不计入覆盖率"。
-
-#### 2.2 覆盖率扣分计算
-
-一票否决未触发时，基于测试覆盖率进行扣分：
-
-| 覆盖率范围 | 扣分值 |
-|------------|--------|
-| 100% | 0 分 |
-| ≥ 80% | -4 分 |
-| 60%-79% | -8 分 |
-| 40%-59% | -16 分 |
-| 20%-39% | -24 分 |
-| 10%-19% | -32 分 |
-| 5%-9% | -38 分 |
-| < 5% | **直接 0 分** |
-
-#### 2.3 Demo 补充覆盖抵扣
-
-对于测试未覆盖但 Demo 调用的接口，可抵扣 50% 缺失扣分（上限 5 分）。通过对比 XTS 报告和 Demo 报告的"未覆盖接口详情"章节确定补充覆盖范围。
-
-#### 2.4 构建覆盖核对表
-
-合并两份脚本报告的数据，生成覆盖核对表：
-
-| 类名 | 公开接口总数 | 测试覆盖 | 测试覆盖率 | Demo覆盖 | Demo覆盖率 | 未覆盖接口 | 综合覆盖率 |
-|------|--------------|----------|------------|----------|------------|------------|------------|
-| {ClassName} | {总数} | {测试覆盖数} | {测试覆盖率}% | {Demo覆盖数} | {Demo覆盖率}% | {未覆盖接口} | {综合覆盖率}% |
-
-#### 2.5 生成未覆盖接口清单
-
-从脚本报告的"未覆盖接口详情"章节提取，按影响程度分类：
-
-- **致命缺失**：核心功能无测试且无 Demo（从两份报告的未覆盖列表交集提取）
-- **严重缺失**：重要功能无测试，但 Demo 有部分覆盖（XTS 未覆盖 ∩ Demo 已覆盖）
-- **中等缺失**：边缘功能未覆盖
-
-#### 2.6 覆盖率不足原因分析
-
-分析未覆盖接口的原因，**不减免扣分**：
-
-| 原因类型 | 典型场景 | 扣分处理 |
-|----------|----------|----------|
-| 平台通道限制 | BLE/硬件依赖 MethodChannel | **不减免**，应通过 mock 测试 |
-| Mock 机制缺失 | 未创建 MethodChannel mock | **严苛扣分** |
-| 测试设计遗漏 | 纯 Dart 逻辑未测试 | **严苛扣分** |
-
-> 详细扣分规则和 Mock 测试示例参见 [评分规则详解](references/SCORING_RULES.md)
-
----
-
-### Phase 3：测试场景覆盖检查（满分 25 分）
-
-> 人工分析测试文件代码，检查测试场景覆盖情况。
-
-#### 3.1 测试场景分类检查
-
-| 场景类型 | 检查内容 | 扣分规则 |
-|----------|----------|----------|
-| **正常场景** | 测试正常输入和预期输出 | 缺失扣 5 分 |
-| **异常场景** | 测试异常输入、错误处理、超时 | **缺失扣 8 分** |
-| **边界场景** | 测试空值、极值、边界条件 | 缺失扣 5 分 |
-| **并发场景** | 测试并发调用、多设备连接 | 缺失扣 7 分 |
-
-#### 3.2 异常场景细化检查
-
-| 异常类型 | 检查项 | 扣分规则 |
-|----------|--------|----------|
-| 参数异常 | 无效参数、null 参数测试 | 缺失扣 3 分 |
-| 状态异常 | 设备断开、适配器关闭测试 | **缺失扣 4 分** |
-| 超时异常 | 操作超时处理测试 | 缺失扣 3 分 |
-| 权限异常 | 权限缺失场景测试 | 缺失扣 2 分 |
-
----
-
-### Phase 4：测试代码质量检查（满分 20 分）
-
-> 人工分析测试文件代码，检查测试代码质量。
-
-#### 4.1 测试命名规范
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| 测试组命名 | 使用 `group()` 组织测试 | 未使用扣 3 分 |
-| 测试描述清晰 | 描述测试目的和行为 | 不清晰扣 2 分/测试 |
-| BDD 风格 | 使用 should/when/then 模式 | 未使用扣 1 分 |
-
-#### 4.2 测试独立性
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| 无顺序依赖 | 测试可任意顺序运行 | **有依赖扣 5 分** |
-| 无共享状态 | 测试间不共享可变状态 | 有共享扣 4 分 |
-| 正确清理 | setUp/tearDown 正确使用 | **未使用扣 6 分** |
-| 无外部依赖 | 不依赖网络/外部服务（或 mock） | **有依赖扣 5 分** |
-
-#### 4.3 测试可重复性
-
-| 检查项 | 规范要求 | 扣分规则 |
-|--------|----------|----------|
-| 结果一致 | 多次运行结果相同 | 不一致扣 4 分 |
-| 无随机数据 | 使用固定测试数据 | 有随机扣 3 分 |
-| 无时间依赖 | 不依赖当前时间（或 mock） | 有依赖扣 2 分 |
-
----
-
-### Phase 5：评分计算与报告生成
-
-#### 5.1 评分计算
-
-```
-初始分数 = 100 分
-
-【一票否决判定】（优先检查）：
-1. 无任何测试文件 → 直接 0 分
-2. 测试覆盖率 < 100% 且 Demo 覆盖率 < 100% → 直接 0 分
-3. 累计扣分 > 60 → 直接 0 分
-
-【正常评分】（一票否决未触发时）：
-- 测试结构扣分：max(-15, 实际扣分)
-- 公开接口覆盖率扣分：max(-40, 实际扣分)
-- 测试场景覆盖扣分：max(-25, 实际扣分)
-- 测试代码质量扣分：max(-20, 实际扣分)
-
-最终得分 = max(0, 100 - 总扣分)
-```
-
-#### 5.2 报告生成
-
-按照输出模板生成检视报告，包含以下结构：
-
-1. **评分汇总表**（综合评分 + 各维度得分/扣分）
-2. **公开接口覆盖核对表**（从脚本报告合并数据）
-3. **未覆盖接口清单**（按影响程度分类）
-4. **脚本报告摘要**（XTS + Demo 覆盖率报告关键数据）
-5. **详细检视结果**（各维度分析详情）
-
-> 输出模板参见 [检视报告模板](assets/REPORT_TEMPLATE.md)
-
----
-
-## 输出要求
-
-1. **评分格式必须为**：`**综合评分：XX/100**`（确保 `_parseFlutterLibraryScore` 函数能正确解析）
-2. **必须包含公开接口覆盖核对表**（数据从脚本报告提取）
-3. **必须列出未覆盖接口清单**（从脚本报告的"未覆盖接口详情"提取）
-4. **评分必须是 0-100 的整数**
-5. **扣分必须有具体项目和数值**（不允许模糊扣分）
-6. **使用中文撰写内容**
-7. **脚本产出文件列表**（文件名不带 repoName 前缀）：
-   - `{outputDir}/interface-spec.json` — 接口规格 JSON
-   - `{outputDir}/02-Demo覆盖率报告.md` — Demo 覆盖率报告
-   - `{outputDir}/03-XTS覆盖率报告.md` — XTS 覆盖率报告
-   - `{outputDir}/用例覆盖度检视报告.md` — 最终检视报告
-8. **输出文件自检**：写入结果文件前，先确认上述 4 个文件均已生成且内容完整（**独立文件，禁止只写入 result 执行结果文件**）
-
-### 结构化指标输出（必须执行）
-
-执行环境会在任务 prompt 中下发一个**结构化指标文件输出路径**（`stepId{X}_loop{L}_meta_{N}.json`）。
-检视完成后，**必须**将最终评分以下述 JSON 对象写入该路径：
-
-```json
-{
-  "testCoverageScore": 85,
-  "scoreReason": "XTS覆盖率62%扣18，未覆盖接口38个扣17等（一句话判定依据，≤50字；触发一票否决时必须注明）"
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `testCoverageScore` | number | 用例覆盖度评分（0-100 整数，与报告中 `**综合评分：XX/100**` 的数值一致） |
-| `scoreReason` | string | 评分判定依据摘要（可选，前端悬浮提示展示；0 分时强烈建议写明触发规则，如"XTS 1.87% 触发一票否决"） |
-
-**说明**：该文件由执行框架自动收割入库（前端/历史列表直接读取评分，无需解析报告文本）。若 prompt 未下发该路径则跳过本节。
-
----
-
-## 检视清单
-
-详细检查项参见 [检视清单](references/CHECKLIST.md)
-
----
-
-## 脚本使用
-
-详细脚本参数、用法和输出格式参见 [脚本使用指南](references/SCRIPT_USAGE.md)
+---
+name: flutter-library-test-coverage-check
+description: 对 Flutter 三方库进行用例覆盖度检视，**核心聚焦 Dart 公开接口的覆盖程度**。通过 MCP/scripts 共享脚本自动提取接口规格、分析测试覆盖率和 Demo 覆盖率，基于脚本报告采用严苛扣分制生成检视报告（0-100分）。作为 Flutter 仓库检视流程的最后阶段，依赖接口规格说明和文档质量检视结果。
+license: Apache-2.0
+compatibility: 需要 Node.js 运行环境、Git 仓库访问、接口规格说明文档（可选，脚本可直接从源码提取）
+metadata:
+  version: "1.1.0"
+---
+
+# FlutterLibraryTestCoverageCheckSkill
+
+对 Flutter 三方库进行用例覆盖度检视，**核心聚焦：测试用例和 demo 示例对 Dart 公开接口的覆盖程度**。通过共享脚本自动完成接口提取和覆盖率分析，基于脚本报告采用严苛扣分制评分。
+
+> ⚠️ **核心定位**：Flutter 三方库对外导出的接口是 **Dart 层定义的**（位于 `lib/` 目录），本 SKILL 聚焦于测试用例和 demo 对这些 **Dart 公开接口**的覆盖程度。接口提取和覆盖率分析由 `MCP/scripts/` 目录下的三个 Node.js 共享脚本自动完成（本 SKILL 通过相对路径引用，不保存脚本副本），检视者基于脚本报告进行评分和深度分析。
+
+---
+
+## 任务参数
+
+| 参数 | 必需 | 说明 |
+|------|------|------|
+| `repoUrl` | ✅ | Git 仓库地址，支持分支 `?branch=xxx` |
+| `outputDir` | ✅ | 输出目录绝对路径，存放检视报告和脚本产出 |
+| `interfaceDocPath` | ❌ | 接口规格说明文档路径（如已有则作为参考，脚本可直接从源码提取） |
+| `repoName` | ✅ | 仓库名称（用于报告标识） |
+
+---
+
+## 输入依赖
+
+本 SKILL 是 Flutter 仓库检视流程的**最后阶段**，依赖：
+
+- **前置 SKILL**: `library-interface-analyzer`（接口规格说明，可选 — 脚本可直接从源码提取）
+- **前置 SKILL**: `flutter-library-documentation-quality-check`（文档质量检视报告）
+- **输入文件**: `接口规格说明.md`（可选）、`文档质量检视报告.md`
+- **仓库源码**: 已克隆到 `{outputDir}/source/`
+- **运行环境**: Node.js（用于执行 `MCP/scripts/` 目录下的共享分析脚本）
+
+---
+
+## 脚本依赖
+
+本 SKILL **不保存脚本副本**，直接调用 `MCP/scripts/` 目录下的三个共享 Node.js 脚本，**自动完成接口提取和覆盖率分析**：
+
+| 脚本 | 功能 | 输出 |
+|------|------|------|
+| `flutter-extract-interfaces.cjs` | 从 `lib/` 源码提取 Dart 公开接口规格 | `interface-spec.json` |
+| `flutter-analyze-xts-coverage.cjs` | 分析 test/ 目录测试用例覆盖率 | `03-xxx-XTS覆盖率报告.md` |
+| `flutter-analyze-demo-coverage.cjs` | 分析 example/lib 目录 Demo 覆盖率 | `02-xxx-Demo覆盖率报告.md` |
+
+**派生变量**：
+- `skillDir`：本 SKILL 所在目录（任务 prompt 中“SKILL 目录”下发的绝对路径）
+- `mcpScriptsDir`：共享脚本目录 = `{{skillDir}}/../../../MCP/scripts`（即 `3rdLibraryLoop/MCP/scripts`）
+
+> 详细脚本参数、用法和输出格式参见 [脚本使用指南](references/SCRIPT_USAGE.md)
+
+---
+
+## 评分体系（严苛扣分制）
+
+**初始分数：100 分**，采用扣分制计算最终得分。
+
+| 维度 | 满分 | 扣分上限 | 核心检查内容 |
+|------|------|----------|--------------|
+| 测试结构完整性 | 15 | -15 | 测试目录、文件结构、框架使用 |
+| 公开接口覆盖率 | 40 | -40 | **核心：脚本报告的覆盖率数据** |
+| 测试场景覆盖 | 25 | -25 | 正常、异常、边界、并发场景 |
+| 测试代码质量 | 20 | -20 | 命名、独立性、可重复性、清理 |
+
+**特殊规则（直接 0 分）**：
+- 无任何测试文件 → **0 分**
+- **接口覆盖率未达 100% → 直接 0 分**（测试覆盖率或 Demo 覆盖率任意一个达到 100% 即可豁免）
+- 累计扣分超过 60 分 → **0 分**
+
+> 详细评分规则、扣分表和一票否决判定流程参见 [评分规则详解](references/SCORING_RULES.md)
+
+---
+
+## 工作流程
+
+```
+Phase 0: 接口提取与覆盖率分析（脚本自动执行）
+    ↓
+Phase 1: 测试结构分析（15 分）
+    ↓
+Phase 2: 公开接口覆盖率评分（40 分，核心维度）
+    ↓
+Phase 3: 测试场景覆盖检查（25 分）
+    ↓
+Phase 4: 测试代码质量检查（20 分）
+    ↓
+Phase 5: 评分计算与报告生成
+```
+
+---
+
+### Phase 0：接口提取与覆盖率分析（脚本自动执行）
+
+> ⚠️ **关键改进**：本阶段使用共享脚本（位于 `{{skillDir}}/../../../MCP/scripts/`，本 SKILL 不保存副本）自动完成接口提取和覆盖率分析，替代原有的人工读取接口规格说明和手动匹配覆盖率的流程。脚本基于 Dart 正则解析，支持 export 链追踪、monorepo、实例变量追踪等复杂场景。
+
+#### 0.1 提取接口规格
+
+从仓库源码目录提取 Dart 公开接口规格，生成 `interface-spec.json`：
+
+```bash
+node "{{skillDir}}/../../../MCP/scripts/flutter-extract-interfaces.cjs" \
+    --repoDir {outputDir}/source \
+    --output {outputDir}/interface-spec.json
+```
+
+脚本自动完成：
+- pubspec.yaml 解析 → 包名 → 入口文件定位
+- export 链递归追踪（src/ 相对路径 + package: 跨包路径）
+- export hide/show 过滤
+- 类/枚举/mixin/extension 成员提取（方法、属性、构造函数、字段）
+- 顶层函数/常量/变量/typedef 提取
+- `_` 前缀私有成员过滤
+- `///` 文档注释提取
+- monorepo 多子包支持
+
+> 如果已有前置 SKILL 生成的 `接口规格说明.md`，可作为参考对照，但**以脚本提取的 `interface-spec.json` 为准**（脚本提取更精确、更完整）。
+
+#### 0.2 分析测试覆盖率（XTS）
+
+使用 `interface-spec.json` 分析 test/ 目录的测试覆盖率：
+
+```bash
+node "{{skillDir}}/../../../MCP/scripts/flutter-analyze-xts-coverage.cjs" \
+    --spec {outputDir}/interface-spec.json \
+    --libroot {outputDir}/source \
+    --output {outputDir}/03-XTS覆盖率报告.md
+```
+
+脚本扫描目录：`test/` + `example/test/` + `example/integration_test/`
+
+报告输出关键数据：
+- **方法级覆盖率**（用于一票否决判定和扣分计算）
+- **类级覆盖率表**（每个类的覆盖数/未覆盖数/覆盖率）
+- **未覆盖接口详情**（按类分组，含签名、参数、说明）
+- **已覆盖接口详情**（含覆盖文件路径）
+- **文件覆盖详情**（每个测试文件覆盖的接口列表）
+
+#### 0.3 分析 Demo 覆盖率
+
+使用 `interface-spec.json` 分析 example/lib 目录的 Demo 覆盖率：
+
+```bash
+node "{{skillDir}}/../../../MCP/scripts/flutter-analyze-demo-coverage.cjs" \
+    --spec {outputDir}/interface-spec.json \
+    --libroot {outputDir}/source \
+    --output {outputDir}/02-Demo覆盖率报告.md
+```
+
+脚本扫描目录：`example/lib/`（支持 `examples/lib`、`demo/lib` 等 fallback）
+
+报告结构与 XTS 报告相同，区别在于扫描的是 Demo 源码而非测试源码。
+
+#### 0.4 读取脚本报告
+
+从两份 Markdown 报告中提取关键数据：
+
+| 数据项 | XTS 报告位置 | Demo 报告位置 | 用途 |
+|--------|-------------|-------------|------|
+| 方法级覆盖率 | "覆盖率总览"章节 | "覆盖率总览"章节 | 一票否决判定 + 扣分计算 |
+| 类级覆盖率表 | "类级覆盖率"章节 | "类级覆盖率"章节 | 覆盖核对表 |
+| 未覆盖接口 | "未覆盖接口详情"章节 | "未覆盖接口详情"章节 | 未覆盖接口清单 |
+| 已覆盖接口 | "已覆盖接口详情"章节 | "已覆盖接口详情"章节 | Demo 补充覆盖判定 |
+| 按类型统计 | "按接口类型统计"章节 | "按接口类型统计"章节 | 接口分类分析 |
+
+> **效率提示**：Step 0.1 提取的 `interface-spec.json` 被 Step 0.2 和 Step 0.3 共享，避免重复提取。若不关心中间 JSON，Step 0.2/0.3 也可直接使用 `--libroot` 参数一步到位（脚本内部自动提取接口）。
+
+---
+
+### Phase 1：测试结构分析（满分 15 分）
+
+> 基于脚本报告和源码目录结构进行人工分析。
+
+#### 1.1 测试目录定位
+
+**Flutter 三方库的测试代码标准位置**：
+
+| 扫描优先级 | 目录路径 | 检查内容 |
+|------------|----------|----------|
+| ⭐⭐⭐ 最高 | `test/` | Flutter 标准测试目录（主测试代码） |
+| ⭐⭐ 高 | `example/` | 示例应用（demo 调用公开接口） |
+| ⭐ 中 | `example/integration_test/` | 集成测试（可选） |
+| ⭐ 低 | 根目录 `*_test.dart` | 非标准位置测试文件 |
+
+> 脚本报告中的"源文件数"可用于快速判断测试文件数量。
+
+#### 1.2 测试目录检查（严苛扣分）
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| 测试目录存在 | 至少存在一个测试目录 | **缺失扣 15 分（致命）** |
+| 测试文件数量 | ≥1 个测试文件 | **缺失扣 10 分** |
+| 测试文件命名 | 以 `_test.dart` 结尾 | 不规范扣 3 分/文件 |
+| 测试目录组织 | 有合理的子目录结构 | 无组织扣 2 分 |
+
+#### 1.3 测试框架使用检查
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| flutter_test 使用 | pubspec.yaml 配置 flutter_test | **缺失扣 5 分** |
+| mock 框架使用 | 使用 mockito 或 fake | 未使用扣 3 分 |
+| 测试覆盖率工具 | 配置 test_coverage 或 coverage | 未配置扣 2 分 |
+
+> 详细检查项参见 [检视清单](references/CHECKLIST.md)
+
+---
+
+### Phase 2：公开接口覆盖率评分（满分 40 分，核心维度）
+
+> ⚠️ **这是本 SKILL 的核心检查项**，直接决定评分合理性。覆盖率数据**直接从脚本报告读取**，无需手动计算。
+
+#### 2.1 一票否决规则判定（优先检查）
+
+从脚本报告读取覆盖率数据，执行一票否决判定：
+
+```
+1. 读取 XTS 覆盖率（来自 flutter-analyze-xts-coverage.cjs 报告的"方法级覆盖率"）
+2. 读取 Demo 覆盖率（来自 flutter-analyze-demo-coverage.cjs 报告的"方法级覆盖率"）
+3. 判定：
+   - XTS 覆盖率 = 100% → ✅ 豁免一票否决，进入正常评分
+   - Demo 覆盖率 = 100% → ✅ 豁免一票否决，进入正常评分
+   - 两者均 < 100% → ❌ 触发一票否决，直接 0 分
+```
+
+> ⚠️ **覆盖率统计口径**：脚本排除 constant（常量）、enumValue（枚举值）、constructor（构造函数）类型，只计算 method/property/field/function/type/variable 的覆盖率。这些被排除的类型在报告中标注"不计入覆盖率"。
+
+#### 2.2 覆盖率扣分计算
+
+一票否决未触发时，基于测试覆盖率进行扣分：
+
+| 覆盖率范围 | 扣分值 |
+|------------|--------|
+| 100% | 0 分 |
+| ≥ 80% | -4 分 |
+| 60%-79% | -8 分 |
+| 40%-59% | -16 分 |
+| 20%-39% | -24 分 |
+| 10%-19% | -32 分 |
+| 5%-9% | -38 分 |
+| < 5% | **直接 0 分** |
+
+#### 2.3 Demo 补充覆盖抵扣
+
+对于测试未覆盖但 Demo 调用的接口，可抵扣 50% 缺失扣分（上限 5 分）。通过对比 XTS 报告和 Demo 报告的"未覆盖接口详情"章节确定补充覆盖范围。
+
+#### 2.4 构建覆盖核对表
+
+合并两份脚本报告的数据，生成覆盖核对表：
+
+| 类名 | 公开接口总数 | 测试覆盖 | 测试覆盖率 | Demo覆盖 | Demo覆盖率 | 未覆盖接口 | 综合覆盖率 |
+|------|--------------|----------|------------|----------|------------|------------|------------|
+| {ClassName} | {总数} | {测试覆盖数} | {测试覆盖率}% | {Demo覆盖数} | {Demo覆盖率}% | {未覆盖接口} | {综合覆盖率}% |
+
+#### 2.5 生成未覆盖接口清单
+
+从脚本报告的"未覆盖接口详情"章节提取，按影响程度分类：
+
+- **致命缺失**：核心功能无测试且无 Demo（从两份报告的未覆盖列表交集提取）
+- **严重缺失**：重要功能无测试，但 Demo 有部分覆盖（XTS 未覆盖 ∩ Demo 已覆盖）
+- **中等缺失**：边缘功能未覆盖
+
+#### 2.6 覆盖率不足原因分析
+
+分析未覆盖接口的原因，**不减免扣分**：
+
+| 原因类型 | 典型场景 | 扣分处理 |
+|----------|----------|----------|
+| 平台通道限制 | BLE/硬件依赖 MethodChannel | **不减免**，应通过 mock 测试 |
+| Mock 机制缺失 | 未创建 MethodChannel mock | **严苛扣分** |
+| 测试设计遗漏 | 纯 Dart 逻辑未测试 | **严苛扣分** |
+
+> 详细扣分规则和 Mock 测试示例参见 [评分规则详解](references/SCORING_RULES.md)
+
+---
+
+### Phase 3：测试场景覆盖检查（满分 25 分）
+
+> 人工分析测试文件代码，检查测试场景覆盖情况。
+
+#### 3.1 测试场景分类检查
+
+| 场景类型 | 检查内容 | 扣分规则 |
+|----------|----------|----------|
+| **正常场景** | 测试正常输入和预期输出 | 缺失扣 5 分 |
+| **异常场景** | 测试异常输入、错误处理、超时 | **缺失扣 8 分** |
+| **边界场景** | 测试空值、极值、边界条件 | 缺失扣 5 分 |
+| **并发场景** | 测试并发调用、多设备连接 | 缺失扣 7 分 |
+
+#### 3.2 异常场景细化检查
+
+| 异常类型 | 检查项 | 扣分规则 |
+|----------|--------|----------|
+| 参数异常 | 无效参数、null 参数测试 | 缺失扣 3 分 |
+| 状态异常 | 设备断开、适配器关闭测试 | **缺失扣 4 分** |
+| 超时异常 | 操作超时处理测试 | 缺失扣 3 分 |
+| 权限异常 | 权限缺失场景测试 | 缺失扣 2 分 |
+
+---
+
+### Phase 4：测试代码质量检查（满分 20 分）
+
+> 人工分析测试文件代码，检查测试代码质量。
+
+#### 4.1 测试命名规范
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| 测试组命名 | 使用 `group()` 组织测试 | 未使用扣 3 分 |
+| 测试描述清晰 | 描述测试目的和行为 | 不清晰扣 2 分/测试 |
+| BDD 风格 | 使用 should/when/then 模式 | 未使用扣 1 分 |
+
+#### 4.2 测试独立性
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| 无顺序依赖 | 测试可任意顺序运行 | **有依赖扣 5 分** |
+| 无共享状态 | 测试间不共享可变状态 | 有共享扣 4 分 |
+| 正确清理 | setUp/tearDown 正确使用 | **未使用扣 6 分** |
+| 无外部依赖 | 不依赖网络/外部服务（或 mock） | **有依赖扣 5 分** |
+
+#### 4.3 测试可重复性
+
+| 检查项 | 规范要求 | 扣分规则 |
+|--------|----------|----------|
+| 结果一致 | 多次运行结果相同 | 不一致扣 4 分 |
+| 无随机数据 | 使用固定测试数据 | 有随机扣 3 分 |
+| 无时间依赖 | 不依赖当前时间（或 mock） | 有依赖扣 2 分 |
+
+---
+
+### Phase 5：评分计算与报告生成
+
+#### 5.1 评分计算
+
+```
+初始分数 = 100 分
+
+【一票否决判定】（优先检查）：
+1. 无任何测试文件 → 直接 0 分
+2. 测试覆盖率 < 100% 且 Demo 覆盖率 < 100% → 直接 0 分
+3. 累计扣分 > 60 → 直接 0 分
+
+【正常评分】（一票否决未触发时）：
+- 测试结构扣分：max(-15, 实际扣分)
+- 公开接口覆盖率扣分：max(-40, 实际扣分)
+- 测试场景覆盖扣分：max(-25, 实际扣分)
+- 测试代码质量扣分：max(-20, 实际扣分)
+
+最终得分 = max(0, 100 - 总扣分)
+```
+
+#### 5.2 报告生成
+
+按照输出模板生成检视报告，包含以下结构：
+
+1. **评分汇总表**（综合评分 + 各维度得分/扣分）
+2. **公开接口覆盖核对表**（从脚本报告合并数据）
+3. **未覆盖接口清单**（按影响程度分类）
+4. **脚本报告摘要**（XTS + Demo 覆盖率报告关键数据）
+5. **详细检视结果**（各维度分析详情）
+
+> 输出模板参见 [检视报告模板](assets/REPORT_TEMPLATE.md)
+
+---
+
+## 输出要求
+
+1. **评分格式必须为**：`**综合评分：XX/100**`（确保 `_parseFlutterLibraryScore` 函数能正确解析）
+2. **必须包含公开接口覆盖核对表**（数据从脚本报告提取）
+3. **必须列出未覆盖接口清单**（从脚本报告的"未覆盖接口详情"提取）
+4. **评分必须是 0-100 的整数**
+5. **扣分必须有具体项目和数值**（不允许模糊扣分）
+6. **使用中文撰写内容**
+7. **脚本产出文件列表**（文件名不带 repoName 前缀）：
+   - `{outputDir}/interface-spec.json` — 接口规格 JSON
+   - `{outputDir}/02-Demo覆盖率报告.md` — Demo 覆盖率报告
+   - `{outputDir}/03-XTS覆盖率报告.md` — XTS 覆盖率报告
+   - `{outputDir}/用例覆盖度检视报告.md` — 最终检视报告
+8. **输出文件自检**：写入结果文件前，先确认上述 4 个文件均已生成且内容完整（**独立文件，禁止只写入 result 执行结果文件**）
+
+### 结构化指标输出（必须执行）
+
+执行环境会在任务 prompt 中下发一个**结构化指标文件输出路径**（`stepId{X}_loop{L}_meta_{N}.json`）。
+检视完成后，**必须**将最终评分以下述 JSON 对象写入该路径：
+
+```json
+{
+  "testCoverageScore": 85,
+  "scoreReason": "XTS覆盖率62%扣18，未覆盖接口38个扣17等（一句话判定依据，≤50字；触发一票否决时必须注明）"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `testCoverageScore` | number | 用例覆盖度评分（0-100 整数，与报告中 `**综合评分：XX/100**` 的数值一致） |
+| `scoreReason` | string | 评分判定依据摘要（可选，前端悬浮提示展示；0 分时强烈建议写明触发规则，如"XTS 1.87% 触发一票否决"） |
+
+**说明**：该文件由执行框架自动收割入库（前端/历史列表直接读取评分，无需解析报告文本）。若 prompt 未下发该路径则跳过本节。
+
+---
+
+## 检视清单
+
+详细检查项参见 [检视清单](references/CHECKLIST.md)
+
+---
+
+## 脚本使用
+
+详细脚本参数、用法和输出格式参见 [脚本使用指南](references/SCRIPT_USAGE.md)