@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Skills/arkts-library-test-coverage-check/references/CHECKLIST.md

@@ -0,0 +1,253 @@
+# ArktsLibraryTestCoverageCheckSkill 详细检查清单
+
+本文件为 SKILL.md 中各维度的详细检查项展开说明，供执行检视时逐项对照。
+
+---
+
+## 维度 1：公开接口覆盖率（TC-01~TC-05）
+
+### TC-01 核心接口未覆盖（Critical，-15 分）
+
+**定义**：公开核心功能接口（标注为必须/required）无任何测试用例。
+
+**检查方法**：
+1. 从 `接口规格说明.md` 提取所有标注为 required/必须 的公开接口
+2. 扫描所有测试文件，查找对这些接口的直接调用或间接测试
+3. 核心接口包括但不限于：
+   - 库的主入口方法
+   - 文档标注为必须的功能
+   - README 中列为核心功能的接口
+
+**判定标准**：
+- ✅ 有至少一个测试函数直接测试该接口 → 已覆盖
+- ⚠️ 仅在其他测试中间接调用但未专门测试 → 需评估
+- ❌ 无任何测试函数涉及该接口 → 未覆盖
+
+> **归零规则 6 关联**：当 DEMO 目录和 test 目录均未对全部公开接口实现 100% 覆盖时，触发归零规则 6，综合评分直接为 0 分。只要 DEMO 或 test 目录中任意一个达到 100% 接口覆盖，即不触发此归零规则。
+
+### TC-02 重要接口未覆盖（Major，-10 分）
+
+**定义**：重要公开接口缺少测试用例（非核心但影响主要功能流程）。
+
+**检查方法**：同 TC-01，但针对文档标注为推荐/可选的重要接口。
+
+### TC-03 边界场景缺失（Major，-8 分）
+
+**定义**：有测试的接口但缺少边界值/异常输入测试。
+
+**典型缺失场景**：
+- 数值参数：缺少极大值、极小值、零值、负值测试
+- 字符串参数：缺少空字符串、超长字符串、特殊字符测试
+- 数组参数：缺少空数组、超大数组测试
+- 对象参数：缺少 null、空对象、缺失字段测试
+- Promise 返回：缺少 reject 场景测试
+
+### TC-04 可选接口未覆盖（Minor，-3 分）
+
+**定义**：可选功能接口（标注为 optional）未测试。
+
+### TC-05 接口参数组合未覆盖（Major，-5 分）
+
+**定义**：接口有多参数时，仅测试了部分参数组合，缺少全组合覆盖。
+
+---
+
+## 归零规则 6 详细说明：接口覆盖率 100% 要求
+
+**触发条件**：DEMO 目录和 test 目录的公开接口覆盖率**均未达到 100%**。
+
+**不触发条件**（满足其一即可）：
+- DEMO 目录（`demo/`、`example/`、`sample/` 等）中的代码调用了全部公开接口 → DEMO 覆盖率 100%
+- test 目录（`test/`、`tests/`、`__tests__/`、`ohosTest/` 等）中的测试覆盖了全部公开接口 → test 覆盖率 100%
+
+**计算方法**：
+1. 从 `接口规格说明.md` 提取全部公开接口列表（设为 N 个）
+2. 扫描 DEMO 目录，统计其中调用的公开接口数（D 个），DEMO 覆盖率 = D/N × 100%
+3. 扫描 test 目录，统计其中覆盖的公开接口数（T 个），test 覆盖率 = T/N × 100%
+4. 若 max(DEMO覆盖率, test覆盖率) = 100%，则不触发归零；否则触发
+
+**注意**：此归零规则叠加于维度扣分之上，即使维度扣分后仍有剩余分数，只要触发此规则，综合评分直接为 0 分。
+
+---
+
+## 维度 2：测试质量（TC-06~TC-11）
+
+### TC-06 断言缺失（Critical，-10 分）
+
+**定义**：测试函数中无任何 assert/expect 断言语句。
+
+**检查方法**：
+1. 逐个扫描测试函数体
+2. 查找 `assert*`、`expect*`、`chai.expect`、`should.*` 等断言调用
+3. 仅包含 `console.log` 而无断言的测试视为断言缺失
+
+**判定标准**：
+- ✅ 有至少一个非空断言 → 通过
+- ❌ 无任何断言或仅有 `console.log` → 断言缺失
+
+### TC-07 断言过弱（Minor，-5 分）
+
+**定义**：测试仅有断言"不抛异常"，未验证正确输出。
+
+**典型模式**：
+```typescript
+// ❌ 断言过弱
+it('should work', () => {
+  expect(() => myFunction()).not.toThrow(); // 仅验证不抛异常
+});
+
+// ✅ 正确断言
+it('should work', () => {
+  const result = myFunction();
+  expect(result).toBe(expectedValue); // 验证输出
+});
+```
+
+### TC-08 测试独立性（Major，-8 分）
+
+**定义**：测试间存在数据依赖，无法独立运行。
+
+**典型问题**：
+- 测试 A 修改全局状态，测试 B 依赖该状态
+- 测试使用共享 mock 数据且未在 afterEach 中清理
+- 测试顺序影响结果（换顺序就失败）
+
+### TC-09 Mock 过度（Minor，-5 分）
+
+**定义**：测试中 Mock 占比过高，导致测试脱离真实环境。
+
+**判定标准**：
+- Mock 数量 > 被测代码调用数的 50% → Mock 过度
+- 关键鸿蒙 API 全部 Mock → Mock 过度
+- 自身逻辑内部方法也被 Mock → Mock 过度
+
+### TC-10 负面测试缺失（Major，-8 分）
+
+**定义**：缺少异常/失败场景测试。
+
+**应覆盖的负面场景**：
+- 输入参数为 null/undefined/非法值
+- 网络请求失败
+- 权限不足
+- 资源不可用
+
+### TC-11 测试数据硬编码（Minor，-3 分）
+
+**定义**：测试数据全硬编码，未提取为 fixtures/常量/工厂函数。
+
+---
+
+## 维度 3：鸿蒙化特性测试覆盖（TC-12~TC-17）
+
+### TC-12 鸿蒙 API 调用未测试（Critical，-12 分）
+
+**定义**：源码中调用的 @ohos.* API 在测试中无覆盖。
+
+**检查方法**：
+1. 在源码中扫描所有 `import from '@ohos.*'` 和直接调用 `@ohos.*` 的位置
+2. 在测试文件中查找对应 API 的测试覆盖
+3. 每个使用的 @ohos API 应有至少一个测试
+
+**关键鸿蒙 API 类别**：
+- 系统服务：@ohos.bluetooth、@ohos.network 等
+- UI 框架：@ohos.arkui.* 等
+- 存储：@ohos.data.* 等
+- 设备：@ohos.deviceInfo 等
+
+### TC-13 权限场景未测试（Major，-8 分）
+
+**定义**：需权限的 API 无权限授予/拒绝场景测试。
+
+### TC-14 Lifecycle 测试缺失（Major，-10 分）
+
+**定义**：ArkTS 组件生命周期方法无测试覆盖。
+
+**应覆盖的生命周期**：
+- aboutToAppear / aboutToDisappear
+- onPageShow / onPageHide
+- onBackPress
+- onActive / onInactive
+
+### TC-15 NAPI 测试缺失（Major，-10 分）
+
+**定义**：Native 模块通过 NAPI 暴露的接口无测试覆盖。
+
+**检查方法**：
+1. 找到所有 `napi_define_class` / `napi_define_properties` 暴露的方法
+2. 在测试中查找对这些方法的调用测试
+
+### TC-16 跨设备场景未测试（Minor，-5 分）
+
+**定义**：鸿蒙多设备/分布式场景无测试。
+
+### TC-17 鸿蒙配置测试缺失（Minor，-3 分）
+
+**定义**：module.json5 中的关键配置（权限、设备类型等）未在测试中验证。
+
+---
+
+## 维度 4：测试分类覆盖（TC-18~TC-22）
+
+### TC-18 缺少单元测试（Major，-8 分）
+
+**定义**：对独立函数/方法无单元级测试（测试最小功能单元）。
+
+**判定标准**：
+- 检查是否有针对单个方法/函数的独立测试
+- 单元测试应不依赖外部系统或 Mock 较少
+
+### TC-19 缺少集成测试（Minor，-5 分）
+
+**定义**：对模块间交互无集成级测试。
+
+### TC-20 缺少端到端测试（Minor，-5 分）
+
+**定义**：对完整功能流程无 E2E 测试（从用户视角验证完整链路）。
+
+### TC-21 测试命名不规范（Minor，-3 分）
+
+**定义**：测试文件/函数命名不符合规范。
+
+**命名规范**：
+- 测试文件必须包含 test/Test/spec 关键词
+- 测试函数描述应清晰表达测试意图
+- 建议格式：`it('should {预期行为} when {条件}')`
+
+### TC-22 测试分类标注缺失（Minor，-2 分）
+
+**定义**：测试未标注类型（unit/integration/e2e）。
+
+---
+
+## 维度 5：测试基础设施（TC-23~TC-26）
+
+### TC-23 测试框架配置缺失（Major，-5 分）
+
+**定义**：缺少鸿蒙测试框架配置。
+
+**检查项**：
+- 是否存在 @ohos/hypium 依赖配置
+- 是否有测试运行配置文件
+- oh-package.json5 中是否声明测试依赖
+
+### TC-24 测试脚本缺失（Minor，-3 分）
+
+**定义**：无测试运行脚本（如 hvigorw test 或自定义脚本）。
+
+### TC-25 CI 集成缺失（Minor，-3 分）
+
+**定义**：无 CI/CD 测试流程配置（如 .github/workflows 或 CI 脚本）。
+
+### TC-26 测试数据管理缺失（Minor，-2 分）
+
+**定义**：缺少测试数据/fixtures 的统一管理。
+
+---
+
+## 归零规则检查要点
+
+1. **核心接口完全无测试**：逐一确认所有 required 接口均无测试 → 触发归零规则 1
+2. **覆盖率 < 10%**：计算覆盖率后判定 → 触发归零规则 2
+3. **无测试文件**：扫描结果为空 → 触发归零规则 3
+4. **未发现鸿蒙化代码**：Phase 1 扫描无结果 → 触发归零规则 4
+5. **源码不可访问**：目录不存在或无权限 → 触发归零规则 5

