takeone

takeone

takeone 可以无头录制 Web 应用。你在实时浏览器中排练视频，排练过程会变成一个场景文件，然后场景按自己的时钟重放并录制。你的思考时间不会出现在视频中，光标、缩放和画框会在之后应用，因此无需重新录制即可重新设计视频样式。

工作流分为五个阶段，按以下顺序进行：

1. 排练。 在应用中实时点击操作。每一步都会显示页面。
2. 标记视频的起始位置。
3. 导出。 takeone 会重放操作路径以确认其有效，然后写入场景文件。
4. 试运行。 按录制速度运行，并返回一张联系表（每个步骤对应一帧的图像）。
5. 录制。 捕获并渲染视频。

安装和设置

每个项目只需执行一次，在首次录制前完成。每个步骤都可以安全地重复执行。

1. 检查是否已安装。 如果 package.json（位于项目目录或 videos/ 文件夹中）列出了 takeone，请跳到步骤 4。

2. 检查 Node。 node -v 必须为 20 或更高版本。如果未安装 Node 或版本较旧，请告知用户并停止：没有它，其他操作都无法进行。

3. 在场景文件所在位置安装软件包。 导出的场景会运行 import … from "takeone"，因此必须在场景文件旁边安装软件包。

   • JavaScript 或 TypeScript 项目（包含 package.json）：使用项目自己的包管理器将 takeone 添加为开发依赖项，锁文件会显示所用的包管理器：npm i -D takeone、pnpm add -D takeone、yarn add -D takeone 或 bun add -d takeone。
   • **其他项目，或不应改动应用依赖项时：**为视频单独创建一个文件夹。

     mkdir -p videos && cd videos && npm init -y && npm pkg set type=module && npm i -D takeone
     

     从该文件夹运行所有 takeone 命令。场景文件、.takeone/ 状态文件夹和 recordings/ 都会保存在其中。

   CLI 随软件包一起提供：运行 npx takeone <command> 即可使用。npx takeone guide 会在一个屏幕上打印完整工作流。全局安装（npm i -g takeone）后可直接使用 takeone 命令，但场景仍需要本地安装。

4. 准备机器。 运行 npx takeone setup。它会：

   • 下载 Chromium（约 650 MB，每台机器只需下载一次）
   • 检查 ffmpeg；它随软件包一起提供
   • 启动无头浏览器，以验证录制能否正常运行

   最后会显示 Ready.，或者显示说明问题所在的 ✗ 行。在 Linux 服务器上，缺少系统库通常是失败原因。运行 npx takeone setup --with-deps 安装所需库，该命令需要 sudo。如果无法使用 sudo，请让用户运行该命令。

5. 注册 MCP 服务（可选，推荐）。 它的回复会附带屏幕截图，因此一次调用既能执行操作，也能展示页面。请为当前使用的 Agent 注册该服务：

   claude mcp add takeone -- npx -y takeone mcp     # Claude Code
   codex mcp add takeone -- npx -y takeone mcp      # Codex
   

   其他客户端可在其 MCP 配置中使用 {"command": "npx", "args": ["-y", "takeone", "mcp"]}。

   MCP 服务会在会话启动时加载，因此这些工具要到下一个会话才会显示。无需等待：本次会话剩余操作请使用 CLI，并告知用户重启后即可使用 MCP 工具。MCP 服务和 CLI 共用一个浏览器会话，因此在两者之间切换不会丢失任何内容。

之后如需更新，请运行 npm i -D takeone@latest，然后运行 npx takeone session stop，让正在运行的浏览器会话加载新版本。

命令

