SuperAPI AI 工具集

refine-journey

编程与开发

查看项目

更新于 10-16 07:11

技能介绍

用途

refine-journey 是一个“技能工程师”角色技能,目的是让 journey-builder 技能本身变得更好:它从 journey-builder 运行的失败中学习,评估产出了什么,诊断哪些指令薄弱或缺失,然后重写这些指令。其目标明确不是修复产品,而是修复构建产品的技能。

输入与参数

Spec 文件通过 $ARGUMENTS 传入。如果未提供参数,则使用当前目录下的 spec.md。

主要流程

Phase 1:收集证据 读取上一次 journey-builder 运行产生的全部内容,包括:journeys/(列出所有 journey 文件夹,对最近的 journey 读取 journey.md、所有 testability_review_.md、所有 ui_review_.md)、完整重读 spec 文件、生成的测试代码(读取最近 journey 文件夹中的每个测试文件)、截图(读取最近 journey 的 screenshots/ 文件夹中的全部截图)、仓库根目录下的 SKILL.md。

Phase 2:运行客观检查 逐项执行并记录通过/失败:

  • 2a 构建检查:检测构建系统(Swift Package Manager、npm、cargo、go build 等),运行构建命令,记录成功或失败及错误。
  • 2b 测试检查与速度测量:运行单元测试和该 journey 的 UI 测试并计时(使用 time 或等效方式),以秒记录时长;记录通过数、失败数、失败项及原因;任何单个测试超过 10 秒即为速度异味,需要标记。
  • 2c 截图审计:读取全部截图,检查是否显示可用的应用,或是空白屏/错误状态/占位文本/损坏的 UI;仅应用窗口检查(若出现桌面壁纸、dock、菜单栏或其他应用则为技能失败,说明使用了错误的截图 API);设计质量检查(套用 frontend-design 标准:排版、间距、对齐、颜色一致性、视觉层级,能“运行”但不够精良的截图属于设计失败);步骤覆盖(journey.md 中每一步是否都有对应截图)。
  • 2d journey 质量检查:journey.md 是否描述了从开始到结束的真实用户路径;测试是否真正完成完整用户操作并验证结果(录制测试必须产出录制,搜索测试必须找到结果,停在“按钮存在”的测试不完整);3 轮打磨是否全部完成(检查 testability_review_round{1,2,3}.md 和 ui_review_round{1,2,3}.md);每轮是否产出新的带时间戳文件(而非覆盖)。
  • 2e spec 覆盖检查:对 spec 中每条需求建立覆盖表(需求 | 覆盖它的 journey | 测试通过 | 截图 OK)。
  • 2f 打磨轮次质量:对 3 轮打磨逐一检查,测试性(是否发现并修复真实问题,还是走过场)、重构(测试代码是否干净:正确的等待、稳定的选择器、可访问性标识符)、UI 审查(是否真正捕获并修复设计问题,比较第 1 轮与第 3 轮截图是否有可见改进)。
  • 2g 真实结果检查(关键):对每个 journey 测试回答“该测试是否到达 journey 的真实结果”,停在“验证对话框已打开”的测试是在测试 UI 存在性而非功能;每个 journey 测试都必须到达其 OUTCOME(产出录制、找到结果、播放内容、删除数据等);统计到达真实结果与停在 UI 元素存在性的测试数量。

Phase 3:为本次运行评分 按权重计算:规格覆盖(每条需求有 journey,20%)、测试(通过数,15%)、构建(通过/失败,10%)、截图质量(通过设计检查的比例,15%)、真实结果(journey 测试到达真实结果的比例,15%)、打磨完成度(3 轮中完成的轮数,10%)、步骤覆盖(有截图的 journey 步骤比例,10%)、测试速度(总耗时与最慢测试,5%)。测试速度评分:与上一次运行时间比较(来自 journey-refinement-log.md),更快=100%,相同=50%,更慢=0%;首次运行:低于 30 秒=100%,30-60 秒=75%,60-120 秒=50%,超过 120 秒=25%。将分数连同时间戳和发现摘要写入 journey-refinement-log.md(若不存在则创建)。

Phase 4:诊断技能指令失败 对 Phase 2 发现的每个缺口,追问“SKILL.md 中哪条指令缺失、不清晰或太弱以至无法阻止该问题”,用 5 Whys 追溯到技能指令层面,输出失败、Why 1-5、指令缺口(SKILL.md 中的具体章节或缺失章节)、修复方案(要新增或修订的具体指令)。资料还列出了常见指令失败模式:过于笼统、缺少恢复指令、缺少强制、缺少具体示例、测试未触及真实结果、每轮无改进、截图未被审查、使用全屏而非仅应用截图、缺少设计打磨、不必要的等待(用固定 sleep 而非等待条件)、选错 journey。

Phase 5:重写 SKILL.md 针对每个诊断出的指令缺口,对根 SKILL.md 做针对性编辑。编辑规则:外科式修改(只改具体薄弱章节)、具体优于抽象(用确切命令和预期输出替代“验证它能工作”)、必须优于应该(把可选语气改为强制)、补充示例(抽象规则配具体正误示例)、补充检查点(若阶段被跳过,加门禁“在确认 X 之前不得进入第 N+1 步”)、补充恢复路径(对每个“运行 X”加上“若 X 失败则做 Y”)。反臃肿规则:每句话都必须让 agent 做点什么,删掉概念描述;优先锐化已有规则而非新增;编辑后统计总行数,若净增长超过 20 行,需找出可删除内容;不得跨章节重复规则,需合并;编辑后重读整个 SKILL.md 检查内部一致性。

Phase 6:撰写改进报告 按固定模板追加到 journey-refinement-log.md,内容包括:标题(Refinement Run — 时间戳)、分数、评估的 journey、测试速度(总时长、与上次比较、最慢测试)、发现的失败(失败及根因指令缺口)、对 SKILL.md 的修改(章节及修改原因)、预测影响、下次运行需关注的内容。

Phase 7:告知用户下一步 输出简明摘要:本次分数、测试速度及变化、发现的三大失败、SKILL.md 的修改内容、下一次运行的确切命令 /journey-builder、下次运行需关注的内容。

限制

资料未提供关于收费、价格、平台支持范围等具体信息;该技能的运行依赖 journey-builder 的既有产出与 SKILL.md 文件结构。