humblebanana/open-record-replay

Open Record/Replay

通过演示教 Computer Use 智能体。

录制一次 macOS 工作流，保存证据，让智能体将其转化为可复用的技能。

Open Record/Replay 是一个本地优先的 macOS 录制器，适用于那些演示起来比写下来更容易的工作流。它将用户的真实桌面操作捕获为结构化产物，例如 session.json 和 events.jsonl，验证录制质量，并将证据打包以供智能体的技能创建流程使用。

目标很简单：如果用户能演示一次桌面工作流，智能体就应该有足够的证据来学习它。

flowchart LR
A["User demonstrates a macOS workflow"] --> B["Open Record/Replay records events"]
B --> C["session.json + events.jsonl"]
C --> D["Validate recording quality"]
D --> E["Prepare skill input package"]
E --> F["Agent creates its own reusable Computer Use skill"]

为什么存在

有些工作流很难用提示词描述：

- 它们依赖于可见的桌面 UI。
- 它们涉及文件选择器、菜单、模态框或拖放。
- 它们跨越多个应用。
- 它们依赖于个人工作区布局或团队特定惯例。
- 它们从演示中学习比从书面操作手册中学习更容易。

Open Record/Replay 为智能体提供具体的证据流，而不是要求它们从模糊的描述中推断工作流。

你可以录制什么

Open Record/Replay 可以捕获以下工作流的操作级证据：

- 通过桌面聊天应用发送文件或图片。
- 创建文档并分享其链接。
- 打开浏览器页面、搜索并启动正确的媒体。
- 在浏览器和桌面应用之间切换。
- 重复一个没有干净 API 或连接器覆盖的 UI 流程。

录制器可以捕获：

- window.changed
- mouse.click
- mouse.drag
- keyboard.text_input
- keyboard.submit
- selection.changed
- 应用/窗口归属
- UI 目标
- 选中项
- 辅助功能树或差异上下文

events.jsonl 是主要证据。截图不属于当前核心录制路径。

快速演示

这是教智能体一个新桌面工作流的典型流程。

bash
git clone https://github.com/humblebanana/open-record-replay.git
cd open-record-replay
npm install
npm run check

检查 macOS 权限：
bash
node bin/orr.js permissions check

请求缺失的权限：
bash
node bin/orr.js permissions request

开始录制：
bash
node bin/orr.js record start --name send-file-demo --out runs --request-permissions

现在在你的 Mac 上演示该工作流程。例如：

1. 打开一个桌面聊天应用。
2. 选择一个收件人或频道。
3. 附加一个本地文件。
4. 确认上传。
5. 发送一条简短的后续消息。

完成后，停止录制：
bash
node bin/orr.js record stop latest

验证证据：
bash
node bin/orr.js session validate-recording latest

准备技能输入包：
bash
node bin/orr.js skill prepare latest --runs runs --out skill-inputs

该包将被写入：
text
skill-inputs//
├── README.md
├── events.jsonl
└── session.json

将此目录交给当前 agent 的技能创建流程。

输出产物

录制输出：
text
runs/sessions//
├── session.json
├── events.jsonl
├── orr_session.json
└── recording_manifest.json

技能输入包：
text
skill-inputs//
├── README.md
├── events.jsonl
└── session.json

session.json 记录录制边界、时间信息和事件路径。events.jsonl 是演示期间所发生事件的事实来源。

Agent 集成

此仓库包含一个宿主指令技能：

skills/open-record-replay/SKILL.md

agent 应使用它来了解何时开始录制、何时停止、如何检查 events.jsonl，以及如何将证据包交给自己的技能创建流程。

预期的 agent 流程：

1. 检查或请求所需的 macOS 权限。
2. 仅在用户准备好时开始录制。
3. 录制开始后，结束当前回合并等待用户完成演示。
4. 当用户表示演示完成时，停止录制器。
5. 读取 session.json 和 events.jsonl。
6. 验证录制。
7. 准备技能输入包。
8. 使用 agent 自己的技能创建系统来创建并验证最终技能。

CLI 参考
bash
node bin/orr.js permissions check
node bin/orr.js permissions request
node bin/orr.js record start --name my-workflow --out runs --request-permissions
node bin/orr.js record stop latest
node bin/orr.js session list
node bin/orr.js session inspect latest
node bin/orr.js session events latest
node bin/orr.js session validate-recording latest
node bin/orr.js skill prepare latest --runs runs --out skill-inputs

稳定的公共路径是录制、验证和技能输入打包。

要求

- macOS。
- Node.js 18+。
- Swift 工具链 / Xcode Command Line Tools。
- 辅助功能权限。
- 输入监控权限。
核心录制器不需要屏幕录制权限。

隐私

录制内容默认保存在本地，但 events.jsonl 可能包含敏感数据：

- 窗口标题。
- URL。
- 输入的文本。
- 选中的文本。
- 文件名。
- 本地路径。
- 来自应用和网页的辅助功能树文本。

在分享录制内容之前请先检查。不要发布包含密钥、私人文档、客户数据、内部 URL 或个人信息在内的原始录制内容。

参见 隐私。

状态

Open Record/Replay 是 alpha 阶段软件。

当前公开范围：
text
macOS 原生录制器
+ CLI
+ session.json / events.jsonl
+ 录制验证
+ Skill 输入包
+ 宿主 Agent Skill 创建交接

未来工作可能包括更丰富的适配器或可选的视觉证据。它们不属于当前稳定的公开路径。

文档

- 安装
- Agent 使用
- 录制数据契约
- 隐私
- 发布检查清单
- 贡献