步骤	MCP 工具	CLI
启动，可选登录	takeone_start {scenario, url, headed, viewport}	首条命令，带上 --scenario login.ts
操作	takeone_do {verb, target, text}	npx takeone do <verb> <target> [text]
查看页面	takeone_look {filter, role, all}	npx takeone look
标记	takeone_mark {name: "start"}	npx takeone mark start
记录	takeone_journal {action, ids}	npx takeone journal [drop|keep|setup] 3-5
导出	takeone_export {file}	npx takeone session export demo.ts
试运行	takeone_dry_run {file}	npx takeone dry-run demo.ts
录制	takeone_record {file}	npx takeone record demo.ts
停止浏览器	takeone_stop	npx takeone session stop

动词：goto、click、type、press、hover、scroll、scroll-to、wait-for、wait-url、wait、zoom、zoom-out。

打开浏览器前先规划视频

在首次 goto 前，用三到六个步骤写下故事，例如“打开 Projects，创建一个项目，在列表中展示该项目，放大查看其状态”。每个步骤都应展示观众能看到的变化。然后只排练这些步骤。规划能缩短排练时间，因为你会清楚哪些点击属于视频内容，哪些只是四处查看。

• 从已加载完成的页面开始。 录制应从已加载完成的页面开始，而不是加载动画页面。将导航和准备工作放在 mark start 之前；不希望观众看到的操作则放在 mark setup 之后。
• 录制前准备好数据。 如果视频需要已有项目，请在设置步骤中创建，或在排练前通过应用的 API 创建。只有当创建本身就是视频重点时，才应在镜头前创建。
• 尽量简短。 每段视频控制在 20 到 60 秒。与其制作一段较长的视频，不如制作两段较短的视频，这样更容易做好，也更方便观看。

排练：阅读视图，按编号操作

首次 goto 会启动 Chrome。每个跳转到新页面或打开对话框的步骤都会返回视图。视图会按区域分组，列出屏幕上的所有元素及其编号，并说明页面标记中对各元素的功能描述：

header
  1 link "Acme" [icon logo] → /
sidebar "Workspace"
  4 link "Projects" [current] → /projects
main
  12 button "New project"
  13 button [icon ellipsis] (opens menu)
  14 switch "Email alerts" [off]
off screen: 22 more elements. Headings: 30 "Members", 41 "Billing"

视图还会附带一张截图，并在图中标出相同的编号。MCP 会附上图片；CLI 会打印图片路径。先阅读文本。只有文本无法解答问题时才打开截图，例如查看布局、图标、图表，或确认镜头中的效果是否合适。然后按编号操作：click 12、type 5 "acme-prod"、zoom 14。编号对应最近一次视图。

其他步骤只会输出发生变化的内容：

• + 新增元素及其编号
• - 已移除的元素
• ~ 状态变化
• 警报、对话框和页面错误（!）

通常只需查看这些差异，就能决定下一步操作，因此不必每次操作后都调用 look。

目标也可以是普通文字（"new project"）、role:name（button:Create）、text=Deployed、css=.monaco-editor，或坐标点 640,360。如果控件名称是数字，请使用 button:2。

视图中的每一行都读取自页面标记。takeone 从不会通过点击来判断元素的功能。这是有意为之：在后台尝试点击 Delete 或 Create 按钮，确实会执行相应操作。

何时使用哪个命令

情况	使用	不要使用
进入页面或打开对话框时	do 已经打印的视图	额外执行 look
点击、输入或按键之后	变更报告（+、-、~）	look，除非报告指出页面还在变化
文字中看不到的内容：图标、布局、图表、画面效果是否合适	截图（通过 MCP 内联显示；使用 CLI 时查看 view: 路径）	根据名称猜测
查找屏幕外或长页面上的内容	look --filter <text>，然后执行 scroll-to <n>	盲目滚动后再查看
对最新视图中的内容执行操作	使用其编号（click 12）	重新输入其名称
页面已在你查看的视图之后发生变化，或你知道标签	普通文字（click "new project"）	使用旧视图中的编号
多个控件名称相同	使用其编号，或搭配 --nth 使用 role:name。导出时会尽可能通过旁边的文字定位	CSS 选择器
等待应用完成操作：保存、部署、配置资源	使用 wait-for "<text that appears>"，并设置足够长的 --timeout	使用 wait <ms>，因为这只是猜测
留出一点时间让观看者阅读	使用 wait 800 到 wait 1500	什么都不做：连续操作会显得仓促
放大展示结果	使用 zoom <n>，然后执行 zoom-out	每次点击都缩放，因为自动缩放已经会跟随点击
导出前检查路径	journal	抱着侥幸心理直接导出
录制前检查完整视频	执行 dry-run，然后查看联系表	先执行 record：录制失败会浪费几分钟
编辑场景时快速检查路径	dry-run --fast	把快速检查当作录制一定会通过的证明
只改变外观（背景、光标、大小）	使用其他配置执行 render <recording-dir>	重新录制
完成后，或更新 takeone 后	session stop	让浏览器继续运行

