node-version-compatibility-tester-yashu

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

功能概述

通用 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、瞬态锁识别、脚本成功 ≠ 业务成功）及使用指南