# dshcode

> DSH 浏览器端一键启动组合包：搭建 Web 宿主、API 网关、浏览器插件名册、模型提示与自动开浏览器。

## Metadata

- Author: [@whitelonng](https://github.com/whitelonng)
- Repo: <https://github.com/whitelonng/dshcode.git>
- GitHub: [whitelonng/dshcode](https://github.com/whitelonng/dshcode)
- Stars: 90
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agent`, `deepseek`, `deepseekharness-plugin`, `dsh-plugin`, `harness`
- Forks: 8
- Open Issues: 0
- Last push: 2026-08-20T20:02:51.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## One-Line Positioning
An out-of-the-box bundle for DSH browser-side, featuring Web service, API gateway, browser plugin registry, model context prompts, and default browser launch capability all in one package. A single `dsh --profile web` command in the terminal pulls up the complete web-based DSH.

## Core Features
- **One-click browser-side DSH startup**: When starting with `dsh --profile web`, mounts all Web host entries (HTTP service, API gateway, Session projection cache, local storage) and displays the access address
- **Auto-open default browser**: After the service port is ready, calls the system default browser to open `http://127.0.0.1:3080`, no manual link copying needed
- **Model context prompts**: Registers `app:web-surface` prompt segment, telling the model the user is using the local Web interface and update conventions
- **Bash variable exposure**: Exposes `DSH_WEB_URL` environment variable in the managed Shell environment for script access to current Web entry
- **Trusted host whitelist**: Pass `--trusted-host` multiple times to add allowed hosts or domains to the browser's API trust fence
- **Community plugin hosting**: Treats optional community products like GenUI, Annotation, Web-UI as browser plugins, with deployment toggles manageable in Settings

## Technical Implementation
- **Language**: TypeScript (ESM)
- **Key dependencies**: `@deepseek-ai/cordis`, `@deepseek-ai/dsh-host-webserver`, `@deepseek-ai/dsh-host-frontend-static`, `@deepseek-ai/dsh-app-boot`, `commander`, `open`
- **Architecture pattern**: Cordis function plugin + Bundle Patch: `src/index.ts` exports function plugin format with `name` / `inject` / `Config` / `apply`; `cordis.patch.yml` is a patch list layered on top of dsh-base, declaring host entries to insert or override one by one
- **Entry files**: `src/index.ts` (runtime glue plugin), `src/startup.ts` (CLI argument parsing), `cordis.patch.yml` (host assembly manifest)

## Use Cases
Regular users who just installed DSH and want to chat with the model in the browser just need to run `dsh --profile web`. If you want to access the local Web interface from a LAN phone or other terminal, add the remote host to the whitelist via `--trusted-host`. If you only want pure CLI interaction, you can choose the `dsh-headless` bundle; this package is not CLI-friendly and must be used with the Web side.

## Prerequisites & Compatibility
| Dependency | Minimum Version | Description |
|---|---|---|
| DSH | Not declared | This bundle does not declare DSH version requirements in its own package.json |
| Node | >= 22.19.0 | Root package.json declares `^22.19.0 || >=24.0.0`; this package uses Node built-in modules like `node:child_process`, `node:os`, `node:url` |
| Platform | Cross-platform | Works on macOS / Windows / Linux; default browser launch is handled uniformly by the `open` library, with extra wait for PowerShell child process exit code on Windows |
| Native modules | None | Does not depend on any napi / native compiled modules; runtime only uses Node built-in modules and pure JS dependencies |

## Installation
```bash
dsh plugin --profile web add github:whitelonng/dshcode/packages/bundle/web-app
```

## Configuration Options
| Config | Type | Description | Default |
|---|---|---|---|
| `openBrowser` | boolean | Whether to auto-open default browser after service is ready; automatically disabled when starting remotely via SSH | `true` |
| `printUrl` | boolean | Whether to print access line like `dsh web: http://...` in terminal (including LAN address) | `true` |
| `surfaceContext` | boolean | Whether to register `app:web-surface` prompt segment and `DSH_WEB_URL` environment variable; can be disabled in non-interactive layers | `true` |
| `trustedHosts` | string[] | Trusted host list passed via `--trusted-host`, concatenated to the API trust fence | `[]` |
| `--host` | string | Bind address; explicitly rejects `0.0.0.0` (for security reasons) | Falls back to `127.0.0.1` when not specified |
| `--port` | number | Listening port; `0` lets the system assign a free port | Falls back to `3080` when not specified |
| `--no-open` | boolean | Disable auto-open browser behavior after startup | `--open` |

## FAQ
**Q: Console shows `frontend dist not built` at startup, how to handle?**

A: This bundle only serves pre-built frontend dist to the browser. You need to run `pnpm run build` in the repository root first to generate the frontend artifacts, then start `dsh --profile web`. There is no fallback logic to serve directly from source code.

**Q: I want my LAN phone to access dsh web, how to configure?**

A: Default binds to `127.0.0.1:3080`, external cannot connect directly. This package deliberately does not support `--host 0.0.0.0`. You need to use a reverse proxy or tunnel, then add the peer host to the API trust whitelist via `--trusted-host http://your-proxy.local`.

**Q: What do I need to do after installing to dsh to enable it?**

A: This bundle is a Web profile layer plugin. Please start dsh with `dsh --profile web` after installation; the headless profile with the same name will not mount it and will fall back to CLI interaction.

**Q: Is there a switch to disable auto-opening browser on every startup?**

A: Yes. Simply add `--no-open` at startup; the plugin also automatically skips this step during remote SSH login to avoid popping up a local browser on the server.

**Q: How to uninstall or disable this bundle?**

A: This bundle belongs to the Web profile layer. Removing the entire `dsh --profile web` startup method disables it; to replace with another Web surface implementation, override the `web-runtime` line in your own profile patch without modifying this package's code.

**Q: Why doesn't the browser auto-refresh after I modify frontend code?**

A: The client plugin HMR channel is idle by default. Hot reload only takes effect when running `pnpm run dev:web` simultaneously to watch for client bundle rebuilds; changes to apps/web shell or other regular packages require rebuilding artifacts and manually refreshing the page.

## Difficulty Level
Beginner — works with a single command; all tunable parameters have reasonable defaults; ordinary users can complete startup without reading source code. You only need to glance at startup parameters when you need to customize the hosting host or binding port.

## Known Issues & Limitations
- **Frontend dist must be built first**: The bundle locates pre-built artifacts via `require.resolve`; unbuilt state refuses to start with an error, suggesting `pnpm run build`
- **LAN address sampled only at startup**: After network card changes, it won't rebroadcast; the printed LAN URL and trust fence remain consistent
- **Community plugin switches require restart**: Settings page only persists desired state, not hot-swapping mounted external plugins; restart dsh after switching for changes to take effect
- **Web shared HMR not yet enabled**: The `hmr` line in `cordis.patch.yml` is set to `disabled`, with source comments marking it to be re-enabled after reload lifecycle testing is complete (`cordis.patch.yml:21`)
- **Does not support binding to all network interfaces**: `--host 0.0.0.0` is actively rejected at CLI parsing stage; CLI has not yet implemented safe all-interface exposure
- **Temporary tools calling mode switch**: The `tools` line in `cordis.patch.yml` reads environment variable `DSH_TOOLS_MODE` (`native` / `code` / `both`); this environment variable entry will be removed after Web UI provides per-session selection

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dshcode](https://deepseek-plugin.org/plugins/whitelonng/dshcode/packages/bundle/web-app)
Wiki generated by AI (model: `MiniMax-M2.5`)