explore 和 find 是用于按 URL 枚举页面的旧命令。视图和 look --filter 可以完成同样的工作，而且更省事。

充分排练

• 按视频中的顺序排练完整路径。 多余的绕路会自动删掉，但每个额外步骤都需要在日志中多检查一次。
• 页面显示视频起始画面后，立即调用 mark start。 此前的内容不会出现在视频中，所以可以先放心查看。
• 输入观看者应该看到的内容。 使用真实的名称和值（例如“acme-prod”，而不是“test123”）。这些内容最终都会显示在屏幕上。
• 步骤失败时，先阅读错误再重试。 错误会说明页面显示了什么：登录页面意味着会话尚未通过身份验证；“not found”意味着 URL 或 ID 有误。重复执行同一步骤很少能解决问题。
• 路径变化时重新排练；只有时间安排变化时，编辑文件即可。 等待时间、输入速度、缩放比例和额外停顿都可以在导出的场景中通过修改一行完成。点击顺序改变则需要重新排练并重新导出。
• 完成前先检查。 查看 dry-run 联系表和 record 生成的关键帧表：每个节拍是否都到位？有没有内容被截断？画面中是否出现加载状态？

从演练到视频

1. 视频开始前可以随意点击浏览。 会让页面回到较早状态的步骤会作为绕路从导出内容中移除。例如，打开菜单后再将其关闭。
2. 在视频应该开始的地方调用 mark start。 此前的所有操作都算作浏览。如果应用需要进行不应录入视频的准备工作，请在 mark start 前调用 mark setup。例如，打开项目或清空表单。
3. 导出前检查日志。 journal 工具会显示每个步骤执行后的页面状态。使用 keep 恢复误删的步骤，使用 drop 移除步骤。
4. 导出。 导出前会先在新标签页中重放保留的步骤。如果重放失败，错误会指出出错的步骤，并显示页面返回的内容。
   • 导出的文件使用角色和名称定位，不使用视图编号。
   • 名称中包含实时计数或徽章的内容会写成模式。例如，"Issues 157" 会变为 /^Issues(?![\w.])/。
   • 导出到现有文件时，只会替换 // takeone:steps-begin 与 // takeone:steps-end 之间的代码块，因此块外的编辑会保留。
5. 录制前先试运行。 试运行会严格按照录制时的节奏操作页面，因此试运行通过就意味着录制也会通过。查看联系表：这是检查整个视频成本最低的方式。
6. 录制。 结果文件为 recordings/<name>-<time>/output.mp4，另附一张用于检查录制效果的关键帧表。

导出的文件是普通的 TypeScript。再次演练不如手动修改来得快时，可以直接调整文件中的时间（s.wait）、打字速度和缩放。references/scenario-api.md 列出了所有方法和选项。

已登录的应用

将登录操作放入场景的 explore.setup，然后使用该文件启动会话。会话只登录一次，之后的每个步骤都会复用登录状态。导出的场景会导入该文件，并在录制前执行相同的登录操作。

import { defineScenario, withExplore } from "takeone";

