yu2025-luo/dsh-file-panel

dsh-file-panel

CI License: MIT

面向 DeepSeek Harness（dsh Web 图形界面）的插件：实时追踪会话中 Agent 创建或下载到本地的文件与图片，并在右侧弹出面板中展示——类似 Codex 的文件查看器。

会话期间只要有文件或图片写入本地磁盘，面板就会自动在右侧弹出。每个文件条目支持：

- 👁 预览 — 图片直接内联显示；文本文件显示前 256 KB 内容；其他类型显示元信息。
- 📂 所在位置 — 在系统文件管理器中定位该文件（Windows 用 explorer.exe /select，macOS 用 open -R，Linux 用 xdg-open）。
- ↗ 打开 — 用系统默认程序打开文件（复用 Harness 内置的 host.openPath RPC）。
- 📋 复制路径 — 复制绝对路径到剪贴板。

面板底部还提供「打开工作目录」快捷入口。

English

截图

会话文件面板

右侧停靠的会话文件面板：每行可预览、打开、定位、复制路径；底部按钮打开会话工作目录。面板支持按住标题栏自由拖动，左边缘与底边可拖拽缩放，缩得过窄时自动出现滚动条。

安装

需要已安装 DeepSeek Harness 的 dsh 命令行（npm 包 @deepseek-ai/dsh）以及 pnpm。

从本地源码安装

cd dsh-file-panel
npm install          # 仅安装开发依赖 esbuild
npm run build        # 生成 lib/index.js 与 lib/client.js（已提交进仓库）

注册到 web 配置（link: 方式会实时跟踪你的源码目录）
dsh plugin --profile web add link:.

从 GitHub 安装

dsh plugin --profile web add github:yu2025-luo/dsh-file-panel

构建产物已随仓库提交，安装时无需执行任何构建脚本。

启用

重启 dsh web 服务（插件集合在重启时生效），然后刷新
http://127.0.0.1:3080。无需任何配置。

卸载：

dsh plugin --profile web remove dsh-file-panel

使用说明

| 操作 | 效果 |
| --- | --- |
| Agent 创建/下载文件 | 面板自动弹出（新文件带 新 徽标） |
| 单击条目 | 内联预览（图片 / 文本 / 元信息） |
| 悬停条目上的按钮 | 预览、打开、所在位置、复制路径 |
| 🔔 铃铛 | 开关「新文件自动弹出」 |
| – / × | 收起为右下角悬浮按钮（带新文件角标）或完全隐藏 |
| 底部「打开工作目录」 | 打开当前会话的工作目录 |

面板状态（打开/收起）与自动弹出偏好保存在 localStorage。自动弹出的
基线按会话计算：面板首次看到该会话时已存在的文件不会再次触发弹出。

工作原理

一个 npm 包包含两个半边，通过一条 loader 行（cordis.patch.yml → 行
file-panel）注册：

宿主半边 (src/index.js)                     浏览器半边 (src/client.jsx)
───────────────────────                     ─────────────────────────────
ctx.on('fs/observed')         ──┐
write/edit 等工具上报的        │            shell.overlay 插槽入口：
文件（精确、归属到会话）        │            右侧停靠的悬浮面板
按会话工作目录的递归             ├──▶ FileTracker（按会话维护文件列表、
fs.watch                         │     忽略规则、容量上限、访问栅栏）
（覆盖 curl、Invoke-WebRequest ─┘                │
等 shell 下载场景）                             ▼
RPC 通道 /file-panel
authority: 'loopback'
list · readText · readImage
reveal · describe
▲
│ 每 1.5 秒轮询
客户端：ctx.connection.rpc.call()
打开文件：内置 api.host.openPath

浏览器半边注册进官方 shell.overlay 插槽（附加式的整框悬浮层），通过
标准 useSessions 属性读取当前会话，并轮询插件自建的仅限本机的 RPC
通道。该通道用 ctx.connection.rpc.handle 注册——这是静态插件包官方
支持的 RPC 接口。

安全性

- /file-panel 通道以 authority: 'loopback' 注册，只有从
127.0.0.1 提供的页面才能调用。通过局域网访问（--trusted-host）时
面板会显示提示并保持不活动。
- 所有读取/定位接口只接受追踪器实际见过的绝对路径（工具写入或受监控
工作目录下的 watcher 事件），RPC 无法被当作任意读文件/定位的通用
能力滥用。

目录结构

src/
index.js      宿主半边：追踪器装配 + /file-panel RPC 端点
tracker.js    纯 Node 文件追踪器（fs/observed 接入、递归 watcher
防抖、忽略规则、容量上限、RPC 栅栏）
client.jsx    浏览器半边：右侧面板 UI（React、JSX）
build.mjs       两个半边的 esbuild 构建脚本
cordis.patch.yml  插入 loader 行的 bundle patch
tests/          node:test 单元测试 + 宿主半边冒烟测试
lib/            构建产物（已提交，安装时无需构建）

开发

npm install
npm run build   # 重新构建 lib/index.js 与 lib/client.js
npm test        # node --test

修改 src/client.jsx 后的快速迭代：

npm run build

然后强制刷新 GUI 页面（lib/client.js 以 cache-control: no-cache
提供；插件集合只在重启后变化，但 bundle 内容每次请求都会重新
计算哈希——见 dsh-client-modules）。重度开发 UI 时也可以在 harness
源码目录运行 pnpm run dev:web，在文件变化时自动重建客户端 bundle。

兼容性

基于 @deepseek-ai/dsh 0.1.0-rc.x 的公开接口构建：

- 宿主：ctx.connection.rpc.handle / ctx.on('fs/observed')
- 客户端：shell.overlay 插槽、useSessions 标准属性、
ctx.connection.rpc.call、ctx.locale

DeepSeek Harness 目前处于预发布阶段，这些接口可能变动。升级 dsh
后如果面板失效，请检查 package.json 中的版本声明并重新构建。

已知限制

- 递归 watcher 使用 fs.watch({ recursive: true })（需 Node ≥ 20）。
在不支持该能力的平台上，面板仍能追踪 Harness write/edit 工具
产生的全部文件，但 shell 侧下载可能漏报。
- 面板数据是进程内的：重启后从空开始（只记录实际观察到的文件，不
扫描历史会话）。
- 默认忽略 node_modules、.git 及临时文件噪音。
- 无桌面环境的 Linux 上 describe 返回 canReveal: false，隐藏
「所在位置」按钮。

发布到 GitHub / npm

1. 创建 GitHub 仓库并推送（本目录已是 git 仓库，且已打好 v0.1.4
标签）：

git remote add origin https://github.com/yu2025-luo/dsh-file-panel.git
git push -u origin main --tags

2. 在仓库页面的 About → ⚙ → Topics 中加上
dsh-plugin 主题，以及
deepseek-harness、dsh、deepseek、file-preview。加上主题后，
仓库会自动出现在公开的插件主题页面上。
3. 用户可用
dsh plugin --profile web add github:yu2025-luo/dsh-file-panel#v0.1.4
安装。
4. 也可以发布到 npm（npm publish），之后用
dsh plugin --profile web add dsh-file-panel 安装。

会从 dsh-plugin 主题自动聚合的社区目录：
Oh-My-DSH（每 8 小时自动同步）和
awesome-deepseek-harness
（PR 方式收录）。

发布前记得提升版本号并重新执行 npm run build。

许可证

MIT