devchristian1337/record-and-replay

Record & Replay (瀏覽器 + 桌面)

Record & Replay 讓代理能夠學習使用者示範的工作流程，並將其轉換為可重複使用的技能。兩種模式：

• 瀏覽器模式（預設，證據最豐富）：一個有頭的 Playwright 瀏覽器（如果可用的話，使用系統的 Google Chrome）將每個使用者操作記錄到 events.jsonl 中，包含多個選擇器候選，以及 Playwright 追蹤區塊（trace-NNN.zip）。可在 macOS、Windows 和 Linux 上運作。
• 桌面模式（原生應用程式）：一個輕量級的單進程記錄器（pynput）擷取全域滑鼠/鍵盤事件、活動視窗變更、點擊時刻的螢幕截圖以及每次點擊的無障礙目標（macOS AX、Windows UI Automation），輸出到 desktop-events.jsonl + screens/，並遮罩密碼欄位 — 與 Codex 同等級（Codex 也記錄事件/上下文串流，而非影片），約佔 1-3% CPU。可在 macOS、Windows 和 Linux (X11) 上運作。請參閱下方的「桌面錄製」。

只要工作流程僅限於瀏覽器，就選擇瀏覽器模式 — 其語義選擇器產生的技能遠比桌面座標來的更好。

設定（一次性）

cd ~/.agents/skills/record-and-replay
node setup.mjs      # npm install + (僅在缺少 Chrome 時才下載 Chromium) + 自我測試
node install.mjs    # 連結到代理技能目錄（macOS/Linux 上為符號連結，Windows 上為目錄連接點）

安裝了 playwright npm 套件。當 Google Chrome 已安裝時，不會下載瀏覽器（記錄器使用 channel: 'chrome'）；否則腳本會下載 Chromium。兩個腳本都是跨平台的（Node）。

錄製工作流程

1. 開始之前，告訴使用者關閉他們不希望被捕捉到的視窗、檔案和對話，並且不要輸入他們不希望被儲存的機密。僅在使用者準備好開始時，在背景中分離地啟動記錄器。始終傳入 --name <slug>，以便事先知道輸出目錄：

   cd ~/.agents/skills/record-and-replay
   # macOS / Linux:
   nohup node scripts/recorder.mjs --minutes 30 --name <slug> [--url <startUrl>] \
     > ~/.agents/recordings/recorder.log 2>&1 &
   # Windows (PowerShell):
   Start-Process node -WindowStyle Hidden -ArgumentList "scripts/recorder.mjs","--minutes","30","--name","<slug>"
   

   具有原生背景執行功能的代理（例如 Claude Code 的 Bash run_in_background）可以改用該功能。輸出會寫入 ~/.agents/recordings/<slug>/。

2. 驗證啟動一次（啟動後約 2-3 秒 — 單次檢查，非輪詢迴圈）：確認 ~/.agents/recordings/<slug>/session.json 存在且 "status": "recording"（記錄器成功時也會在日誌中列印一行 {"status":"recording",...}）。如果檢查失敗，請閱讀日誌：recording_already_active（退出碼 2）表示另一個錄製已持有鎖定；launch_failed 或缺少模組錯誤則表示需要進行設定。報告實際問題，而不是告訴使用者錄製已開始。

3. 啟動檢查後，不要 sleep、輪詢或等待在迴圈中。結束你的回合：告訴使用者錄製已開始、時間限制是多少，以及一個小的浮動控制視窗（右下角，類似 Codex 的錄製控制項）有一個計時器以及暫停/繼續、停止和捨棄（點擊兩次確認）按鈕。暫停時不會捕捉任何內容 — 事件和追蹤都會停止。如果使用者意外關閉控制視窗，它會自己重新開啟；關閉主瀏覽器視窗也會結束會話（避免完全使用 Cmd+Q 退出瀏覽器，這可能會遺失最後一分鐘的追蹤）。啟動時傳遞 --badge 可使用頁面內徽章代替控制視窗（適用於特殊環境的後備方案）。

4. 暫停/繼續（使用者要求您暫停，或者您需要跳過敏感片段）：touch ~/.agents/recordings/<slug>/PAUSE 會在 2 秒內暫停；刪除該檔案以繼續。控制視窗按鈕和 PAUSE 檔案會保持同步；session.json 會攜帶當前的 paused 狀態。暫停間隔會作為 paused/resumed 標記出現在 events.jsonl 中，並且在追蹤中不存在。

5. 當使用者表示他們完成時：

   • 如果進程仍在執行，請優雅地停止它：touch ~/.agents/recordings/<slug>/STOP（記錄器會在 2 秒內注意到並完成最終化）。
   • 讀取 session.json — status: "recording" 表示仍在運作；"completed" 表示輸出已是最終狀態；"discarded" 表示使用者按了捨棄 — 證據檔案已被刪除，承認並絕對不要從中建立技能。endReason 是以下之一：user_stopped、user_discarded、browser_closed、stop_file、time_limit、signal、event_limit。
   • 在回應之前檢查捕捉到的事件：執行 node scripts/summarize.mjs <outDir> 以獲取緊湊的時間軸，然後直接讀取 events.jsonl 以獲取需要細節的步驟。

