用途
k6 Test Maintenance 是 grafana/xk6-subcommand-agent 下的一个技能，用于维护、修复和改进已经存在的 k6 测试脚本，而不是从零编写新测试。它关心的典型场景包括：阈值随观测数据变化而调整、k6 版本升级后的脚本迁移、被测服务变更后的测试适配、测试代码清理与现代化，以及按当前最佳实践做审计。
主要能力
技能内置五类维护任务，每一类在 references/workflows.md 中都有逐步操作流程：
- 阈值收紧（Threshold tightening）——根据观测到的指标调整阈值数值。
- 版本迁移（Version migration）——为新 k6 版本更新脚本。
- 服务变更适配（Service change adaptation）——底层服务变化时修正测试。
- 重构（Refactoring）——清理并现代化测试代码。
- 最佳实践审计（Best practices audit）——对照当前 k6 最佳实践检查脚本，覆盖阈值、负载设计、资源管理、代码质量和浏览器相关细节。
其核心原则是“感知行为的变化控制”（behavior-aware change control）。每处提议的改动都要分类：
- 语法性改动（行为不变）：k6 运行时产生相同的指标、通过/失败结果和端点，例如重命名变量、let 改 const、删除未用导入、更新注释、重新格式化。这类改动直接应用。
- 行为性改动（行为不同）：任何影响指标、通过/失败、时序、请求目标或负载形态的改动，例如阈值数值变化、添加 sleep()、端点 URL 更新、重写 check、场景变化、新增阈值。这类改动必须以 diff 加理由呈现，并要求确认。
技能明确说明，“行为性”的门槛被刻意设得很低：如果拿不准，就当作行为性改动并询问——一个看起来微不足道的阈值变化可能级联影响 CI 门禁、SLO 计算和告警。
依赖
- k6-manage：安全地获取和编辑 GCk6 托管脚本（§5：GET、备份、编辑、校验、PUT、用 sha256 验证）。触碰任何云托管脚本前先阅读它。
- gcx：访问 Grafana Cloud API 的唯一工具。
- mcp-k6 工具：validate_script 和 get_documentation。先检查可用性；若缺失则回退到 k6 x docs。
- k6 x docs CLI：在 mcp-k6 未配置时用于查文档。
- k6 CLI：本地校验（k6 inspect、k6 run）。
使用方式
每次编辑都遵循验证循环，任何流程产出的修改脚本都不得在未验证的情况下呈现或 PUT，需反复修复并重跑直到通过：
- 解析检查：k6 inspect <script>，可捕获语法错误、无效选项、损坏的导入，适用于所有类型包括浏览器测试（无需浏览器）。若 mcp-k6 可用，再运行 validate_script。
- 本地冒烟（非浏览器、服务可达）：k6 run --vus 1 --iterations 1 <script>。
- 对改动分类并按矩阵验证，配方见 references/verification.md。
- 云托管脚本：按 k6-manage §5 的安全编辑配方应用（GET → 备份 → 编辑 → 校验 → 以 application/octet-stream PUT → sha256 验证）。
改动分类：
- Class A——仅声明式配置。diff 只限于 options.thresholds 或类似声明式字段，不改变 k6 运行时执行的内容；default 函数、导入模块和 check 谓词内的字节完全一致。例如 p(95)<500 → p(95)<420。
- Class B——运行时逻辑变化。对 default 函数、导入、辅助模块、请求 URL、check 谓词，或对 scenarios.*.vus/iterations/duration/executor（会改变负载形态和指标分布）的任何改动。例如改 URL、加 check、重写鉴权、切换执行器。
存疑时按 Class B 处理。
验证矩阵：
| 类别 | 测试时长 | 验证方式 |
|---|---|---|
| A | 任意 | sha256 + k6 inspect + 历史通过/失败预测，无需云端运行 |
| B | 短（< 5 分钟） | sha256 + k6 inspect + 完整云端运行（k6-manage §11） |
| B | 长（≥ 5 分钟） | sha256 + k6 inspect + 本地 1 次迭代冒烟 + 用本地副本以 --vus 1 --iterations 1 做 k6 云端运行；仅在云端冒烟通过后才 PUT 到已保存测试 |
验证深度取决于改动类别，而不是测试时长——大多数编辑不需要完整运行，而生产测试可能运行数小时。各类别的配方（Class A 预测表、Class B 短/长、场景变化和放宽阈值等边界情况）见 references/verification.md。
文档查阅：在提出任何触及 k6 API、导入或模式的改动前，必须对照当前文档确认并在报告中引用来源。查阅顺序为：mcp-k6（首选，get_documentation("best_practices")、get_documentation("javascript-api/k6-browser")、validate_script(...)）；k6 x docs CLI（始终可用，如 k6 x docs using-k6 thresholds、k6 x docs javascript-api k6-http、k6 x docs search "websocket migration"）；网页抓取（最后手段）https://grafana.com/docs/k6/latest/。采用 2 次调用策略：先试直接路径，若返回主题列表再选子主题调用第二次；需要完整父路径（using-k6 thresholds，而非 thresholds）。k6 x docs 提供的是已安装 k6 版本的文档，迁移时可能落后于目标版本。
异步 check 模式：浏览器测试中一个常见缺陷是用 k6 的 check() 搭配异步谓词。内置 check() 不会 await Promise，因此 check(page, { 'title': p => p.locator('h1').textContent() === 'Foo' }) 会因为 Promise 对象为真值而静默通过。两种有效修复：一是从 jslib 引入异步感知的 check：import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js'，之后谓词可为 async 且内部可 await；二是在 check 前先解析值：const text = await page.locator('h1').textContent(); check(text, { ... })，保留 k6 标准同步 check。在任何流程（迁移、重构、审计）中遇到该问题，都应标记为行为性缺陷并提出上述修复之一。
脚本来源：GCk6 托管——通过 k6-manage §5 拉取和推送（GET → 备份 → 编辑 → 校验 → PUT → sha256 验证）；本地磁盘——直接读取和编辑，呈现前先验证。开始前先确定来源：GCk6 测试 URL 或 ID 属于云托管；文件路径属于本地。
适用场景
适用于已经存在 k6 测试脚本、需要对它做增量维护的工程场景：需要依据趋势数据收紧阈值、随 k6 版本升级做迁移、后端服务接口或行为变化后同步更新测试、清理历史测试代码、以及对照最佳实践审查脚本质量。它也适用于 Grafana Cloud k6 中托管的脚本的编辑与安全推送。
限制与注意事项
- 云脚本格式：GCk6 脚本可能是单文件或 tar 归档，编辑前用 file(1) 检测（见 k6-manage §5）。
- 零观测阈值：对没有任何观测的指标设置阈值会默认通过。新增阈值时须确认测试确实会发出该指标。
- abortOnFail 级联：若某阈值设置了 abortOnFail: true，收紧它意味着运行会更早中止，需要警示用户。
- 浏览器脚本校验：没有浏览器时无法用 k6 run --iterations 1 校验浏览器脚本。使用 k6 inspect 做仅解析校验，或通过 mcp-k6 的 validate_script。
- k6 x docs 版本对齐：k6 x docs 提供已安装 k6 版本的文档，迁移到更新版本时本地文档可能不反映目标 API，需在迁移查阅中注明。
- 编辑后的脚本漂移：推送云托管脚本后，下次运行使用新版本，但历史运行保留其打包快照。排查过去失败时，应比较运行打包的脚本（只读），而不是当前脚本。
参考资料
- references/workflows.md——五类维护任务的逐步流程。
- references/verification.md——按类别划分的编辑后验证配方。