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 提示 |
pwsh | bash | ❌ 仅审计（Windows 上 dsh 的 bash 工具实际注册名为 pwsh，PowerShell） |
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
