dsh-file-tracker · 文件活动监视器

一个 DSH 双端插件：让 agent 动过的文件，你当场就能看见。

agent 说"我改好了"，到底改了哪几个文件？dsh-file-tracker 把每一轮里 write / edit / shell 调用碰过的路径抓出来，按「目录」和「时间线」两种视角摊开在 web GUI 里。不用翻日志，不用问它。

···  →  文件活动
        ┌──────────────────────────────┐
        │ 动过的目录 │ 时间线           │
        │ 📁 nvidia-driver/x64   2 次   │
        │    7za.exe          14:03:11 │
        │ 📁 src                  5 次   │
        │    client.js        14:05:02 │
        └──────────────────────────────┘

它做什么

宿主半边（Cordis host）监听 session/event 的 tool/call，把工具参数里的路径解析出来，按「会话 → 目录 → 文件」聚合，并逐行落盘。

识别方式	工具	置信度
精确参数解析	write edit read read_image move copy delete glob grep ops_glob ops_grep	1.0
命令串启发式	pwsh powershell shell bash sh cmd terminal	0.6（半透明徽章）

客户端半边在 web GUI 里挂一个面板，两个视图：

• 动过的目录 — 每个被碰过的目录一行，带改动次数、最近一次动的文件与时间；点开看该目录下的文件明细。
• 时间线 — 逐条事件倒序，失败的调用标红点；点开看工具名与 turn/step 号。

徽章含义：

写	改	读	看	移	删	壳
write	edit	read	glob/grep	move	delete	pwsh 等命令

右键跳转文件夹

在面板的任意一行上点右键，会弹出上下文菜单：

• 在文件夹中显示 — 文件条目：打开系统文件管理器并选中该文件；目录条目：直接打开该目录。
• 复制路径 — 把该条记录对应的绝对路径复制到剪贴板。

打开动作由宿主执行（POST /ft/open），客户端只上报事件的 fseq：

• 路径不由客户端指定。宿主从自己的事件簿里按 fseq 反查真实路径，客户端无法借此打开任意路径。
• 沿用与 DSH 官方相同的 Explorer 调用约定（file:// URI + 非 ASCII 还原 + 逗号/等号转义）。
• 文件若已被移动或删除，自动退回打开它所在的目录。
• 结果以轻提示反馈（成功 / 路径不存在 / 找不到系统文件管理器）。

需要系统 PATH 里存在 C:\Windows（explorer.exe 所在目录）。缺失时菜单会提示「找不到系统文件管理器」。

安装

前置：DSH Desktop，Node ≥ 22。

git clone https://github.com/Mys12word/dsh-file-tracker "$HOME\.dsh\plugins\dsh-file-tracker"
powershell -NoProfile -ExecutionPolicy Bypass -File "$HOME\.dsh\plugins\dsh-file-tracker\install-profile.ps1"

脚本只做三件事，都可手动完成：

1. 往 profile package.json 的 dependencies 写 "dsh-file-tracker": "link:<插件绝对路径>"
2. 往 dsh.profile.bundles 数组里加 dsh-file-tracker
3. 在 ~/.dsh/profiles/<profile>/node_modules/ 建 junction

完全退出并重启 DSH Desktop 后生效。 只刷新页面不够——bundle 列表在启动时读取。

数据面 API

同源 HTTP，loopback 信任栅栏：非 127.0.0.1 Host 或跨站 Origin 一律 403。

端点	说明
GET /ft/events?sessionId=<id>&after=<fseq>	增量拉事件，after 为游标
GET /ft/summary?sessionId=<id>	目录聚合视图
GET /ft/sessions	会话列表（含 cwd、标题）

数据文件

~/.dsh/file-tracker/events.jsonl — 追加式 JSONL，单行一条：

{"fseq":387,"sid":"session-…","cwd":"C:\\…","tool":"pwsh","turn":13,"step":1,"kind":"shell","file":"nvidia-driver/x64","dir":"nvidia-driver","conf":0.6}

超过 8 MB 自动截断，保留最近 1000 行。删掉整个 ~/.dsh/file-tracker/ 目录即可重置，不影响任何其他功能。

设计要点

• fail-open：每条事件的解析、每个客户端 DOM 副作用都包在 try/catch 里。插件自身出问题绝不打断宿主 turn，也绝不弄白你的界面。
• 壳类是启发式：它只回答"大概动了哪个目录"，别拿它当审计证据。要精确就让工具用 file_path 参数。
• 配色自持：不依赖宿主的语义令牌（那些令牌在浮层里对比度很低），面板自带 --ftt-* 调色板，按当前界面背景亮度自动选亮/暗，并用 MutationObserver 跟随主题切换。
• 零配置：没有设置项，装完就有。

已知限制

• 面板锚定当前对话的会话。从侧边栏其他会话行打开，看到的仍是当前会话的事件（v1 行为）。
• 目录/路径是从命令原文里抠出来的，所以注册表键（HKLM:\…）、URL 之类偶尔也会入列——那是 agent 敲过的字面串，不代表真的碰了文件系统。
• 只记录当前进程生命周期内新发生的事件，不回溯历史会话的事件流（历史 JSONL 仍在磁盘上）。

FAQ

「壳」是什么意思？ shell 类事件的缩写徽章——这次操作是执行命令，不是读写文件，所以它带的路径是启发式猜出来的（0.6 置信度，半透明显示）。

为什么面板里出现了 HKLM:\SYSTEM\…？ 同上：那是命令文本里的字面路径，被"壳类"启发式抓到了。它可能只是 Get-ItemProperty 在读注册表。

面板为什么不刷新？ 宿主侧 webServer 不可用时会退化为"只收集不路由"，重启后自动补齐。客户端每 1.2 s 轮询一次，失败退避到 4 s。

开发

node --check lib/index.js
node --check lib/client.js
node test/client.test.mjs    # 19 项断言
node test/host.test.mjs      # 24 项断言

客户端是 vanilla DOM（不引 React），打包契约：window.__ModuleLoader__.load({ id, factory }) 的 factory 返回值本身就是模块体，apply / inject 必须在顶层，文件以 return module.exports; 结尾。

License

MIT