6. 取消是根據內容而不是 endReason 定義的：如果錄製包含很少或沒有 kind: "dom" 事件 — 無論 endReason 是什麼 — 都將其視為已取消。承認，不要建立或更新技能。

7. 如果錄製包含足夠的資訊來識別可重複使用的工作流程，預設情況下為其建立或改進一個技能 — 即使使用者沒有明確要求。不要僅在產生摘要或重放計劃後就停止。請遵循下方的「從錄製建立技能」 — 從簡短的釐清環節開始。

8. 如果錄製內容過於薄弱或模糊，無法識別工作流程，請不要猜測。解釋不清楚的地方並詢問使用者缺失的部分。

並發錄製

一次只能有一個活動錄製（鎖定檔案 ~/.agents/recordings/.lock）。如果記錄器以 recording_already_active 退出，請勿強制啟動另一個；告訴使用者錄製已正在進行，並詢問是要使用它還是先停止它。使用相同的 --name 重新啟動是安全的：之前的 events.jsonl 會以帶時間戳記的 .bak 檔案保留，而不是附加到其中。

解讀事件

events.jsonl 是主要證據；session.json 僅提供時間/路徑；trace-NNN.zip 區塊是 DOM 級別的真相 (npx playwright show-trace <outDir>/trace-*.zip；session.json 的 traceChunks 按順序列出它們)。追蹤預設為輕量模式 — 每個操作都有完整的 DOM 快照，但沒有連續的螢幕截圖（保持較低的 CPU 使用率）。當使用者想要像素級別的視覺證據時，使用 --trace full 啟動，或使用 --trace off 以獲得絕對最小的足跡。

每行是一個事件：{seq, t (自開始以來的毫秒數), kind, type, url, ...}。

• kind: "page" — 導航、下載、對話框、分頁開啟/關閉。導航將工作流程劃分為階段。
• kind: "dom" — 使用者操作。target.selectors 攜帶多個選擇器候選：testId、role ({role, name})、id、nameAttr、text、css。在生成重放程式碼時，優先使用此順序；css 是最後的手段。
• type: "input" 事件是去彈跳的 — 每個欄位一個事件，帶有最終值（在失焦、按 Enter、變更以及表單提交時刷新）。密碼/信用卡/OTP 類型的欄位（英文和土耳其文名稱：password, parola, şifre, kart, kimlik…）會預先遮罩送達（***MASKED***，masked: true）。
• selection 和 copy 事件揭示了使用者正在處理的內容 — 當使用者提到「這個」或「我選取的東西」時，這通常是最好的線索。看起來像機密的選取內容（OTP、API 金鑰、令牌）會被遮罩。paste 事件僅攜帶長度/字數，從不攜帶內容。
• 敏感資料：遮罩是啟發式的，並非保證 — 而且它僅適用於 events.jsonl。追蹤區塊不會被遮罩：DOM 快照包含原始輸入值（包括在 JSONL 中遮罩的值），而螢幕截圖則捕捉螢幕上所有可見的內容（揭露的令牌、2FA 驗證碼、餘額）。將整個 ~/.agents/recordings/<name>/ 目錄視為敏感：僅在本地檢查它，切勿上傳或提交它，也切勿在摘要或生成的技能中引用其中的字面機密 — 請使用佔位符或通用描述。

從錄製建立技能

在撰寫之前，請閱讀 references/skill-authoring.md：它包含問題庫、frontmatter 限制、SKILL.md 骨架、捆綁腳本的規則和品質檢查清單。如果環境中提供了 skill-creator 技能，其指導也適用。建立一個實際的可發現技能（一個 SKILL.md 資料夾），而不僅僅是一個 Markdown 操作手冊。

複製此核對清單並逐項勾選：

- [ ] 1. 總結錄製內容；記錄每個差距（決策、遮罩片段、盲點）
- [ ] 2. 釐清：一則訊息，最多 6 個問題，僅針對差距
- [ ] 3. 檢查是否有涵蓋此工作流程的現有技能 → 更新它而不是重複建立
- [ ] 4. 撰寫技能 + evals/evals.json（錄製內容是測試案例 1）
- [ ] 5. 驗證：node scripts/export-skill.mjs <skillDir> --check → 修正錯誤，重新執行
- [ ] 6. 提供觸發檢查和一次乾執行；將修正回饋，更新 metadata.version
- [ ] 7. 提供 claude.ai ZIP 匯出

步驟 2 — 在撰寫前釐清。 沒有音訊：錄製內容顯示發生了什麼，而不是為什麼。從錄製中回答它能顯示的內容，然後詢問使用者 — 一次，在一則訊息中，最多 6 個問題 — 關於它無法顯示的內容：結果以及如何判斷它是否有效，哪些值在不同執行之間會變化，為什麼他們在某個時刻選擇了 X，哪些操作是繞路，他們會說什麼來觸發技能（以及什麼不應該觸發），以及哪些操作需要確認。引用您所指的時刻（「在 02:14 你清除了日期篩選器 — 為什麼？」）。如果您有結構化問題工具，請使用它；否則使用純文字聊天。僅當錄製內容加上使用者的請求已經回答了所有問題時才跳過此環節，並說明這一點。

