dsh-file-panel
 
面向 DeepSeek Harness（dsh Web 图形界面）的插件：实时追踪会话中 Agent 创建或下载到本地的文件与图片，并在右侧弹出面板中展示——类似 Codex 的文件查看器。
会话期间只要有文件或图片写入本地磁盘，面板就会自动在右侧弹出。每个文件条目支持：
- 👁 预览 — 图片直接内联显示；文本文件显示前 256 KB 内容；其他类型显示元信息。
- 📂 所在位置 — 在系统文件管理器中定位该文件（Windows 用
explorer.exe /select，macOS 用open -R，Linux 用xdg-open）。 - ↗ 打开 — 用系统默认程序打开文件（复用 Harness 内置的
host.openPathRPC）。 - 📋 复制路径 — 复制绝对路径到剪贴板。
面板底部还提供「打开工作目录」快捷入口。
截图
右侧停靠的会话文件面板：每行可预览、打开、定位、复制路径；底部按钮打开会话工作目录。面板支持按住标题栏自由拖动，左边缘与底边可拖拽缩放，缩得过窄时自动出现滚动条。
安装
需要已安装 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 标签）：
``sh 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](LICENSE)