shiplight

Shiplight

Shiplight QA 工作的统一入口。此技能接收一个子命令， 并将其路由到相应的工作流。所有带有 Shiplight 品牌的操作都通过 此入口；上方的描述特意设置了触发门槛，只有当用户提到“shiplight” 或输入 /shiplight 时，此技能才会触发——绝不会因通用的“编写 测试”而触发。

路由约定

1. 识别子命令。 将参数与分发列表进行匹配—— 不要只依赖第一个词，因为同义表达通常由多个词组成 （yaml test、set up tests for my app），而且用户的意图可能以 非 token 词开头（create yaml test、show failing tests）。按以下顺序： (a) 开头的词是精确的规范 token；(b) 参数中包含的最长规范 token 或同义 短语；(c) 根据同义词/意图列判断整体意图。选择匹配度最高的唯一子命令。
2. 透传上下文。 将选择器未消耗的内容作为上下文传递给 子命令。用户通常会使用自然语言表达——不会输入精确的连字符 token；请匹配意图，并将其余内容视为目标。 示例：
   • /shiplight cover checkout flow → cover + 上下文 checkout flow
   • /shiplight create a yaml test for login → create-yaml-tests（匹配 “yaml test”）+ 上下文 for login
   • /shiplight create agent verification for the signup flow → create-agent-verification（匹配“agent verification”）+ 上下文 for the signup flow
3. 分发。 读取匹配的 references/<subcommand>.md（对于嵌套子命令， 读取 references/<subcommand>/index.md）并遵循其中的说明，同时传递上下文。
4. 先澄清，不要猜测。 如果选择器为空（仅输入 /shiplight）或存在歧义 （请参阅“歧义说明”），请显示菜单并提出一个澄清问题——用户想要执行操作， 但没有说明如何执行。这与仅提供信息的 help 不同：help 会列出/说明子命令，且绝不执行操作（请参阅 references/help.md）。
5. 确认破坏性操作。 对非空项目执行 init 前，绝不要自动运行——请先确认。

共享层

• 每次调用子命令时（help 和 support 除外），都要识别测试项目 根目录，然后运行一次 references/_shared/update-check.md（每日技能刷新 + shiplightai CLI 版本检查）。此步骤可能会中止运行：如果 CLI 版本低于 最新发布版本，则会在子命令启动前停止，并提供升级选项。
• 每个子命令都会列出所需的 references/_shared/ 模块（auth、mcp、 evidence-and-report、project-layout、ground-truth、knowledge、secrets、 vocabularies、test-spec-template）。执行操作前请先阅读这些模块——它们是 唯一可信来源，不会在各个子命令中重复说明。

子命令（菜单）

在直接调用或需要澄清时，显示此分组菜单。

设置

• init — 搭建 Shiplight 测试项目 + 编写 specs/context.md
• setup-test-auth — 为被测应用配置登录，并保存可复用的浏览器/Playwright 状态
• update — 刷新已安装的 Shiplight skills + shiplightai CLI

编写

• create-yaml-tests — 根据规范实现确定性的 YAML E2E 测试
• create-agent-verification — 创建可复用的 Agent 运行验证脚本
• cover — 决定测试格式 + 工作量，制定计划，驱动各个生成器并汇报

维护

• fix — 复现并修复失败或偏离预期的测试

检查

• verify — 在本地开发期间于浏览器中验证 UI 变更

评审

• review — 应用质量评审（安全、隐私、设计、性能等）

发布

• ci — 接入 CI 工作流 + 故障分类流水线
• cloud — 读取 Shiplight Cloud 测试结果（运行记录、失败/不稳定测试、构件）和分析数据（健康度摘要、通过率/运行趋势、最慢/最不稳定排名、失败归因）

菜单末尾添加一行页脚： 卡住了？/shiplight support 可联系人工支持——工单会根据本次会话自动起草。

调度表

