dsh-web-plugins/packages/dsh-web-plugins

一句话定位

给浏览器版 DSH（webdsh）加上"在网页里装插件"的能力：把原本要敲 dsh plugin add 的命令变成 /plugin 斜杠命令，并在设置页里多出两个标签页，让用户用表单也能安装、启用、停用、卸载插件。

核心能力

• 注册 /plugin 斜杠命令：在聊天 composer 里就能装、列、删、启、停插件
• 在「设置 → 插件」下注入两个标签页：「Add a plugin」用于安装，「Installed」用于管理
• 安装来源覆盖 npm 包名、tarball URL、owner/repo#ref 形式的 GitHub 仓库、本地文件系统路径，以及用户从自己电脑上传的 .tgz / .tar.gz 文件
• 在「Installed」标签页里直接开关、删除已安装的插件，每行显示版本、状态、是否带有浏览器侧面板
• 没有声明 cordis 组合层的纯依赖包会被识别出来，对应的 Enable 按钮自动置灰并说明原因

技术实现

• 语言: TypeScript（host 端）+ TypeScript + React（client 端）
• 关键依赖: @deepseek-ai/cordis（host 端上下文）、@deepseek-ai/dsh-commands（命令注册）、@deepseek-ai/dsh-client-runtime 与 @deepseek-ai/dsh-client-ui-settings（client 注入目标，由 dsh.client.inject 声明）
• 架构模式: Cordis 双面插件；host 端 src/index.ts 通过 apply(ctx) 把 plugin 命令注册进 ctx.commands；client 端 src/client.tsx 通过 apply(ctx) 调用 slots.inject('settings.plugins.tab', ...) 在设置侧栏挂载两个标签组件。安装器逻辑不归本插件所有，由宿主 app 通过 globalThis.__DSH_WEB_PLUGINS__（client 端）与 setPluginManager()（host 端）注入
• 入口文件: packages/dsh-web-plugins/src/index.ts（host 端）+ packages/dsh-web-plugins/src/client.tsx（client 端），由 package.json 的 exports 暴露为 . 与 ./client

适用场景

所有在 webdsh 浏览器版 DSH 上想自己加装第三方插件、又不想打开终端敲 dsh plugin add 的人——既能在聊天框里用 /plugin 走命令，也能在设置页里点几下完成安装、启停与卸载。

前置依赖与兼容性

安装方式

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

配置项

本插件无需额外配置。安装源（npm 名 / tarball / 仓库 / 路径 / 本地文件）由用户在使用时填入，不是 schema 字段；插件管理器本身由宿主 webdsh 注入（globalThis.__DSH_WEB_PLUGINS__ 与 setPluginManager()），用户不需要手动设置。

常见问题

Q: 安装 / 启用 / 卸载后要立即生效吗？

A: 不需要任何额外步骤，但页面要刷新一次。插件组合在启动时固定——「Add a plugin」和「Installed」两个标签页每次变更都会提示「Reload to apply — composition is fixed at boot」，点页面上的「Reload now」按钮或手动刷新即可。

Q: 启用按钮是灰的、点不动怎么办？

A: 该包没有声明 cordis.patch.yml（组合层），属于纯依赖——src/client.tsx 的 Enable 按钮在这种情形下被永久 disabled，并显示 tooltip "This package adds no rows to the composition."。它没法给组合增加任何行，所以没有开关可开。

Q: 可以从本地 .tgz 文件安装吗？

A: 可以。Settings → 插件 → Add a plugin 标签页里有「From file…」按钮，accept=".tgz,.tar.gz,application/gzip,application/x-gzip"；文件会先被 stage 到宿主虚拟文件系统，再走 install。

Q: 这个「Installed」标签页和「Plugin list」有什么关系？

A: 「Installed」只列出你用本插件安装的插件。构建时随 webdsh 一同发布的插件是构建期 composition 层，不在「Installed」里出现，也没法在那里关掉——它们在「Plugin configuration」和「Plugin list」里。

Q: /plugin 命令和设置页里的两个标签页是同一个东西吗？

A: 是的。src/index.ts 注册 /plugin 命令，src/client.tsx 注册两个标签页——同一插件的两个面：命令行面给聊天 composer 用，UI 面给设置页用。

Q: 这个插件只能在浏览器里用吗？

A: 是。packages/dsh-web-plugins/package.json 的 dsh.client.platform="web"，platform 不匹配的 profile 不会加载它。

Q: 安装时报 "The plugin manager is not ready yet." 怎么办？

A: 这是宿主还没把 PluginManager 注入到 setPluginManager() 时段报的——通常出现于启动早期。如果持续存在，说明你运行的 webdsh 构建没有装插件管理器，请检查 host 是否正常。

上手难度

入门 — 打开设置页 → 插件就能用，没有 schema 配置项，也不需要命令行知识。

已知问题与限制

• 组合在启动时固定：任何 install / enable / disable / remove 都要 reload 页面才会真正生效，源码与 UI 文案已明确提示（src/client.tsx:184-208、src/index.ts:90-100）
• Enable 按钮对没有 cordis 组合层的包被永久置灰，提示文案 "This package adds no rows to the composition." 不会自动消失（src/client.tsx:252-258）
• 仅 web profile 可用：dsh.client.platform="web"，在 cli / api 等其他 profile 下既不加载 host 端也不加载 client 端（packages/dsh-web-plugins/package.json:13-24）
• host 端 manager 是模块级单例变量（src/index.ts:33），需要宿主 app 主动调用 setPluginManager() 注入；若宿主忘了注入，/plugin 命令会一直返回 "The plugin manager is not ready yet."（src/index.ts:73-75）

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.