Index of every page on this site: llms.txt
All skills
steelan9199 avatar

/node-version-compatibility-tester-yashu

@9e01957
Run it yourself

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

  • 5 files
  • 43.6 KB
  • Updated 4 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/steelan9199/wechat-publisher/node-version-compatibility-tester-yashu

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesbattle-experiences.md

≈3.7k tokens on demand. Your agent reads this file only when SKILL.md points to it.

实战经验 / 踩坑记录

加载时机:执行测试过程中遇到错误、评估测试规模、决定是否插入 smoke test 阶段时加载本文件。

⚠️ 本章定位:补充提示,不修改任何现有强制 SOP。当 AI 在真实测试中遇到与本章相似的场景时,应优先参考这里的诊断与处理流程。如果经验与现有 SOP 冲突,以 SOP 为准并把矛盾点反馈给用户。

经验 1:测试规模与总控脚本策略

背景

测试一个具备 N 个功能的技能在 M 个 Node 版本下的兼容性,理论执行次数 = N × M。常见的 N 与 M 组合:

技能复杂度 N(功能数) M(Node 版本数) 总执行次数
简单(CRUD 单条) 4-6 3 12-18
中等(CRUD+批量) 12-20 3 36-60
复杂(多模块) 30+ 3 90+

当总执行次数 ≥ 12 时,逐条手工调用会产生两个问题:

  1. 错误处理粒度粗:用户通常会附带「如果测试过程中发生任何错误,直接终止测试」规则,AI 必须在「脚本错误」「业务错误」「瞬态错误」之间做精细判断
  2. 上下文压力:每个工具调用占用 token,76 次串行执行会快速耗尽预算

现象

AI 选择「逐条串行调用脚本」模式,结果:

  • 前 30 次一切顺利,第 31 次遇到一个真错误,但被另一个瞬态错误(如 API 锁、限频、网络抖动)掩盖
  • AI 无法精确判断"该立即终止"还是"该重试"
  • 测试报告里把"瞬态锁错误"和"Node 不兼容错误"混在一起,难以诊断

诊断

把 19 个场景 × 3 个版本 = 57 次执行拆解后,发现:

  • 大部分执行是幂等读(list/get),可以一次性批量执行
  • 真正的"创建/修改/删除"是有副作用的,需要单独隔离测试
  • 错误来源大致分三层:①Node 运行时 ②脚本逻辑 ③远端 API 瞬态

解决

采用「总控测试脚本 + 分层执行」策略:

  1. 第一层(批量读):在当前 Node 版本下,1 个 shell 命令 chain 跑完所有 get/list 类接口(如 node field/list.js; node record/get.js; node table/list.js;),每个脚本独立输出 JSON,整体判断 code === 0
  2. 第二层(隔离写):对每个 create/update/delete/batch-* 类脚本,单独建独立 shell 命令,每个命令执行后立即验证副作用(再 list 一次确认变更生效)
  3. 第三层(错误分类):总控脚本中定义三类终止条件:
    • Node 运行时错误(如 SyntaxError, Cannot find module)→ 立即终止,标记该 Node 版本不兼容
    • 脚本逻辑错误(如返回 code != 0 且非 1254291/99991663 等已知瞬态码)→ 立即终止
    • 远端 API 瞬态错误 → 等待 3 秒后重试 1 次,仍失败则按"脚本逻辑错误"处理

教训

# 教训
1 总执行次数 ≥ 12 时,优先用总控脚本,而不是逐条调用
2 拆"读"和"写"两层执行,先批量读验证连通性,再隔离写验证业务
3 错误处理必须三分类(Node / 脚本 / API),不能一刀切终止
4 把"如果出错就终止"的规则具体化为「哪种错、怎么终止、重试几次」

经验 2:Smoke Test 优先策略

背景

在 3 个 Node LTS 版本(18.20.8 / 20.20.1 / 动态查询的最新 LTS)下测试同一个技能时,如果一上来就全量执行 19 场景 × 3 版本 = 57 次,会在第一个 Node 版本上花费大量时间,而其实兼容性测试的关键问题只有两个:

  • 该 Node 版本能否解析并执行目标脚本?
  • 该 Node 版本能否支持目标脚本用到的 Node API(如 fetch、fs/promises、ES Modules)?

现象

