dsh-web-files/packages/dsh-web-files

一句话定位

webdsh 是把 DeepSeek Harness 跑在浏览器里的纯静态发布版。本条目描述它自带的 Files 面板子包 @dsh-web/files:在 webdsh 侧栏加一个文件夹图标,唤起一个可直接浏览、上传、下载 workspace 文件的抽屉,并把"用户已经看到这个面板"这一事实告知 AI agent,让人和模型能在同一份文件上协作。

核心能力

• 浏览 workspace 文件并以面包屑导航:read / list / mkdir / remove / rename / archive 全部走同一个 __DSH_WEB_FILES__ 桥,跟 agent 命令跑的是同一份文件系统,不是平行的副本(client.tsx:34-46,53,139-158)。
• 上传:点击 Upload 选文件,或直接把本地文件拖进面板,松手落到当前目录(cwd),同名直接覆盖,完成后自动持久化到 IndexedDB(client.tsx:242-257,287-294)。
• 下载单文件或多目标:勾选后点 "Download N selected",单文件按原文件名走浏览器原生下载;多文件或目录被自动打成 zip 一次性下载,zip 名按所在目录 basename(client.tsx:223-240,322-326,379-388)。
• 文本预览:对判定为文本的文件做侧边预览面板;判定方式只看前 4 KB 有没有 NUL 字节,避免把 PNG 渲染成乱码;非文本文件直接提示下载,不假装能预览(client.tsx:92-95,161-177,402-404)。
• 聊天里的文件路径直接打开:监听 dsh-web:open-path 自定义事件,路径点开后自动打开面板并定位到对应目录/文件(client.tsx:587-591)。
• 删除与建目录:删除前用 globalThis.confirm 二次确认;New folder 走原生 prompt 取名,内部 __DSH_WEB_FILES__.mkdir 落到 host 侧(client.tsx:259-270,272-283)。

技术实现

• 语言: TypeScript + React (.tsx),运行在浏览器 webdsh 内
• 关键依赖: @deepseek-ai/cordis(ctx 与 plugin 生命周期);React 18 hooks(useState / useEffect / useCallback / useRef);宿主由 @deepseek-ai/dsh-client-runtime 与 @deepseek-ai/dsh-client-ui-layout 提供注入点 slots
• 架构模式: cordis bundle 子包。cordis.patch.yml 用 - insert 把 id: web-files、name: '@dsh-web/files' 写进 host profile 的 composition;package.json#dsh 用 bundle.patch 指向该 patch、client.inject 把浏览器入口喂给 dsh 的客户端加载器。分两半:src/index.ts 是 host 半区(只向 systemPrompt 注入一段说明),src/client.tsx 是 browser 半区(渲染侧栏按钮 + 抽屉面板,挂载到 sidebar.footer.action slot(order: -1,让它排在终端按钮之上)与 shell.overlay slot)
• 入口文件: packages/dsh-web-files/src/index.ts(host)、packages/dsh-web-files/src/client.tsx(browser)、packages/dsh-web-files/cordis.patch.yml、packages/dsh-web-files/package.json

适用场景

当用户通过浏览器跑 webdsh,想把本地素材(图片、数据集、文档)或从模型取回的产物进出 AI workspace 时,直接用这个面板就能在视觉上完成拖拽上传、批量下载、文本查看,不再需要打开第二个工具。同时它给 agent 多一条"文件面板就在你旁边,你需要文件时应让用户拖进去而不是你去 fetch"的指令,让多轮协作中的文件交接更顺畅。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:futrime/webdsh/packages/dsh-web-files

配置项

本插件无需额外配置——装上即在 webdsh 侧栏多一个"Files"按钮。

常见问题

Q: 安装后从哪里打开 Files 面板?

A: 在 webdsh 浏览器界面侧栏(终端按钮上方)有一个文件夹图标,点一下就在页面底部唤起一个高度自适应(Files 抽屉)再点一次或点 Close 即收起。

Q: 文件面板里的 workspace 跟 agent 用的是同一个吗?

