前言¶
在 DeepSeek Harness（DSH）里让智能体改代码，常见做法是盯着 diff、靠 git 回滚，或者手动从备份里捞文件。一轮对话里可能动很多文件，还可能通过脚本间接写入磁盘；若只想撤销「这一轮」的改动，又不想动项目里的提交历史，就需要把「一轮」当成时间单位来记、来退。
下面介绍社区插件 dsh-file-history（维护者 EmptyVessel-000，SkillHub 分类为「记忆」）。它在每一轮对话结束后对工作区拍快照，在改动了文件的回复下方展示变更卡片，并支持只还原文件、只还原对话、或两者一起还原；侧栏还提供时间线与检查点。数据存放在 ~/.dsh/file-history/，不读写项目目录下的 .git。
这是什么¶
dsh-file-history 是面向 DSH Web 端的文件历史插件：每一轮对话结束，插件记录该轮前后工作区在磁盘上的真实状态（不限于 AI 工具直接写入的文件），并在有改动的回复下展示文件列表、增删行数与 diff，配合还原与分支操作。
简介（仓库与目录页一致）：Per-turn snapshot of your DSH workspace. Any turn can be restored — files, conversation, or both.
核心功能¶
按轮次快照¶
快照落在 $DSH_HOME/file-history/（默认 ~/.dsh/file-history/），不进项目目录。项目没有 .git 也能用；有 git 仓库时插件也不读写项目里的 .git、提交、分支或暂存区。内容相同的文件只存一份；超出保留策略的旧记录会回收。
对话下方的变更卡片¶
只有真正改动了文件的轮次会出现卡片：列出新增 / 修改 / 删除、各文件增删行数、被跳过的大文件数量。点文件名可看该轮 diff；底部四个操作——只还原文件、只还原对话、全部还原、从这一轮开分支；还原后可「撤销还原」。
侧栏时间线¶
「文件历史」页倒序展示：顶部为「现在」，往下是检查点与各轮。可展开详情并还原。检查点圆点颜色区分来路（会话开头、分叉、手动标记）；父分支上的轮次压暗只读，操作按钮不可用。
输入框上方的改动条¶
当存在检查点且工作区与检查点不一致时，显示差异摘要（文件数、增删行数），可展开逐文件查看并「还原到检查点」。若同一线上的另一分支更晚改过同一文件，会出现提示并可跳转到该分支会话。
检查点¶
可在侧栏或卡片上「设为检查点」，保存当前文件树。检查点与会话线绑定；从同一会话分叉出去的会话共用一条线。自动裁剪按分支计算：保留最近 keepRecentTurns 轮，并在该族检查点足够时以 pruneAfterCheckpoints 为切点裁剪。
侧栏底部提供「清除轮次快照」（保留骨架与分支节点）与「清除所有分支历史」（含检查点，回到刚安装时的状态），仅作用于当前会话线的分支族。
还原行为摘要¶
| 操作 | 磁盘文件 | 对话 |
|---|---|---|
| 只还原文件 | 写回该轮开始前的内容 | 不动 |
| 只还原对话 | 不动 | 从该轮之前分叉新会话，原会话保留 |
| 全部还原 | 写回该轮开始前的内容 | 分叉新会话并切换过去 |
「从这里开分支」把文件恢复到该轮结束时的样子并开新会话，不删除原会话及之后轮次。手动改动的文件不计入插件历史，还原时会被快照覆盖。
插件不做代码审查，也不替代 git。实现上借鉴 VS Code 侧栏「时间线」的思路，单位从「一次保存」换成「一轮对话」，并可在对话内连对话一起回退。
安装与启用¶
需要 DSH 0.1.x（package.json 中 engines.dsh 为 ^0.1.5）、Node.js ≥ 20、git ≥ 2.20。git 不在 PATH 时可通过配置 gitPath 或环境变量 DSH_FILE_HISTORY_GIT 指定绝对路径；找不到 git 时不阻断对话，卡片上会提示不可用。
安装（Web profile）：
dsh plugin --profile web add dsh-file-history
装完后重启 DSH。卸载：
dsh plugin --profile web remove dsh-file-history
配置写在 profile 的 cordis.patch.yml，也可在 设置 → 插件 → 文件历史 中修改，下一轮生效，无需重启。示例字段见仓库 config.example.yml：
- insert:
- id: file-history
name: 'dsh-file-history'
config:
gitPath: ''
excludes: []
maxFileBytes: 5242880
maxEntries: 100
pruneAfterCheckpoints: 2
keepRecentTurns: 20
maxDirFiles: 20000
maxRepoFiles: 20000
maxBytes: 2147483648
默认排除 node_modules、.git、dist、build、.venv 等，单文件超过 5 MB 不记；工作区内嵌 git 仓库按文件记录并沿用该仓库的忽略规则。
典型用法¶
- 安装并重启 DSH，在侧栏打开「文件历史」（面板不会自动弹出）。
- 与智能体正常对话；某轮若改动了工作区文件，在该回复下方查看变更卡片，点文件名核对 diff。
- 改错时按需点「只还原文件」「只还原对话」或「全部还原」；需要保留当前会话又试另一条路时，用「从这里开分支」。
- 在满意状态点「设为检查点」；之后输入框上方会持续对比检查点，可随时「还原到检查点」。
- 在时间线中跳到任意轮次或检查点查看详情；父分支只读轮次需通过改动条上的卡片切到对应分支再操作。
适用场景与注意¶
适合在 DSH 里频繁让智能体改同一工作区、又希望按「轮」回滚且尽量不碰项目 git 历史的开发者。也适合没有初始化 git 的临时目录。
使用前请注意：
- 插件以当前 DSH 进程权限读写工作区与
~/.dsh/file-history/；安装前建议查看 GitHub 源码 与 MIT 许可证。 - 只跟随会话工作目录，不跨盘扫描；符号链接按普通文件处理；安装前的改动不在历史中。
- 手动删除
file-history/下数据后历史无法找回；这不是永不丢失的归档工具。 - 与
dsh-better-sidebar的「本轮产出文件」共用位置，同时安装时以本插件卡片为准。
已知限制与数据策略以仓库 README「已知限制」「数据」两节为准。
结尾¶
dsh-file-history 把 DSH 工作区的变更粒度对齐到「每一轮对话」，在对话内完成查看 diff、还原文件或分叉会话，历史与项目 git 解耦。当前版本为 0.2.4（见仓库 package.json）。
- SkillHub 目录页：https://www.skillhub.cn/plugins/EmptyVessel-000/dsh-file-history
- 源码与文档：https://github.com/EmptyVessel-000/dsh-file-history
社区插件目录由 SkillHub 等站点维护，与 DeepSeek / 幻方无官方从属关系；DSH 本身遵循「一切皆插件」的扩展方式，可按需从目录选用并自行审阅源码。
