dsh-agent-lab · Agent 回归实验台

把一次真实会话录成运行（run），再和另一次运行并排对比：工具选择、参数、结果、成败与用量到底变了什么。

这是「给 agent 配置做 pytest」的第一步。完整设想里的重放 / 变体矩阵 / CI 门禁见文末路线图；本版本先把最容易被忽略、也最花时间的一环做扎实——看清两次运行的行为差异。

它解决什么

• 换了模型、effort、提示词或插件版本，同一个任务的行为变了吗？
• 两次跑同一个流程，一次成功一次失败，差异出在哪一步？
• 插件作者收到「它乱改文件」的反馈，怎么把现场留下来对照？

现有工具只能看录像；这个插件把两次运行的轨迹摆在一起，并标出差异。

使用

侧栏打开 回归实验台 图标，然后：

1. 从会话导入 —— 选择一个已有会话（含正在进行的），录制成运行。
2. 再录一次（或选择库里已有的两次运行）。
3. 页面自动把 基线 A 与 对照 B 并排对齐：

• 顶部指标：行为相似度、工具调用数、失败数、Token、耗时、步骤，各自带 A→B 增量与变好/变差着色；
• 配置指纹：模型、effort、工具 schema 数、工具 schema 哈希、系统提示词哈希、沙箱与审批策略；
• 任务：两次运行的用户提示词（不同会显式提醒）；
• 对齐轨迹：可点击的逐行对比。状态分为 一致 / 参数漂移 / 结果变化 / 成败翻转 / 缺失 / 新增，插入或丢失一次调用不会让后面全部错位；
• 展开一行：左右两侧完整参数与结果并排显示，并列出发生变化的参数键；
• 仅差异：只看不一致的行；轨迹顶部的色条是整段行为的缩略图。

运行库保存在 $DSH_HOME/agent-lab/runs/*.json，可直接阅读、可版本化。

对比口径

比较的是行为不变量，不是模型文本：工具名、顺序、参数、成功/失败、结果内容。

• 参数与结果都做了归一化（工作目录替换为 <cwd>、换行统一、行尾空白清理），所以换工作区不会造成假差异。
• 序列对齐使用 Needleman–Wunsch（同名工具才能配对，名称不同会优先判为缺失/新增），避免「多一次调用，后面全红」。
• 「行为相似度」是 60% 轨迹对齐 + 25% Token 量 + 15% 失败数差异的启发式分数，只用来看趋势，报告里始终保留原始 diff。

明确不做（v0.1）

• 不重放：只读取会话日志，不会重新调模型，也不会改动工作区。
• 不做变体矩阵、CI 门禁、worktree 隔离、外部工具夹具。
• 不递归录制子代理/工作流树。
• 运行记录只在本机；不含任何上传。

技术实现

文件	作用
index.js	Host 半：同源 JSON API（/agent-lab/api/*）、会话读取、运行库读写
lib/capture.mjs	会话事件 → 运行记录（提示词、配置指纹、轨迹、用量、活动耗时）
lib/compare.mjs	归一化、序列对齐、差异分类、指标与相似度
client.js	浏览器半：侧栏图标 + 主页面的并排对比视图
test/compare.test.mjs	对齐与采集的单元测试

数据来源：

• 活跃会话：ctx.sessions.get(id).snapshotEvents()
• 历史会话：ctx.sessionPersistence.open(id, 'read').read(0, N)
• 配置指纹：request/header（provider / model / effort / 工具 schema）与 system/message
• 用量：assistant/message.usage
• 活动耗时：step/start → step/end 求和（会话被中断两天后恢复，不会算成「工作了两天」）

开发

cd plugins/dsh-agent-lab
node test/compare.test.mjs

安装 / 更新（在本 profile 中）：

plugin_manager install_bundle <插件目录的绝对路径>

Host 代码改动在下次 profile 重组（Plugin Manager 操作）或应用重启后生效；浏览器半改动刷新页面即可。

路线图

版本	内容
v0.1（本版）	录制、并排对比、配置指纹、启发式相似度
v0.2	夹具重放：在同一任务上换模型/提示词重跑，自动生成对照运行
v0.3	变体矩阵：行是任务、列是变体，单元格是通过率 / 调用数 / Token
v0.4	断言与门禁：no-tool、file-contains、阈值回归，输出退出码给 CI