前言¶
在 DeepSeek Harness（DSH）這類「一切皆插件」的智能體運行時裏，模型經常通過工具直接修改工作區：寫入文件、編輯文件、刪除文件，甚至執行 shell 命令或發起 HTTP 請求。這些副作用一旦發生，開發者通常缺少一個穩定的回滾入口：文件可能被覆蓋，刪除動作可能無法立即恢復，危險命令也難以事後追蹤。
dsh-time-travel 是 helibeiqi 維護的 DSH 插件，MIT 許可。它的目標比較具體：給工具副作用建立「前狀態快照 → 執行 → 補償」鏈路，提供按輪次倒序恢復工作區的能力，並把命中審計規則的危險操作記錄到審計日誌中。
一句話定位¶
這是一個面向 DSH 插件系統的可逆時間旅行與審計插件：當 fs.write、fs.delete、bash、http.request 等工具產生副作用時，插件嘗試記錄前狀態並註冊補償動作，隨後通過 ctx.timeTravel.rewindTo(turnId) 按輪次恢復工作區，同時內置審計規則引擎記錄危險操作。
倉庫信息：
name: dsh-time-travel
owner: helibeiqi
license: MIT
package.json version: 0.2.0
engines: node >=18
核心功能¶
下面介紹幾個可覈實的能力。
監聽工具管線事件¶
插件監聽 DSH 的工具管線事件：
tools/pre-execute
tools/result
它圍繞四類工具建立快照與補償鏈路：
fs.write
fs.delete
bash
http.request
其中，文件類工具更適合做自動補償；shell 和 HTTP 請求類工具通常難以自動逆轉，插件會走審計或人工處理路徑。
按輪次回滾工作區¶
插件提供 ctx.timeTravel.rewindTo(turnId)。調用後，它會按輪次倒序執行補償，嘗試恢復工作區到指定輪次之前。
例如：
const report = await ctx.timeTravel.rewindTo('T3')
這一行的含義是：撤銷 T3 及之後所有可補償的工具副作用，並返回一份回滾報告。
提供一組運行時 API¶
插件掛載後，運行時上下文會暴露 ctx.timeTravel，可使用的能力包括：
rewindTo
rewindAll
records
clear
其中：
rewindTo(turnId)：回滾到指定輪次之前；rewindAll()：執行全部可補償回滾；records(sessionId)：查看工具副作用記錄；clear()：清理記錄。
示例：
const records = ctx.timeTravel.records('session-abc123')
await ctx.timeTravel.rewindAll()
內置審計規則引擎¶
插件內置審計規則引擎。當操作命中危險 shell、敏感路徑寫、不可補償寫操作等規則時，會追加一行 JSON 到審計日誌。
默認審計日誌路徑爲：
audit-log.jsonl
該路徑可通過 audit.logPath 配置。
審計日誌使用 JSON Lines 格式，每條記錄是一行 JSON，便於後續接入日誌系統或做人工複覈。
失敗隔離¶
插件副作用通過 ctx.on() 註冊。插件卸載時會自動撤銷這些副作用。
同時，插件設計目標之一是：快照或審計失敗不應影響工具本身執行。也就是說，回滾與審計是附加鏈路，不應阻塞正常的工具調用。
安裝與啓用¶
在插件工程根目錄執行：
dsh plugin --profile web add /absolute/path/to/dsh-time-travel
這裏的 /absolute/path/to/dsh-time-travel 需要替換爲本地倉庫絕對路徑。
如果手動打包安裝，README 給出的等價路徑是先執行 npm pack，再在 profile 目錄安裝生成的 tgz 包。示例中使用的是：
npm pack
然後：
cd ~/.dsh/profiles/web
npm install /absolute/path/to/dsh-time-travel-0.1.0.tgz --no-save --no-audit --no-fund
安裝後，需要重啓 dsh web 使插件生效，默認端口爲：
3080
典型用法¶
下面的示例用於展示插件掛載後的編程調用方式。
import { Context } from '@deepseek-ai/cordis'
import { apply } from 'dsh-time-travel'
// 插件被 dsh 加載後，apply 已執行；以下僅爲編程調用示例
const ctx: Context = /* dsh 注入的根 Context */
// 模型調用 write 覆蓋了 a.txt 之後：
const report = await ctx.timeTravel.rewindTo('T3')
// 撤銷 T3 及之後所有工具副作用
// 查看當前記錄（可按會話過濾）
const records = ctx.timeTravel.records('session-abc123')
// 全部回退
await ctx.timeTravel.rewindAll()
使用順序通常可以這樣理解：
1、插件加載後，ctx.timeTravel 可用；
2、工具執行過程中，插件記錄副作用並準備補償動作；
3、當確認某輪次開始的操作需要撤銷時，調用 rewindTo(turnId)；
4、如果需要查看所有待回滾或已記錄的工具副作用，調用 records(sessionId)；
5、如果確認全部回滾，調用 rewindAll()。
配置項¶
已覈實的配置項包括：
audit.logPath¶
審計日誌輸出路徑，默認值爲：
audit-log.jsonl
日誌格式爲 JSON Lines，相對當前工作目錄解析。
dryRun¶
類型爲布爾值。當 dryRun 爲 true 時，rewind 只輸出報告，不實際執行補償。
適合在排查問題時使用：先確認哪些副作用會被回滾、哪些會被跳過，再決定是否真正執行補償。
maxRecords¶
用於控制內存中保留的最大工具記錄數，默認值爲：
10000
超出上限後，最舊記錄會被丟棄。審計日誌寫入不受該內存記錄限制影響。
可自動補償與僅審計的工具¶
默認映射中，文件類工具更容易做自動補償：
write / edit：可恢復原內容或刪除新建文件
delete：可寫回原內容
而以下工具通常不可自動補償：
bash
pwsh
http.request
這些工具命中審計規則後，插件以審計留痕或 manual 提示爲主，交由人工判斷。
這一點在實際使用時比較重要：不要把 rewindTo 理解成“所有副作用都能一鍵撤銷”。它能恢復的是可補償的文件系統狀態；對於 shell 執行結果、外部 HTTP 請求等已經離開本地工作區的動作，插件不會冒險自動猜測回滾方式。
兼容性與安裝注意¶
插件兼容：
DSH 0.1.0-rc.6
cordis 4.x
schemastery 3.x
安裝時應以本倉庫版本爲準，不建議直接裸裝 @latest。
插件會在當前 dsh 進程權限下運行，並且會讀取工具調用、寫入審計日誌，部分場景下還會嘗試恢復文件。安裝前建議先檢查源碼、依賴與 MIT 許可證，確認它符合當前環境的權限邊界。
適用場景¶
這個插件適合以下幾類場景：
- 在
dsh webprofile 中運行工具密集型智能體，需要快速恢復工作區文件； - 想對
write、edit、delete等文件工具建立可回滾鏈路； - 需要對危險 shell、敏感路徑寫入、不可補償寫操作留下審計痕跡；
- 希望在插件卸載後自動撤銷監聽器，避免污染 DSH 工具管線。
它主要處理的是工作區文件副作用的回滾與審計。會話消息層面的回退、會話事件日誌重放，不在這個插件的職責範圍內。
結尾¶
dsh-time-travel 的價值在於把工具副作用從“執行後只能人工排查”變成“可記錄、可回滾、可審計”。它通過 ctx.timeTravel 提供按輪次回滾能力，通過審計日誌保留危險操作痕跡，並通過 ctx.on() 註冊副作用，保證插件卸載時可以自動撤銷。
倉庫地址：
https://github.com/helibeiqi/dsh-time-travel.git