export default withExplore(defineScenario({ name: "login" }, async () => {}), {
  pages: [],
  setup: async (page) => {
    await page.goto("http://localhost:3000/login");
    await page.fill('input[name="email"]', process.env.DEMO_EMAIL!);
    await page.fill('input[name="password"]', process.env.DEMO_PASSWORD!);
    await page.click('button[type="submit"]');
    await page.waitForURL(/dashboard/);
    // App state the video needs: a theme stored by the app itself, hidden banners, and so on.
    await page.evaluate(() => localStorage.setItem("theme", "dark"));
  },
});

从环境变量读取凭据。切勿将凭据写入文件。

browser.colorScheme: "dark" 只会设置浏览器的深色模式偏好，页面可通过 prefers-color-scheme 读取该设置。如果应用有自己的主题设置，请像上面那样在 setup 中设置。

让画面更出色

• 为观看者缩放，而不是为每次点击缩放。 自动缩放已会跟随点击和输入，并由 zoom.auto 控制。需要让观看者看清某些内容时再显式添加 zoom：例如结果、状态或发生变化的数值。保持约 1.5 s，然后在光标移动较远前调用 zoom-out。每分钟刻意缩放两到四次，比持续移动更易观看。如需关闭某个片段的自动缩放，请调用 s.autoZoom(false)。
• 如实展示耗时较长的步骤。 默认情况下，等待会按实时播放。s.lapse(8, () => …) 会以延时摄影的方式展示较长的等待；s.trim(() => …) 会缩短等待。
• 清晰录制。 默认视口为 1920x1080，且 deviceScaleFactor: 2，可确保缩放后画面清晰。输出尺寸需单独设置（output.width、output.height、output.fps）；要输出 4K，请使用 deviceScaleFactor: 3 录制。无需重新录制即可重新设置现有录制的样式：使用其他 frame、cursor 或 output 设置运行 takeone render <recording-dir>。
• 尽量录制较短的片段。 多个较短的场景比一个较长的场景更容易录好。使用 record --no-render 后再运行 render，可以将录制与样式处理分开。

如果不了解，可能会浪费时间的事项

• 排练和试运行会更改真实数据。 创建用户、项目或文件都会真正创建。请使用唯一名称，或在两次录制之间重置应用，以免后续运行因“名称已被占用”而失败。
• 页面列表中看不到某些文本字段。 代码编辑器（Monaco）和终端（xterm）通过隐藏的文本框接收输入。点击编辑器，然后不指定目标直接输入（type 后只跟文本），即可将内容输入当前焦点所在的位置。
• 录制中的按键序列执行很快。 排练时，两次单独的 press 调用可能错过快捷键的触发时间窗口，例如先按 g 再按 i。导出的场景会连续执行这两次按键，因此在认定应用出错前，请先进行试运行。
• 页面问题会显示为 ! 行。 401 错误或崩溃会在步骤输出中显示为 ! HTTP 401 …。错误中的“登录页面”或“未找到”表示 URL 或身份验证有误，而不是元素名称有误。
• 不会卡住。 每条命令都会报错退出，而不会无限等待，因此不要为命令设置很长的超时时间。命名目标会等待元素出现，最长为 browser.timeout（15 s）。
• 同一台机器上的两个 Agent 需要使用不同的会话。 为第二个 Agent 设置 TAKEONE_SESSION_PORT=9322，它就会获得自己的浏览器。
• 更新后的 takeone 不会影响正在运行的会话。 更新前启动的会话会继续运行旧代码。CLI 会对此发出警告。运行 takeone session stop 以重启会话。

SDK

场景是 TypeScript 模块，运行器也可以在代码中使用：

import { recordScenario, renderRecording, dryRunScenario } from "takeone";
import scenario from "./demo.js";

const rec = await recordScenario(scenario, { outDir: "out/demo" });
await renderRecording({ recordingDir: rec.outDir, config: { frame: { background: "#0b0b0f" } } });

会话方法、目标和所有配置选项，请参阅 references/scenario-api.md。