撰寫規則：

• 將錄製內容視為使用者預期結果的證據，而不是要逐像素重放的腳本。如果連接器/API/CLI/MCP 工具可以語義化地達成相同的結果（建立日曆事件、開啟 PR、發布訊息），則優先選擇它而不是 UI 自動化。
• 當確實需要 UI 重放時，從 scripts/replay-template.mjs 生成 Playwright 腳本：語義定位器（getByTestId > getByRole > getByLabel > getByText），在每個關鍵操作後進行驗證步驟，從環境變數取得機密。除非事件串流沒有提供更好的目標，否則絕不使用原始座標。
• 桌面步驟命名被捕捉的目標（角色 + 名稱 + 視窗，例如 Button "Save" in "Invoice — Acme"），以便無障礙樹工具可以找到它；僅在沒有捕捉到目標時才使用座標。
• 記錄器的持久化設定檔（~/.agents/recordings/.browser-profile）會跨會話保持登入狀態，因此生成的技能通常不需要登入步驟。安全性：該目錄包含即時已驗證的會話資料（cookies/localStorage；Playwright 使用模擬鑰匙圈啟動 Chrome，因此將其視為明文憑證）。切勿未加密地提交、分享或備份它 — 請記住，任何重用它來重放的技能都將使用使用者的登入資訊進行操作。對於在不受信任或高度敏感的網站上的錄製，偏好使用一次性設定檔（--out 加上臨時設定檔）或在事後清除該設定檔。
• 將新技能儲存到 ~/.agents/skills/<skill-name>/（資料夾名稱 = name，kebab-case），並將其符號連結到代理技能目錄（請參閱 install.mjs 以了解模式），以便此機器上的每個代理都可以使用它們。
• 將變化的內容（日期、金額、名稱）參數化，並將不變化的內容硬編碼。在生成的 SKILL.md 中說明工作流程的目的和驗證標準。切勿將機密或遮罩值複製到技能中。

匯出至 claude.ai（提供選項；應要求執行）：node scripts/export-skill.mjs ~/.agents/skills/<name> 會寫入 ~/.agents/exports/<name>.zip（ZIP 根目錄為資料夾；排除 README、evals、快取和錄製證據；在成功前會讀回存檔進行驗證）。如果技能使用了僅限 Claude Code 的 frontmatter（disable-model-invocation, …），則加入 --strip-cc-keys。告訴使用者檔案的位置，並且可以透過「自訂 › 技能 › + › 上傳技能」上傳（必須啟用程式碼執行）。

桌面錄製（macOS、Windows、Linux/X11）

設定：node setup.mjs（從 requirements-desktop.txt 建立最小的 .venv-desktop Python 環境 — pynput+mss+pillow，以及在 Windows 上的 comtypes，約 50 MB；需要 uv）。

權限 (macOS)：記錄器會預先檢查它們並報告機器可讀的狀態，因此永遠不要猜測。start 會印出 permissions: {inputMonitoring, screenRecording, grantTo} 以及當缺少某些東西時的 warning，並自動彈出系統對話框並開啟正確的「設定」面板（--no-permission-prompt 可停用此功能；node scripts/desktop-record.mjs permissions 可按需求執行）。grantTo 指定使用者必須授予權限的應用程式名稱 — TCC 授予綁定到承載代理的 .app 套件，而不是 Python，並且該應用程式之後必須重新啟動。逐字轉達 grantTo；告訴使用者「授予您的終端機」通常是錯誤的。Windows 不需要權限，也不需要管理員權限。

引擎是一個單進程記錄器（約 0-3% CPU）：輸入事件串流 + 活動視窗/標題變更 + 每次點擊時的一張半解析度 JPEG（最大 1/700 毫秒） → desktop-events.jsonl + screens/。每次點擊還攜帶游標下元素的無障礙描述（kind: "target" 行，透過 forSeq 連接到點擊）：role、name、automationId、window、ancestors — 一個語義目標，例如 Button "Save"，而不是單純的座標（macOS AX、Windows UI Automation；Linux 上無）。打字輸入作為 type: "text" 事件送達，其中包含每次輸入爆發的最終值（已套用退格鍵修正）；快捷鍵和特殊鍵作為 press 事件送達（ctrl+c、enter）。螢幕截圖、目標查詢和焦點檢查在工作執行緒上執行，從不在輸入回調中執行：緩慢的回調會導致 macOS 事件點被停用，以及 Windows 鉤子被靜默移除（記錄器也會監視後者並重新安裝鉤子）。

這與 Codex 同等級：Codex 的 Record & Replay 也會記錄...

[因原文截斷而截斷]