dshcode/packages/bundle/web-app

一句话定位

DSH 浏览器端的开箱组合包，把 Web 服务、API 网关、浏览器插件名册、模型上下文提示以及默认浏览器唤起能力一次性装好，在终端里一行 dsh --profile web 就能拉起完整的网页版 DSH。

核心能力

一键拉起浏览器端 DSH：在 dsh --profile web 启动时挂载所有 Web 宿主行（HTTP 服务、API 网关、Session 投影缓存、本地存储），并提示访问地址
自动打开默认浏览器：服务端口就绪后调用系统默认浏览器打开 http://127.0.0.1:3080，无需手动复制链接
模型上下文提示：注册 app:web-surface 提示段落，告诉模型当前用户在使用本机 Web 界面以及更新约定
Bash 变量透出：在管理的 Shell 环境里暴露 DSH_WEB_URL 环境变量，方便脚本调用当前 Web 入口
可信主机白名单：通过 --trusted-host 多次传入为浏览器的 API 信任栅栏追加允许的主机或域名
社区插件托管：把 GenUI、Annotation、Web-UI 等可选社区产品作为浏览器插件统一收录，部署开关可在设置里管理

技术实现

语言: TypeScript (ESM)
关键依赖: @deepseek-ai/cordis、@deepseek-ai/dsh-host-webserver、@deepseek-ai/dsh-host-frontend-static、@deepseek-ai/dsh-app-boot、commander、open
架构模式: Cordis 函数插件 + Bundle Patch：src/index.ts 导出 name / inject / Config / apply 的函数插件形式；cordis.patch.yml 是一份叠加在 dsh-base 之上的补丁清单，逐条声明要插入或覆盖的宿主行
入口文件: src/index.ts（runtime glue 插件）、src/startup.ts（命令行参数解析）、cordis.patch.yml（宿主装配清单）

适用场景

刚装好 DSH 想要在浏览器里和模型对话的普通用户，跑 dsh --profile web 就够了。如果想从局域网手机或其他终端访问本机 Web 界面，再通过 --trusted-host 把对方主机名加进白名单。如果只想要纯命令行交互，可以选择 dsh-headless 组合包，本包对命令行不友好、必须配合 Web 端使用。

前置依赖与兼容性

依赖	最低版本	说明
DSH	未声明	该组合包未在自身 package.json 声明 dsh 版本要求
Node	>= 22.19.0	仓库根 package.json 声明 `^22.19.0 \|\| >=24.0.0`；本包使用 `node:child_process`、`node:os`、`node:url` 等 Node 内置模块
平台	跨平台	在 macOS / Windows / Linux 上都能工作；启动默认浏览器由 `open` 库统一处理，Windows 下额外等待 PowerShell 启动子进程退出码
原生模块	无	不依赖任何 napi / 原生编译模块；运行时只使用 Node 内置模块与纯 JS 依赖

安装方式

dsh plugin --profile web add github:whitelonng/dshcode/packages/bundle/web-app

配置项

配置	类型	说明	默认值
`openBrowser`	boolean	是否在服务就绪后自动打开默认浏览器；通过 SSH 远程启动时会被自动关闭	`true`
`printUrl`	boolean	是否在终端打印 `dsh web: http://...` 的访问行（含局域网地址）	`true`
`surfaceContext`	boolean	是否注册 `app:web-surface` 提示段落和 `DSH_WEB_URL` 环境变量；非交互式层可关闭	`true`
`trustedHosts`	string[]	通过 `--trusted-host` 传入的可信主机列表，会拼接到 API 信任栅栏	`[]`
`--host`	string	绑定的主机地址；明确拒绝 `0.0.0.0`（出于安全考虑）	未指定时回退 `127.0.0.1`
`--port`	number	监听端口；传 `0` 由系统分配空闲端口	未指定时回退 `3080`
`--no-open`	boolean	关闭启动后自动打开浏览器的行为	`--open`

常见问题

Q: 启动时控制台显示 frontend dist not built 该怎么处理？

A: 该组合包只把已经构建好的前端 dist 提供给浏览器，需要先在仓库根目录跑一次 pnpm run build 把前端产物生成出来，再启动 dsh --profile web。源码里没有从源码直接服务的兜底逻辑。

Q: 我想让同局域网手机访问 dsh web，要怎么配？

A: 默认绑定 127.0.0.1:3080，外部无法直连。该包刻意不支持 --host 0.0.0.0，需要在反向代理或隧道后面再用 --trusted-host http://your-proxy.local 把对端主机加进 API 信任白名单。

Q: 安装到 dsh 后需要做什么才能启用？

A: 该组合包属于 Web profile 层插件，安装后请用 dsh --profile web 启动 dsh；同名的 headless profile 不会挂载它，会回退到命令行交互。

Q: 想关掉每次启动都自动开浏览器的行为，有开关吗？

A: 有。启动时附加 --no-open 即可；远程 SSH 登录时插件也会自动跳过这一步，避免在服务器上弹出本地浏览器。

Q: 想卸载或停用这个组合包，该怎么做？

A: 该组合包属于 Web profile 层，移除整条 dsh --profile web 启动方式即可停用；若需替换为其他 Web 表面实现，在自己的 profile 补丁里覆盖 web-runtime 行即可，无需修改本包代码。

Q: 修改了前端代码为什么浏览器没自动刷新？

A: 客户端插件热更新通道默认空闲，仅当同时跑 pnpm run dev:web 监听客户端 bundle 重建时，无刷新重载才会生效；apps/web shell 与其他普通包改动需要重建产物后手动刷新页面。

上手难度

入门 — 一条命令即可使用，所有可调参数都有合理默认值，普通用户不需要读源码就能完成启动；要自定义托管主机或绑定端口时才需要看一眼启动参数。

已知问题与限制

前端 dist 必须先构建：组合包通过 require.resolve 定位已构建产物，未构建时会以错误形式拒绝启动，并提示执行 pnpm run build
局域网地址仅启动期采样：网卡变化后不会重新广播，启动时打印的 LAN URL 与信任栅栏始终保持一致
社区插件开关需要重启：Settings 页面只持久化期望状态，不会热插拔已挂载的外部插件；切换后重启 dsh 才生效
Web 共享 HMR 暂未开启：cordis.patch.yml 中 hmr 行被设为 disabled，源码注释标记待 reload 生命周期测试完成后重新启用（cordis.patch.yml:21）
不支持所有网络接口绑定：--host 0.0.0.0 会在命令行解析阶段被主动拒绝，CLI 暂未实现安全防护下的全接口暴露
临时工具调用模式开关：cordis.patch.yml 的 tools 行读取环境变量 DSH_TOOLS_MODE（native / code / both），待 Web UI 提供每会话选择后会移除该环境变量入口