前言¶
做智能體（Agent）開發時，一類問題反覆出現：你在真實界面上覆現了故障，Agent 卻只能拿到你打的一段描述和一份日誌。畫面上很明顯的 bug，在幾百行日誌裏無從定位；而「我當時按了什麼」只有你自己記得。手動貼截圖、截動圖、翻日誌，拼出來的證據常常缺一角。
dsh-incident-studio（插件名 dsh-incident-studio，維護者 Eclipse-NotFound，分類「工作流」）就是爲這件事做的 DSH 插件。它把屏幕畫面、日誌行、鍵鼠輸入放在同一條毫秒時間軸上，錄完打點、圈選區間、拖框標註、寫一句話，然後一鍵把關鍵幀條帶、動圖、對齊後的日誌切片和描述填進 composer 交給 Agent。
它不綁定任何遊戲或項目：日誌源是配置出來的，任何會寫文件的程序都能接，程序也可以用 HTTP 接口直接推事件。
核心功能¶
插件在錄製期間同步採集四類證據，共用一套牆鍾時間：
| 證據 | 來源 | 精度 |
|---|---|---|
| 畫面 | 宿主抓幀（三條路徑，見下文） | 默認 6 fps，每幀帶牆鍾時間 |
| 事件 | 日誌文件跟隨 + 打點 + HTTP 推送 | 行寫入時刻，約幾十毫秒；推送可帶精確時間 |
| 鍵鼠 | 輪詢助手（僅目標程序在前臺時） | 約 30 Hz，誤差 ±1 個採樣間隔 |
| 你的描述 | 畫面上的標註框 + 一句話 | 掛在選中的區間上 |
交付給 Agent 的每一行日誌都帶 [00:12.340] 形式的相對時間戳，與圖像幀、按鍵事件同源，Agent 不需要猜是哪一行、也不用猜你當時按了什麼。
錄製結束後你把內容交給 Agent 的方式是「產物 + 緊湊紀要」：現象、區間、產物路徑、標註說明、鍵鼠統計，以及最多 80 行日誌（錯誤行與打點優先保留，打點行附帶「前一條輸入」）；完整記錄在 bundle.md 裏。
安裝與啓用¶
要求 DeepSeek Harness 0.2.1+（package.json 中寫 engines.dsh 爲 >=0.2.1-rc.1 <0.3.0）。插件包內 client.js 已經隨倉庫提交，無需構建。
# 從倉庫直接安裝（client.js 已隨倉庫提交，無需構建）
dsh plugin --profile <profile> add https://github.com/Eclipse-NotFound/dsh-incident-studio
桌面端的 profile 由應用自己管理：在 設置 → 插件 裏按倉庫地址安裝。README 特別提醒不要把 CLI 裝進 profiles/web，那樣不會出現在桌面端。裝完需要重啓一次纔會加載宿主半側；瀏覽器半側隨宿主發佈，頁面會熱更新重跑。
停用方式有兩種：
# 在 dsh.profile.bundles 裏刪掉 dsh-incident-studio，或在 profile 的 patch 里加：
- id: incident-studio
disabled: true
使用流程¶
面板入口是右側欄的 +（引導頁「Incident Studio」），或 composer 下方的 🎥 Capture 按鈕。首次掛載會自己打開一次並記在 localStorage。
1、配置日誌源（只需一次）：面板 → 設置 → 填日誌文件的絕對路徑或相對工作區路徑。文件可以晚於錄製開始出現，先開錄製再啓動程序也能接上。同一頁面填目標進程名（例如 Remains），鍵鼠記錄才知道該在哪個窗口前臺時記錄。
2、錄製：選採集源 →「● Start recording」。出問題時按「⚑ Mark」，可以打多次；打點會自動記下問題出現前你最後按下的那個鍵。
3、復看與標註：默認區間是最後一次打點 ±3 秒。拖動播放頭時日誌列表同步定位；點日誌行跳回對應畫面。Input 區塊能展開區間內每一次按鍵/點擊，點擊單條同樣 seek。在畫面上拖出紅框，每個框都可以寫一句說明。
4、交付：Build artifacts → Fill composer。附件默認帶關鍵幀條帶，GIF 可選；確認後回車發送，或直接點 Send now。
產物落盤位置¶
產物寫進當前會話工作區的 .dsh-incidents/<recording-id>/：
.dsh-incidents/20261104-193045-a1b2c3/
frames-20261104193045.png 6 幀橫向條帶，帶時間戳與紅框
clip-20261104193045.gif 區間動圖（460 px 寬）
input.jsonl 原始鍵鼠事件，每行一個 JSON
bundle.md 完整紀要：描述、標註座標、全部事件行、輸入記錄
bundle.json 同上的機器可讀版
程序側：HTTP 推送接口¶
除了跟隨日誌文件，本機進程（模組、測試腳本、dev server）可以直接推事件：
curl -X POST http://127.0.0.1:<dsh端口>/dsh-incident-studio/api/ingest \
-H "content-type: application/json" \
-H "x-incident-token: <面板設置裏顯示的令牌>" \
-d '{"text":"進入 raiders 房間","src":"RConnect","level":"info"}'
x-incident-token 每進程一個，在面板設置裏可見；同源面板自己推送不需要令牌。請求體帶 wall（epoch 毫秒）時按你給的時間入軸，否則用收到時刻。
三條採集路徑¶
插件按宿主進程能力選路徑，三條路的產物都是「帶牆鍾時間的幀」，後續標註、導出、交付完全一致：
| 宿主進程能拿到什麼 | 走哪條 | 說明 |
|---|---|---|
electron.desktopCapturer |
定時抓 JPEG | 默認 6 fps / 960 px / q62，可以按窗口選源 |
只有 Node（Electron utility 進程 / 純 dsh web） |
Windows GDI 抓屏助手 tools/grab-frames.ps1 |
整個虛擬桌面；長駐 PowerShell 寫 JPEG，主機收幀後刪臨時文件 |
真實瀏覽器打開 dsh web |
getDisplayMedia + MediaRecorder |
需要屏幕共享授權，停錄後本地抽幀 |
README 註明一個實測結論：DSH 桌面宿主拿不到 desktopCapturer（/state 裏 nativeReason: "desktopCapturer 不可用"），桌面端實際走 GDI。GDI 用 System.Drawing + Graphics.CopyFromScreen，320 px / 4 fps 時單幀約 5 KB。代價是無法選單個窗口。幀緩衝默認上限 900 幀 / 96 MB / 5 分鐘，超出丟最早的幀。
鍵鼠記錄的取捨¶
tools/record-input.ps1 是長駐助手，每 20 ms 讀一次 GetAsyncKeyState，只寫變化。設計上刻意不裝鍵盤鉤子、不做鍵位翻譯、不碰 ToUnicode：鉤子既像鍵盤記錄器，又會把系統輸入延遲拖進你的進程。記錄範圍默認只在目標程序持有前臺時進行，切出去會寫一條失焦日誌。
首次啓動會做一次真探測，結果落在 $DSH_HOME/storages/dsh-incident-studio/input-capability.json，面板設置裏能看到可用鍵位數或具體原因。依賴 Windows + 系統自帶的 Windows PowerShell 5.1。
配置寫在 <DSH_HOME>/storages/dsh-incident-studio/profiles.json（DSH_HOME 默認 ~/.dsh），面板設置改的就是這個文件：
{
"version": 1,
"activeId": "my-project",
"profiles": [
{
"id": "my-project",
"name": "我的項目",
"sources": [
{ "id": "main", "label": "主日誌", "color": "#6aa9ff", "kind": "file",
"path": "C:/Users/you/AppData/Roaming/MyApp/logs/main.log", "enabled": true, "preRoll": true }
],
"input": { "enabled": true, "targets": "Remains.exe", "scope": "target", "pollMs": 20, "trailHz": 0 }
}
]
}
path 不展開 %VAR% 和 $HOME；preRoll（默認開）在錄製開始時抓文件尾部最多 96 KB / 800 行並標成「錄製前」；input.targets 是目標進程名（最多 8 個），scope 爲 "all" 時記錄除插件自身外所有前臺窗口。
適用場景與注意¶
適合需要在真實界面上覆現問題的人——遊戲模組、GUI 客戶端、前端交互這類「看一眼就明白、翻日誌很難找」的場景。插件不綁定項目，日誌源和目標進程都由你配置，可以同時跟多個日誌文件。
注意幾點：
- 插件以當前
dsh宿主進程的權限運行，抓幀、鍵鼠採集和 HTTP 推送都可能觸及本機敏感數據。安裝或啓用前應當先讀一遍源碼與LICENSE（MIT），確認它採集的邊界符合你的環境要求。 - 抓幀和鍵鼠記錄只在按下「開始錄製」之後進行，停止即停。桌面端 GDI 拍的是整個虛擬桌面，敏感窗口請先移開。
- 鍵鼠記錄不記任何文字內容，只在目標程序持有前臺時採集；插件宿主進程本身始終被排除，面板裏的輸入不會被記入。
結尾¶
這個插件的價值在於可覈對性：畫面、日誌、按鍵在同一時間軸上，Agent 拿到的不再是「你猜的那一刻」，而是有座標、有時間戳、有輸入序列的證據。項目在社區目錄的分類是「工作流」，星標 0，仍屬早期階段；功能邊界和踩坑記錄都在 README 裏，決定引入前建議通讀。
目錄頁：https://www.skillhub.cn/plugins/Eclipse-NotFound/dsh-incident-studio
倉庫：https://github.com/Eclipse-NotFound/dsh-incident-studio
