Skip to main content

web-app/packages/bundle/web-app

14Stars0Forks0Issues0Watchers

A web interface for long tasks, showing key progress and allowing details to unfold when needed.

Categories▣ UI Enhancements
Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki

ⓘ This plugin is a sub-package of the ayuanwong/deepseek-harness-ux monorepo — stars and activity count the whole repository.

ayuanwongayuanwong
·ayuanwong/dsh-ux
Language
TypeScript
License
BSD-3-Clause
Branch
main
agent-harnessai-agentdeepseek-harnessdeveloper-toolsdshdsh-plugintypescriptweb-ui

Install

cmdweb profile
$ dsh plugin --profile web add @deepseek-ai/dsh-web-app

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin ayuanwong/deepseek-harness-ux/packages/bundle/web-app for me: review the repository at https://github.com/ayuanwong/dsh-ux first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

本文档对应 packages/bundle/web-app 子路径，是落地页 /plugins/{owner}/{repo} 中插件百科模块的内容来源。该目录是 DSH 主仓自带的 profile 组合包层（不是独立的 npm 插件），安装命令把它作为 web profile 的浏览器表层组合包加入。

一句话定位

@deepseek-ai/dsh-web-app 是 DSH 的浏览器表层组合包：在 dsh-base 之上叠加 Web 宿主、API 网关、本地存储、浏览器插件名录和 web-runtime 粘合插件，并承担 dsh --profile web 的命令行解析（--host / --port / --trusted-host），让你执行 dsh --profile web 就能在浏览器里打开 DSH 的网页界面。

核心能力

  • 提供 dsh --profile web 启动入口：解析 --host、--port、可重复的 --trusted-host 与 --help，端口在参数解析完成前不会绑定
  • 注册 Web 宿主行：webserver（默认 127.0.0.1:3080）、API 网关、workspace、投影缓存、JSONL/JSON 存储、会话统计、消息反馈、Web 标题生成
  • 注册浏览器端插件名录：连接（fetch/SSE）、模块加载、会话侧栏与各种 UI 子模块、设置面板、目标/计划/工具调用轨迹等 30+ 行客户端插件
  • 解析并提供构建好的前端 dist：通过 @deepseek-ai/dsh-web-frontend 的 exports 找到 dist/index.html，挂载静态资源回退位
  • 采样一次 LAN 信任快照并对外提供 webRuntime 服务：作为 API 网关浏览器信任栅栏的 trustedHosts 来源，bind 一次后再广播
  • 拼接面向模型的 GUI 提示词：在系统提示词中追加 app:web-surface 段，告诉模型「this page 指什么、如何更新、不要起替代服务器」；同时把 DSH_WEB_URL 注册到受管 bash 环境
  • 加载完成后打印 dsh web: http://127.0.0.1:<port> [LAN: http://<ip>:<port>] 行，作为 supervisor / 烟雾测试的 readiness 信号，并等待 Loader 树结算后再打印避免兄弟行失败时误报

技术实现

  • 语言: TypeScript（ESM，工作区 monorepo）
  • 关键依赖: @deepseek-ai/dsh-host-webserver（webserver 宿主）、@deepseek-ai/dsh-host-apiproxy（API 网关）、@deepseek-ai/dsh-host-frontend-static（静态资源回退位）、@deepseek-ai/dsh-web-frontend（dist 解析目标）、commander（命令行解析）；完整列表见 dependencies（约 60 个工作区包）
  • 架构模式: profile 组合包（patch bundle）—— 包内 cordis.patch.yml 通过 manifest 字段 dsh.bundle.patch 暴露给 profile 组合器，在 dsh-base 之上叠加 / 禁用 / 替换插件行；src/index.ts 与 src/startup.ts 是其自身作为运行时粘合插件（web-app / web-startup）的实现
  • 入口文件: src/index.ts（web-runtime 粘合插件）+ src/startup.ts（web-startup 命令行 Provider）+ cordis.patch.yml（实质 patch 载荷，428 行）+ src/invariant.ts（空实现，仅注册包名）

适用场景

给想要在浏览器里用 DSH、而不是在 TUI 或一次性命令里用 DSH 的用户：在 DSH 安装目录执行 dsh --profile web，即可在浏览器里得到与本地 TUI 等价但更易分享和截图的图形界面。它也适合需要把 DSH 暴露给同网段其他设备协作的人：加 --host 0.0.0.0 后 LAN 内其他机器用 --trusted-host 即可访问。

前置依赖与兼容性

依赖最低版本说明
DSH0.1.0-rc.6+同名工作区包 @deepseek-ai/cordis 与 @deepseek-ai/dsh-invariants 需在宿主中可用；本 bundle 依赖 dsh-base 作为底层 patch
Node>=22.19.0来自 monorepo 根 engines.node：^22.19.0 || >=24.0.0
平台macOS / Windows / Linuxpatch 跨平台；webserver、API 网关、LAN 信任采样均通过 node:os 的 networkInterfaces 跨平台实现
原生模块无该包本身无原生依赖；下层 @deepseek-ai/dsh-sandbox-local 在 Windows 上挂载 @deepseek-ai/dsh-sandbox-windows-acl，是组合行为而非本包声明

安装方式

dsh plugin --profile web add github:ayuanwong/deepseek-harness-ux/packages/bundle/web-app

配置项

