screenci

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ScreenCI Video and Guide Skill

ScreenCI 视频与引导技能

Use this skill when the task is about ScreenCI video recording workflows in an existing project, or updating

.video.ts

files and

screenci.config.ts

Trigger this skill when the user asks to:

create a video
show a flow as a video
create a guide/demo video

Routing rules:

If the user provides a URL, always use the
```
playwright-cli
```
skill first to inspect the real page flow and selectors before editing the ScreenCI script.
If the user provides source code for the target page/component, that usually means browser exploration is not required first.
If the request is only about application/source-code changes (not recording or
```
.video.ts
```
updates), do not use this skill.

当任务涉及现有项目中的ScreenCI视频录制工作流，或更新

.video.ts

文件和

screenci.config.ts

时，使用此技能。

当用户提出以下请求时触发此技能：

创建视频
将流程以视频形式展示
创建引导/演示视频

路由规则：

如果用户提供URL，在编辑ScreenCI脚本前，务必先使用
```
playwright-cli
```
技能检查真实页面流程和选择器。
如果用户提供目标页面/组件的源代码，通常意味着无需先进行浏览器探索。
如果请求仅涉及应用/源代码变更（而非录制或
```
.video.ts
```
更新），请勿使用此技能。

Quick Start

快速开始

Assume the project is already initialized. Add or edit video scripts in

videos/

If you are creating new videos, remove the starter

videos/example.video.ts

file.

bash

undefined

假设项目已完成初始化。在

videos/

目录下添加或编辑视频脚本。

如果要创建新视频，请删除初始的

videos/example.video.ts

文件。

bash

undefined

iterate locally without recording

本地迭代，不进行录制

npx screenci test --ui

verify repeatedly until green

反复验证直到测试通过

npx screenci test

only record after tests pass

仅在测试通过后进行录制

npx screenci record

undefined

npx screenci record

undefined

What ScreenCI Adds

ScreenCI 新增功能

ScreenCI uses Playwright-style

.video.ts

files and adds recording-specific helpers:

```
video()
```
declares one output video per test.
```
hide()
```
removes setup and loading sections from the final recording.
```
autoZoom()
```
follows a larger form or page area with smooth camera motion. Use it sparingly, and start with its default options unless the user explicitly asks for different zoom behavior or the flow clearly needs a targeted override.
```
createNarration()
```
is mandatory for every video: define it in every
```
.video.ts
```
file and include spoken narration throughout the demo. The opening narration should first state the purpose of the video, then continue with the explanation or walkthrough. Define the map once, then call
```
await narration.key.start()
```
where each line should begin. Use
```
await narration.key.finish()
```
only when the next action must wait for audio to finish.
Narration text can include inline speech-control tags such as
```
[pronounce: screen see eye]
```
,
```
[short pause]
```
,
```
[medium pause]
```
, and
```
[long pause]
```
when a word needs guided pronunciation or an intentional pause.

ScreenCI 使用类Playwright风格的

.video.ts

文件，并添加了录制专属的辅助函数：

```
video()
```
为每个测试声明一个输出视频。
```
hide()
```
从最终录制内容中移除设置和加载环节。
```
autoZoom()
```
通过平滑的镜头移动跟随较大的表单或页面区域。请谨慎使用，除非用户明确要求不同的缩放行为，或流程明显需要针对性覆盖，否则请使用默认选项。
```
createNarration()
```
是每个视频的必填项：在每个
```
.video.ts
```
文件中定义它，并在演示全程添加语音旁白。开场旁白应首先说明视频的用途，然后再进行讲解或演示。只需定义一次映射，然后在需要开始每一行旁白的位置调用
```
await narration.key.start()
```
。仅当下一个操作必须等待音频结束时，才使用
```
await narration.key.finish()
```
。
旁白文本可包含内联语音控制标签，如
```
[pronounce: screen see eye]
```
、
```
[short pause]
```
、
```
[medium pause]
```
和
```
[long pause]
```
，用于指导生僻词发音或添加有意的停顿。

Required Conventions

必填规范

Every video MUST follow these conventions:

Narration on every video (required, no exceptions) — always define
```
createNarration({ ... })
```
and add narration to every
```
.video.ts
```
file. Videos without narration are not acceptable.
Open with the video's purpose — the first spoken narration should clearly state what the video is for before moving into the step-by-step explanation.
Start on the requested page — the visible video should always begin on the page the user requested.
Hide initial setup — the initial page load should almost always be wrapped in
```
hide()
```
. Keep authentication, navigation to the starting page, loading spinners, cookie banner dismissal, and any other non-demo boilerplate inside that hidden block so they are cut from the final recording.
Navigate visibly with clicks — after hidden setup, move through the demo by clicking real links and buttons instead of calling
```
page.goto()
```
.
Use autoZoom sparingly on large page areas — add
```
autoZoom()
```
only for larger sections that benefit from camera guidance (e.g. a full form, a full dialog, or a broad list area). Keep usage sparse, and make sure each
```
autoZoom()
```
block includes multiple related interactions (typing, selecting, toggling, confirming, etc.), not just a single click.
End autoZoom before page changes — it is better to let an
```
autoZoom()
```
block finish before a navigation/page change. Staying zoomed during navigation is confusing. Start a new
```
autoZoom()
```
block on the next page/section when needed.
Prefer default action options — for
```
autoZoom()
```
and locator actions such as
```
click()
```
,
```
fill()
```
,
```
pressSequentially()
```
,
```
check()
```
,
```
uncheck()
```
,
```
selectOption()
```
,
```
selectText()
```
, and similar helpers, start with ScreenCI's default options. Do not add custom
```
zoom
```
,
```
click
```
,
```
position
```
, timing, or other locator-action overrides unless the user asks for them or the recording flow clearly needs a specific adjustment.