简体中文

Open Record/Replay 用来通过一次真实演示，让 Computer Use Agent 学会一个 macOS 桌面工作流。

它会把用户在 Mac 上的真实操作录制成 session.json 和 events.jsonl，检查录制质量，并打包成 Agent 可以读取的 Skill 输入包。最终 Skill 不由 Open Record/Replay 直接生成，而是交给当前 Agent 使用自己的 Skill 创建流程完成。

核心目标很简单：如果用户可以演示一次工作流，Agent 就应该有足够的证据去学习它。
mermaid
flowchart LR
A["用户演示 macOS 工作流"] --> B["Open Record/Replay 录制事件"]
B --> C["session.json + events.jsonl"]
C --> D["验证录制质量"]
D --> E["打包 Skill 输入"]
E --> F["Agent 创建自己的可复用 Computer Use Skill"]

为什么需要它

有些工作流很难直接写成提示词：

- 它依赖真实桌面 UI。
- 它涉及文件选择器、菜单、弹窗或拖拽。
- 它横跨多个 App。
- 它依赖个人工作区布局或团队内部习惯。
- 用户演示一次，比写一份很长的操作说明更清楚。

Open Record/Replay 给 Agent 的不是模糊描述，而是一份真实事件证据流。

可以录制什么

典型场景包括：

- 在桌面聊天 App 里发送文件或图片。
- 创建文档并分享链接。
- 打开网页、搜索内容并播放指定媒体。
- 在浏览器和桌面 App 之间切换操作。
- 复现一个没有稳定 API 或 connector 的 UI 流程。

录制器可以捕捉：

- window.changed
- mouse.click
- mouse.drag
- keyboard.text_input
- keyboard.submit
- selection.changed
- App / 窗口归属
- UI target
- 选中文件或文本
- Accessibility tree / diff 上下文

events.jsonl 是最关键的证据。截图不是当前核心录制链路的一部分。

快速演示

安装并检查项目：
bash
git clone https://github.com/humblebanana/open-record-replay.git
cd open-record-replay
npm install
npm run check

检查 macOS 权限：
bash
node bin/orr.js permissions check

请求缺失权限：
bash
node bin/orr.js permissions request

开始录制：
bash
node bin/orr.js record start --name send-file-demo --out runs --request-permissions

然后在 Mac 上演示你的工作流。比如：

1. 打开一个桌面聊天 App。
2. 选择联系人或群聊。
3. 附加一个本地文件。
4. 确认上传。
5. 发送一条补充消息。

完成后停止录制：
bash
node bin/orr.js record stop latest

验证录制质量：
bash
node bin/orr.js session validate-recording latest

准备 Skill 输入包：
bash
node bin/orr.js skill prepare latest --runs runs --out skill-inputs

产物会写入：
text
skill-inputs//
├── README.md
├── events.jsonl
└── session.json

把这个目录交给当前 Agent 的 Skill 创建流程即可。

产物结构

录制输出：
text
runs/sessions//
├── session.json
├── events.jsonl
├── orr_session.json
└── recording_manifest.json

Skill 输入包：
text
skill-inputs//
├── README.md
├── events.jsonl
└── session.json

session.json 记录录制边界、时间和事件路径。events.jsonl 是判断用户到底做了什么的 source of truth。

Agent 如何接入

仓库里包含一个给 Agent 使用的说明 Skill：

skills/open-record-replay/SKILL.md

Agent 应该通过它理解什么时候开始录制、什么时候停止、如何读取 events.jsonl，以及如何把证据包交给自己的 Skill 创建流程。

推荐流程：

1. 检查或请求必要的 macOS 权限。
2. 只在用户准备好时开始录制。
3. 录制开始后，Agent 停止当前回合，等待用户演示完成。
4. 用户说完成后，Agent 停止录制。
5. 读取 session.json 和 events.jsonl。
6. 验证录制质量。
7. 准备 Skill 输入包。
8. 使用当前 Agent 自己的 Skill 创建系统生成并验证最终 Skill。

CLI 命令
bash
node bin/orr.js permissions check
node bin/orr.js permissions request
node bin/orr.js record start --name my-workflow --out runs --request-permissions
node bin/orr.js record stop latest
node bin/orr.js session list
node bin/orr.js session inspect latest
node bin/orr.js session events latest
node bin/orr.js session validate-recording latest
node bin/orr.js skill prepare latest --runs runs --out skill-inputs

当前稳定公开路径是：录制、验证、打包 Skill 输入。

环境要求

- macOS。
- Node.js 18+。
- Swift toolchain / Xcode Command Line Tools。
- Accessibility 权限。
- Input Monitoring 权限。

核心录制器不需要 Screen Recording 权限。

隐私

录制默认保存在本地，但 events.jsonl 可能包含敏感信息：

- 窗口标题。
- URL。
- 输入文本。
- 选中文本。
- 文件名。
- 本地路径。
- App 和网页里的 Accessibility tree 文本。

分享录制前必须先检查内容。不要公开包含密钥、私有文档、客户数据、内部 URL 或个人信息的原始录制。

详见 Privacy。

项目状态

Open Record/Replay 目前是 alpha 版本。

当前公开范围：
text
macOS 原生录制器
+ CLI
+ session.json / events.jsonl
+ 录制质量验证
+ Skill 输入包
+ 交给宿主 Agent 创建最终 Skill

未来可能会增加更丰富的适配器或可选视觉证据，但这些不是当前稳定公开路径。

文档

- 安装说明
- Agent 使用说明
- 录制数据契约
- 隐私说明
- 发布检查清单
- 贡献指南