A: 是同一个。面板所有读写都通过全局 __DSH_WEB_FILES__ 桥,由 src/host/bridges.ts 在 webdsh 启动时 publishFilesBridge(),read/write/list/mkdir/remove 直接落到 agent 命令跑的那个 filesystem——容器在走 WebContainer,容器没起来则回落到页面自带的 volume,所以 agent 在终端里刚写的文件,面板里 Refresh 一次就看见。

Q: 聊天里点开的文件路径会怎么样?

A: 路径点击经 host 统一的 host.openPath 走 dsh-web:open-path 自定义事件,本插件的 browser 半区监听后自动打开面板:点文件就在预览面板里显示,点目录就跳进该目录并刷新列表。无需手动导航。

Q: 我可以在线预览 PDF、图片、视频吗?

A: 不可以。面板预览只对启发式判定为"文本"的文件渲染到 <pre> 里(前 4 KB 内没有 NUL 字节就算文本),非文本就给一行提示"This file is not text. Download it to open it elsewhere.",二进制文件必须下载到本地用别的工具打开。

Q: 为什么不显示文件大小和修改时间?

A: 因为 webdsh 用的容器 filesystem API 没有 stat,仅列举 name 与 directory 两列;硬塞大小/时间列只会在容器挂掉、回退到 page volume 时出现"列有时有、有时没有",所以默认就是不显示。

Q: 下载多个文件或整个目录怎么操作?

A: 在列表条目前勾选需要的目标(有"Select everything here"的全选复选框),点工具栏的 "Download N selected":单文件直接走浏览器原生下载(原文件名),多文件或包含目录时打包成 zip 一次性下载,zip 名按所在目录的 basename。

Q: 我可以拖拽上传吗?会上传到哪?

A: 可以。把一个或多个文件拖到 Files 面板任意位置松手即上传,或点 Upload 走系统文件选择器;上传目标目录就是当前正在浏览的目录(cwd),同名文件直接覆盖,写完自动持久化,刷新不丢。

Q: 删除文件安全吗?

A: 删除走的是 __DSH_WEB_FILES__.remove,删除前会有一次 globalThis.confirm 二次确认,目录会附带"and everything in it"提示,防止误删整棵子树。

上手难度

入门——一键安装,侧栏多了个按钮即用,不需要任何额外配置或学习成本。

已知问题与限制

• 不显示文件大小和修改时间,因为容器侧文件系统 API 没有 stat(client.tsx:18-21,bridges.ts:368-371)。
• 不能在线预览 PDF、图片、视频等二进制文件,只能下载到本地查看(非文本就走"Download it to open it elsewhere"提示;client.tsx:402-404)。
• 整个面板以单个 workspace 为作用域,跨 workspace 切换需要刷新页面(webdsh 整体行为,不是本插件单独行为)。

DeepSeek Harness in a browser tab — the real agent, real Node, no server to run.

DeepSeek Harness (dsh) is an agent harness where everything is a plugin. dsh web runs a Node host and serves a browser client to it. webdsh is that, as static files — the host runs inside the page, and the agent's commands run in WebContainers: Node itself, in the tab.

