dsh-driftwatch

dsh-toolkit 家族成员：dsh-mcp-bridge · dsh-win-toolkit · dsh-netassist · dsh-driftwatch

DeepSeek Harness agent 的行为漂移报告工具。

你改了个提示词、插件或模型，感觉行为不太一样了。但到底哪里变了、变了多少？

DriftWatch 读两份 session log，精确告诉你 agent 行为的分歧：工具调用序列、工具构成、文件目标、推理量、重试、耗时。零依赖，可直接进 CI。

English docs: README.md.

解决什么问题

DSH 记录一切（模型可见即被记录），证据一直都在——但手工读一份 59 MB 的轨迹不是工作流。已有工具各自解决了相邻问题：

工具	回答的问题
dsh-replay	「把这个轨迹给我看」（调试）
dsh-eval-harness	「这符合我写的预期吗？」（断言）
dsh-driftwatch	「这次运行和上次有什么不同？」（对比）

DriftWatch 刻意不做断言、不渲染轨迹。它产出一份漂移报告：结构化的、可评审的行为变化陈述，另附可选的 CI 阈值门禁。

快速开始

# 列出 $DSH_HOME/sessions 下的会话
npx dsh-driftwatch list

# 对比两次运行（支持 id、id 前缀、路径）
npx dsh-driftwatch compare session-b6c2dcf3 session-b130e75b

# CI 门禁：漂移分 ≥35 时失败
npx dsh-driftwatch compare before after --fail-on-drift 35 --markdown drift.md

真实运行输出（两个实际会话）：

**Verdict: 🔴 significant drift** — score 54/100

| | A (baseline) | B (candidate) |
|---|---|---|
| turns | 4 | 4 |
| records | 6577 | 2692 |
| tool calls | 163 | 82 |
| duration | 1117m 15s | 1079m 13s |

## Tool usage changes
| tool | A | B | Δ |
|---|---:|---:|---:|
| `write` | 41 | 7 | -34 |
| `edit` | 43 | 29 | -14 |
| `pwsh` | 48 | 36 | -12 |
| `todo_write` | 0 | 4 | +4 |

测量什么

信号	细节	权重
工具序列	LCS 对齐：保留 / 删除 / 新增 + 分歧率	40%
工具构成	每个工具在两边的次数差	25%
指标	记录数、轮次、步骤、消息、推理片段/字符、压缩、重试、工具错误、每轮最多工具数	20%
文件目标	只出现在 A / 只出现在 B / 共有 的路径	15%

加权合成 0–100 漂移分，三档：stable（<10）、moderate（10–34）、significant（≥35）。

DriftWatch 从不判断漂移是否可接受——那是你的判断。分数和阈值只是让变化可见。

CI 集成

# .github/workflows/drift.yml
- name: Behavior drift check
  run: |
    npx dsh-driftwatch compare "$BASELINE_SESSION" "$CANDIDATE_SESSION" \
      --fail-on-drift 35 --markdown drift-report.md
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: drift-report
    path: drift-report.md

--json 输出完整机器可读报告（分数、差量、文件集合），供看板或 PR 机器人消费。

作为 dsh 插件

装进 profile 后，agent 会获得两个工具：

dsh plugin --profile web add dsh-driftwatch

工具	agent 能做什么
drift_compare	对比两个会话并把漂移报告直接呈现出来
drift_list	列出可选会话，挑一个基线

适用于「对比你这次和上次做同一个任务的过程」——让 agent 自己收集证据。

session log 是怎么读的

DSH 的 session log 是 append-only 的 .jsonl.zstd：每次追加写入一个独立的 zstd 帧，所以一份日志是多帧拼接。Node 的 zlib 只解第一帧，其流式 API 会拒绝后续帧；DSH 官方用的是私有 zstd 句柄 + koffi FFI 兜底。

DriftWatch 保持零依赖，用自愈式策略：扫描 zstd 帧魔数（28 B5 2F FD），从每个候选起点贪婪解码直到切片解码成功。实测 20 MB / 34 729 帧的日志：解出 59 MB，耗时约 1.4 秒。

局限

• 记录类型按防御式读取：未知类型忽略、缺失字段容忍。未来格式变化只会让报告降级，不会崩溃。
• 序列对齐在 400 万单元对内是精确 LCS；超出后退化为多重集重叠，并在报告中注明。
• DriftWatch 对比的是行为，不是正确性。稳定的运行也可能是错的，漂移的运行也可能更好。

License

MIT