维护/修复现有 k6 测试脚本时：安全地收紧阈值、迁移版本…

当用户要求修复失败的 k6 测试、收紧阈值、迁移 k6 版本、服务变更后更新脚本、重构或按最佳实践改进脚本时使用。

适用场景

解决思路

1. 先判断脚本来源：GCk6 测试 URL 或 ID 视为云托管脚本；文件路径视为本地脚本。
2. 对云托管脚本，在触碰前先阅读 k6-manage，并按 §5 安全编辑流程操作：GET → backup → edit → validate → PUT → 通过 sha256 验证。
3. 对本地磁盘脚本，直接读取和编辑；在展示前必须验证。
4. 使用 gcx 作为访问 Grafana Cloud API 的唯一工具。
5. 检查 mcp-k6 工具是否可用，优先使用 validate_script 和 get_documentation；若不可用，回退到 k6 x docs。
6. 使用 k6 CLI 做本地验证：k6 inspect、k6 run。
7. 对每一次编辑都运行验证循环，修复并重跑直到通过，绝不展示或 PUT 未验证脚本。
8. 验证循环第 1 步 Parse-check：运行 k6 inspect <script>，捕获语法错误、无效 options、坏 imports；对所有类型包括 browser 测试有效（无需浏览器）；若 mcp-k6 可用，也运行 validate_script。
9. 验证循环第 2 步 Local smoke：在非 browser 且服务可达时，运行 k6 run --vus 1 --iterations 1 <script>。
10. 验证循环第 3 步：分类变更，并按矩阵验证；配方见 references/verification.md。
11. 验证循环第 4 步：云托管脚本按 k6-manage §5 安全编辑配方应用：GET → backup → edit → validate → PUT as application/octet-stream → sha256-verify。
12. 对每个拟议变更做行为感知变更控制：判断它是否改变测试运行时行为。
13. 语法类变更（行为不变）：k6 runtime 产生相同 metrics、pass/fail 结果和 endpoints；例如重命名变量、let → const、删除未使用 imports、更新注释、重格式化；直接应用。
14. 行为类变更（行为不同）：任何影响 metrics、pass/fail、timing、请求目标或 load shape 的变更；例如改 threshold 值、添加 sleep()、更新 endpoint URL、重写 check、修改 scenario、新增 threshold；始终作为 diff 呈现并附理由，且要求确认。
15. 将行为类判定阈值故意设低；如有疑问，按行为类处理并询问；看似 trivial 的 threshold 变更可能级联到 CI gates、SLO 计算和告警。
16. 变更分类 Class A：仅声明式配置变更；diff 限于 options.thresholds 或类似不改变 k6 runtime 执行内容的声明式字段；default function、imported modules、check predicates 内部字节完全相同；例如 p(95)<500 → p(95)<420。
17. 变更分类 Class B：运行时逻辑变更；任何对 default function、imports、helper modules、请求 URL、check predicates，或 scenarios.*.vus/iterations/duration/executor 的变更（会改变 load shape 和 metric distributions）；例如改 URL、添加 check、重写 auth、切换 executors。
18. 如有疑问，按 Class B 处理。
19. 按验证矩阵验证 Class A：任意时长；sha256 + k6 inspect + historical pass/fail prediction；无需 cloud run。
20. 按验证矩阵验证 Class B 短测试（< 5 min）：sha256 + k6 inspect + full cloud run（k6-manage §11）。
21. 按验证矩阵验证 Class B 长测试（≥ 5 min）：sha256 + k6 inspect + local 1-iteration smoke + 对本地副本执行 k6 cloud run，带 --vus 1 --iterations 1；仅当 cloud smoke 通过后，才 PUT 到已保存测试。
22. 验证深度取决于变更类别，不取决于测试时长；按类配方见 references/verification.md。
23. 在提出任何触碰 k6 APIs、imports 或 patterns 的变更前，先对照当前文档确认，并在报告中引用来源。
24. 文档查找顺序第 1：优先 mcp-k6：get_documentation("best_practices")、get_documentation("javascript-api/k6-browser")、validate_script(...)。
25. 文档查找顺序第 2：使用 k6 x docs CLI：k6 x docs using-k6 thresholds；k6 x docs javascript-api k6-http；k6 x docs search "websocket migration"；采用 2-call 策略：先试直接路径，若返回 topic list，选择 subtopic 再次调用；必须用完整 parent paths（如 using-k6 thresholds，不是 thresholds）；k6 x docs 服务已安装 k6 版本的文档，迁移到更新版本时可能滞后。
26. 文档查找顺序第 3：最后才用 web fetch：https://grafana.com/docs/k6/latest/。
27. 处理 async check pattern：browser 测试常见 bug 是用 k6 的 check() 配 async predicates；内置 check() 不 await Promises，导致 check(page, { 'title': p => p.locator('h1').textContent() === 'Foo' }) 因 Promise 对象 truthy 而静默通过。
28. 修复 async check 方式一：从 jslib 使用 async-aware check：import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js'，predicates 可为 async 且内部 await 生效。
29. 修复 async check 方式二：在 check 前解析值：const text = await page.locator('h1').textContent(); check(text, { ... })，保留来自 k6 的标准同步 check。
30. 在任何工作流（migration、refactor、audit）中遇到该问题时，标记为 behavioral bug 并提出上述修复之一。
31. 执行 Threshold tightening 工作流：基于 observed metrics 提出阈值，附 observed-metric 理由、diff、应用，并按 Class A 验证。
32. 执行 Version migration 工作流：查找 deprecated/renamed APIs，分类 syntactic vs behavioral，应用，并按 Class B 验证。
33. 执行 Service change adaptation 工作流：将每个 service change 映射到 script change，提出修复，并按 Class B 验证。
34. 执行 Refactoring 工作流：找出问题，自动应用 syntactic 变更，提出 behavioral 变更，确认后按 Class B 验证。
35. 执行 Best practices audit 工作流：以文档为驱动，审计 thresholds、load design、resource management、code quality、browser specifics。
36. 所有五个工作流都遵循 behavior-aware change control：自动应用 syntactic 变更；将 behavioral 变更作为 diffs 呈现以确认。
37. 处理 cloud script format：GCk6 脚本可能是单文件或 tar archives；编辑前用 file(1) 检测（见 k6-manage §5）。
38. 处理 zero-observation thresholds：在无 observations 的 metric 上的 threshold 默认通过；添加新 threshold 时，确保测试实际发出该 metric。
39. 处理 abortOnFail cascades：若 threshold 有 abortOnFail: true，收紧它意味着运行更早 abort；警告用户。
40. 处理 browser script validation：browser 脚本在无浏览器时不能用 k6 run --iterations 1 验证；用 k6 inspect 做 parse-only validation，或通过 mcp-k6 用 validate_script。
41. 处理 k6 x docs 版本对齐：k6 x docs 提供已安装 k6 版本的文档；迁移到更新版本时，本地文档可能不反映目标 API；在 migration lookups 中注明。
42. 处理 script drift after edit：推送云托管脚本后，下一次运行使用新版本，但 historical runs 保留其 bundled snapshot；调查过去失败时，比较 run-bundled script（只读），而不是当前脚本。
43. 参考 references/workflows.md 获取五个维护任务的逐步流程。
44. 参考 references/verification.md 获取按类别的编辑后验证配方。

适用边界 · 注意事项

• 不适用于维护非 k6 的测试脚本、非 JavaScript/browser 压测脚本或完全不用 k6 的场景。
• 不适用于无法使用 k6 CLI、mcp-k6、k6 x docs、gcx、k6-manage 等必要工具/服务，且无法进行本地或云端验证的环境。
• 不适用于在未判断脚本来源（本地 vs GCk6 云托管）时直接套用云托管安全编辑流程。