English ｜ 简体中文

dsh-file-explorer-kit

GitHub：https://github.com/ice5kysl/dsh-file-explorer-kit ｜ MIT License ｜ 目标 dsh：@deepseek-ai/dsh ≥ 0.1.1-rc.2

按官方规范编写的 dsh（DeepSeek Harness）插件（bundle 形态），解决一个痛点：

工作区里放了很多文件，每次想看一眼目录结构或某个文件内容，都要切到 Finder / 资源管理器——很麻烦。

本插件让你直接在会话里浏览工作区目录并预览文件，不必离开 dsh Web：

• 会话第三个 tab「文件」（对话 | 轨迹 | 文件）：注册进官方 conversation.view 视图环，排在 chat（order 0）与 trajectory（order 10）之后（order 20），tab 条自动出现； 标签文案跟随界面语言（文件 / Files）；
• 以当前会话的工作区目录为根打开；目录面包屑 + 目录/文件列表（目录优先、 大小/时间、隐藏点文件开关）、任意绝对路径跳转；
• 打开期间自动刷新（agent 在后台写文件也能看到）；切走再切回按会话记忆上次目录；
• 中英双语界面：按浏览器语言自动检测（zh → 中文，其它 → English），顶栏 「中 / EN」按钮随时切换并记住偏好；
• 右侧预览：Markdown 默认渲染（预览 / Raw 一键切换；渲染前经 marked 解析 + DOMPurify 消毒，防仓库内恶意 md 的 XSS，预览内链接一律新标签打开）、图片内联显示、 其他文本带行号（超长截断并提示）、PDF 内嵌、二进制文件提供「复制路径 / 在文件管理器中打开」（走官方 ctx.workspaces.openPath）；
• 目录/文件数据全部走宿主侧 /dsh-files 只读接口，插件不修改任何文件。

为什么需要宿主侧路由（设计说明，均依据官方文档/源码）

官方浏览器契约里只有目录级浏览（ctx.workspaces.listDirectory → host.listDirectory， DirectoryListing.entries 只含目录行），没有文件行，也没有任何读取文件内容的 RPC； dsh-workspace-kit 里核查过的「client 只能消费构建期生成的 ctx.remote.*」结论同样成立。 因此要预览任意工作区文件，只能走官方 ctx.webServer.register 路由接缝（ dsh-host-webserver：WebRoute { kind, path, handler }，named prefix 优先于 fallback）：

| 端点（GET） | 说明 | |---|---| | /dsh-files/home | 宿主账户主目录 | | /dsh-files/list?path=<abs> | 单层目录：文件+目录行（kind/size/mtimeMs/hidden）+ 面包屑，镜像官方 DirectoryListing 语义（缺 path = 主目录） | | /dsh-files/text?path=&maxBytes= | 文本预览头（utf-8 解码、NUL 嗅探判二进制、截断标记；服务端 300 KB 上限） | | /dsh-files/raw?path= | 原字节流（按扩展名猜 Content-Type，供 <img>/PDF 内嵌） |

• 只读、无写端点；客户端从不自行拼接路径（所有 path 都来自服务端响应或框架 提供的工作区/会话路径）。
• 每个请求过一道 host-trust 闸门，镜像官方 /api 信任围栏的姿势： loopback Host 直通；非 loopback 需要同源 Origin 标记。不是认证层——与官方 web server 一致（默认绑 127.0.0.1；部署时保持 loopback 绑定）。
• 路由在插件 apply 里经 ctx.effect(() => ctx.webServer.register(...)) 注册，随插件 fiber 卸载自动释放。

更多细节——完整路由契约、错误形态与权限/安全边界：docs/usage.zh-CN.md（English: docs/usage.md）。

快速安装（本机个人 dsh）

已发布到 npm —— 如果你已在本机跑 dsh Web，一行即可安装：

dsh plugin --profile web add dsh-file-explorer-kit

下面的 git 方式用于开发 / 尝鲜最新源码。

前置：dsh 在 PATH（@deepseek-ai/dsh ≥ 0.1.1-rc.2），Node 20+。

# 0. 获取源码（或直接使用本地目录）
git clone https://github.com/ice5kysl/dsh-file-explorer-kit && cd dsh-file-explorer-kit

