| 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。
全局前置条件
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 索引
