用途
Journey Builder 用于为产品构建并测试以真实用户视角进行的端到端旅程。它从项目根目录的 spec.md 读取产品规格，检查 journeys/ 目录中已有的旅程，从中挑选尚未被覆盖的最长用户路径，然后为该路径编写一条完整的 UI 测试旅程。
主要能力
- 读取 spec.md，列出每条需求下的全部验收标准，不遗漏、不挑拣。
- 检查 journeys/ 中每条 journey.md 的覆盖情况，区分“已完全实现且有截图证据的标准”与“未覆盖或缺少截图证据的标准”。
- 一次只构建一条旅程，每条旅程都以真实用户路径贯穿应用，并在每个有意义步骤后截图。
- 采用深度链式原则：每一步产生的结果由下一步消费或验证，每一步都必须验证新的内容；禁止重复点击已经验证过的元素或重复走同一条导航路径。
- 要求每条旅程在 journey.md 顶部列出所覆盖的规格需求，并列出每条需求下的全部验收标准，不得只列子集。无法在本旅程覆盖的标准需明确延迟到某个后续旅程，且必须由且仅由一个旅程负责。
- 在运行测试时强制执行 5 秒截图间隔规则：snap 辅助函数记录相邻截图间隔并实时写入 screenshot-timing.jsonl，超过 5 秒的间隔会被监控发现并可能导致测试被终止；确属不可避免的长等待需通过 slowOK 标记。
- 测试结束后执行关键证据审查：按顺序阅读所有截图，叙述其展示的故事，与 journey.md 的阶段逐一比对，确认每个阶段都有截图证据；若某阶段缺失，需阅读测试与应用代码找出跳过的原因并修复根因，而非增加 if 守卫绕过。
- 提供三轮打磨循环，包含可测试性审查等阶段，每轮生成新的带时间戳文件，不覆盖此前轮次。
使用方式
前置条件为项目根目录存在 spec.md，以及一个可测试的应用（macOS 使用 XCUITest，Web 使用 Playwright）。技能定义的工作流程大致如下：
- 首先加载共享 pitfalls 列表中的全部文件（使用 gh gist 命令查看），并将相关经验应用到本次工作。遇到新的阻塞并找到解决方案后，可按指定格式向该 gist 新增 pitfall 文件。
- macOS 场景下复制模板文件（如 JourneyTestCase.swift）到 UI 测试目标目录，并运行 xcodegen generate；同时确保 project.yml 中 UI 测试目标相关设置正确。
- 读取 journey-state.md（不存在则创建）检查旅程状态，优先处理状态为 in-progress 或 needs-extension 的旅程；仅当所有已有旅程都已完成且全部验收标准被覆盖时，才从 spec 中选择下一条未覆盖路径。
- 读取 spec.md 与已有 journeys/*/journey.md，建立已完全覆盖标准与未覆盖标准的集合。
- 选择或扩展一条旅程：扩展时运行测试并测量时长，补齐未覆盖标准；新建时选择最长的未覆盖用户路径，创建 journeys/{NNN}-{name}/ 目录，并以深度链方式编写 journey.md。
- 编写单个测试文件，像真实用户一样操作，通过 XCTAttachment（macOS）或 Playwright 定位器截图（Web）在每个有意义步骤后截图，命名形如 {journey}-{NNN}-{step}.png。时间前缀由提取脚本自动添加。
- 仅运行该测试，修复失败并测量实际耗时，提取截图；如映射的验收标准仍有未覆盖，则返回继续实现，不得进入打磨阶段。
- 执行关键证据审查，确认每个阶段均有截图证据。
- 执行三轮打磨循环。
适用场景
适用于已有明确产品规格（spec.md）、需要以真实用户旅程验证验收标准是否被真实实现的项目，尤其适合 macOS 应用（XCUITest）和 Web 应用（Playwright）的端到端 UI 测试。也适合需要逐条追踪需求覆盖、要求截图证据、并控制测试运行节奏（截图间隔监控）的场景。
限制
- 运行前必须存在 spec.md，并具备可测试的应用环境；缺失时无法按流程执行。
- 必须使用支持的测试框架（macOS 为 XCUITest，Web 为 Playwright）。
- 不允许使用占位或模拟实现来满足验收标准；某条标准必须在真实实现、测试步骤与截图证据三者齐备时才算覆盖。
- 存在 5 秒截图间隔的强制约束，长等待需显式标记，并可能因超时被监控终止并重启。
- 关于安装方式、收费与价格等信息，暂未提供。