# Node Version Compatibility Tester Yashu

> 自动测试指定技能在不同Node.js LTS版本下的兼容性。激活条件：用户消息须包含以下关键词之一:`测试Node版本兼容性`、`多版本Node测试`、`Node版本兼容性测试`。

- Skill: `steelan9199/node-version-compatibility-tester-yashu` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds add steelan9199/node-version-compatibility-tester-yashu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/steelan9199/node-version-compatibility-tester-yashu/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: steelan9199 (https://skillmd.com/u/steelan9199)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/steelan9199/node-version-compatibility-tester-yashu

---


## 功能概述

通用 Node.js 版本兼容性测试工具。对任意用户指定技能，在 3 个 Node.js LTS 版本（18.20.8 / 20.20.1 / 动态查询的最新 LTS）下，**对该技能的所有功能脚本逐一执行真实功能测试**，输出兼容性矩阵报告。

### 什么是"所有功能"

- 读取目标技能的 **SKILL.md**
- 找到「全脚本索引清单」表格，里面列出了该技能的所有功能脚本
- **每个脚本都要测试**，不能遗漏

## 触发映射

| 用户输入触发词                                             | AI 执行动作              |
| ---------------------------------------------------------- | ------------------------ |
| "测试Node版本兼容性" / "多版本Node测试" / "技能兼容性测试" | 按【兼容性测试模式】执行 |

## 环境说明

| 项目              | 说明                                                                     |
| ----------------- | ------------------------------------------------------------------------ |
| 依赖工具          | NVM（Node Version Manager）                                              |
| Node 版本         | 测试 3 个 LTS 版本：18.20.8 / 20.20.1 / **动态查询的当前最新 LTS**       |
| Shell             | PowerShell 5（Windows）/ bash（macOS/Linux）                             |
| 脚本执行          | 本技能为**纯文档型 Skill**，不包含可执行脚本目录，所有命令由 AI 直接运行 |
| $SKILL_DIR        | `d:\skill\private-skills\.trae\skills\node-version-compatibility-tester` |
| $TARGET_SKILL_DIR | 用户指定的被检测技能目录                                                 |

## 执行流程（强制遵循，逐条执行，禁止跳步）

> ⛔ **最高优先级规则**：以下 10 步必须**逐条执行**。每完成一步，才能进入下一步。**严禁合并步骤、跳过步骤、或用"常识"替代步骤。**

```
第1步：nvm --version → 确认 NVM 已安装
        ↓ 未安装 → 提示用户安装 NVM，中断
第2步：读取 references/node-version-query.md
        ↓ 这一步不可跳过！它定义了如何查询和提取最新 LTS 版本号
第3步：nvm list available → 查询远程可用的 Node.js 版本
        ↓ 必须执行此命令，禁止用 nvm list 替代！
第4步：从 nvm list available 的输出中提取最新 LTS 版本号
        ↓ 按 node-version-query.md 中的规则提取（第 2 列 LTS 列第一行）
        ↓ 记下这个版本号，例如 24.18.0
第5步：nvm list → 检查本机是否已安装三个版本
        ↓ 三个版本 = 18.20.8 / 20.20.1 / 第4步提取的最新 LTS
        ↓ 有缺失 → 立即中断，告知用户缺失的版本号和安装命令
第6步：读取目标技能的 SKILL.md → 提取「全脚本索引清单」
        ↓ 获取所有功能脚本列表，全部都要测试
第7步：nvm use <版本> → 依次切换到 18.20.8 / 20.20.1 / 最新 LTS
第8步：在每个版本下，安装依赖并执行所有功能脚本
        ↓ 参考 test-execution-guide.md 的 4 步 SOP
第9步：记录每个版本 × 每个功能的测试结果
第10步：生成兼容性测试报告
```

### 第 3-4 步的详细说明（关键！这是最容易出错的步骤）

**为什么必须用 `nvm list available` 而不是 `nvm list`？**

| 命令                 | 作用                                | 问题                                              |
| -------------------- | ----------------------------------- | ------------------------------------------------- |
| `nvm list`           | 列出**本机已安装**的版本            | 看不到远程的最新 LTS；如果最新 LTS 没安装就看不到 |
| `nvm list available` | 列出**远程 Node.js 官方发布的**版本 | ✅ 能获取真正的最新 LTS 版本号                    |

> ❌ **错误做法**：`nvm list` → 看到当前在用 24.18.0 → 认为"24.18.0 就是最新 LTS"
>
> ✅ **正确做法**：`nvm list available` → 解析输出获取 LTS 列版本号 → 得到 **真正的最新 LTS**

**`nvm list available` 输出示例（Windows）：**

```
|   CURRENT    |     LTS      |  OLD STABLE  | OLD UNSTABLE |
|--------------|--------------|--------------|--------------|
|    26.4.0    |   24.18.0    |   0.12.18    |   0.11.16    |
```

→ 跳过表头，取第一行数据**第 2 列（LTS 列）** = **24.18.0**，这就是最新 LTS。

## 全局前置条件

| 前置条件             | 检查方式        | 缺失时处理                                                                                              |
| -------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
| 本机已安装 NVM       | `nvm --version` | 提示用户安装 NVM                                                                                        |
| 3 个测试版本均已安装 | `nvm list`      | 见 [references/node-version-query.md](references/node-version-query.md) 第「最新 LTS 版本缺失处理规则」 |

> 3 个测试版本中前 2 个为固定版本（18.20.8 / 20.20.1），第 3 个最新 LTS 需通过 NVM 动态查询。**NVM 查询规则、最新 LTS 缺失处理**详见 [references/node-version-query.md](references/node-version-query.md)。

## 【兼容性测试模式】执行步骤

| 步骤 | 执行动作       | 必须执行的命令 / 操作（按顺序）                                                                                                                                     | 详细参考                                                      |
| ---- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| 1    | 查询最新 LTS   | ① 读取 `references/node-version-query.md`；② 运行 `nvm list available`；③ 从输出提取最新 LTS 版本号（第 2 列 LTS 列第一行）；④ 运行 `nvm list` 确认三个版本均已安装 | [node-version-query.md](references/node-version-query.md)     |
| 2    | 读取技能文档   | 读取目标技能的 SKILL.md，提取「全脚本索引清单」表格                                                                                                                 | —                                                             |
| 3    | 遍历所有功能   | 对清单中的**每一个功能脚本**，在 3 个 Node 版本下分别执行                                                                                                           | —                                                             |
| 4    | 切换 Node 版本 | 运行 `nvm use <version>` 切换到对应 Node.js 版本                                                                                                                    | —                                                             |
| 5    | 执行功能测试   | `cd` 到技能 scripts 目录；`npm install`；按目标技能文档构造参数文件；执行脚本                                                                                       | [test-execution-guide.md](references/test-execution-guide.md) |
| 6    | 记录测试结果   | 将每个版本 × 每个功能的测试结果（✅通过 / ❌失败 + 错误信息）记录到内存                                                                                             | —                                                             |
| 7    | 生成报告       | 汇总所有版本的测试结果，生成兼容性测试报告                                                                                                                          | 见下方「输出结果」                                            |

> ⛔ **步骤 1 的四个子步骤必须全部完成，不可跳过任何一个。尤其是 `nvm list available`，这是获取最新 LTS 版本号的唯一可靠来源。**
>
> 实际运行测试的完整 SOP（4 步流程、测试参数构造、凭证处理、授权保护处理）详见 [references/test-execution-guide.md](references/test-execution-guide.md)。

### 测试范围规则（强制）

- **必须测试所有功能**：不能跳过任何一个功能脚本
- **不能只看 package.json 的 engines 字段**：即使 engines 指定了版本，也要实际运行测试
- **旧测试文档无效**：不要依赖历史测试结果，每次都要重新执行

## 公共规则

| 规则                    | 说明                                                                                                                                                  |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **禁止 `node --check`** | 必须对每个功能进行**真实功能测试**，仅做语法检查不算通过                                                                                              |
| **执行前必读文档**      | 在测试目标技能的每个功能之前，必须先读取该技能的 SKILL.md 学习调用方式，禁止假设命令格式                                                              |
| **凭证需求询问**        | 对需要 API 凭证的功能，先读取 `$TARGET_SKILL_DIR/.env` 获取凭证；若 `.env` 不存在，则终止任务并使用 `AskUserQuestion` 向用户索要凭证                  |
| **授权保护禁止绕过**    | 检测到目标技能有授权保护信号（license-key.txt、免费试用限制等）→ 立即终止该功能测试并标记「跳过（授权保护）」，**禁止用 curl/Invoke-RestMethod 绕过** |
| **多版本测试建议**      | 总执行次数 ≥ 12 时优先用总控脚本；多版本切换后必先 smoke test 再全量执行                                                                              |

> 「公共规则」的实战经验与踩坑案例（总控脚本策略、Smoke Test 优先、瞬态锁识别、脚本成功 ≠ 业务成功）详见 [references/battle-experiences.md](references/battle-experiences.md)。

## 全局错误处理

| 错误场景                                                 | 错误表现                              | 处理方式                                                                                                                            |
| -------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| nvm 未安装                                               | 执行 `nvm list` 报错                  | 提示用户安装 NVM                                                                                                                    |
| 当前最新 LTS 版本未安装                                  | `nvm list` 中没有当前最新 LTS 版本    | **立即中断测试**，告知用户具体版本号，并提供 `nvm install x.y.z` 命令                                                               |
| 其他测试版本未安装                                       | `nvm list` 中没有用户指定的 Node 版本 | 询问用户是否安装对应版本，或者更换测试版本                                                                                          |
| Node 版本切换失败                                        | `nvm use <version>` 返回非零退出码    | 检查 nvm 配置，重试切换，或跳过该版本                                                                                               |
| 技能运行报错                                             | 测试过程中技能执行失败                | 记录完整错误信息，继续测试其他版本                                                                                                  |
| 飞书 API 瞬态锁（code 1254291 / `LockNotObtainedError`） | HTTP 响应错误但脚本正常退出           | 等待 3 秒后重试 1 次，仍失败则按业务错误处理（详见 [经验 3](references/battle-experiences.md#经验-3飞书-api-瞬态锁冲突识别与处理)） |

## 输出结果

**测试结果表格说明**：

- 列名（功能1、功能2...）来自目标技能的「全脚本索引清单」
- 每个单元显示 ✅（通过）或 ❌（失败）
- 总测试次数 = Node版本数 × 功能数量（例如 3×5=15 次）

**成功时输出示例：**

```
✅ Node.js版本兼容性测试完成

📊 测试结果汇总：
| Node.js版本 | get-tenant-access-token | feishu-to-markdown | markdown-to-feishu | url-to-document-id | clear_temp | 状态 |
|------------|------------------------|-------------------|-------------------|-------------------|------------|------|
| 18.20.8    | ✅ 通过               | ✅ 通过           | ✅ 通过           | ✅ 通过           | ✅ 通过    | 完全兼容 |
| 20.20.1    | ✅ 通过               | ✅ 通过           | ✅ 通过           | ✅ 通过           | ✅ 通过    | 完全兼容 |
| 24.18.0    | ✅ 通过               | ✅ 通过           | ✅ 通过           | ✅ 通过           | ✅ 通过    | 完全兼容 |

✅ 结论：该技能完美支持所有测试的Node.js LTS版本

📝 下一步：可以根据测试结果更新技能的环境要求说明
```

**失败时输出示例：**

```
❌ Node.js版本兼容性测试发现问题

📊 测试结果汇总：
| Node.js版本 | get-tenant-access-token | feishu-to-markdown | markdown-to-feishu | url-to-document-id | clear_temp | 状态 |
|------------|------------------------|-------------------|-------------------|-------------------|------------|------|
| 18.20.8    | ✅ 通过               | ✅ 通过           | ❌ 失败           | ✅ 通过           | ✅ 通过    | 部分兼容 |
| 20.20.1    | ✅ 通过               | ✅ 通过           | ✅ 通过           | ✅ 通过           | ✅ 通过    | 完全兼容 |
| 24.18.0    | ✅ 通过               | ✅ 通过           | ❌ 失败           | ✅ 通过           | ✅ 通过    | 部分兼容 |

❌ 问题说明：markdown-to-feishu 在 Node.js 18.20.8 和 24.18.0 版本下失败
错误信息：Error: Cannot find module 'some-module'

解决建议：检查技能依赖是否兼容这些 Node.js 版本，或者更新依赖配置
```

## References 索引

| 文档                                                                     | 作用                                                                            |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| [references/node-version-query.md](references/node-version-query.md)     | 必测版本号、NVM 查询规则、最新 LTS 缺失处理                                     |
| [references/test-execution-guide.md](references/test-execution-guide.md) | 实际运行测试 4 步 SOP、测试参数构造、凭证处理策略、授权保护处理规则             |
| [references/usage-guide.md](references/usage-guide.md)                   | 通用使用模板、推荐提示词、典型示例                                              |
| [references/battle-experiences.md](references/battle-experiences.md)     | 4 篇实战经验（总控脚本、Smoke Test、瞬态锁识别、脚本成功 ≠ 业务成功）及使用指南 |