Introduction

The philosophy of DSH (an agent development framework) is “Everything is a plugin.” dsh-plugin-desktop is the official companion plugin for DSH-desktop. The vanilla desktop client remains minimal; enhanced features are unlocked only after installing this plugin. It runs inside the dsh service process. On one hand, it exposes the internal state needed by the desktop client through stable HTTP endpoints, replacing previous hacky approaches that estimated usage by sniffing webRequest or unpacking files. On the other hand, it injects an enhanced in-page context menu and a “Pin Conversation” extension into the Web UI.

Core Features

This plugin provides the following main capabilities:

  • Desktop state exposure: Reads current session and usage data directly through HTTP endpoints.
  • Global quick input: Provides a unified sending channel for external programs to send prompts to DSH.
  • Web UI enhancement: Injects a full in-page context menu (session/workspace/content/link/input box) and a “Pin Conversation” feature into the Web UI.
  • Terminal bridging: Provides the /api/shell endpoint for PTY terminal interaction.

Installation

The official recommended installation method is via the command line:

dsh plugin add github:Quan-Robin/dsh-plugin-desktop

The DSH-desktop-for-Linux tray or settings page also provides a one-click “Install Companion Plugin” feature. To install it manually, copy the directory to $DSH_HOME/profiles/web/node_modules/dsh-plugin-desktop/ and register it in $DSH_HOME/profiles/web/cordis.patch.yml:

- insert:
    - id: dsh-plugin-desktop
      name: dsh-plugin-desktop
      inject:
        - webServer
        - apiProxy

Typical Usage

After installation, the desktop client continuously sniffs /api/session.* requests to stay synchronized. The following are usage examples of several core APIs:

  • Check the current session state:
    curl http://127.0.0.1:3080/api/state

A sample response includes `currentSessionId`, `turn` status, and so on.
  • Send global quick input:
    # POST /api/prompt { sessionId?, text }
    # sessionId 缺省用当前会话
  • Query usage data:
    curl http://127.0.0.1:3080/api/usage

It returns aggregated session usage information.
  • Set the current session:
    # POST /api/set-session { sessionId }
    # 用于桌面壳在 Web UI 切换会话时调用

Technical Details

  • Zero dependencies: The plugin itself does not depend on npm packages; the desktop client can install it directly by copying the directory.
  • Adaptation mechanism: The plugin API has not yet been documented. Interactions are concentrated in three ADAPTER functions in lib/index.js (EVENT_BUS_SHAPES, ROUTER_SHAPES, and PROMPT_SHAPES). To adapt to the actual dsh, you only need to modify these three lists.
  • Real-time synchronization: The desktop client continuously sniffs /api/session.* requests to ensure that current session changes caused by UI navigation are correctly synchronized.

Use Cases

This plugin is suitable for developers who need to deeply integrate DSH state management, build desktop-level quick input channels, or enhance the Web UI interaction experience.

References