# agent-screenplay 中文文档

规范地址：https://npmcn.com/package/agent-screenplay/

版本：0\.1\.4
npm 元数据更新时间：2026-11-03T01:50:17.519Z
中文译文更新时间：2026-11-03T02:16:21.696Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/agent-screenplay
原文对照：https://npmcn.com/package/agent-screenplay/?lang=original
项目主页：https://github.com/gmpetrov/agent-screenplay#readme
源码仓库：https://github.com/gmpetrov/agent-screenplay

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.3 MB，103 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：6 个
- 首次发布：2026-11-02T22:38:35.662Z
- 最新版本发布：2026-11-03T01:50:17.351Z
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

为AI代理编写屏幕工作室质量的屏幕记录：编写一个场景，剧本拍摄并编辑它（平滑光标，自动缩放，标注，画外音）。

## 安装

```sh
npm install agent-screenplay
```

也可以使用：`pnpm add agent-screenplay`、`yarn add agent-screenplay`、`bun add agent-screenplay`

## README

# 剧本

[https://github.com/user-attachments/assets/dd9898da-4900-4a91-8620-57a860c46093](https://github.com/user-attachments/assets/dd9898da-4900-4a91-8620-57a860c46093)

**Screen studio质量的屏幕录音，由你的AI代理制作。**

询问Claude Code、Codex、Cursor或任何代理： _“制作一个视频，展示人类的交接是如何进行的”_． 代理探索你的应用程序，并写一个短 **场景**;剧本在浏览器（或桌面应用程序）中播放，拍摄，并像Screen Studio一样编辑视频：平滑光标，自动缩放动作，点击效果，标注，聚光灯，字幕，标题卡和可选的画外音。

![Storyboard of an example video](https://npmcn.com/package/agent-screenplay/docs/handoff-storyboard.png)

剧本不包含人工智能，也不需要模型钥匙：你的代理负责思考，剧本负责拍摄和编辑。

## 安装

```bash
npx agent-screenplay init
```

npm包是 `agent-screenplay`;全局安装(`npm i -g agent-screenplay`)，其命令为 `screenplay`.

`init` 下载Chromium（一次），将剧本MCP服务器添加到它找到的代理（Claude Code, Codex, Cursor）中，并安装指导他们制作优秀视频的指南。在此之后重新启动代理。

## 使用它

在 **克劳德代码**、类型 `/screenplay` 说你想说的话：

```
/screenplay Make a 30-second walkthrough of https://askli.co
/screenplay Film how to invite a teammate in our app, with a French voice-over
```

在 **法典,光标** 或者任何拥有MCP服务器的代理，只要问： _“屏幕录制……”_． 经纪人会浏览网站，询问你是否需要画外音，写好剧本，拍成电影，检查故事板，然后把MP4给你。改变外观： `npx agent-screenplay style <scenario.json>`.

没有MCP，任何可以运行命令的代理都可以直接使用CLI：

```bash
npx agent-screenplay guide                    # how to write a good scenario
npx agent-screenplay check demo.json          # plays the steps fast, without filming
npx agent-screenplay record demo.json         # films and edits → demo.mp4 + demo.storyboard.png
npx agent-screenplay render demo.json         # re-edits the last take (style, zoom, text, voice) without filming
```

要求：节点20+。Ffmpeg和绘图库随包一起发布。

## 一个场景

```json
{
  "url": "https://app.example.com/inbox",
  "style": { "background": "dawn" },
  "steps": [
    { "title": "Human handoff, in one click", "subtitle": "New in 2.4" },
    { "click": "text=Camille Laurent", "say": "When the AI agent gets stuck, the conversation lands in your inbox." },
    { "callout": "role=button[name='Take over']", "text": "Take over from the AI agent" },
    { "click": "role=button[name='Take over']", "say": "One click, and the conversation is yours." },
    { "type": "Hi Camille, I'm on it.", "into": "placeholder=Write a reply…" },
    { "click": "role=button[name='Send']" },
    { "highlight": "text=Assigned to you", "text": "Your teammates see it's yours" },
    { "end": "Available today on every plan" }
  ]
}
```

-   **目标** 以人们看到的方式命名元素： `text=…`， `role=button[name='…']`， `label=…`， `placeholder=…`， `testid=…`， `css=…` (web)、 `at=x,y` （桌面应用程序没有可访问的元素）。
-   **行动**： `goto`， `click`， `type`， `press`， `hover`， `scroll`， `select`， `wait`， `pause`.
-   **方向**： `title` 和 `end` 卡, `callout` （一个泡泡指向一个元素）， `highlight` (聚光灯), `zoomTo`，在任何台阶上 `say` （字幕和声音）， `zoom`， `hold`.
-   **风格**：背景预设（柔光渐变）； `dawn`， `iris`， `citrus`， `apricot`， `coral`， `blaze`， `cloud`， `glacier`， `tide`， `meadow`)，你自己的渐变，颜色或图像；填充，角半径，阴影，光标(`arrow` 默认情况下，强调色的圆角箭头； `macos`， `dot`)及其点击效果(`ripple` 默认情况下; `rays`， `confetti`， `sparkle`)，最大缩放，浏览器框架，强调色。看到 [风格](https://npmcn.com/package/agent-screenplay/#readme-style).
-   **输出**： 1920×1080默认为30 FPS；任何大小，最高4K， 24至60 fps，可选GIF。

完整的格式是JSON模式 [`schema/scenario.schema.json`](https://npmcn.com/package/agent-screenplay/schema/scenario.schema.json) （`npx agent-screenplay schema`)，并由代理引导 [`skills/screenplay/SKILL.md`](https://npmcn.com/package/agent-screenplay/skills/screenplay/SKILL.md)． 例子见 [`examples/`](https://npmcn.com/package/agent-screenplay/examples).

`check` 和 `record` 真正执行步骤（点击“发送”发送）：在演示帐户或登台环境中点场景。

## 风格

通过眼睛来设定外观： `npx agent-screenplay style demo.json` 在浏览器中打开编辑器，在最后录制的一帧上。选择渐变（或自己制作），颜色或图像（将其放在页面上），设置填充，角和阴影，然后保存到 **这个视频** 或 **所有的视频**，无需再次拍摄即可进行渲染。

![The style editor](https://npmcn.com/package/agent-screenplay/docs/style-editor.png)

“所有视频”写道 `screenplay.config.json`，适用于其文件夹及其以下的每个场景；场景本身 `style` 赢，一场接一场。手工设置相同：

```json
{
  "style": {
    "background": { "gradient": ["#0ea5e9", "#6366f1"], "angle": 135 },
    "padding": 96,
    "radius": 20,
    "shadow": true
  }
}
```

标题和结尾卡(`title` 和 `end` 步骤) **默认关闭**使他们兴奋 `"cards": true`，或使用编辑器中的开关。

`background` 是预设名称(`dawn` 默认情况下;较早的预设，例如 `aurora` 或者 `ocean` 仍然工作)，一个颜色(`"#0f172a"`)，映像路径（相对于设置它的文件），或者 `{ "gradient": [2 to 4 colors], "angle": degrees }`.

## 签署的

-   `npx agent-screenplay login https://app.example.com` 打开浏览器窗口，然后登录 **关上窗户**． 会话保存为 `.screenplay/auth.json` （当你离开时，当窗口关闭时；输入终端也可以工作）。使用它 `"auth": { "storageState": ".screenplay/auth.json" }`． 将该文件从git中删除。
-   **机器人检查** （Cloudflare的“稍等……”）：剧本的浏览器呈现为一个普通的Chrome浏览器，所以不需要人的检查自己通过。当一个网站要求一个人证明他们是人类时， `check` 这么说：跑吧 `login` 在该站点上，通过窗口中的检查，关闭它，然后设置 `auth.storageState`． 有些网站在每次访问时都会再次询问；这些不能自动拍摄。
-   没有屏幕的代理可以通过以下步骤登录： `{ "type": "${EMAIL}", "into": "label=Email" }`， `{ "type": "${PASSWORD}", "into": "label=Password", "secret": true }`. `${VAR}` 是从环境中读取的； `secret` 屏蔽标题和日志中的文本。

## 画外音

默认为关闭。每个场景都打开它：

```json
"voice": { "enabled": true, "language": "fr" }
```

每一步的 `say` 是说出来的，视频等待每个句子结束，所以声音设定了节奏。三种获得声音的方法：

-   **[Cartesia](https://cartesia.ai/)**:设置 `CARTESIA_API_KEY`.
-   **[ElevenLabs](https://elevenlabs.io/)**:设置 `ELEVENLABS_API_KEY`． 当两个键都设置时，使用笛卡尔，除非 `"provider": "elevenlabs"`.
-   **你自己的音频文件**没有钥匙，请踏一步 `"audio": "voice/02.mp3"` （MP3， WAV, M4A…），例如你在ElevenLabs或Cartesia的web应用程序中生成的行。代理可以为你编写叙述，每一步一行，准备粘贴在那里。添加音频不需要新的拍摄： `render`.

旁白被缓存：重新渲染未修改的文本不需要任何成本。 `voice.id` 选择另一个声音， `voice.speed` 它的速度。没有声音, `say` 仍然显示为标题。

## 桌面应用程序

使用 `"app": "<name>"` 而不是 `"url"`． 通过操作系统的可访问性api来执行这些步骤 [agent-desktop](https://github.com/vercel-labs/agent-desktop) （安装了剧本），窗口是用ffmpeg拍摄的，没有系统光标；编辑过程与网站相同。

|  | 需要 |
| --- | --- |
| macOS | 允许您的终端或代理应用程序在系统设置→隐私与安全→ **屏幕录制** 和 **可访问性** |
| 窗户 | 没有什么 |
| Linux | 一个 **X11** 会话与AT-SPI访问总线（GNOME上的标准）。不支持Wayland：它会阻止屏幕捕获和合成输入 |

桌面录音需要一个真正的屏幕：它们不能在无头容器中运行。网站可以。

当“剧本”驱动电脑时，屏幕顶部的一个小药丸显示（“剧本正在录制”或“排练”，在检查期间） **停止** 按钮，立即结束运行。这颗药丸没有被捕捉到，所以它从来没有出现在视频中。macOS和Windows； `SCREENPLAY_INDICATOR=0` 关掉它。

### 整个屏幕

`"screen": true` 拍摄整个主屏幕，而不是一个窗口，视频从一个应用程序到另一个或使用菜单栏。 `{ "open": "<app>" }` 启动一个应用程序或把它带到前台，一个步骤 `"app"` 动作在另一个应用程序，和 `"surface": "menubar"` (或 `menu`， `sheet`， `popover`， `alert`)查找应用程序窗口外的元素。屏幕上的一切都被拍摄下来，包括桌面图标和通知：首先清理屏幕；在macOS `"hideOthers": true` 隐藏其他应用程序。

## 它是如何工作的

```
scenario.json ──▶ play + film ──────────────────▶ take (frames + timeline of actions)
                  web: Playwright, headless Chromium          │
                  desktop: agent-desktop + ffmpeg             ▼
                                                  edit: time remap (long waits sped up),
                                                  camera (spring zooms), cursor path,
                                                  overlays, captions, voice track
                                                              │
                                                              ▼
                                                  draw each frame (Skia) → ffmpeg → MP4
```

剧本准确地知道每次点击发生的地点和时间，以及它所作用的每个元素的方框，所以缩放是根据元素来设定的，而不是根据鼠标移动来猜测。在编辑过程中，光标沿着类似人类的平滑路径绘制。

## 开发

```bash
npm install
npm run build
npm test                 # unit tests
npm run test:e2e         # records a real scenario in headless Chromium and talks to the MCP server
```

### 释放

```bash
npm version patch --no-git-tag-version   # or minor / major; also updates src/version.ts
```

合并更改，然后在main上标记提交：

```bash
git tag v0.1.4 origin/main && git push origin v0.1.4
```

标签开始 `.github/workflows/release.yml`． 它检查标签是否与版本匹配并处于主状态，运行测试，发布到npm（带有出处），并根据合并的拉取请求创建GitHub版本。像这样的版本 `0.2.0-beta.1` 去npm's `next` 标签。在GitHub的UI中创建一个带有新标签的版本也可以。

`examples/demo-app` 是一个小的web应用程序，尝试场景； `examples/desktop-app/notes.py` 是一个用于Linux桌面录音的GTK应用程序。

## 许可证

麻省理工学院。绑定: [国际米兰](https://rsms.me/inter/) （SIL开放字体许可证），通过ffmpeg `ffmpeg-static` （GPL），代理-桌面（Apache-2.0）。

## 常见问题

### agent-screenplay 是什么？

为AI代理编写屏幕工作室质量的屏幕记录：编写一个场景，剧本拍摄并编辑它（平滑光标，自动缩放，标注，画外音）。

### 如何安装 agent-screenplay？

在项目目录运行 npm install agent-screenplay，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 screenplay、agent-screenplay，可以用 npx screenplay 直接运行。

### agent-screenplay 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### agent-screenplay 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### agent-screenplay 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### agent-screenplay 可以商用吗？

agent-screenplay 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### agent-screenplay 还在维护吗？

最新版本 0\.1\.4 发布于 2026/11/03（今天）；至今共发布 6 个版本，其中过去 12 个月发布了 6 个；首次发布于 2026/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。