Preface¶

When using agents in the DSH web interface, sessions, workspaces, presets, and configurations gradually accumulate. Common operational needs are quite specific: too many sessions require grouping and searching, accidental deletions need recovery, long messages need collapsing, historical messages need searching, presets and configurations need online editing, and scheduled tasks need reliable triggering.

dsh-toolbox-web is a toolbox plugin for dsh web, maintained by AbcdefgXW and licensed under MIT. It consolidates session management, recycle bin, subdirectory management, search, preset editing, configuration editing, archive management, scheduled heartbeat, and long message collapsing into a single plugin, reducing the cost of switching between multiple entry points.

What This Is¶

dsh-toolbox-web can be understood as a management toolbox for the DSH web side. It loads as a DSH plugin and requires Node.js ≥ 22.13 as its runtime environment.

Below, I’ll introduce its core capabilities, installation methods, typical usage, and limitations to be aware of before use.

Core Features¶

Session Management¶

Session management is the foundational part of the toolbox, covering the most common daily session operations:

• Delete sessions — the delete action moves them to the recycle bin.
• Copy sessions.
• Move sessions.
• Reset workspace root.
• Tag grouping.
• View session content.
• Truncation and editing capabilities in conversation management, disabled by default and requiring explicit enablement in settings.
• Automatic marking of empty sessions.

Here, “delete” does not mean direct physical deletion but moving items to the recycle bin.

Recycle Bin¶

The recycle bin retains deleted sessions or subdirectories. The default retention period is 30 days, during which you can:

• Restore.
• Permanently delete.
• View the content of deleted sessions.

If you only want to temporarily remove a session, the recycle bin provides space for secondary confirmation.

Subdirectory Management¶

You can maintain a directory structure under the workspace, supporting:

• Creating directories.
• Renaming directories.
• Deleting directories.
• Copying directories.
• Batch assigning sessions to a specified directory.

This is suitable for organizing sessions by project, topic, or workflow, avoiding overly flat session lists.

Search¶

Search capabilities are used to find text within session content. It prioritizes the official SQLite index and provides grouping and filtering on results:

• Group by visible sessions, archived sessions, recycle bin sessions, and sub-agent sessions.
• Filter by time range.
• View hit text previews.
• Click to jump to the corresponding location.
• Optional semantic search.

Note that search is disabled by default. When using custom search or semantic search, session extraction may be required; after use, a DSH service restart is needed to fully release memory.

Preset Editing¶

Agent preset files can be edited online within the toolbox.

This suits scenarios where you need to quickly adjust agent behavior, prompts, or preset parameters without manually modifying files in the file system.

Configuration Editing¶

dsh configuration files can be edited online within the toolbox. The configuration editing process includes YAML validation and atomic writes.

This is suitable for adjusting plugin switches, heartbeat configuration, recycle bin configuration, and other settings. However, you should still confirm the current configuration content before making changes.

Archive Management¶

Archive management handles official archived sessions, supporting:

• Viewing.
• Restoring.
• Deleting.

If sessions are moved to official archives, you can view and handle them here in one place.

Scheduled Heartbeat¶

The scheduled heartbeat allows DSH to execute tasks according to certain rules, such as inspections, reports, or periodic checks.

It supports two types of scheduling:

• Interval heartbeat: triggered at fixed minute intervals.
• Fixed-time scheduling: triggered at specified times daily, weekly, or monthly.

Targets can be set to:

• Main workspace root.
• Any session.
• WeChat, QQ, or Feishu IM channels.

Scheduling runs within the dsh backend process and does not require the web page to remain open. As long as the dsh service is running, the heartbeat configuration takes effect.

IM channel push is an optional capability that depends on dsh-msg-hub. If this service is not installed, related IM targets are unavailable, and the heartbeat can fall back to the main workspace root or a specified session.

Long Message Collapsing¶

Long message collapsing reduces the impact of overly long messages on the reading interface. Messages exceeding a threshold number of lines are automatically collapsed and can be expanded for full viewing by clicking. The default threshold is 15 lines and can be adjusted.

Session View Tab Collapse¶

Multiple view tabs usually appear above sessions. The toolbox provides one-click collapse and expand capability, collapsed by default, and remembers the current state.

If the top of the current session interface has many tabs, this feature reduces visual clutter.

Independent Sub-Agent Session Management¶

Sub-agent sessions are no longer mixed with regular sessions but are grouped by parent session for management. Supports:

• Viewing.
• Opening.
• Deleting (which sends them to the recycle bin).

This suits investigating multiple sub-agent sessions derived from a specific parent session.

Release Memory¶

The toolbox provides a release-memory operation to clear plugin caches and attempt to trigger GC.

It suits performing a proactive cleanup after long-running usage with increasing memory usage.

Installation and Enablement¶

Installation Using the dsh Command¶

Installing via dsh plugin is recommended. The following command installs from the GitHub repository:

dsh plugin --profile web add github:AbcdefgXW/dsh-toolbox-web

You can also install using the published npm package name:

dsh plugin --profile web add dsh-toolbox-web

