内容
<!-- 项目徽章 -->
[![Python][python-shield]][python-url]
[![MCP][mcp-shield]][mcp-url]
[![uv][uv-shield]][uv-url]
[![Stargazers][stars-shield]][stars-url]
[![Issues][issues-shield]][issues-url]
[![Website][website-shield]][website-url]
<br />
<p align="center">
<a href="https://videodb.io/"><img src="assets/videodb-logo.png" alt="VideoDB" height="72"></a>
</p>
<h1 align="center">VideoDB 记录与回放</h1>
<p align="center">
记录桌面工作流程一次。编译成可重复使用的智能技能。
<br />
<br />
<strong>记录 → 编译 → 将技能交给智能代理</strong>
</p>
<p align="center">
<a href="#installation">安装</a>
·
<a href="#features">功能</a>
·
<a href="#how-it-works">工作原理</a>
·
<a href="https://docs.videodb.io"><strong>文档</strong></a>
·
<a href="https://github.com/video-db/open-record-replay/issues">报告问题</a>
</p>
---
## 什么是记录与回放？
一个 MCP 服务器，记录人类操作的桌面工作流程，并将其编译成可重复使用的技能文件。生成的 `SKILL.md` 可以交给智能代理，让智能代理可以稍后执行工作流程。
- **记录** — 捕获原生无障碍事件、输入值、目标元数据和可选的屏幕视频到 VideoDB 进行视觉参考。
- **编译** — 大型语言模型将事件日志和场景描述转换为可重复使用的 `SKILL.json` 和人类可读的 `SKILL.md` 文件。
- **使用** — 服务器将生成的 `SKILL.md` 安装到智能代理的全局技能目录中，以便未来的智能代理运行可以使用技能指令、输入、验证检查和执行指导。
在屏幕上演示一次任务，服务器生成一个自包含的、版本化的技能工件。该仓库不包括回放引擎；回放由消耗生成技能的智能代理执行。
---
## 安装
### 先决条件
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) 包管理器
- 一个 [VideoDB](https://console.videodb.io) API 密钥
### 1. 克隆并安装
```bash
git clone https://github.com/video-db/open-record-replay.git
cd open-record-replay
uv sync
```
### 2. 设置 API 密钥
在项目根目录下创建一个 `.env` 文件：
```env
VIDEODB_API_KEY=your_VIDEODB_API_KEY
```
### 3. 配置 MCP 客户端
将以下内容添加到您的 MCP 配置文件（`claude_desktop_config.json`、VS Code MCP 设置等）：
```json
{
"mcpServers": {
"videodb-record-replay": {
"command": "uv",
"args": ["run", "python", "server.py"],
"cwd": "/path/to/open-record-replay"
}
}
}
```
### 4. 重启客户端
五个工具和两个资源将出现。您可以开始记录。
<details>
<summary><strong>平台特定设置</strong></summary>
**macOS** — 需要屏幕录制、麦克风、无障碍和输入监控权限。运行权限助手：
```bash
uv run python scripts/smoke_macos_hook.py --prompt-permissions
```
如果 `ready_for_event_recording` 为 false，请在 **系统设置 > 隐私和安全 > 无障碍** 和 **输入监控** 中启用终端进程，然后重新运行。
**Windows** — 使用 UI 自动化。不需要额外的设置。
**Linux** — 使用 AT-SPI。确保 `at-spi2-core` 已安装，并且您的桌面环境已启用无障碍。
</details>
---
## 用法
记录是人类在环路中的。智能代理启动记录，宣布记录处于活动状态，然后等待。人类操作员执行正在捕获的 UI 工作流程。
```
record_skill_tool("my-workflow", lead_in_seconds=5)
→ 智能代理告诉操作员记录处于活动状态
→ 操作员切换到目标应用程序并执行工作流程
→ 操作员返回到 MCP 客户端并说“停止”
→ 智能代理调用 stop_recording_tool(trim_end_seconds=10)
→ 智能代理调用 compile_skill_tool(video_id, "my-workflow")
→ 智能代理验证/报告 global_skill_md_path 以供未来使用
```
<details>
<summary><strong>lead_in_seconds</strong></summary>
记录器立即开始捕获，然后编译器忽略事件，直到有效的工作流程开始。使用 `lead_in_seconds=5`，操作员可以从 MCP 客户端切换到目标应用程序，并在 5 秒后开始演示工作流程。
</details>
<details>
<summary><strong>trim_end_seconds</strong></summary>
丢弃记录尾部的事件。在操作员必须切换回 MCP 客户端以说“停止”时使用。例如，`trim_end_seconds=10` 忽略最后 10 秒的事件，以便生成的技能不包括操作员返回终端或聊天窗口。
</details>
<details>
<summary><strong>仅事件模式</strong></summary>
如果 VideoDB 屏幕捕获不可用，系统将退回到仅记录原生无障碍事件。调用 `compile_skill_tool` 时使用 `video_id=""` 或 `video_id="none"` 从事件日志编译。
</details>
---
## 工作原理
```
人类执行工作流程
|
v
+------------------------------------------------------------------+
| 原生无障碍/UIA/AT-SPI 钩子 -> events.jsonl |
| VideoDB 捕获 SDK -> video_id，当捕获成功时 |
+------------------------------------------------------------------+
|
v
+------------------------------------------------------------------+
| 编译器 |
| events.jsonl + 可选的场景摘要/转录 -> SKILL.json |
| SKILL.json -> SKILL.md |
+------------------------------------------------------------------+
|
v
+------------------------------------------------------------------+
| 智能技能安装 |
| ~/.mcp-videodb/skills/<name>/SKILL.md |
| ~/.codex/skills/<name>/SKILL.md，除非覆盖 |
+------------------------------------------------------------------+
```
无障碍钩子提供操作日志。VideoDB 场景索引在屏幕捕获可用时添加视觉上下文。编译器将这些信号组合成未来的智能代理可以使用的技能文件。
---
## 功能
| 功能 | 描述 |
|---------|-------------|
| **双重记录** | 捕获原生无障碍事件和全捕获可用时的屏幕视频进行视觉参考 |
| **大型语言模型编译** | VideoDB 场景索引和 `generate_text` 将事件日志、场景描述和转录文本编译成结构化的 `SKILL.json` |
| **优雅降级** | 当屏幕捕获不可用时，退回到仅事件记录 |
| **跨平台** | Windows（UIA）、macOS（AX）和 Linux（AT-SPI）的原生无障碍钩子 |
| **技能版本控制** | 自动递增重新编译；存档旧版本为 `SKILL.vN.json` |
| **变量模板** | 提示编译器将记录的字面值（如搜索查询、日期、下拉选择和文件路径）转换为可重复使用的输入 |
| **人类在环路中** | 记录由操作员驱动，而不是智能代理驱动 — 人类演示，人工智能学习 |
---
## 工具
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `request_capture_permissions_tool` | — | 在记录前请求麦克风和屏幕捕获权限 |
| `record_skill_tool` | `name: str`、`lead_in_seconds: float = 0.0` | 开始人类在环路中的工作流程记录 |
| `stop_recording_tool` | `trim_end_seconds: float = 0.0` | 停止活动记录并将视频导出到 VideoDB（如果捕获可用） |
| `compile_skill_tool` | `video_id: str`、`name: str` | 将记录编译成 `SKILL.json` 和 `SKILL.md`，然后全局安装 `SKILL.md` 以供未来智能代理使用 |
| `list_skills_tool` | — | 列出通过此 MCP 生成的所有技能 |
### 资源
| 资源 | 描述 |
|----------|-------------|
| `skills://list` | 列出所有可用的技能为 JSON |
| `skills://{name}/content` | 将技能的 `SKILL.md` 加载到智能代理上下文中 |
---
## 技能输出
编译的技能位于 `~/.mcp-videodb/skills/<name>/`：
| 文件 | 目的 |
|------|---------|
| `SKILL.json` | 结构化的技能定义，包括步骤、输入、验证检查、记录的表面数据和执行策略 |
| `SKILL.md` | 人类和智能代理可读的 Markdown，遵循 agentskills.io 标准 |
| `SKILL.vN.json` | 存档的以前版本在重新编译时 |
每个生成的 `SKILL.json` 都包含一个 `execution_strategy` — `web_browser`、`desktop_app`、`hybrid`、`terminal`、`file_system` 或 `unknown` — 以便使用该技能的智能代理知道首选的工具路径。每个 `SKILL.md` 都包含执行指导、持续改进指导和智能代理工具优先级指导。
在创建 `SKILL.md` 后，`compile_skill_tool` 还会将其安装到智能代理的全局技能目录中，默认为 `~/.codex/skills/<name>/SKILL.md`，并返回 `global_skill_md_path` 和一个 `agent_instruction`，提醒智能代理验证或报告全局安装。智能代理应确保此全局安装步骤已发生，以便技能在未来运行中可用。设置 `CODEX_HOME` 可更改 Codex 目录的基础路径，或设置 `AGENT_GLOBAL_SKILLS_ROOT` 可直接覆盖全局技能目录。
---
## 架构
```
open-record-replay/
├── server.py # FastMCP 入口点，工具和资源定义
├── state.py # 共享服务器状态单例
├── config.py # 常量，.env 加载
├── registry.py # 技能 CRUD + 版本控制
│
├── capture/
│ ├── recorder.py # 记录原生无障碍事件 + 可选的 VideoDB 捕获
│ ├── ax_client.py # JSONL IPC 包装器，用于原生无障碍伴侣
│ ├── capture_client.py # VideoDB 捕获 SDK 包装器
│ └── native/
│ ├── ax_hook_win32.py # Windows：UI 自动化 + 键盘轮询 + TCP IPC
│ ├── ax_hook_darwin.py # macOS：无障碍 API + pynput + 管道 IPC
│ └── ax_hook_linux.py # Linux：AT-SPI + pynput + 管道 IPC
│
├── compiler/
│ ├── compiler.py # 大型语言模型编译：索引场景 → 匹配事件 → 提示 → 规范化
│ ├── prompts.py # 大型语言模型系统提示，用于结构化技能生成
│ ├── md_generator.py # 将 SKILL.json 转换为智能代理可读的 SKILL.md
│ ├── tool_manifest.py # 表面到工具的映射，用于回放指导
│ └── recommended_tools.json
│
├── schema/
│ └── skill.schema.json # JSON Schema（draft-07）用于 SKILL.json 验证
│
├── scripts/
│ └── smoke_macos_hook.py # macOS AX 钩子权限助手
```
---
## 故障排除
<details>
<summary><strong>记录无法开始</strong></summary>
- 验证 `.env` 中是否设置了 `VIDEODB_API_KEY` 并且有效
- 运行 `request_capture_permissions_tool` 并批准任何权限提示
- 在 macOS 上，检查屏幕录制和无障碍权限
- 检查是否没有其他应用程序正在使用无障碍钩子
</details>
<details>
<summary><strong>编译失败或返回空步骤</strong></summary>
- 确保记录具有有意义的 UI 交互（不仅仅是空闲时间）
- 如果视频索引速度慢，尝试仅使用事件编译（`video_id=""`）
- 大型语言模型可能需要另一次生成尝试 — 编译器配置为最多 2 次尝试
</details>
<details>
<summary><strong>macOS 上权限提示未出现</strong></summary>
```bash
# 重置权限并重试
uv run python scripts/smoke_macos_hook.py --prompt-permissions
```
如果 `ready_for_event_recording` 为 false，请在 **系统设置 > 隐私和安全 > 无障碍** 和 **输入监控** 中手动启用终端。
</details>
<details>
<summary><strong>Windows：未记录键盘事件</strong></summary>
- 确保被记录的应用程序支持 UI 自动化（大多数现代应用程序支持）
</details>
---
## 社区和支持
- **文档**：[docs.videodb.io](https://docs.videodb.io)
- **问题**：[GitHub 问题](https://github.com/video-db/open-record-replay/issues)
- **Discord**：[加入 VideoDB 社区](https://discord.gg/py9P639jGz)
- **API 密钥**：[console.videodb.io](https://console.videodb.io)
---
<p align="center">由 <a href="https://videodb.io">VideoDB</a> 团队 ❤️ 制作</p>
<!-- MARKDOWN LINKS & IMAGES -->
[python-shield]: https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white
[python-url]: https://www.python.org/
[mcp-shield]: https://img.shields.io/badge/MCP-1.0+-000000?style=for-the-badge&logo=anthropic&logoColor=white
[mcp-url]: https://modelcontextprotocol.io/
[uv-shield]: https://img.shields.io/badge/uv-package_manager-DE5FE2?style=for-the-badge&logo=astral&logoColor=white
[uv-url]: https://docs.astral.sh/uv/
[stars-shield]: https://img.shields.io/github/stars/video-db/open-record-replay.svg?style=for-the-badge
[stars-url]: https://github.com/video-db/open-record-replay/stargazers
[issues-shield]: https://img.shields.io/github/issues/video-db/open-record-replay.svg?style=for-the-badge
[issues-url]: https://github.com/video-db/open-record-replay/issues
[website-shield]: https://img.shields.io/website?url=https%3A%2F%2Fvideodb.io%2F&style=for-the-badge&label=videodb.io
[website-url]: https://videodb.io/