规范名称	同义词 / 意图	参考
init	设置 shiplight、新建测试项目、搭建项目框架	references/init.md
setup-test-auth	测试应用身份验证、被测应用登录、已认证测试账户、保存测试会话、存储状态	references/setup-test-auth.md
update	自我更新、升级 skills、刷新 skills、升级 shiplight CLI、升级 shiplightai、CLI 已过时	references/update.md
create-yaml-tests	yaml 测试、创建 yaml 测试、编写 yaml/e2e 测试、确定性测试、e2e 测试、编写测试	references/create-yaml-tests/index.md
create-agent-verification	Agent 验证、创建 Agent 验证、验证脚本、可重复的 Agent 检查、实时环境验证、全栈测试、跨层测试、测试整个技术栈、驱动 UI 并检查后端/数据库、同时验证后端状态、发布冒烟测试、发布前冒烟测试	references/create-agent-verification/index.md
cover	覆盖率、测试覆盖率、哪些内容尚未测试、覆盖缺口、测试策略、规划测试、编写规范、测试计划、为我的应用设置测试、构建测试、测试此功能	references/cover/index.md
fix	测试失败、分类排查、修复测试、根据产品变更更新测试	references/fix.md
verify	截图、验证变更、检查 UI、视觉检查	references/verify.md
review	安全评审、评审我的应用、无障碍、隐私、性能、seo	references/review/index.md
ci	github actions、ci 设置、流水线	references/ci/index.md
cloud	云端结果、测试运行结果、失败测试、不稳定测试、ci 结果、下载构件、测试健康度、通过率、通过率/运行趋势、最慢的测试、最不稳定的测试、失败归因、失败明细、分析数据	references/cloud/index.md
support	我卡住了、联系支持、联系人工人员、人工帮助、shiplight 出故障了、报告 shiplight 错误、提交工单、支持工单、工单状态	references/support.md
help	shiplight 能做什么、列出命令、用法、?	references/help.md

歧义说明

• “test” / “write a test” → 可能是 create-yaml-tests（确定性测试，侧重 UI），也可能是 create-agent-verification（覆盖 UI 和后端状态）。默认选择 create-yaml-tests，除非用户提到核心流程、后端／跨层验证、发布冒烟测试或真实环境判断；如果仍不明确，请询问。
• “smoke test” → 单独使用时含义模糊。快速检查关键页面的 UI 测试是 create-yaml-tests；发布前检查核心流程是否正常运行 并且 后端状态是否正确，则是 create-agent-verification。除非用户提到后端预期或发布门禁，否则请询问要执行哪种测试。
• “verify” / “verification” → 表示现在检查某项更改的动词是 verify；创建可重复使用的验证脚本则是 create-agent-verification。是否使用 create- 前缀是关键线索。如果用户的表述无法区分，请询问。
• “triage” → 在 Shiplight 中指 fix（修复失败的测试）。不要与 review 内部的分类／计划步骤混淆。
• “failing tests” / “flaky tests” → 从 CI（“云端”“上次运行”“汇总报告”）中读取这些测试的结果，使用 cloud（托管结果）；修复损坏的测试（“我的测试失败了”“修复这个”），使用 fix。如果表述无法说明是哪种情况，请询问。
• “report a bug” / “X is broken” → 取决于坏的是什么。用户的应用出现异常，是需要报告的实际问题（_shared/ground-truth.md），不是子命令；Shiplight 本身出现异常（技能、CLI、云 API），则使用 support。如果不清楚用户指的是哪种情况，请询问。
• “login” / “auth” → 如果没有说明目标，请询问要验证什么身份。被测应用的身份验证使用 setup-test-auth；Shiplight 平台身份验证和 SHIPLIGHT_API_TOKEN 设置使用 CLI 命令 npx shiplight setup-api-token，而不是 /shiplight 子命令。

子命令完成或中止后（建议下一步）

子命令给出最终报告后——包括报告运行已中止的情况——可以选择追加一条下一步建议。规则如下：