dsh plugin add automatically mounts the registration lines bundled with the plugin. After installation, it is not recommended to manually modify cordis.patch.yml in the profile to insert this plugin again, as this may cause a duplicate loader entry id error and prevent startup.

Manual Installation¶

To manually install from the repository, run:

git clone https://github.com/AbcdefgXW/dsh-toolbox-web.git
cd dsh-toolbox-web
npm install --omit=dev

After installation, place the plugin into a plugin path loadable by dsh and restart dsh web.

Enabling the Plugin¶

After installation, follow these steps:

1. Restart dsh web.
2. Force-refresh the page in your browser using Ctrl+Shift+R.
3. Open the toolbox entry in the bottom-left corner.
4. Navigate to pages such as Sessions, Recycle Bin, Sub-agents, Subdirectories, Search, Presets, Configuration, or Archives.
5. Go to “Settings → Toolbox” to configure feature switches and the scheduled heartbeat.

Windows and macOS Environment Variables¶

When deploying on Windows or macOS, you need to set DSH_HOME and DSH_CHANNELS_CWD to point to the actual DSH data directory and workspace directory in use.

These two variables allow the plugin to locate the correct session, configuration, and workspace paths.

Uninstallation¶

You can uninstall using the dsh command:

dsh plugin --profile web remove dsh-toolbox-web

For manual uninstallation, remove dsh-toolbox-web from the package.json in the profile, delete related dependencies or symlinks, and remove plugin state data. Restart dsh web after uninstalling.

Typical Usage¶

Managing a Large Number of Sessions¶

If you already have many sessions, you can handle them as follows:

1. Enter the session management page.
2. Tag frequently used sessions.
3. Move irrelevant sessions to more appropriate directories.
4. Delete sessions that are no longer needed but may still be referenced, sending them to the recycle bin.
5. When restoration is needed, enter the recycle bin and choose restore.

Finding Historical Messages¶

When you are unsure which session contains a particular response:

1. Enter the search page.
2. Enter keywords.
3. Filter by visible sessions, archived sessions, recycle bin sessions, or sub-agent sessions.
4. Set a time range.
5. View hit text previews.
6. Click to jump to the corresponding session content.

If semantic search is enabled, you can also find sessions with similar content by relevance.

Modifying Presets or Configuration¶

When you need to adjust agent presets or dsh configuration:

1. Enter the preset editing page to modify agent preset files.
2. Or enter the configuration editing page to modify the dsh configuration file.
3. Confirm the YAML validation results before saving.
4. After saving, restart dsh as required for the configuration to fully take effect.

Configuring a Scheduled Heartbeat¶

If you need scheduled task triggers:

1. Go to “Settings → Toolbox → Scheduled Heartbeat”.
2. Enable the scheduled heartbeat switch.
3. Set the interval in minutes or fixed-time scheduling rules.
4. Fill in the prompt message.
5. Choose the target: main workspace root, any session, or an IM channel.
6. If pushing to WeChat, QQ, or Feishu, first install and configure dsh-msg-hub.

Notes on IM Channel Pushes¶

IM channel push is an optional capability that depends on dsh-msg-hub.

• WeChat uses the simulated web protocol, i.e., ilinkai. Frequent proactive messaging carries account risk-control risks, so a heartbeat interval of no less than 15 minutes is recommended.
• QQ’s official open platform requires applying for “proactive message permission” for proactive messages. If not enabled, pushes may fail silently.
• Feishu uses the official API, with relatively lower compliance risk.

If dsh-msg-hub is not installed, IM targets are unavailable, but heartbeats to the main workspace root and specified sessions will still work properly.

Applicable Scenarios and Notes¶

Suitable for the following scenarios:

• Maintaining multiple workspaces and a large number of sessions in dsh web.
• Needing the recycle bin, tags, and subdirectories to organize sessions.
• Needing to search historical session content.
• Needing to edit agent presets or dsh configuration online.
• Needing scheduled heartbeats for periodic tasks.
• Needing long message collapsing to reduce reading distractions.

Points to note before use:

• The plugin reads and writes DSH session, configuration, and related files, so it runs with the current dsh process permissions. Review the source code before installation and confirm that the MIT license meets your usage requirements.
• Deleting sessions defaults to moving them to the recycle bin, not immediate physical deletion.
• Truncation and editing in conversation management are disabled by default and require explicit enablement.
• After modifying session files, restart dsh for full effect.
• Search is disabled by default. After using custom search or semantic search, restart the DSH service to fully release memory.
• IM channel pushes depend on dsh-msg-hub; if not installed, they automatically fall back to non-IM targets.
• WeChat proactive push carries account risk-control risks; frequency control is recommended.
• QQ proactive messaging requires the corresponding permission; otherwise, it may fail silently.

Conclusion¶

The value of dsh-toolbox-web lies in consolidating common but scattered management actions on the DSH web side: sessions can be grouped, recycled, searched, and edited; presets and configurations can be modified online; long messages can be collapsed; and scheduled tasks can run continuously.

Repository address:

https://github.com/AbcdefgXW/dsh-toolbox-web