用途
gathering-context 是一个用于 WebdriverIO 测试失败排查的上下文收集技能。当调查一个失败的 WebdriverIO 测试、需要理解测试在做什么以及在哪里中断时使用。它由 Investigator 智能体调用，只负责收集和整理证据，不进行诊断或修复。
主要能力
该技能读取失败测试的所有可用产物，并返回结构化的 Markdown 摘要。具体包括：
- 读取项目缓存文件（如 .webdriverio-skills/project-context.md、project-context.json、custom-rules.md，以及 references/website-analysis/<target>/ 下的分析文件），利用缓存的 reporter、service、artifact 和环境细节缩小发现范围。
- 定位产物：读取 wdio.conf.js 或发现的 WDIO 配置文件，解析 reporters、日志路径、快照目录、视频输出路径以及配置的服务。
- 读取 spec 文件：提取匹配 testName 的 it() 块完整内容，识别所有外层 describe() 块和范围内的 Mocha 钩子（before、beforeEach、after、afterEach），并记录所有 import/require 语句。
- 递归遍历页面对象依赖：从 import 出发，递归跟随所有 import/require，提取方法名、实现、使用的 WebdriverIO 命令以及传给 $() 或 $$() 的选择器。
- 搜索自定义命令：在代码库中搜索 addCommand，记录注册位置（browser 或 element）、完整实现，并追踪自定义命令之间的调用链。
- 读取日志：过滤与失败测试相关的行，匹配 COMMAND、DATA、RESULT 记录，重建运行时实际执行的命令序列。
- 收集 HTML 快照：按文件名/时间戳顺序加载，检查页面对象选择器在失败时快照中是否存在、是否隐藏、禁用或属性异常。
- 收集视觉产物：记录截图和视频文件路径与时间戳，不分析其内容。
使用方式
该技能由 Investigator 智能体调用，输入为一个结构化失败对象，包含：
- testName：it() / describe() 标题
- specFile：spec 文件的相对路径
- errorMessage：断言或异常消息
- stackTrace：完整堆栈跟踪
- logFile（可选）：wdio 日志文件路径
- snapshotDir（可选）：HTML/截图/视频保存目录
如果 snapshotDir 或 logFile 已在失败对象中提供，则直接使用，跳过对应路径的发现步骤。
目标解析规则：读取 references/website-analysis/<target>/... 时，<target> 解析为测试 URL/baseUrl 的小写站点主机名（如 demo.learnwebdriverio.com）；如果主机未知，则使用 unknown-target 并继续，不阻塞流程。
如果缓存文件缺失或过期，先运行 managing-project-customizations。
输出结构
返回给 Investigator 的结构化 Markdown 摘要包含以下部分：
- Context: <testName>
- Test Flow：基于 spec 文件、范围内钩子和页面对象方法，逐步重建测试在做什么。
- Last Known Good State：基于日志命令序列和中间 HTML 快照，说明失败前测试已成功完成的内容。
- Point of Failure：错误、堆栈跟踪摘录、失败的 WebdriverIO 命令、涉及的选择器、包含失败命令的页面对象方法。
- DOM State at Failure：失败时 HTML 快照的关键观察，如选择器是否存在、隐藏、禁用，元素是否缺失或状态异常。
- Visual Artifacts：截图文件路径（按时间戳顺序）、视频文件路径（如有）、HTML 快照路径（从旧到新）。
- Active Services：列出配置的服务，并标记可能与失败相关的服务。
- Custom Commands Involved：列出测试流程中调用的自定义命令及其源码位置。
- Hypothesis：基于收集证据的一两句话，说明最可能的失败原因，不超出产物支持范围进行推测。
适用场景
适用于调查失败的 WebdriverIO 测试，需要理解测试执行流程、定位失败点、关联页面对象选择器与 DOM 快照、重建运行时命令序列的场景。特别适合需要系统化收集证据后再进行诊断的自动化测试排查流程。
限制
该技能只收集和整理证据，不进行诊断或修复。它不解析报告格式，只记录产物路径。对于截图和视频，不分析其内容，只记录文件路径和时间戳，由 Investigator 决定是否传给具备视觉能力的模型。自定义命令不会在 WDIO 日志中以命名条目出现，只能通过交叉引用底层原生命令序列与其实现来理解。