剧本
https://github.com/user-attachments/assets/dd9898da-4900-4a91-8620-57a860c46093
Screen studio质量的屏幕录音，由你的AI代理制作。
询问Claude Code、Codex、Cursor或任何代理： “制作一个视频，展示人类的交接是如何进行的”． 代理探索你的应用程序，并写一个短 场景;剧本在浏览器（或桌面应用程序）中播放，拍摄，并像Screen Studio一样编辑视频：平滑光标，自动缩放动作，点击效果，标注，聚光灯，字幕，标题卡和可选的画外音。
剧本不包含人工智能，也不需要模型钥匙：你的代理负责思考，剧本负责拍摄和编辑。
安装
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：
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和绘图库随包一起发布。
一个场景
{
"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)，最大缩放，浏览器框架，强调色。看到 风格. - 输出： 1920×1080默认为30 FPS；任何大小，最高4K， 24至60 fps，可选GIF。
完整的格式是JSON模式 schema/scenario.schema.json （npx agent-screenplay schema)，并由代理引导 skills/screenplay/SKILL.md． 例子见 examples/.
check 和 record 真正执行步骤（点击“发送”发送）：在演示帐户或登台环境中点场景。
风格
通过眼睛来设定外观： npx agent-screenplay style demo.json 在浏览器中打开编辑器，在最后录制的一帧上。选择渐变（或自己制作），颜色或图像（将其放在页面上），设置填充，角和阴影，然后保存到 这个视频 或 所有的视频，无需再次拍摄即可进行渲染。
“所有视频”写道 screenplay.config.json，适用于其文件夹及其以下的每个场景；场景本身 style 赢，一场接一场。手工设置相同：
{
"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屏蔽标题和日志中的文本。
画外音
默认为关闭。每个场景都打开它：
"voice": { "enabled": true, "language": "fr" }
每一步的 say 是说出来的，视频等待每个句子结束，所以声音设定了节奏。三种获得声音的方法：
- Cartesia:设置
CARTESIA_API_KEY. - ElevenLabs:设置
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 （安装了剧本），窗口是用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
剧本准确地知道每次点击发生的地点和时间，以及它所作用的每个元素的方框，所以缩放是根据元素来设定的，而不是根据鼠标移动来猜测。在编辑过程中，光标沿着类似人类的平滑路径绘制。
开发
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
释放
npm version patch --no-git-tag-version # or minor / major; also updates src/version.ts
合并更改，然后在main上标记提交：
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应用程序。
许可证
麻省理工学院。绑定: 国际米兰 （SIL开放字体许可证），通过ffmpeg ffmpeg-static （GPL），代理-桌面（Apache-2.0）。