让 AI Agent「看一遍就会干活」record-and-replay-skill 开源项目深度解析引言2026 年 OpenAI 给 Codex CLI 推了一个 macOS 专属的Record Replay插件你当着 Agent 的面演示一遍操作它就把这套流程录下来蒸馏成一个可复用的技能。思路很惊艳但有两个硬伤——只支持 macOS且绑定 Codex 生态。社区很快出现了开源复刻ugarchance/record-and-replay-skill。它用 Playwright pynput 把这套能力重建了一遍做到跨平台macOS / Windows / Linux 跨 AgentClaude Code / Codex CLI / opencode / 任意能跑 shell 的 Agent并且完全开源MIT。本文带你拆解它的整体架构、核心模块代码与关键设计取舍。一、项目速览项内容仓库ugarchance/record-and-replay-skill主语言JavaScriptNode 驱动桌面端引擎用 Python开源协议MIT核心依赖playwright ^1.61.0桌面端依赖pynputmsspillow约 50MB 的.venv-desktop一句话定位把用户的「演示」录成 evidence再蒸馏成一个可复用的 Agent Skill它的核心思想一句话概括录制不是像素级脚本而是「意图证据」。Agent 读录制产物理解用户想达成什么然后用语义化定位器selector和验证步骤生成技能而不是逐帧回放坐标。二、它解决什么痛点GUI 操作难自动化很多内部系统、老旧后台没有 API只能靠人工点。传统 RPA 写坐标、写 XPath脆弱且难维护。Agent 不会「学」Claude Code 这类 Agent 能写代码但没法「看人怎么做一遍」就学会。Codex 的 Record Replay 封闭原生插件仅 macOS普通用户用不了。这个 Skill 把「演示 → 技能」的闭环开源化、跨平台化让任意 Agent 都能拥有「看一遍就会」的能力。三、两种录制模式Browser 模式默认证据最丰富用 Playwright 启动一个有头浏览器优先用你已装的 Google Chrome否则用自带 Chromium把每个用户动作录进events.jsonl同时保存 Playwright trace 分片trace-NNN.zip含 DOM 快照 截图60 秒一个检查点。平台支持macOS / Windows / Linux 全支持。Desktop 模式原生桌面应用用单进程录制器pynput捕获全局鼠标/键盘事件、活动窗口切换以及每次点击时刻的半分辨率 JPEG写入desktop-events.jsonlscreens/。设计哲学与 Codex 一致录的是「事件/上下文流」不是视频。CPU 占用实测约 0–3%。macOS / Windows / LinuxX11均支持。作者明确拒绝「连续全分辨率录像」原始帧管线会压垮机器。这是工程上很清醒的取舍。四、两层证据Two-layer evidenceBrowser 模式采用双层证据设计这是整个项目最精巧的地方层文件内容用途语义层events.jsonl用户动作 多候选选择器生成技能的主证据真相层trace-NNN.zip每次动作的 DOM 快照 截图像素级 ground truth可用npx playwright show-trace回看events.jsonl每行一个事件{ seq, t, kind, type, url, ... }。kind: page导航、下载、弹窗、标签页开关导航会把流程切成「阶段」。kind: dom用户动作target.selectors携带多个候选选择器。五、多候选选择器稳定回放的关键这是回放「不脆」的核心。每条 DOM 事件都记录多个定位候选按优先级排列testId → rolename → id → nameAttr → text → css生成回放脚本时优先用前面的候选css是最后手段。这意味着即使页面文案微调、class 重构技能依然大概率能定位到元素。输入事件做了防抖debounce一个字段只产一条事件记录最终值在 blur / Enter / change / 提交时 flush。密码、卡号、OTP 类字段兼容英文与土耳其文parola / şifre / kart / kimlik默认脱敏为***MASKED***。六、核心模块与关键代码目录结构record-and-replay/ ├── SKILL.md # Agent 读取的技能定义 ├── package.json ├── setup.mjs / install.mjs # 跨平台安装与 Agent 目录链接 ├── install.sh / setup.sh # POSIX 包装脚本 └── scripts/ ├── recorder.mjs # 浏览器录制器--self-test 可做无头自测 ├── summarize.mjs # events.jsonl → 紧凑 markdown 时间线 ├── replay-template.mjs # 生成回放脚本的骨架 ├── desktop-record.mjs # 桌面录制驱动start/pause/resume/stop/status ├── desktop-lite-recorder.py # 桌面引擎单进程事件/窗口/截图流 └── desktop-summarize.py # desktop-events.jsonl → markdown 时间线1)recorder.mjs—— 单活动录制 限流自保录制器用锁文件保证「同一时刻只有一个录制」constLOCK_PATHpath.join(RECORDINGS_ROOT,.lock);if(!SELF_TESTfs.existsSync(LOCK_PATH)){constotherJSON.parse(fs.readFileSync(LOCK_PATH,utf8));if(other.pidpidAlive(other.pid)){console.error(JSON.stringify({error:recording_already_active,...}));process.exit(2);}}为防止恶意/出错页面 JS 把磁盘写满做了每秒 总量双重限流constMAX_EVENTS_TOTAL100_000;constMAX_EVENTS_PER_SEC200;暂停期间连「会话标记」之外的事件一律丢弃if (paused evt.kind ! session) return;保证暂停区间在证据里是真空的。2)summarize.mjs—— 把原始流压成技能友好时间线它把噪声scroll、selection压掉导航变成二级标题连续相同动作合并计数functionbestSelector(target){conststarget.selectors;if(s.testId)returntestId${s.testId};if(s.roles.role.name)returnrole${s.role.role}${s.role.name};if(s.id)return#${s.id};if(s.nameAttr)return[name${s.nameAttr}];if(s.text)returntext${s.text};returns.css||?;}输出示例[01:23] click button(rolebutton Add expense)、[01:25] type into input[roletextbox] → 100。非--full模式下最多 500 行过长截断并提示「还有 N 行」。3)desktop-lite-recorder.py—— 单进程、线程化、低 CPU# 只录三样东西绝不连续读屏# - 全局鼠标/键盘事件 (pynput)# - 活动窗口变化 (每秒轮询变了才写)# - 点击瞬间一张半分辨率 JPEG (700ms 内最多 1 张)停止靠outDir/STOP文件轮询无信号Windows 上也一致到点或超时就干净收尾。4)replay-template.mjs—— 语义化回放骨架生成的回放脚本坚决不用坐标// 规则坐标 NOT语义 locator 优先// getByTestId getByRole getByLabel getByTextawaitpage.goto(https://example.com);// await page.getByRole(button, { name: Add expense }).click();// await page.getByLabel(Amount).fill(process.env.AMOUNT ?? 100);// await page.getByText(Expense saved).waitFor({ timeout: 10_000 });每个关键步骤后都有验证expect / waitFor敏感值从环境变量取绝不硬编码。还复用了录制器的持久化浏览器 profile保留登录态生成的技能通常无需再登录。七、安装与使用gitclone https://github.com/ugarchance/record-and-replay-skill ~/.agents/skills/record-and-replaycd~/.agents/skills/record-and-replaynodesetup.mjs# npm install (无 Chrome 则下载 Chromium) 自测nodeinstall.mjs# 软链到 ~/.claude/skills/、~/.codex/skills/、~/.config/opencode/skills/录制浏览器后台分离运行nohupnodescripts/recorder.mjs--minutes30--namemy-task~/.agents/recordings/recorder.log21nodescripts/summarize.mjs ~/.agents/recordings/my-task录制过程中有右下角浮动控制窗对标 Codex 的 Recording Controls实时计时、暂停/继续、停止、丢弃两击确认。暂停时事件与 trace 同时停止也可通过touch outDir/PAUSE/STOP文件让 Agent 程序化控制。八、安全与隐私设计值得所有录制类工具借鉴浏览器脱敏是启发式的、且只覆盖events.jsonl密码/OTP/卡号字段预脱敏、粘贴内容不记录、疑似密钥的选择/复制脱敏但trace 分片不脱敏DOM 快照含原始输入值、截图拍到一切。作者反复强调整个录制目录都是敏感凭据本地看、别上传、别提交、摘要里别引原文。桌面录制完全不脱敏每次按键和截图都是原始数据summarizer 会显式警告 Agent。持久化 profile 视同明文凭据含活登录态 cookie/localStoragePlaywright 用 mock keychain 启动 Chrome绝不可提交或分享。页面 JS 加固录制 binding 带 nonce 防护、用完从window移除事件流限流 封顶防假事件注入、防写满磁盘。九、工程亮点总结跨平台 跨 Agent一份录制Claude Code / Codex / opencode 通用。两层证据 多候选选择器回放稳定不脆。轻量优先浏览器 trace 默认light无连续录像桌面 ~0–3% CPU30 分钟录制只有几十 MB。信号无关停止STOP 文件轮询全平台干净收尾。安全默认偏保守脱敏 明文凭据警告 抗滥用限流。十、适用场景与局限适合内部后台/无 API 系统的流程自动化、把重复 GUI 操作变成团队可复用技能、给 Agent「演示教学法」。局限桌面模式只有坐标 窗口标题弱于浏览器语义选择器需借助 computer-use 层如 cua-driver落地回放。录制产物含敏感信息需谨慎保管别随手 commit。录制是「意图证据」不是脚本复杂/歧义流程仍需人确认Agent 不会瞎猜。总结record-and-replay-skill把 Codex 的 Record Replay 从一个封闭 macOS 插件重做成了一个开源、跨平台、跨 Agent的「演示即技能」基础设施。它的两层证据、多候选选择器、轻量低 CPU、保守安全默认都是很成熟的工程判断。如果你想让 Agent「看一遍就会干活」这是一个值得收藏并本地跑一遍的项目。仓库地址https://github.com/ugarchance/record-and-replay-skill下一篇预告同类项目横评——video-db/open-record-replay桌面工作流→技能、Marker-Inc-Korea/open-record-replay隐私优先浏览器录制与本文项目的差异与选型建议。