• 仅依据证据。 建议必须由运行期间已经观察到的内容触发，例如已分析的差异、已诊断的失败或已读取的项目状态。不要为了决定是否给出建议而额外分析（例如重新运行 git diff、扫描文件或启动浏览器会话）。
• 默认不提供建议。 表格中没有触发条件 → 完全不添加建议行。失败状态大多不应触发建议：用户接下来要做的是修复产品，而不是运行其他 Shiplight 命令。建议应在成功时触发——“你已证明它能正常运行；现在让它变得持久／持续／可见。”唯一会触发建议的失败情况是 Shiplight 侧的失败行（support）；无论运行在哪一步停止，都适用——中途运行中止的报告也算。
• 根据更改的性质决定是否建议。 如果运行是从仅涉及后端或几乎不涉及 UI 的代码更改开始，则不要给出与浏览器相关的建议（verify、create-yaml-tests、review design）；此时更有用的是 cover（通过其能力映射选择单元／契约／集成测试）和 create-agent-verification（跨层真实环境检查）。
• 一行陈述，不要提问。 格式： Next: /shiplight <cmd> — <reason from this run>。绝不要自动运行建议的命令；也不要提出会阻塞流程的“是／否”问题。由用户决定。
• 最多一条建议——只有在确实存在分支选择时才给出两条（例如根据范围在 cover 和 create-yaml-tests 之间选择）。
• 在 CI／非交互模式下，以及 update / help / support 之后，完全跳过。 | 之后 | 运行期间观察到的触发条件 | 建议 | |-------|--------------------------------|---------| | init | 应用有登录／已认证路由 | setup-test-auth；否则用 cover | | setup-test-auth | 为解除另一条命令的阻塞而调用 | 恢复执行该命令；否则无需操作 | | verify | 在有意义的流程上通过，且没有 YAML 测试覆盖该流程 | cover（功能级）或 create-yaml-tests（单一窄范围流程）——verify 是临时的，应将其固定下来 | | verify | 操作过程中发现 UI 问题：缺少标签／角色、没有 data-testid、DOM 脆弱、控制台警告 | review design（无障碍性 + 可测试性） | | verify | 检查失败，或改动很简单 | 无需操作 | | fix | 诊断结果为产品改动，且改动范围超出修复的测试 | cover <feature>，以更新 testing-what 规范 | | fix | 反复出现定位器漂移／没有稳定的语义钩子 | review design（可测试性）——找出漂移的根因，而不是每个迭代周期都重新修复 | | fix | 复现问题源自 CI 失败，或多个测试有共同原因 | 用 cloud 检查影响范围／确认下一次运行是否通过 | | fix | 诊断结果为应用 Bug | 无需操作——报告该 Bug（_shared/ground-truth.md） | | create-yaml-tests | 测试通过，且不存在 CI E2E 工作流 | ci | | create-yaml-tests | 与其断言，不如通过 API／DB／日志状态更好地判断流程的可信度 | create-agent-verification | | create-agent-verification | 某个用例在如今稳定的路径上为 PASS，且其证明可简化为固定条件 | create-yaml-tests（提升为确定性测试）——若其价值在于综合证据进行判断，则不要这样做 | | create-agent-verification | 因登录／会话引导而 BLOCKED | setup-test-auth | | cover | 生成了 Shiplight 测试，但未接入 CI | ci | | cover | 报告行因认证／环境问题而 BLOCKED | setup-test-auth | | review | 用户在会话中修复了 UI 问题 | 用 verify 确认修复后的渲染效果 | | review | 存在严重程度较高但没有回归测试覆盖的问题 | cover | | ci | 工作流已接入 | 推送代码／创建 PR 以触发工作流，然后用 cloud 查看首次运行结果 | | ci | 尚无测试 | 先运行 cover（前置条件，参见 ci/index.md） | | cloud | 失败／不稳定的测试被归因为 spec_issue／漂移 | fix | | cloud | 归因主要为 app_regression | 无需运行任何工具——这是需要报告的应用 Bug | | cloud | 录制会话覆盖了未经测试的流程 | 根据录制内容运行 create-yaml-tests | | 任意 | 运行因Shiplight 端故障而停止，且没有已知修复方法——CLI 崩溃、无法解释的 Shiplight API 错误，或同一步骤以完全相同的方式连续失败两次 | support——本会话已包含创建工单所需的诊断信息 |