Trajectory_Gen

Trajectory_Gen 是一个基于 Playwright + TypeScript 的人工操作轨迹采集工具，用于记录用户在浏览器完成指定任务时的交互序列（点击 / 悬停 / 滚动等），并生成结构化 JSON 数据。

目录结构

Trajectory_Gen/
├─ dist/              # tsc 编译后的 JS 输出（自动生成）
├─ logs/              # 任务执行完毕后保存 action 轨迹
├─ node_modules/      # 依赖
├─ src/               # 源代码
│  ├─ recorder.ts     # 启动浏览器、调度任务、保存日志
│  ├─ inject.js       # 注入页面的监听脚本（UI、去噪）
│  └─ types.ts        # TypeScript 类型定义
├─ tasks/             # 待执行任务（*.json）
│  └─ sample_task.json
├─ package.json       # npm 脚本 & 依赖
├─ tsconfig.json      # TypeScript 编译配置
└─ README.md          # 项目说明（本文件）

功能概览

1. 浏览器控制：使用 Playwright 打开任务指定网站（Chromium，非 headless）。
2. 事件监听：在页面注入 inject.js，实时捕获
   • CLICK：立即记录。
   • HOVER：防抖 3 s（HOVER_DELAY），仅检测到最近 1 s 内页面有实际 DOM 变化才计入。
   • SCROLL：节流 0.5 s 记录一次位置。
   • INPUT / KEYDOWN：输入内容、按键。
3. 截图系统
   • 两种模式：
     • Auto Screenshot（默认）：按下任一用户动作后 200 ms 自动截图，并在后续 300 ms 内若检测到 DOM 变化则再补一张；每 5 s 冷却一次。
     • Manual Screenshot：完全关闭自动截图，需用户手动触发。
   • 切换方式：左下角绿色/蓝色按钮 Auto Screenshot / Manual Screenshot 一键切换。
   • 手动触发：
     • 点击左下角 📸 Screenshot 按钮（仅 Manual 模式可见）。
     • 使用热键 Alt + S（或 Alt + Shift + S 备用）快速截图。
   • 视觉反馈：顶部冷却进度条 + 右下 Toast"📸 Screenshot captured"。
4. 录制 UI（按钮位置）
   • 左下角：Auto/Manual 切换按钮（bottom 20px）+ 手动 📸 Screenshot（bottom 60px）。
   • 右下角：Finish Recording（bottom 20px）。
   • 底部：Hover 进度条；顶部：Screenshot 冷却条。
5. 结束方式：
   • 点击 Finish Recording；
   • 或在运行脚本的终端按 Enter。
6. 数据输出：生成

   {
     "annotation_id": "xxxx",
     "action_reprs": [
       "[link] Standings -> CLICK",
       "[window] scrollY=560 -> SCROLL"
     ]
   }

   保存到 logs/<annotation_id>.json；截图文件保存到 screenshots/。

安装与运行

# 克隆仓库后安装依赖
npm install
# 首次安装浏览器
npx playwright install chromium

# 运行任务（会自动 build）
npm run dev

自定义任务

在 tasks/ 中放置形如：

{
  "annotation_id": "task-001",
  "confirmed_task": "Find the standings for the English Premier League.",
  "website": "sports.yahoo",
  "domain": "Entertainment",
  "subdomain": "Sports"
}

多文件将按文件名顺序依次执行。

可配置项

位置	变量	说明
src/inject.js	HOVER_DELAY	Hover 防抖阈值 (ms)
src/inject.js	SCROLL_INTERVAL	Scroll 节流间隔 (ms)
src/inject.js	SCREENSHOT_DEBOUNCE	DOM 变化后自动截图去抖 (ms)
src/inject.js	SCREENSHOT_COOLDOWN	截图冷却时长 (ms)
src/inject.js	ACTION_WINDOW	仅在最近 N ms 用户动作时才自动截图
src/inject.js	screenshotMode	默认截图模式 (auto|manual)

注意事项

1. Node 版本 ≥18：Playwright、TypeScript 5 需要高版本 Node。
2. 重新编译：修改 src/ 代码后务必执行 npm run build，或直接 npm run dev（已包含 build 步骤）。
3. 站点重载问题：极少数站点在加载后通过 document.write 或前端路由重置 DOM，如遇 UI 消失，可在控制台执行 window.__injectRecorder && window.__injectRecorder() 重新注入脚本。
4. 日志体积：Hover & Scroll 已做去噪；若仍过大，可调大阈值或在离线阶段清洗。

---

如果本项目对你有帮助，欢迎 Star / Fork 🌟，有任何问题可提 Issue 反馈 🙌