package/vendor/Server/Skills/arkts-library-test-coverage-check/references/MCP_TOOL_USAGE.md

@@ -0,0 +1,115 @@
+# MCP 工具使用指南
+
+本文档说明本 SKILL 可复用的 MCP 脚本工具，用于接口覆盖率分析和测试文件扫描，避免重复造轮子。
+
+---
+
+## 可用 MCP 脚本工具
+
+### 1. `script_arkts_analyze_demo_coverage` — Demo 接口覆盖率分析
+
+**脚本路径**: `MCP/scripts/analyze-demo-coverage.cjs`
+
+**功能**：无需手工提取接口规格，直接一步完成接口提取、Demo 覆盖率匹配和 Markdown 报告生成。
+
+**适用场景**：本 SKILL Phase 2 的公开接口覆盖率评估中，用于计算 DEMO 目录的接口覆盖率。
+
+**调用方式**：
+
+```bash
+node "{{workspaceRoot}}/MCP/scripts/analyze-demo-coverage.cjs" \
+  --libroot "{{libroot}}" \
+  --output "{{outputDir}}/demo-coverage-report.md"
+```
+
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--libroot` | ✅ | 库源码根目录绝对路径（含 `library/` 和 `entry/src/main/ets/`） |
+| `--spec` | ❌ | 已有的 `interface-spec.json` 路径（由 `extract-interfaces.cjs` 生成） |
+| `--output` | ❌ | 输出 Markdown 报告路径，默认 `02-{库名}-Demo覆盖率报告.md` |
+| `--mode` | ❌ | 匹配模式：`auto`(默认) \| `ast` \| `regex` |
+| `--lib` | ❌ | 库名覆盖 |
+
+**自动完成**：
+1. 获取接口规格（从 `--spec` JSON 读取，或从 `libroot` 源码自动提取）
+2. 递归扫描 `entry/src/main/ets/` 下的 `.ets` 文件
+3. AST/正则双层匹配接口调用
+4. 直接生成最终 Markdown 覆盖率报告
+
+### 2. `script_arkts_analyze_xts_coverage` — XTS 覆盖率分析
+
+**脚本路径**: `MCP/scripts/analyze-xts-coverage.cjs`
+
+**功能**：分析 XTS 测试用例对接口的覆盖情况，一步完成接口提取、XTS 覆盖率匹配和报告生成。
+
+**适用场景**：本 SKILL Phase 2 的公开接口覆盖率评估中，用于计算 test 目录的接口覆盖率。
+
+**调用方式**：
+
+```bash
+node "{{workspaceRoot}}/MCP/scripts/analyze-xts-coverage.cjs" \
+  --libroot "{{libroot}}" \
+  --output "{{outputDir}}/xts-coverage-report.md"
+```
+
+**参数说明**：
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--libroot` | ✅* | 库源码根目录路径（含 `library/` 和 `entry/src/ohosTest/`） |
+| `--spec` | ✅* | 已有的 `interface-spec.json` 路径（与 `libroot` 二选一） |
+| `--output` | ❌ | 输出 Markdown 报告路径，默认 `03-{库名}-XTS覆盖率报告.md` |
+| `--mode` | ❌ | 匹配模式：`auto`(默认) \| `ast` \| `regex` |
+
+> `libroot` 与 `spec` 至少提供一个。提供 `spec` 时跳过接口提取步骤。
+
+**扫描范围**：`entry/src/ohosTest/` 下所有 `.ets` 和 `.ts` 测试文件。
+
+### 3. `script_extract_interfaces` — 接口规格提取
+
+**脚本路径**: `MCP/scripts/extract-interfaces.cjs`
+
+**功能**：从库源码提取公开接口规格，生成 JSON 格式的接口规格文件。
+
+**适用场景**：当需要手动补充接口规格时使用。本 SKILL 通常直接使用 `--spec` 参数传入已有 JSON。
+
+---
+
+## 在本 SKILL 中的使用方式
+
+### 覆盖率计算流程
+
+```
+Phase 1: 扫描测试文件和鸿蒙代码
+    ↓
+Phase 2: 调用 MCP 脚本计算覆盖率
+    ├── DEMO 覆盖率 → analyze-demo-coverage.cjs
+    │   （扫描 entry/src/main/ets/ 下的接口调用）
+    └── test 覆盖率 → analyze-xts-coverage.cjs
+        （扫描 entry/src/ohosTest/ 下的接口调用）
+    ↓
+Phase 3: 综合评分（结合 MCP 报告 + 手动检视项）
+    ↓
+Phase 4: 生成最终报告
+```
+
+### 脚本身份验证
+
+执行脚本后，检查退出码和输出文件：
+
+- 退出码 `0` → 成功，继续流程
+- 退出码非 `0` → 失败，回退到手工扫描流程
+
+### 脚本与手工结合的检视项
+
+MCP 脚本自动完成**接口覆盖率计算**（维度 1 的基础数据），但以下检视项仍需人工分析：
+
+| 维度 | 脚本自动 | 人工分析 |
+|------|----------|----------|
+| 公开接口覆盖率 | 覆盖率百分比（TC-01~TC-05 基础数据） | 边界场景、参数组合覆盖判定 |
+| 测试质量 | — | 断言质量、Mock 过度、负面测试等 |
+| 鸿蒙化特性测试 | — | 鸿蒙 API 调用测试、权限场景等 |
+| 测试分类覆盖 | — | 单元/集成/E2E 分类判断 |
+| 测试基础设施 | — | 框架配置、CI 集成等 |

