Ottohere-Mourn/TeachReplay

TeachReplay

教一次，随处回放。

🌐 项目网站

TeachReplay 是一个与执行框架无关的示范教学（Teach-by-Demonstration）引擎：演示一次工作流——
点击、输入的值、shell 命令——它就会变成一个可复用、参数化的技能，之后可以在真实计算机上用不同的输入
回放，并给出明确的成功/失败判定。

TeachReplay 演示 — 教学 → 编译 → 更改参数 → 回放 → 成功

教学 → 编译 → 更改参数 → 回放 → 成功 · 26 秒 · 观看高清版

什么是 TeachReplay？

Teach → Record → Compile → Replay → Verify

1. 教学（Teach）——开始录制，并在计算机上演示一次任务。
2. 录制（Record）——录制器观察计算机的语义状态（URL、可见文本、
元素角色和值），并将其差异化为带版本号的轨迹。密码字段保持
掩码；每个值都经过敏感信息脱敏。
3. 编译（Compile）——确定性编译器将轨迹转换为参数化技能：
你演示的值成为输入，你的值作为默认值。GUI 步骤在语义上被锚定
（角色 + 名称，绝不使用原始坐标）；shell 命令成为真正的 CLI 步骤，
并带有其记录的退出码。
4. 回放（Replay）——引擎在每一步重新快照，以语义方式匹配目标，执行操作，并
验证每一步的效果。一次有界重试，一个可选的模型辅助恢复钩子，
然后是明确的失败。
5. 验证（Verify）——成功要求所记录的条件（URL 或确认文本）成立。
“引擎停止了”绝不是成功。

包概览

| 包 | 用途 |
| --- | --- |
| @teachreplay/core | 轨迹 schema · 录制器 · 参数化技能编译器 · 参数替换 · 回放引擎 · 验证器 · 文件存储 · createTeachRuntime 编排 |
| @teachreplay/remote | 通用 SSH Linux 计算机后端（Xvfb + Chrome DevTools），带 GUI + shell 通道——不特定于任何提供商 |
| @teachreplay/mock | 用于测试和本地演示的确定性内存演示计算机 |
| @teachreplay/adapter-dsh | 注册 teach_ 工具的 DeepSeek Harness 插件 |

架构

核心拥有所有示范教学逻辑，并且只依赖 Node.js——这是一个
被强制执行的不变量（独立性测试）。适配器
只贡献后端、存储和事件接收器：

| 集成 | 状态 |
| --- | --- |
| 独立运行（createTeachRuntime + 文件存储 + mock/远程后端） | ✅ 已包含 — 参见独立演示 |
| OpenMausBot（TeachReplay-OpenMausBot） | ✅ 轻量适配器 — 基于核心重建的 v0.1 集成 |
| DeepSeek Harness（deepseek-ai/deepseek-harness） | ✅ 适配器面向真实的 DSH 插件 API — 见下文 |

用于 DeepSeek Harness 的 TeachReplay

@teachreplay/adapter-dsh 为
DeepSeek Harness 智能体添加了演示式教学工具：
teach_start / teach_stop / teach_compile / teach_replay /
teach_shell — 相同的 Record → Compile → Replay → Verify 引擎，没有重复的核心
逻辑。

- 面向真实的 DSH 插件 API：@deepseek-ai/cordis /
@deepseek-ai/dsh-tools 是 peerDependencies，并固定为
devDependencies（4.0.1 / 0.1.1-rc.2，即 DSH 在
dsh-v0.1.1-rc.2 解析的确切配对），因此本仓库自身的构建会针对
真实的 defineTool/Plugin.Object 类型编译该插件 — 没有本地垫片。此版本基于一次
在完整 DSH 工作区检出中验证过的 DSH 原生重写（参见
适配器 README）
- 安装：pnpm add @teachreplay/adapter-dsh — 在 DSH 处于
开发者预览阶段时，DSH 的子包以 next dist-tag 发布到 npm；参见
适配器 README
（⚠️ DSH 处于开发者预览阶段，存在破坏兼容性的变更；
每个版本需重新验证）
- 演示：examples/dsh-demo 在本地运行
teach_start → demonstrate → teach_stop → teach_compile → change
parameters → teach_replay → success — 通过 DshTeachSession 直接
针对 mock 计算机，而不是通过 DSH 的真实工具
运行时

（DSH 在开发者预览阶段不接受外部拉取请求 —
参见其自身的 CONTRIBUTING.md — 因此这作为独立包发布，
而非上游 PR。）*

快速开始

git clone https://github.com/Ottohere-Mourn/TeachReplay.git
cd TeachReplay
pnpm install
pnpm build
pnpm demo        # standalone: record → compile → change parameters → replay → verify
pnpm test        # 50 tests, including the zero-harness-dependency invariant
pnpm typecheck

该演示完全在内置演示计算机上运行 — 无需凭据、无需网络、无需 harness。

真实评估

scripts/mini-benchmark.mjs 针对一台真实的远程 Linux 计算机
（GUI + CLI，SSH 环境已配置）运行 8 个任务 / 14 次回放。每次成功都会对照机器上的
真实基准进行检查，而不仅仅是回放自身的判定。最新真实运行（结果见
scripts/teach-benchmark-results.json）：

| 指标 | 结果 |
| --- | --- |
| 判定正确 | 14/14 |
| 正常回放成功 | 12/12 |
| 变更参数重放 | 6/6 |
| GUI + CLI 工作流 | 成功，处理后的输出匹配 |
| 严重 UI 漂移 / 元素缺失 | 检测为显式失败（2/2） |
| 真值不匹配 | 0 |

一次诚实的小规模健全性检查——并非对当前最先进水平的宣称。

局限性

- 录制观察的是状态转换（轮询，约 500 毫秒），而非输入事件——非常快速的操作
可能会被合并。缓慢、刻意的演示才是预期的输入方式。
- 点击是从状态变化推断出来的；模糊的转换不会记录点击，而不是记录错误的点击。
- 模型辅助恢复是一个可选钩子（ModelBackend）——由适配器来接入智能体。
- 重放速度受 SSH 往返时间限制（在评估机器上约 4 秒/步）。
- DSH 处于开发者预览阶段，会有破坏兼容性的更改——每个版本都需重新验证。

归属与许可

Apache-2.0（见 LICENSE）。TeachReplay 提取自 TeachReplay v0.1，后者是在
OpenMausBot（Apache-2.0）内部开发的——有关衍生作品的
归属信息，请参见 NOTICE，其中包括源自 OpenMausBot 计算机使用工具的 CDP 辅助程序。
从录制到技能并非新想法——TeachReplay 的价值在于其可用且经过验证的组合：
演示 → 结构化轨迹 → 参数化技能 → 可执行重放 → 跨 GUI + CLI 的显式验证。