本 bundle 在 cordis.patch.yml 中给宿主行写入默认 config，这是 profile 组合器读取的静态声明。下表只列出对普通用户可见、可由命令行 / 部署覆盖的入口；cordis.patch.yml 中对工具与会话类插件的细粒度默认值（如 web-presentation.maxInputBytes=8192、session-projection-cache.writeEveryEvents=200 等）不在用户层暴露。

入口类型说明默认值
--host <host>命令行参数webserver 绑定地址；传 0.0.0.0 可从同网段其他机器访问未传则用 127.0.0.1（patch 默认值）
--port <port>命令行参数webserver 监听端口；传 0 让操作系统随机分配空闲端口未传则用 3080（patch 默认值）
--trusted-host <authority...>命令行参数（可重复）追加到 API 网关浏览器信任栅栏的来源（host 或 host:port）；与 LAN 自动采样的 IP 字面量合并空数组
webRuntime.printUrlpatch 配置启动完成后是否打印 dsh web: ... URL 行；非交互式场景可关true
webRuntime.surfaceContextpatch 配置是否向模型注册 app:web-surface 提示词段和 DSH_WEB_URL bash 变量；非 GUI 一次性调用可关true
webRuntime.trustedHostspatch 配置来自 webStartup 的命令行 --trusted-host 列表，会拼到 LAN 采样之后空数组
tools.modepatch 配置（环境变量驱动）工具呈现模式：native（默认）、code、both；临时开关，等 Web UI 拥有按会话选择能力后下线process.env.DSH_TOOLS_MODE，未设置走 schema 默认（native）
session-query-sqlite.pathpatch 配置Web 内容搜索用 SQLite 索引路径':memory:'（进程内内存索引）
system-prompt.personapatch 配置默认 system personaYou are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.

常见问题

Q: 装上之后怎么打开网页界面？

A: 在 DSH 安装目录下执行 dsh --profile web。终端会打印一行 dsh web: http://127.0.0.1:3080（绑定全网卡时还会附 (LAN: http://<你的局域网IP>:3080)），浏览器访问这个地址就能进入 GUI。

Q: 端口被占用了怎么办？

A: 启动时加 --port 0 让操作系统随机分配空闲端口，或显式指定 --port 8080 换一个端口。绑定地址可以用 --host 0.0.0.0 让局域网或公网机器也能访问。

Q: 我从另一台机器访问这个 Web 界面，浏览器一直报 host 不被信任？

A: 那是 /api 网关的浏览器信任栅栏在拦请求（防 DNS rebinding）。启动时加 --trusted-host 你的主机名或IP:端口（可重复），或在部署的 patch 中把 connection.trustedHosts 扩展成包含你的来源。IP 字面量 host 不需要带端口也能通过。

Q: 终端只打印 dsh web: http://127.0.0.1:3080，没有 LAN 地址，怎么从别的设备访问？

A: 只有当你启动时用了 --host 0.0.0.0 才会额外打印 LAN 地址。lanAddresses 是启动时的网卡快照，bind 之后再变化也不会重广播；其他情况下只打印本机回环地址，需要让别的设备访问必须显式 bind 全网卡。

Q: 启动时报 frontend dist not built; run pnpm run build from the repository root first 怎么办？

A: 这意味着这个仓库 checkout 还没编译前端 dist。在仓库根目录执行 pnpm run build（包含 build:lib 与 build:web），等前端 dist 生成后再重新 dsh --profile web。本包没有源码直服务的回退路径，必须先构建。

Q: dsh-base 已经装过了，还要再装 web-app 吗？

A: 需要。base 是所有 profile 的公共地基，不带 Web 宿主行；web-app 是在 base 之上叠加 webserver、API 网关、存储、投影缓存、浏览器插件名录以及 web-runtime 粘合插件的那一层，缺了它 dsh --profile web 打不开。

Q: 能用 dsh --profile web --help 看启动参数吗？

A: 可以。--help 不会绑定端口也不会打印 URL，只列出 --host、--port、--trusted-host 与示例命令，命令行解析完成后即退出。

Q: 默认的 system persona 能换吗？

A: 能。在更上层 profile 的 cordis.patch.yml 用 id: system-prompt 整行覆盖 config.persona，或换用 Agent Preset 中的 system 字段；web-app 这一层只提供默认 You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.。

上手难度

入门 — 这是 profile 标准的浏览器表层。dsh --profile web 就能用，需要自定义时基本只需在命令行加 --port / --host / --trusted-host 或在 profile 层写几行 patch 覆盖默认 id。

已知问题与限制

  • 前端 dist 必须已构建：对 dist 的 require.resolve 在激活时会明确报错并给出构建提示；本包没有从源码直接服务的回退路径
  • lanAddresses 是启动期快照：启动后的网卡变化不会重新公告，打印的 LAN URL 始终与配置的信任栅栏一致——但反过来说，热插网卡的新地址不会被自动加入
  • 共享 HMR 暂时禁用：cordis.patch.yml 第 21 行留有 TODO: Re-enable shared HMR for Web after its reload lifecycle is tested.，当前 id: hmr 显式 disabled: true；客户端插件的无刷新重载需要 pnpm run dev:web watcher 运行才能生效，浏览器插件以外的所有变更（apps/web shell、纯 packages）必须重新构建相关 Web 产物再刷新页面
  • 工具模式开关是临时的：tools.mode 的 DSH_TOOLS_MODE 环境变量（native / code / both）是为 Web UI 按会话选择工具呈现能力而存在的临时配置钩子，等 UI 那边的能力落地后该环境变量会退役

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/ayuanwong/deepseek-harness-ux/packages/bundle/web-app)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory