shiplight

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shiplight

The single entry point for Shiplight QA work. This skill takes a subcommand and routes it to the right workflow. Everything Shiplight-branded comes through here; the description above is deliberately gated so this skill fires only when the user names "shiplight" or types

/shiplight

— never on a generic "write a test".

Shiplight QA工作的统一入口。该技能接收一个子命令并将其路由至对应的工作流。所有Shiplight相关的操作都通过此处执行；上述描述设置了触发限制，因此仅当用户提及"shiplight"或输入

/shiplight

时才会激活该技能——不会因通用的"编写测试"请求触发。

Routing contract

路由规则

Identify the subcommand. Match the argument against the dispatch table — do not rely on the first token alone, because synonyms are often multi-word (
```
yaml test
```
,
```
set up tests for my app
```
) and intents may lead with a non-token word (
```
create yaml test
```
,
```
show failing tests
```
). In order: (a) an exact canonical token as the leading word; (b) the longest canonical-token or synonym phrase the argument contains; (c) overall intent against the synonym/intent column. Pick the single best-matching subcommand.
Pass-through context. Forward whatever the selector didn't consume to the subcommand as context. Natural phrasing is expected — users won't type the exact hyphenated token; match the intent and treat the rest as the target. Examples:
- ```
/shiplight cover checkout flow
```
  →
```
cover
```
  + context
```
checkout flow
```
- ```
/shiplight create a yaml test for login
```
  →
```
create-yaml-tests
```
  (matched on "yaml test") + context
```
for login
```
- ```
/shiplight create agent verification for the signup flow
```
  →
```
create-agent-verification
```
  (matched on "agent verification") + context
```
for the signup flow
```
Dispatch. Read the matching
```
references/<subcommand>.md
```
(or
```
references/<subcommand>/index.md
```
for nested subcommands) and follow it, carrying the context forward.
Clarify, don't guess. If the selector is empty (
```
/shiplight
```
alone) or ambiguous (see Ambiguity notes), show the menu and ask one clarifying question — the user wants to act but didn't say how. This differs from
```
help
```
, which is informational:
```
help
```
lists/explains subcommands and never executes (see
```
references/help.md
```
).
Confirm destructive actions. Never auto-run
```
init
```
against a non-empty project — confirm first.

识别子命令：将参数与调度表匹配——不要仅依赖第一个词，因为同义词通常是多词短语（如
```
yaml test
```
、
```
set up tests for my app
```
），且用户意图可能以非命令词开头（如
```
create yaml test
```
、
```
show failing tests
```
）。匹配优先级为：(a) 作为开头词的完全匹配标准命令；(b) 参数中包含的最长标准命令或同义词短语；(c) 整体意图与同义词/意图列匹配。选择最匹配的单个子命令。
传递上下文：将选择器未识别的内容作为上下文转发给子命令。支持自然表述——用户不会输入完全符合连字符格式的命令；匹配意图后，将剩余内容作为目标处理。示例：
- ```
/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
```
调度执行：读取匹配的
```
references/<subcommand>.md
```
（对于嵌套子命令则读取
```
references/<subcommand>/index.md
```
）并按照指引执行，同时携带上下文信息。
明确询问，不猜测：如果选择器为空（仅输入
```
/shiplight
```
）或存在歧义（参见歧义说明），则显示菜单并提出一个明确性问题——用户想要执行操作但未说明具体方式。这与
```
help
```
命令不同，
```
help
```
仅提供信息：
```
help
```
会列出/解释子命令且从不执行操作（参见
```
references/help.md
```
）。
确认破坏性操作：切勿在非空项目中自动运行
```
init
```
命令——需先确认。

Shared layer

共享层

On every subcommand invocation (skip for
```
help
```
and
```
support
```
), identify the test project root, then run
```
references/_shared/update-check.md
```
once (daily skill refresh +
```
shiplightai
```
CLI version gate). It can halt the run: a CLI behind the latest published version stops the subcommand before it starts, and offers an upgrade.
Each subcommand names the
```
references/_shared/
```
modules it needs (auth, mcp, evidence-and-report, project-layout, ground-truth, knowledge, secrets, vocabularies, test-spec-template). Read those before acting — they are the single source of truth, not restated per subcommand.

在每次调用子命令时（
```
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）。执行操作前需先读取这些模块——它们是唯一的事实来源，不会在每个子命令中重复说明。

Subcommands (menu)

子命令（菜单）

Show this grouped menu when invoked bare or when clarifying.

Setup

```
init
```
— scaffold a Shiplight test project + write
```
specs/context.md
```
```
auth
```
— set up / repair login and saved storage state
```
update
```
— refresh installed Shiplight skills + the
```
shiplightai
```
CLI

Author

```
create-yaml-tests
```
— implement deterministic YAML E2E tests from a spec
```
create-agent-verification
```
— create a reusable agent-run verification script
```
cover
```
— decide test format + effort, plan, drive the producers, report

Maintain

```
fix
```
— reproduce and repair failing or drifted tests

Check

```
verify
```
— verify UI changes in the browser during local development

Review

```
review
```
— app-quality review (security, privacy, design, performance, …)

Ship

```
ci
```
— wire CI workflows + failure-triage pipeline
```
cloud
```
— read Shiplight Cloud (Nova) test results (runs, failing/flaky tests, artifacts) and analytics (health summary, pass-rate/run trends, slowest/flaky rankings, failure attribution)

Help

```
help
```
— list subcommands, or
```
help <subcommand>
```
for details (does not execute)
```
support
```
— get human help: file a support ticket with session diagnostics, check replies

End the menu with one footer line:

Stuck? /shiplight support reaches a human — the ticket drafts itself from this session.

当用户仅调用

/shiplight

或需要明确意图时，显示以下分组菜单。

设置

```
init
```
—— 搭建Shiplight测试项目 + 编写
```
specs/context.md
```
```
auth
```
—— 设置/修复登录状态和存储状态
```
update
```
—— 更新已安装的Shiplight技能 +
```
shiplightai
```
CLI

编写测试

```
create-yaml-tests
```
—— 根据规范实现确定性YAML端到端测试
```
create-agent-verification
```
—— 创建可复用的Agent运行验证脚本
```
cover
```
—— 确定测试格式与工作量、规划测试、推动执行并生成报告

维护测试

```
fix
```
—— 复现并修复失败或偏移的测试

验证

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

评审

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

发布

```
ci
```
—— 配置CI工作流 + 失败分类流水线
```
cloud
```
—— 查看Shiplight Cloud（Nova）测试结果（运行记录、失败/不稳定测试、工件）和分析数据（健康摘要、通过率/运行趋势、最慢/最不稳定测试排名、失败归因）

帮助

```
help
```
—— 列出子命令，或使用
```
help <subcommand>
```
查看详情（不执行操作）
```
support
```
—— 获取人工帮助：提交包含会话诊断信息的支持工单，查看回复

菜单末尾添加一行页脚：

遇到问题？输入/shiplight support联系人工——工单会自动从当前会话生成诊断信息。

Dispatch table

调度表

Canonical	Synonyms / intents	Reference
`init`	set up shiplight, new test project, scaffold	`references/init.md`
`auth`	log in, save session, storage state, authentication	`references/auth.md`
`update`	self-update, upgrade skills, refresh skills, upgrade the shiplight cli, bump shiplightai, cli out of date	`references/update.md`
`create-yaml-tests`	yaml test(s), create a yaml test, write a yaml/e2e test, deterministic test, e2e test, write a test	`references/create-yaml-tests/index.md`
`create-agent-verification`	agent verification, create agent verification, verification script, repeatable agent check, live-env verification, full-stack test, cross-layer test, test the whole stack, drive the UI and check the backend/database, verify the backend state too, release smoke test, pre-release smoke	`references/create-agent-verification/index.md`
`cover`	coverage, test coverage, what's untested, coverage gaps, testing strategy, plan tests, write a spec, test plan, set up tests for my app, build tests, test this feature	`references/cover/index.md`
`fix`	failing test, triage, repair test, update test for product change	`references/fix.md`
`verify`	screenshot, verify the change, check the UI, visual check	`references/verify.md`
`review`	security review, review my app, accessibility, privacy, performance, seo	`references/review/index.md`
`ci`	github actions, ci setup, pipeline	`references/ci/index.md`
`cloud`	cloud results, test run results, failing tests, flaky tests, ci results, download artifacts, test health, pass rate, pass-rate/run trend, slowest tests, flakiest tests, failure attribution, failure breakdown, analytics	`references/cloud/index.md`
`support`	I'm stuck, contact support, talk to a human, human help, shiplight is broken, report a shiplight bug, file a ticket, support ticket, ticket status	`references/support.md`
`help`	what can shiplight do, list commands, usage, `?`	`references/help.md`

标准命令	同义词 / 意图	参考文档
`init`	set up shiplight, new test project, scaffold	`references/init.md`
`auth`	log in, save session, storage state, authentication	`references/auth.md`
`update`	self-update, upgrade skills, refresh skills, upgrade the shiplight cli, bump shiplightai, cli out of date	`references/update.md`
`create-yaml-tests`	yaml test(s), create a yaml test, write a yaml/e2e test, deterministic test, e2e test, write a test	`references/create-yaml-tests/index.md`
`create-agent-verification`	agent verification, create agent verification, verification script, repeatable agent check, live-env verification, full-stack test, cross-layer test, test the whole stack, drive the UI and check the backend/database, verify the backend state too, release smoke test, pre-release smoke	`references/create-agent-verification/index.md`
`cover`	coverage, test coverage, what's untested, coverage gaps, testing strategy, plan tests, write a spec, test plan, set up tests for my app, build tests, test this feature	`references/cover/index.md`
`fix`	failing test, triage, repair test, update test for product change	`references/fix.md`
`verify`	screenshot, verify the change, check the UI, visual check	`references/verify.md`
`review`	security review, review my app, accessibility, privacy, performance, seo	`references/review/index.md`
`ci`	github actions, ci setup, pipeline	`references/ci/index.md`
`cloud`	cloud results, test run results, failing tests, flaky tests, ci results, download artifacts, test health, pass rate, pass-rate/run trend, slowest tests, flakiest tests, failure attribution, failure breakdown, analytics	`references/cloud/index.md`
`support`	I'm stuck, contact support, talk to a human, human help, shiplight is broken, report a shiplight bug, file a ticket, support ticket, ticket status	`references/support.md`
`help`	what can shiplight do, list commands, usage, `?`	`references/help.md`

Ambiguity notes

歧义说明

"test" / "write a test" → could be
```
create-yaml-tests
```
(deterministic, UI focused) or
```
create-agent-verification
```
(spans UI and backend state). Default to
```
create-yaml-tests
```
unless the user signals a core journey, backend/ cross-layer proof, release smoke, or live-env judgment — but if unclear, ask.
"smoke test" → ambiguous alone. A quick UI pass over key screens is
```
create-yaml-tests
```
; a pre-release check that a core journey works and left the right backend state is
```
create-agent-verification
```
. Ask which, unless the user names a backend expectation or a release gate.
"verify" / "verification" → the verb (check a change now) is
```
verify
```
; creating a reusable verification script is
```
create-agent-verification
```
. The
```
create-
```
framing is the tell. Ask if the user's phrasing doesn't disambiguate.
"triage" → in Shiplight this means
```
fix
```
(repair failing tests). Do not confuse with
```
review
```
's internal triage/plan step.
"failing tests" / "flaky tests" → reading them from CI ("in the cloud", "from the last run", plural reporting) is
```
cloud
```
(Nova results); repairing a broken test ("my test is failing", "fix this") is
```
fix
```
. Ask if the phrasing doesn't say which.
"report a bug" / "X is broken" → depends on what is broken. The user's app misbehaving is ground truth to report (
```
_shared/ground-truth.md
```
), not a subcommand; Shiplight itself misbehaving (skill, CLI, cloud API) is
```
support
```
. Ask if unclear which one the user means.

"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
```
（Nova结果）；修复单个失败测试（"我的测试失败了"、"修复这个测试"）对应
```
fix
```
。若用户表述无法明确区分，需询问。
"report a bug" / "X is broken" → 取决于什么出现问题。用户应用故障属于需要报告的事实依据（
```
_shared/ground-truth.md
```
），不属于子命令；Shiplight自身故障（技能、CLI、云API）对应
```
support
```
。若存在歧义，需询问用户。

After a subcommand completes or aborts (next-step suggestion)

子命令完成或终止后的下一步建议

After a subcommand's final report — including the report of an aborted run — optionally append one next-step suggestion. Rules:

Evidence-only. A suggestion must be triggered by something already observed during the run — the diff analyzed, the failure diagnosed, the project state read. Never run extra analysis (a new git diff, file scan, or browser session) just to decide a suggestion.
Silence is the default. No trigger from the table → no suggestion line at all. Failure states mostly suggest nothing: the user's next step is fixing the product, not another Shiplight command. Suggestions fire on success — "you proved it works; now make that durable / continuous / visible." The one failure that does fire is the Shiplight-side failure row (
```
support
```
), and it fires wherever the run stops — a mid-run abort report counts.
Gate on the nature of the change. When the run started from a code change that is backend-only or barely touches UI, suppress the browser-flavored suggestions (
```
verify
```
,
```
create-yaml-tests
```
,
```
review design
```
);
```
cover
```
(picks unit/contract/integration via its capability map) and
```
create-agent-verification
```
(cross-layer live checks) are the useful pointers there.
One line, statement not question. Format:
```
Next: /shiplight <cmd> — <reason from this run>
```
. Never auto-run the suggested command; never ask a blocking yes/no. The user decides.
At most one suggestion — two only when genuinely forked (e.g.
```
cover
```
vs
```
create-yaml-tests
```
by scope).
Skip entirely in CI / non-interactive mode, and after
```
update
```
/
```
help
```
/
```
support
```
.

After	Trigger observed during the run	Suggest
`init`	app has login/authed routes	`auth` ; otherwise `cover`
`auth`	invoked to unblock another command	resume that command; otherwise nothing
`verify`	passed on a meaningful flow with no YAML test covering it	`cover` (feature-level) or `create-yaml-tests` (single narrow flow) — verify is ephemeral, lock it in
`verify`	UI smells seen while driving: missing labels/roles, no `data-testid` s, brittle DOM, console warnings	`review design` (accessibility + testability)
`verify`	check failed, or the change was trivial	nothing
`fix`	diagnosis was product change and the change extends beyond the repaired tests	`cover <feature>` to refresh the testing-what spec
`fix`	repeated locator drift / no stable semantic hooks	`review design` (testability) — root-cause the drift instead of re-fixing every sprint
`fix`	repro came from a CI failure, or several tests shared one source	`cloud` to check blast radius / confirm the next run is green
`fix`	diagnosis was an app bug	nothing — report the bug ( `_shared/ground-truth.md` )
`create-yaml-tests`	tests pass and no CI E2E workflow exists	`ci`
`create-yaml-tests`	flow's confidence needs API/DB/log state better judged than asserted	`create-agent-verification`
`create-agent-verification`	case `PASS` on a now-stable path whose proof reduces to fixed conditions	`create-yaml-tests` (promote to deterministic) — not when its worth is the judgment across evidence
`create-agent-verification`	`BLOCKED` on login/session bootstrap	`auth`
`cover`	produced Shiplight tests, no CI wiring	`ci`
`cover`	report rows `BLOCKED` on auth/env	`auth`
`review`	user fixed UI findings in-session	`verify` to confirm the fixes render
`review`	high-severity findings without regression coverage	`cover`
`ci`	workflow wired	push / open a PR to trigger it, then `cloud` for the first run's results
`ci`	no tests exist yet	`cover` first (precondition, per `ci/index.md` )
`cloud`	failing/flaky tests attributed `spec_issue` / drift	`fix`
`cloud`	attribution dominated by `app_regression`	nothing to run — an app bug to report
`cloud`	recorder sessions covering untested flows	`create-yaml-tests` from the recording
any	the run stopped on a Shiplight-side failure with no known fix — CLI crash, unexplained Shiplight API error, or the same step failing twice identically	`support` — the diagnostics for a ticket are already in this session

