screenci

ScreenCI 视频技能

用于在 ScreenCI 项目（.screenci.ts、screenci.config.ts）中录制视频或静态画面。不适用于仅修改应用源代码的情况。只有任务需要时才加载参考资料。

路由：

• 给定 URL 时，先探索页面：使用 npx screenci explore <url> --click "<name>"，或使用 playwright-cli 技能处理较长的流程，绝不要自行编写 Playwright 脚本。已登录的应用：playwright-cli state-load screenci/.screenci/auth/default.json。
• 给定页面源代码时，通常无需探索。
• 录制器和探索浏览器并不相同。 如果某个步骤在 playwright-cli 中有效，但在 npx screenci test 中失败或遇到机器人检查，或者捆绑的 Chromium 无法启动（缺少系统库，例如 NixOS），原因在于浏览器，而非选择器：在 screenci.config.ts 中设置 use: { channel: 'chrome' } 并重新运行。

快速开始

• 设置代码（SC-XXXX-XXXX）：运行 npx screenci@latest setup SC-XXXX-XXXX（新建项目时添加 --name "<project name>"，如果 ./screenci 属于其他项目则添加 --dir <path>），然后按照它输出的简要说明操作。对于已完成设置的项目，后续的 Edit 提示可能会要求跳过设置：此时直接编辑工作区。
• 否则，项目已存在：编辑 recordings/*.screenci.ts，移除初始示例文件 example.screenci.ts。如果 init 因 screenci/ already exists 而失败，这是预期行为；绝不要删除该目录来重新初始化。
• npx screenci context 会打印项目已知的信息（网站、登录状态、团队备注）。

约定（适用于每个视频）

• 每个视频都要配旁白，开场说明视频的目的；讲述流程，而不是点击操作。详情：references/narration.md。
• 公司口吻：以制作该产品的公司的身份使用「我们」「我们的」「您」。
• 仅使用虚构数据，并将其呈现为真实数据。 使用合理的虚构姓名和电子邮件；视频中绝不提及数据是模拟、示例或虚构的。
• 不要在生产环境提交现实世界的表单（订单、付款、电子邮件、邀请、删除、发布、账户或账单变更）：填写表单，最后停留在已填写完成的表单上，并对提交按钮使用 hover()。旁白绝不提及表单未提交。在开发、预发布或测试部署环境中，则照常提交。
• 从提示指定的页面开始。 如果复制的提示中指定了页面或 URL，视频就从该处打开（对该 URL 使用 page.goto），而不是从网站主页打开；否则从请求的页面开始。使用 hide() 隐藏加载、导航、旋转指示器和 Cookie 横幅；初始导航后，在该隐藏代码块中查找并点击任何 Cookie 同意接受按钮。不要添加登录步骤：参见下面的登录说明。
• 设置完成后，通过点击进行可见导航，不要使用 page.goto()；输入后点击可见结果，而不是使用 press('Enter')。
• 默认操作选项。 不要在 fill() 之前额外调用 click()；除非提出要求或确有必要，否则不要覆盖 zoom、position 或时间设置。
• 使用内置工具包添加叠加层（{ kit: 'callout', anchor, text }、ring、step、spotlight、badge、keys、title）。只有工具包无法实现时才使用自定义 HTML/React：绝不要手写 SVG 或自行挑选颜色；使用 recordings/assets/theme.ts。

常见编辑

任务	阅读
旁白文本、提示、语音、发音	references/narration.md
缩放、摄像头、光标速度、speed()	references/zoom-and-timing.md
高亮、标注、步骤、标题卡	references/overlays.md
静态图像（screenshot()）	references/screenshots.md
登录后的应用	references/login.md
账户、试用、SCREENCI_SECRET、导出	references/account.md, references/export.md

简而言之，登录时：绝不编写登录脚本，也绝不向对方索要密码或验证码；运行 npx screenci login，然后运行 npx screenci login --wait。

命令

• 运行 npx screenci test recordings/<file>.screenci.ts [--grep "<title>"] 进行调试；暂停不会耗时。
• npx screenci preview "<title>" 会录制并上传免费的实时预览：流程正常后，只需执行这一步进行验证。提供预览链接；不要打开视频。
• 只有对方要求获取成品文件时，才运行 npx screenci export。
• CI：绝不要自行添加流水线；对方会在 Web 应用中使用 Add to CI。

向对方反馈

• 对方通常是不写代码的队友。不要让他们运行命令或阅读脚本。用通俗语言说明：视频展示了什么、改了什么、需要他们做什么。
• 如果视频是在正式生产网站上录制，涉及现实操作的步骤（下单、付款、发送、删除、发布、账户或账单变更）都应保持未提交状态。除非对方明确要求，并且先行确认，否则不要在该网站提交这类表单。在开发、预发布或测试部署环境中，阅读、导航及其他操作都没问题。
• 绝不要索要密码、一次性验证码或 API 密钥。
• 按设置说明中规定的方式交付（实时预览、流水线运行或拉取请求）；只有要求运行流水线的情况才通过流水线完成。
• 结尾处单独一行放置打印出来的视频链接 preview（或流水线运行链接）。