实战经验 / 踩坑记录
加载时机:执行测试过程中遇到错误、评估测试规模、决定是否插入 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 时,逐条手工调用会产生两个问题:
- 错误处理粒度粗:用户通常会附带「如果测试过程中发生任何错误,直接终止测试」规则,AI 必须在「脚本错误」「业务错误」「瞬态错误」之间做精细判断
- 上下文压力:每个工具调用占用 token,76 次串行执行会快速耗尽预算
现象
AI 选择「逐条串行调用脚本」模式,结果:
- 前 30 次一切顺利,第 31 次遇到一个真错误,但被另一个瞬态错误(如 API 锁、限频、网络抖动)掩盖
- AI 无法精确判断"该立即终止"还是"该重试"
- 测试报告里把"瞬态锁错误"和"Node 不兼容错误"混在一起,难以诊断
诊断
把 19 个场景 × 3 个版本 = 57 次执行拆解后,发现:
- 大部分执行是幂等读(list/get),可以一次性批量执行
- 真正的"创建/修改/删除"是有副作用的,需要单独隔离测试
- 错误来源大致分三层:①Node 运行时 ②脚本逻辑 ③远端 API 瞬态
解决
采用「总控测试脚本 + 分层执行」策略:
- 第一层(批量读):在当前 Node 版本下,1 个 shell 命令 chain 跑完所有
get/list类接口(如node field/list.js; node record/get.js; node table/list.js;),每个脚本独立输出 JSON,整体判断code === 0 - 第二层(隔离写):对每个
create/update/delete/batch-*类脚本,单独建独立 shell 命令,每个命令执行后立即验证副作用(再list一次确认变更生效) - 第三层(错误分类):总控脚本中定义三类终止条件:
- Node 运行时错误(如
SyntaxError,Cannot find module)→ 立即终止,标记该 Node 版本不兼容 - 脚本逻辑错误(如返回
code != 0且非 1254291/99991663 等已知瞬态码)→ 立即终止 - 远端 API 瞬态错误 → 等待 3 秒后重试 1 次,仍失败则按"脚本逻辑错误"处理
- Node 运行时错误(如
教训
| # | 教训 |
|---|---|
| 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 不兼容:
- 错误码特征:
1254291/LockNotObtainedError/code: 1254291/ 错误信息含"lock"或"加锁" - 行为特征:脚本正常解析、正常发请求、正常解析响应,只是 HTTP 响应是错误
- 重试特征:等待 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 兼容性问题。
解决
判定脚本是否真的"跑通业务"的三步法:
- 执行前:记录脚本预期行为(创建/读取/更新/删除)
- 执行后:对比实际行为与预期行为
- 跨版本对比: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 版本 |
经验使用指南
如何在真实测试中引用本章
- 遇到错误时:先查「经验 3 飞书 API 瞬态锁」→ 再查「经验 4 脚本成功 ≠ 业务成功」→ 最后查现有 SOP 的「错误处理」表
- 测试规模评估时:参考「经验 1 测试规模与总控脚本」决定是否启用总控脚本
- 多版本切换前:参考「经验 2 Smoke Test 优先」决定是否插入 smoke test 阶段
与现有 SOP 的关系
| 现有 SOP 章节 | 本章补充关系 |
|---|---|
| 触发映射 | 无补充 |
| 必须测试的 Node 版本号 | 无补充 |
| 【兼容性测试模式】执行步骤 | 经验 1/2 提供「总控脚本」「smoke test」的参考实现 |
| 强制遵守的执行测试规范 | 经验 4 补充「判定真通过的细化标准」 |
| 授权保护处理规则 | 无补充 |
| 错误处理表 | 经验 3 补充「瞬态锁重试」处理(不替换原表) |
| 如何使用这个 Skill | 无补充 |
反馈与迭代
如果在新场景下发现本章经验不够用,或经验本身有错误,优先反馈给用户而不是自行修改。修改此类"实战经验"应走"提案 → 用户确认 → 更新"流程,避免污染沉淀的经验。