dsh-time-travel

给 DeepSeek Harness (DSH) 的 Cordis 插件：可逆时间旅行与审计 —— 为工具副作用建立「前状态快照 → 执行 → 补偿操作」链路，提供 rewindTo(turnId) 按轮次倒序恢复工作区，并内置审计规则引擎把危险操作落盘 audit-log.jsonl。

兼容 DSH 0.1.0-rc.6（cordis 4.x / schemastery 3.x）。请勿裸装 @latest，以本仓库版本为准。

功能定位

一句话：把"模型用工具改坏了工作区"这件事变得可逆且可审计。

• 监听 tools/pre-execute / tools/result 工具管线事件，对 fs.write / fs.delete / bash / http.request 四类工具建立快照与补偿；
• ctx.timeTravel.rewindTo(turnId)：按轮次倒序执行补偿，恢复工作区到指定轮次之前；
• 审计规则引擎：命中危险 shell、敏感路径写、不可补偿写操作后，追加一行 JSON 到 audit-log.jsonl；
• 全部副作用经 ctx.on() 注册，插件卸载时自动撤销，不污染 dsh 工具管线（快照/审计失败都会被包含，绝不影响工具执行）。

安装

# 在插件工程根目录执行（本目录绝对路径）
dsh plugin --profile web add /absolute/path/to/dsh-time-travel

# 或手动打包安装（绕过 pnpm forwarder 时的等价路径）
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）生效。插件挂载后：

• ctx.timeTravel 可用（rewindTo / rewindAll / records / clear）；
• 当前目录生成 audit-log.jsonl（可用 audit.logPath 配置）。

配置

插件导出 schemastery Config，可在 dsh 的插件配置面板 / profile 中覆盖：

配置项	类型	默认值	说明
turnGapMs	number	5000	同一会话内两次工具调用超过该间隔（ms）则开启新轮次；0 = 每次调用独立成轮
audit.enabled	boolean	true	是否启用审计规则引擎
audit.logPath	string	audit-log.jsonl	审计日志输出路径（JSON Lines，相对 cwd）
audit.rules	dict<boolean>	全部 true	按规则 id 开关：dangerous-shell / sensitive-path-write / non-compensable-write / delete-whole-dir
watchTools	dict<kind>	见下表	工具名 → 补偿器类别映射
maxRecords	number	10000	内存保留的最大工具记录数（超出丢弃最旧；审计日志不受影响）
dryRun	boolean	false	true 时 rewind 只出报告、不实际执行补偿

watchTools 默认映射（按 DSH 0.1.0-rc.6 实际工具名 + 通用桥接名）：

工具名	补偿器类别	可自动补偿
write / edit	fs-write	✅ 恢复原内容 / 删除新建
delete	fs-delete	✅ 写回原内容
bash	bash	❌ 仅审计 + manual 提示
http.request	http	❌ 仅审计

最小使用示例

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 及之后所有工具副作用
// report: { requestedTurnId: 'T3', rewound: 2, skipped: 1, failed: 0, details: [...] }

// 查看当前记录（可按会话过滤）
const records = ctx.timeTravel.records('session-abc123')

// 全部回退
await ctx.timeTravel.rewindAll()

审计日志示例（audit-log.jsonl）：

{"at":"2026-08-20T08:00:00.000Z","turnId":"T1","sessionId":"s1","callId":"c1","toolName":"bash","kind":"bash","isError":false,"hits":[{"ruleId":"dangerous-shell","severity":"critical","message":"bash 命令命中高危模式（rm -rf / mkfs / dd 写盘 / shutdown / curl|sh 等）"}],"command":"rm -rf /tmp/doomed"}

与 dsh-replay / dsh-turn-rewind 的差异

	dsh-time-travel	dsh-replay	dsh-turn-rewind
关注对象	工作区文件系统副作用的可逆补偿	会话事件日志的重放（时序复现）	会话状态按轮次的回退（消息层）
回滚手段	工具调用级前状态快照 + 补偿操作（restore/delete）	按日志重新派发事件	截断 / 重建轮次内的消息
审计	✅ 内置规则引擎（危险 shell / 敏感路径 / 不可补偿写）	通常依赖日志本身	视实现而定
对外 API	ctx.timeTravel Service（rewindTo / records）	重放驱动	轮次回退 API
不可补偿操作	显式标记 manual 并审计，交由人工处理	重放无法改变历史副作用	消息回退不触碰文件系统

一句话：dsh-replay / dsh-turn-rewind 处理的是"对话/会话怎么回到过去"，本插件处理的是"工作区文件怎么回到过去"，两者互补；对不可自动补偿的副作用（bash / http），本插件选择审计留痕 + 人工回滚而非冒险猜测。

开发

pnpm install
pnpm run check   # tsc --noEmit，严格模式零错误
pnpm run build   # tsc → lib/
pnpm test        # node --test（含 rewindTo 恢复文件的端到端事件测试）

License

MIT