• ⚡ Nothing to run. No server, no install, no local Node — the harness boots in the page.
• 🖥️ Real Node, real Python. npm install and pip install both work, and the terminal and the agent share one container.
• 💾 Or a whole PC. Switch the runtime to v86 and the session runs FreeDOS, Windows 1.01, Windows 3.1, Windows 98 or Linux — emulated x86, booted from a disk image, with the tool set that machine actually has.
• 🧩 Real plugins. Install from npm, a tarball, GitHub, or a path — from the browser.
• 📦 Real dsh. The published @deepseek-ai/* packages, unmodified: 114 of 129 rows compose exactly as dsh web composes them.
• 🔒 Yours. Files, sessions and keys live in your browser's storage. Nothing is uploaded.

Table of Contents

• Background
• Install
• Usage
• Maintainers
• Contributing
• License

Background

Nothing here is a fork of dsh. The agent loop, tool registry, model adapters and the entire web client come from npm at install time; the only modification is a cordis.patch.yml layer — the mechanism dsh documents for exactly this.

What this repository adds is the platform underneath: a synchronous POSIX filesystem mirrored to IndexedDB (src/vfs), node:* implemented over it (src/node), the two runtimes a session can run on — WebContainers and an emulated x86 PC (src/runtime) — an in-page virtual server for /api plus the CORS policy every outbound request goes through (src/net), and the plugins this build ships (packages/).

Six composition rows are swapped, each because the shipped one names something a page cannot have — or, in the shell's case, cannot honestly describe. Four more are reconfigured rather than replaced, including the one that decides whether this deployment can open a path at all. npx tsx scripts/alignment.ts prints the whole difference.

Install

Nothing to install — open the page. To run it yourself:

npm ci
npm run build        # → dist/
node scripts/serve.mjs 4173

Node 22 or newer. dist/ is plain static files with relative URLs, so it works at a domain root, a project path, or a local directory.

Usage

Open the page, choose a workspace, start talking.

• Files — the sidebar action above the terminal. Browse the workspace, open a file, drop files in, and take things out: one file as itself, a directory or a tick-box selection as a zip. It is the same filesystem the agent and the terminal use, not a copy. A file path the assistant names in the chat opens here when you click it.
• Terminal — Ctrl+` or the sidebar action. It is Node in this tab, and the same machine the agent's tools run in. Closing it hides it; the session, its scrollback and its working directory are still there when you reopen.
• Python — python3 and pip are there for both of them. The first call fetches a 14 MB interpreter; after that it is stored, and packages installed with pip survive a reload. Write python3: jsh aliases python to it and loses the quoting on the way, so python -c "…" is a syntax error.
• Runtime — the sidebar action below the terminal. A session runs on one machine and this is where you pick it. The default is the Node container above; the alternative is an emulated 32-bit PC, and the panel is that PC's screen — live, with a working keyboard, showing what the assistant is doing. Five machines need no setup at all: Linux (busybox on a serial console, the shortest way here to a real POSIX shell), FreeDOS, MS-DOS 7, Windows 1.01 and KolibriOS. Eleven more boot exactly the same way but are not this deployment's to serve a disk for — Windows 2.03, 3.0, 3.1, 95, 98, ME, NT 4.0 and 2000, MS-DOS 6.22, Buildroot Linux, and Arch Linux, which is a 2022 kernel with bash, python3 and gcc and resumes from a saved machine in about two seconds. For those, open a disk image from your computer or point the panel at a host that has one. Nothing is downloaded until you choose a machine, and a change applies on the next load.
• Plugins — Settings → Plugins, or /plugin add <package> in the composer. Takes an npm name, a tarball URL, owner/repo#ref, or a path. The Installed tab turns one off or removes it; the composition is fixed at boot, so a change applies on the next reload and the panel says so.
• Models — 42 models across six routes are registered up front and need no account, so the page answers before it asks for anything. Settings → Models offers the rest of the provider catalog; typing a key is the whole of configuring one.
• Network — Settings → Network picks the CORS proxy, used only after a direct request has actually failed, and reported to you when it is.
• Persistence — workspace, sessions and transcripts survive a reload. window.dsh.exportFs() downloads a zip; window.dsh.reset() clears it all.

On an emulated machine the assistant is given different tools, because it is a different machine: sh on the Linux guest, dos on the DOS ones — both reading a real character stream, so a command's whole output comes back rather than the last 25 lines of it — and vm_screenshot, vm_screen, vm_key, vm_type, vm_mouse and vm_wait everywhere, which is the whole of the tool set on a guest that only draws pixels. There is no jsh, no Node and no Python in that session, and the guest's disk shares nothing with the workspace your file tools read. The panel and the tools say so.

Worth knowing: the container's shell is jsh, not bash, and it ships no git; python3 is CPython 3.14 compiled to WebAssembly, fetched on first use and kept afterwards, so it has pip but no compiler, no subprocesses and no sockets; and a host that refuses browsers is reachable only through the proxy, which does not extend to the container.

Maintainers

@futrime

Contributing

Issues and PRs welcome at futrime/webdsh. Commits follow Conventional Commits; npx tsc --noEmit and npx tsx scripts/e2e.ts should pass first.

License

Apache-2.0 © Zijian Zhang. The @deepseek-ai/* packages it composes are published by DeepSeek AI under their own terms.