每个视频必须遵循以下规范：

每个视频都必须添加旁白（必填，无例外） — 务必在每个
```
.video.ts
```
文件中定义
```
createNarration({ ... })
```
并添加旁白。没有旁白的视频不符合要求。
开场说明视频用途 — 第一段语音旁白应在进入分步讲解前，清晰说明视频的用途。
从用户请求的页面开始 — 可见的视频必须始终从用户指定的页面开始。
隐藏初始设置环节 — 初始页面加载环节几乎都应包裹在
```
hide()
```
中。将身份验证、导航至起始页面、加载动画、Cookie横幅关闭以及其他非演示的样板内容放入此隐藏块，使其从最终录制内容中移除。
通过点击进行可见导航 — 完成隐藏设置后，通过点击真实链接和按钮来推进演示，而非调用
```
page.goto()
```
。
仅在大页面区域谨慎使用autoZoom — 仅为需要镜头引导的较大区域（如完整表单、完整对话框或宽泛列表区域）添加
```
autoZoom()
```
。请尽量少用，并确保每个
```
autoZoom()
```
块包含多个相关交互（输入、选择、切换、确认等），而非仅单次点击。
页面变更前结束autoZoom — 最好在导航/页面变更前结束
```
autoZoom()
```
块。导航过程中保持缩放会造成混淆。必要时，在下一个页面/区域启动新的
```
autoZoom()
```
块。
优先使用默认操作选项 — 对于
```
autoZoom()
```
和定位器操作（如
```
click()
```
、
```
fill()
```
、
```
pressSequentially()
```
、
```
check()
```
、
```
uncheck()
```
、
```
selectOption()
```
、
```
selectText()
```
及类似辅助函数），请先使用ScreenCI的默认选项。除非用户要求，或录制流程明显需要特定调整，否则请勿添加自定义的
```
zoom
```
、
```
click
```
、
```
position
```
、计时或其他定位器操作覆盖项。

Command Notes

命令说明

```
screenci record
```
runs the recording flow with local Playwright.
```
screenci test --ui
```
runs Playwright in UI mode for fast iteration without screen capture.
```
screenci retry
```
uploads the latest
```
.screenci
```
output when API configuration is available.

```
screenci record
```
使用本地Playwright运行录制流程。
```
screenci test --ui
```
以UI模式运行Playwright，快速迭代且不进行屏幕捕获。
```
screenci retry
```
在API配置可用时，上传最新的
```
.screenci
```
输出内容。

Recording Workflow

录制工作流

Start from the existing initialized ScreenCI package.
Add or edit
```
.video.ts
```
files in
```
videos/
```
. Remove
```
videos/example.video.ts
```
if you are creating new videos and do not need the starter video. For narration, define
```
const narration = createNarration({ ... })
```
near the top of the file and trigger lines with
```
await narration.someKey.start()
```
inside the test body. Make the first narration line state the video's purpose, then use the following lines for the explanation. Use inline tags like
```
[pronounce: ...]
```
and
```
[short pause]
```
inside cue text when needed.
Run
```
npx screenci test --ui
```
to validate selectors and flow.
Run
```
npx screenci test
```
until it passes.

Run

npx screenci record

to produce

.screenci/<video-name>/recording.mp4

and

data.json

从已初始化的ScreenCI包开始。
在
```
videos/
```
目录下添加或编辑
```
.video.ts
```
文件。如果要创建新视频且不需要初始示例视频，请删除
```
videos/example.video.ts
```
。对于旁白，在文件顶部附近定义
```
const narration = createNarration({ ... })
```
，并在测试主体中使用
```
await narration.someKey.start()
```
触发旁白内容。第一段旁白应说明视频用途，后续内容用于讲解。必要时在提示文本中使用
```
[pronounce: ...]
```
和
```
[short pause]
```
等内联标签。
运行
```
npx screenci test --ui
```
验证选择器和流程。
运行
```
npx screenci test
```
直到测试通过。

运行

npx screenci record

生成

.screenci/<video-name>/recording.mp4

和

data.json

。

Specific Tasks

特定任务

Recording videos references/record.md

录制视频 references/record.md