# 1. 构建（产出 lib/index.js + lib/client.js；npm install 的 prepare 钩子会自动构建）
npm install                # 安装构建期依赖（typescript/esbuild/@types/marked/dompurify/lucide-react 等）
npm run build

# 2. 安装进你的 web profile（等价于官方 dsh plugin add 组合包）
bash scripts/install-personal.sh   # 脚本自动向上定位插件目录（仓库根直接运行即可）
#    脚本实际执行：dsh plugin --profile web add <本插件目录>
#    它会把这个包加入 ~/.dsh/profiles/web 的 dsh.profile.bundles（追加在
#    dsh-web-app 之后），包内 cordis.patch.yml 自动插入唯一 Loader 行。

# 3. 验证组合（无需重启）
dsh --profile web --dump-config | grep -n "file-explorer"

# 4. 重启 GUI 生效
#    退出当前 dsh web（Ctrl+C 或 kill 进程）后重新运行 dsh web；
#    浏览器刷新 http://127.0.0.1:3080

生效后：

• 打开任意会话，标题栏出现 对话 | 轨迹 | 文件 三个 tab；点「文件」即在正文区 浏览该会话工作区目录（目录行单击进入、文件行单击预览，↑↓/↵/⌫ 键盘可用）。
• 顶栏一行：面包屑 + 「显示隐藏 / 刷新 / 中EN」+ 绝对路径跳转框；预览面板可 「复制路径 / 在文件管理器中打开」。
• 切到别的会话再回来，「文件」tab 会记住该会话上次浏览的目录（仅内存，不跨刷新）。

与 dsh-workspace-kit 兼容：本插件只占用 conversation.view 的加法槽位（tab）， 不做任何替换式 shadow，两个插件可同时启用。

打包 / 分发（可选）

npm pack          # 产出 dsh-file-explorer-kit-0.3.1.tgz（含预构建 lib/，prepack 自动 build）
# 其他机器：dsh plugin --profile web add ./dsh-file-explorer-kit-0.3.1.tgz

npm 包名：dsh-file-explorer-kit —— npm 上的 dsh-file-explorer 属于另一个无关插件（joejojoking-cloud），安装请一律用 dsh plugin add dsh-file-explorer-kit，不要 dsh plugin add dsh-file-explorer。

开发

npm run typecheck   # tsc --noEmit（宿主 + 浏览器两侧源码）
npm run build       # esbuild：src/host → lib/index.js；src/client → lib/client.js
npm test            # 宿主 /dsh-files 端点独立冒烟测试

源码布局：

src/host/    宿主侧：fs-server.ts（纯目录扫描/文本读取函数）、index.ts（apply：
             ctx.effect 注册 /dsh-files 前缀路由 + host-trust 闸门）
src/client/  浏览器侧：FilesView.tsx（conversation.view tab 的文件浏览器）、
             browse-memory.ts（按会话记忆上次目录）、files-api.ts（/dsh-files
             fetch 客户端 + 类型）、actions.ts（openPath 绑定）、
             locale.ts（中/EN 检测与 L()）、icons.tsx（lucide SVG 行图标）、
             index.ts（apply：conversation.view 注册）
src/shared/  i18n.ts（纯 localize/normalizeLocale，host/client 共用）
cordis.patch.yml   bundle 层：插入唯一 Loader 入口 dsh-file-explorer-kit

兼容性 / 已知边界

• 目标 dsh：@deepseek-ai/dsh v0.1.1-rc.2（dsh web，profile web）。浏览器 face 面向该版本的 conversation.view 视图环契约（tab 由 entries 自动列出、body 按 only: <active id> 只渲染当前视图）与 ctx.workspaces.openPath；上游契约变更时需随版本校验。
• 「文件」tab 只出现在会话内（无会话的 hero 状态没有 tab）；这是会话级视图的固有边界。
• 样式为内联样式（浅色），未跟随系统主题——与 dsh-workspace-kit v1 相同的取舍。
• 安全边界：接口只读；/dsh-files 的信任姿势与官方一致（非认证层）。若部署在容器/ 代理后且 host 头不是 loopback，请保持 dsh web 服务 loopback 绑定或扩展 src/host/index.ts 的 trusted() 白名单。
• LoopDSH 平台每用户实例的接入方式与 dsh-workspace-kit 相同：参考 LoopDSH 仓库内 docs/plugins/loopdsh-integration.md 的「方案 A：harness 启动时幂等预置」。