AI 在 Node 18.20.8 上完整跑完 19 个场景,发现 3 个场景因为 Node 18 不支持某个 API 而失败。但其实 18.20.8 早在 smoke test 阶段就已经暴露问题,后面的 18 次执行是浪费。

诊断

Node 18.20.8 是 feishu-bitable 技能声明的最低支持版本,理论上应该兼容。但脚本里用了某个仅在 Node 19+ 引入的 API,导致 smoke test 阶段就会报错。提前 1 次失败能节省 18 次无效执行。

解决

在「切换 Node 版本」与「全量执行测试」之间插入 smoke test 阶段:

阶段 动作 目的
切换版本后 选 1 个最简单的读接口(如 field/list、record/get),1 个 shell 命令执行 验证 Node 解析、ES Module 加载、fetch 调用
smoke 通过 进入「全量测试」阶段 节省 18+ 次无效执行
smoke 失败 立即记录该 Node 版本不兼容,跳过该版本的剩余测试,继续测试其他版本 不浪费时间在已知失败的版本上

教训

# 教训
1 多版本测试必加 smoke test 阶段,不要直接进入全量执行
2 smoke test 选 1 个最简单、最稳定的读接口(list/get 类),不要选 create/delete
3 smoke test 失败 = 该 Node 版本不兼容,跳过该版本剩余测试,不浪费 token
4 smoke test 通过 ≠ 全量测试一定通过,仍要观察后续阶段的错误

经验 3:飞书 API 瞬态锁冲突识别与处理

背景

飞书 OpenAPI(包括多维表格 Bitable、文档 Docx、通讯录 Contact 等)的服务端对同一资源有写入锁机制。短时间内(毫秒级到秒级)多次对同一 app_token / table_id 发起 create / update / delete 请求,后到的请求会收到 LockNotObtainedError(code 1254291)。

这个错误在 Node 版本兼容性测试中极易误判:

  • 它出现在「Node 版本 A」上,看起来像是 A 不兼容
  • 但实际是测试编排问题(3 个 Node 版本并行 create,触发锁竞争)
  • 如果 AI 严格按「遇到错误就终止」执行,会错误标记 A 不兼容

现象

测试 3 个 Node 版本 × 数据表批量 CRUD 的 create 操作时:

  • Node 18.20.8 ✅ 成功
  • Node 20.20.1 ❌ 返回 code: 1254291, msg: "LockNotObtainedError"
  • Node <最新LTS> ✅ 成功

如果 AI 立即终止,会得出"20.20.1 不兼容"的错误结论。

诊断

通过三个信号判断是瞬态锁而非Node 不兼容:

  1. 错误码特征:1254291 / LockNotObtainedError / code: 1254291 / 错误信息含"lock"或"加锁"
  2. 行为特征:脚本正常解析、正常发请求、正常解析响应,只是 HTTP 响应是错误
  3. 重试特征:等待 3-5 秒后重试,通常立即成功(因为锁是短时持有的)

与 Node 不兼容的对比:

维度 飞书 API 瞬态锁 Node 运行时不兼容
错误码 1254291 / LockNotObtainedError SyntaxError / MODULE_NOT_FOUND / TypeError
错误位置 HTTP 响应体 Node 进程 stdout/stderr
进程退出码 0 非 0
重试后 通常成功 必然失败
跨版本相关性 与 Node 版本无关,跨版本随机出现 特定 Node 版本必现

解决

# 飞书 API 瞬态错误的标准处理流程(伪代码)
$result = node table/batch-create.js --parameter-file-path params.json
if ($result.code -eq 0) {
    # 成功
} elseif ($result.code -eq 1254291 -or $result.msg -match "Lock") {
    # 判定为飞书 API 瞬态锁
    Start-Sleep -Seconds 3
    $result = node table/batch-create.js --parameter-file-path params.json
    if ($result.code -eq 0) {
        # 重试成功,记录"瞬态锁重试 1 次"在报告中
    } else {
        # 重试仍失败,按"业务错误"处理
    }
} else {
    # 其他业务错误,立即终止
}

教训

# 教训
1 遇到 LockNotObtainedError (code 1254291) 不要立即终止,先重试 1 次
2 3 个 Node 版本并行执行 create 类操作是高危动作,会触发飞书侧锁竞争
3 优化方案:3 个 Node 版本串行执行 create 类操作,每版本之间留 2-3 秒间隔
4 报告里要明确区分"瞬态错误重试通过" vs "真实错误终止",方便后续审计
5 同样的瞬态错误模式适用于其他云 API(钉钉、企微、Google API 等),关键是识别「服务端锁」特征

