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 第「最新 LTS 版本缺失处理规则」 |

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

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

| 步骤 | 执行动作 | 必须执行的命令 / 操作（按顺序） | 详细参考 | | ---- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | 1 | 查询最新 LTS | ① 读取 references/node-version-query.md；② 运行 nvm list available；③ 从输出提取最新 LTS 版本号（第 2 列 LTS 列第一行）；④ 运行 nvm list 确认三个版本均已安装 | 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 | | 6 | 记录测试结果 | 将每个版本 × 每个功能的测试结果（✅通过 / ❌失败 + 错误信息）记录到内存 | — | | 7 | 生成报告 | 汇总所有版本的测试结果，生成兼容性测试报告 | 见下方「输出结果」 |

⛔ 步骤 1 的四个子步骤必须全部完成，不可跳过任何一个。尤其是 nvm list available，这是获取最新 LTS 版本号的唯一可靠来源。

实际运行测试的完整 SOP（4 步流程、测试参数构造、凭证处理、授权保护处理）详见 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。

全局错误处理

| 错误场景 | 错误表现 | 处理方式 | | -------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | 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） |

输出结果

测试结果表格说明：

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