在子命令生成最终报告后（包括终止运行的报告），可选择性添加一条下一步建议。规则如下：

仅基于已有证据：建议必须由运行期间观察到的内容触发——已分析的差异、已诊断的故障、已读取的项目状态。切勿为了确定建议而执行额外分析（如新的git diff、文件扫描或浏览器会话）。
默认不提供建议：若表格中无触发条件→完全不显示建议行。故障状态通常不提供建议：用户的下一步是修复产品，而非执行其他Shiplight命令。建议仅在成功运行时触发——"你已验证功能正常；现在让测试更持久/持续化/可视化。"唯一例外是Shiplight自身故障（
```
support
```
），无论运行在哪个阶段终止——包括中途终止的报告，都会触发建议。
根据变更类型调整：若运行始于仅涉及后端或几乎不涉及UI的代码变更，需屏蔽浏览器相关的建议（
```
verify
```
、
```
create-yaml-tests
```
、
```
review design
```
）；此时
```
cover
```
（通过能力图选择单元/契约/集成测试）和
```
create-agent-verification
```
（跨层实时检查）是更有用的指引。
单行陈述，非疑问句：格式为：
```
下一步：/shiplight <cmd> —— <本次运行触发的原因>
```
。切勿自动运行建议的命令；切勿提出需要用户确认的问题。由用户自行决定是否执行。
最多一条建议——仅当存在明确分支时可提供两条（例如根据范围选择
```
cover
```
或
```
create-yaml-tests
```
）。
在CI/非交互模式下完全跳过，且在
```
update
```
/
```
help
```
/
```
support
```
命令后也跳过。

执行命令后	运行期间观察到的触发条件	建议内容
`init`	应用包含登录/授权路由	`auth` ；否则建议 `cover`
`auth`	为解除其他命令的阻塞而调用	恢复执行原命令；否则无建议
`verify`	在有意义的流程上验证通过，但该流程未被YAML测试覆盖	`cover` （功能级）或 `create-yaml-tests` （单个窄流程）——verify是临时验证，需固化为持久测试
`verify`	执行过程中发现UI问题：缺少标签/角色、无 `data-testid` 、DOM不稳定、控制台警告	`review design` （可访问性 + 可测试性）
`verify`	验证失败，或变更内容无关紧要	无建议
`fix`	诊断结果为产品变更，且变更范围超出已修复的测试	`cover <feature>` 以更新测试范围规范
`fix`	重复出现定位偏移 / 无稳定语义钩子	`review design` （可测试性）——从根源解决偏移问题，而非每次迭代都重新修复
`fix`	故障来自CI失败，或多个测试共享同一故障源	`cloud` 以检查影响范围 / 确认下一次运行是否正常
`fix`	诊断结果为应用bug	无建议——需报告bug（ `_shared/ground-truth.md` ）
`create-yaml-tests`	测试通过且无CI端到端工作流	`ci`
`create-yaml-tests`	流程的可信度需要通过API/DB/日志状态进行更精准的判断，而非简单断言	`create-agent-verification`
`create-agent-verification`	在当前稳定路径上验证通过且验证逻辑可简化为固定条件	`create-yaml-tests` （转换为确定性测试）——仅当验证价值不依赖跨证据判断时适用
`create-agent-verification`	因登录/会话初始化而阻塞	`auth`
`cover`	已生成Shiplight测试，但未配置CI	`ci`
`cover`	报告中存在因授权/环境问题而阻塞的条目	`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` ——会话中已包含工单所需的诊断信息