经验 4:「脚本成功 ≠ 业务成功」普适原则

背景

Node 兼容性测试中,AI 经常把"脚本能跑通"和"业务能跑通"混为一谈。脚本层面的成功标准是"进程退出码 = 0 且 stdout 是合法 JSON",业务层面的成功标准是"JSON 中 code: 0 且 msg: success"。

现象

某次测试中,AI 把 media/upload.js 的输出当作"成功":

{
  "code": 0,
  "msg": "文件已上传,返回已有file_token",
  "data": { "file_token": "Lr7Abl8nRof3D6xbp60caEiNnfg" }
}

但这是第二次上传同一文件触发的去重逻辑(脚本读到磁盘哈希匹配,返回已有 token)。如果测试目的是"验证上传功能在新 Node 版本上工作",这次执行没有真正测试上传路径,只是验证了去重查询路径。

诊断

Node 兼容性测试的目的是"验证技能脚本在 3 个 Node 版本下都能跑通",而不是"验证业务行为":

  • ✅ 跑通 = 进程正常退出 + JSON 格式正确 + code === 0
  • ❌ 跑通 ≠ 业务结果符合预期

如果同一脚本在 3 个 Node 版本上都返回相同 file_token,说明 3 次执行走的都是去重路径,没有真正测试上传。这是测试设计漏洞,不是 Node 兼容性问题。

解决

判定脚本是否真的"跑通业务"的三步法:

  1. 执行前:记录脚本预期行为(创建/读取/更新/删除)
  2. 执行后:对比实际行为与预期行为
  3. 跨版本对比:3 个 Node 版本的输出如果完全一致,要警惕是「公共缓存」或「去重逻辑」

对兼容性测试的具体建议:

操作类型 跨版本一致性是否合理 异常信号
get / list ✅ 合理(读操作结果应一致) 无
create ❌ 不应一致(每次应产生新 ID) 3 个版本返回相同 ID = 测试设计有缓存
update ❌ 不应一致(每次应产生新版本号) 3 个版本返回相同 version = 没真正改
delete ⚠️ 部分合理(删除结果应一致) 如果 delete 报错但 3 个版本都报同样错 = 真问题

教训

# 教训
1 判定测试通过前,必须同时检查「进程退出码」和「业务 code」,二者都 0 才算真通过
2 跨版本完全一致的输出要警惕,特别是 create 类操作,可能是缓存/去重逻辑绕过真实测试路径
3 对于去重类逻辑(文件哈希、URL 缓存等),兼容性测试不是它的测试目标,应单独写「去重测试」场景
4 测试报告中应明确记录每次执行的"业务行为"(如"创建了 table_id=tblXxx"),方便审计
5 这条原则适用于所有需要"功能性验证"的兼容性测试,不限于 Node 版本

经验使用指南

如何在真实测试中引用本章

  1. 遇到错误时:先查「经验 3 飞书 API 瞬态锁」→ 再查「经验 4 脚本成功 ≠ 业务成功」→ 最后查现有 SOP 的「错误处理」表
  2. 测试规模评估时:参考「经验 1 测试规模与总控脚本」决定是否启用总控脚本
  3. 多版本切换前:参考「经验 2 Smoke Test 优先」决定是否插入 smoke test 阶段

与现有 SOP 的关系

现有 SOP 章节 本章补充关系
触发映射 无补充
必须测试的 Node 版本号 无补充
【兼容性测试模式】执行步骤 经验 1/2 提供「总控脚本」「smoke test」的参考实现
强制遵守的执行测试规范 经验 4 补充「判定真通过的细化标准」
授权保护处理规则 无补充
错误处理表 经验 3 补充「瞬态锁重试」处理(不替换原表)
如何使用这个 Skill 无补充

反馈与迭代

如果在新场景下发现本章经验不够用,或经验本身有错误,优先反馈给用户而不是自行修改。修改此类"实战经验"应走"提案 → 用户确认 → 更新"流程,避免污染沉淀的经验。

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 9e01957. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 4 months ago

README badge

README badge for steelan9199/wechat-publisher/node-version-compatibility-tester-yashu