package/vendor/Server/Skills/arkts-library-test-coverage-check/scripts/validate-skill.cjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+/**
+ * @tool validate-skill
+ * @description 校验 SKILL 目录是否符合 Agent Skills 规范，检查 frontmatter、结构、渐进式披露。跨平台（Windows/macOS/Linux），仅需 Node.js。
+ * @param skillDir: string - SKILL 目录绝对路径
+ * @hidden
+ *
+ * 用法:
+ *   # CLI 模式
+ *   node validate-skill.cjs /path/to/skill
+ *
+ *   # MCP Gateway 模式（第一个参数为 JSON 字符串）
+ *   node validate-skill.cjs '{"skillDir":"/path/to/skill"}'
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ── 参数解析（兼容 MCP Gateway JSON 模式与 CLI 模式） ──────
+
+function parseArgs(argv) {
+  if (argv.length === 0) return {};
+  const first = argv[0];
+  if (typeof first === 'string' && first.startsWith('{')) {
+    try { return JSON.parse(first); } catch (e) { return {}; }
+  }
+  return { skillDir: first };
+}
+
+// ── 输出统计 ─────────────────────────────────────────────
+
+let PASS = 0;
+let FAIL = 0;
+let WARNINGS = 0;
+
+function checkPass(msg) { console.log(`  ✅ ${msg}`); PASS += 1; }
+function checkFail(msg) { console.log(`  ❌ ${msg}`); FAIL += 1; }
+function checkWarn(msg) { console.log(`  ⚠️  ${msg}`); WARNINGS += 1; }
+
+// ── Frontmatter 解析 ─────────────────────────────────────
+
+function parseFrontmatter(content) {
+  const lines = content.split(/\r?\n/);
+  if (!lines[0] || lines[0].trim() !== '---') {
+    return { frontmatter: null, bodyLines: lines };
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    return { frontmatter: null, bodyLines: lines };
+  }
+  const fmLines = lines.slice(1, end);
+  const fm = {};
+  let currentKey = null;
+  for (const line of fmLines) {
+    const m = line.match(/^([a-zA-Z_][\w-]*):\s*(.*)$/);
+    if (m) {
+      currentKey = m[1];
+      fm[currentKey] = m[2].trim();
+    } else if (currentKey && /^\s+\S/.test(line)) {
+      fm[currentKey] += '\n' + line.trim();
+    }
+  }
+  return { frontmatter: fm, bodyLines: lines.slice(end + 1) };
+}
+
+// ── 主流程 ───────────────────────────────────────────────
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const skillDir = args.skillDir || '';
+
+  if (!skillDir) {
+    console.log('Usage: node validate-skill.cjs <skillDir>');
+    console.log('Error: skillDir parameter is required');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(skillDir) || !fs.statSync(skillDir).isDirectory()) {
+    console.log(`Error: Directory does not exist: ${skillDir}`);
+    process.exit(1);
+  }
+
+  console.log('=== SKILL 规范校验 ===');
+  console.log(`目录: ${skillDir}`);
+  console.log('');
+
+  // ─── 1. SKILL.md 存在性 ───
+  console.log('--- 1. 文件结构检查 ---');
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  if (fs.existsSync(skillFile) && fs.statSync(skillFile).isFile()) {
+    checkPass('SKILL.md 存在');
+  } else {
+    checkFail('SKILL.md 不存在');
+    console.log('无法继续校验，SKILL.md 是必需文件');
+    process.exit(1);
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf-8');
+  const { frontmatter, bodyLines } = parseFrontmatter(content);
+
+  // ─── 2. Frontmatter 检查 ───
+  console.log('');
+  console.log('--- 2. Frontmatter 检查 ---');
+
+  if (frontmatter) {
+    checkPass('YAML frontmatter 存在');
+  } else {
+    checkFail('缺少 YAML frontmatter（文件应以 --- 开头并以 --- 结束头部）');
+  }
+
+  const nameField = frontmatter ? String(frontmatter.name || '') : '';
+  if (nameField) {
+    checkPass(`name 字段存在: ${nameField}`);
+
+    // name 字符集校验
+    if (/^[a-z0-9]+(-[a-z0-9]+)*$/.test(nameField)) {
+      checkPass('name 字符集合规（仅小写字母/数字/连字符）');
+    } else {
+      checkFail('name 字符集不合规：应仅含 a-z/0-9/-，不能首尾连字符或连续连字符');
+    }
+
+    // name 长度校验
+    const nameLen = nameField.length;
+    if (nameLen >= 1 && nameLen <= 64) {
+      checkPass(`name 长度合规 (${nameLen} 字符)`);
+    } else {
+      checkFail(`name 长度不合规：应在 1-64 字符之间（当前 ${nameLen}）`);
+    }
+
+    // name 匹配目录名
+    const dirName = path.basename(path.resolve(skillDir));
+    if (nameField === dirName) {
+      checkPass(`name 匹配父目录名 (${dirName})`);
+    } else {
+      checkFail(`name 不匹配父目录名：name='${nameField}' vs 目录='${dirName}'`);
+    }
+  } else {
+    checkFail('name 字段缺失');
+  }
+
+  const descField = frontmatter ? String(frontmatter.description || '') : '';
+  if (descField) {
+    const descLen = descField.length;
+    if (descLen <= 1024) {
+      checkPass(`description 长度合规 (${descLen} 字符)`);
+    } else {
+      checkFail(`description 过长：应 ≤1024 字符（当前 ${descLen}）`);
+    }
+  } else {
+    checkFail('description 字段缺失或为空');
+  }
+
+  if (frontmatter && frontmatter.license) {
+    checkPass('license 字段存在');
+  } else {
+    checkWarn('license 字段缺失（推荐添加）');
+  }
+
+  if (frontmatter && frontmatter.metadata) {
+    checkPass('metadata 字段存在');
+  } else {
+    checkWarn('metadata 字段缺失（推荐添加 author/version）');
+  }
+
+  // ─── 3. Body 检查 ───
+  console.log('');
+  console.log('--- 3. Body 内容检查 ---');
+
+  const bodyLineCount = bodyLines.length;
+  if (bodyLineCount <= 500) {
+    checkPass(`body 行数合规 (${bodyLineCount} 行, ≤500)`);
+  } else {
+    checkWarn(`body 行数较多 (${bodyLineCount} 行，推荐 < 500，考虑拆分到 references/)`);
+  }
+
+  // 检查任务参数表
+  if (/任务参数|## .*参数|\|\s*参数/.test(content)) {
+    checkPass('包含任务参数说明');
+  } else {
+    checkWarn('未找到任务参数表（推荐添加）');
+  }
+
+  // 检查工作流程概览
+  if (/工作流程概览|Phase|## .*流程/.test(content)) {
+    checkPass('包含工作流程概览');
+  } else {
+    checkWarn('未找到工作流程概览（推荐添加）');
+  }
+
+  // 检查 MCP 工具引用
+  if (/script_|gateway_|kb-server_|MCP\/scripts/i.test(content)) {
+    checkPass('引用了 MCP 工具或脚本');
+  } else {
+    checkWarn('未引用任何 MCP 工具（推荐复用 MCP 能力）');
+  }
+
+  // ─── 4. 渐进式披露检查 ───
+  console.log('');
+  console.log('--- 4. 渐进式披露检查 ---');
+
+  const refsDir = path.join(skillDir, 'references');
+  if (fs.existsSync(refsDir) && fs.statSync(refsDir).isDirectory()) {
+    const refFiles = fs.readdirSync(refsDir)
+      .filter((f) => f.endsWith('.md') && fs.statSync(path.join(refsDir, f)).isFile());
+    checkPass(`references/ 目录存在 (${refFiles.length} 个文档)`);
+
+    // 检查引用深度（一层）
+    const nestedDirs = fs.readdirSync(refsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory()).length;
+    if (nestedDirs === 0) {
+      checkPass('references 保持一层深度');
+    } else {
+      checkFail(`references 存在嵌套子目录 (${nestedDirs} 个)，应保持一层深度`);
+    }
+  } else {
+    checkWarn('无 references/ 目录（详细内容建议拆分到此目录）');
+  }
+
+  const assetsDir = path.join(skillDir, 'assets');
+  if (fs.existsSync(assetsDir) && fs.statSync(assetsDir).isDirectory()) {
+    checkPass('assets/ 目录存在');
+  } else {
+    checkWarn('无 assets/ 目录（如需模板/资源可添加）');
+  }
+
+  const scriptsDir = path.join(skillDir, 'scripts');
+  if (fs.existsSync(scriptsDir) && fs.statSync(scriptsDir).isDirectory()) {
+    checkPass('scripts/ 目录存在');
+  } else {
+    checkWarn('无 scripts/ 目录（如需可执行脚本可添加）');
+  }
+
+  // 检查文件引用使用相对路径
+  const absRefs = (content.match(/\]\(\/[^)]+\)/g) || []).length;
+  if (absRefs === 0) {
+    checkPass('文件引用使用相对路径');
+  } else {
+    checkFail(`发现 ${absRefs} 个绝对路径引用，应使用相对路径`);
+  }
+
+  // ─── 5. 总结 ───
+  console.log('');
+  console.log('=== 校验总结 ===');
+  console.log(`  ✅ 通过: ${PASS}`);
+  console.log(`  ❌ 失败: ${FAIL}`);
+  console.log(`  ⚠️  警告: ${WARNINGS}`);
+  console.log('');
+
+  if (FAIL === 0) {
+    console.log('ALL CHECKS PASSED');
+    process.exit(0);
+  } else {
+    console.log(`VALIDATION FAILED: ${FAIL} 个必须修复的问题`);
+    process.exit(1);
+  }
+}
+
+main();