Introduction¶

After splitting tasks into subagents in DSH, two issues often arise: First, subagents run in the background, and the main session cannot see when they start, end, or what step they are on. Second, for fixed tasks like code review or translation that should always use a specific model and prompt set, you have to manually construct the prompt during every delegation.

Existing community plugins each solve half the problem: dsh-subagent-monitor provides a real-time monitoring panel but doesn’t handle roles or routing; dsh-plugin-subagent-director provides role delegation, but roles can only be defined in settings. This article introduces dsh-subagent-pro, which merges these two lines into one plugin and adds Claude Code-style .dsh/agents/*.md role definitions, allowing roles to be managed as files within the project.

The following sections introduce the features, installation, and typical usage in order.

What is it¶

dsh-subagent-pro is a DeepSeek Harness Web extension plugin maintained by hyperion2144, current version 0.1.0, MIT licensed. One-sentence positioning: Real-time subagent monitoring + Role routing delegation + Agent MD role injection.

It follows a zero-intrusion principle: when no roles or default models are configured, its behavior is identical to when the plugin is not installed. Therefore, you can install it first and only use the monitoring panel, then gradually add roles later.

Core Features¶

Real-time Subagent Panel¶

The plugin listens to subagent/start and subagent/end events, attributing them to the root session via the parent chain, keeping a maximum of 200 entries per root session. The browser polls the snapshot endpoint /api/dsh-subagent-pro/snapshot every 1 second, with state points aligned to the official StateDot specification.

HUD-style Icon Button¶

After loading, the plugin injects a 28×28 linear SVG icon button in the left side of the conversation input area (conversation.input.left slot). When there are running subagents, a warn-yellow badge displays the count in the top-right corner. Clicking the icon opens the monitoring panel.

Role Routing Delegation¶

The plugin registers the subagent_role tool. When parsing models and prompts, it uses a four-layer fallback: call > role > default > inherit. Upon hitting a role, persona and toolFilter are injected into SubagentStartRequest. There are three execution modes: foreground, one-shot background, and continuable background.

Model Introspection¶

The plugin registers the subagent_providers tool. The main agent can proactively query the list of providers, models, and reasoning-effort exposed by the current LLM service. This allows querying before delegating when unsure of available models, eliminating the need to hardcode model names. If the LLM service is unavailable, the tool returns an empty array instead of throwing an error.

Default Model Fallback¶

After configuring defaultProvider / defaultModel, all subagents that do not explicitly specify agentOptions—including built-in subagent / subagent_fork tools—will automatically apply the default model. If the specified provider does not exist, it silently falls back to the parent model.

Claude Code-style Agent MD¶

The plugin automatically scans two directories: ~/.dsh/agents/*.md (global) and <cwd>/.dsh/agents/*.md (project). Frontmatter fields are mapped to RoleTemplate, and the body text is injected as persona into the subagent. Role priority is project md > global md > settings.roles. When all three coexist, the main agent’s guidance will list them all.

Settings Panel and Hot Reload¶

The plugin exposes the Subagent Pro group in the settings panel via the settings.section slot: default delegation configuration and CRUD for settings roles. Roles defined in MD are read-only and labeled with their source (project-md / global-md). Changes to settings.yaml and the settings panel take effect immediately without restart; agent MD is rescanned when settings/change occurs.

Installation and Activation¶

The plugin has not been published to npm yet, so dsh plugin add dsh-subagent-pro (installing by package name) is currently unavailable. You need to install using the GitHub path and tie it to a tag:

dsh plugin --profile <name> add github:hyperion2144/dsh-subagent-pro#v0.1.0

Before the first installation, add an allowBuilds entry to pnpm-workspace.yaml in the target profile:

# ~/.dsh/profiles/<name>/pnpm-workspace.yaml (example; actual key depends on error message)
allowBuilds:
  "dsh-subagent-pro@https://codeload.github.com/hyperion2144/dsh-subagent-pro/tar.gz/<commit-sha>": true

After adding it, run the installation command again. Regarding builds: lib/ is not in the version repository, so the prepare hook builds automatically during installation and is triggered by github: / npm / tgz methods; if using link:./ to reference a local repository, the prepare hook will not execute, so you need to manually run pnpm build in the repository first.

The plugin is a single bundle entry (dsh-subagent-pro), automatically mounting the host half and client half; there is no need to manually write cordis.patch.yml. After mounting, an icon button appears on the left side of the input area, and the monitoring panel can be used.

If you need to override default configurations, override the main entry in the plugin manifest by id:

- id: dsh-subagent-pro
  name: dsh-subagent-pro
  config:
    subagentProvider: spawn
    toolName: subagent_role
    enableRunInBackground: true
    backgroundMode: one-shot
    maxDepth: 3
    applyDefaultRoute: true

Typical Usage¶

Define Roles using Agent MD¶

Write an MD file under <project>/.dsh/agents/ or ~/.dsh/agents/. The filename (without .md) is the role id and must be in kebab-case; description is required. For example, <project>/.dsh/agents/code-reviewer.md:

---
name: 代码审查员
description: 审查代码质量、安全、可维护性与测试覆盖
tools: Read Grep Glob
model: sonnet
---
你是严谨的代码审查员。先给结论再给证据，区分阻塞项与建议项；逐条指出问题并给出可操作的修改建议，语气客观直接，不吹捧也不刻薄。

After saving, the main agent automatically loads this role, and the body persona is injected into the subagent’s system prompt.

Define Roles using settings.roles¶

Suitable for quick debugging in the settings panel. Click ‘+ Add Role’ under the Subagent Pro group and fill in displayName / description / persona / provider / model / toolFilter; the corresponding settings.yaml configuration looks like:

subagent-pro:
  defaultProvider: opencode-go
  defaultModel: minimax-m2.7
  roles:
    translator:
      displayName: 翻译员
      description: 中英互译技术文档
      persona: 你是专业翻译...
      provider: deepseek-official
      model: deepseek-chat
      toolFilter:
        allow: [Read, Grep]

Delegation and Model Query¶

Once roles are ready, the main agent automatically sees the role list (injected via system prompt) and calls subagent_role during delegation:

subagent_role({ role: "code-reviewer", prompt: "审查 src/foo.ts" })
subagent_role({ role: "code-reviewer", model: "deepseek-chat", prompt: "..." })

The role can be the filename of the agent MD or the role id in settings.roles.

The main agent can also call subagent_providers at any time to query available routing:

subagent_providers({ action: "list_providers" })
subagent_providers({ action: "list_models", provider: "opencode-go" })
subagent_providers({ action: "list_reasoning_efforts", provider: "opencode-go", model: "deepseek-v4-flash" })

The three actions return lists of providers, models, and reasoning-effort respectively.

Relationship with Old Plugins¶

This plugin draws heavily on two open-source projects, with a dedicated Acknowledgments section in the README:

• dsh-subagent-monitor (@leetoners/dsh-ui-subagent-monitor v0.2.0): The event attribution, floating panel, HUD icon, and mounting method of the real-time panel all originate from this project.
• dsh-plugin-subagent-director (v0.2.1): The four-layer fallback of subagent_role, default model fallback, settings namespace, and role CRUD all originate from this project.

If migrating from the old plugins, note two points:

1. Data routing is different: The snapshot interface for this plugin is /api/dsh-subagent-pro/snapshot, while the old dsh-subagent-monitor is /api/subagent-monitor/snapshot. Monitoring scripts relying on the old route need to be updated synchronously.
2. The settings namespace has changed from subagent-director to subagent-pro. See ARCHITECTURE §3 in the repository for migration instructions.

Use Cases and Notes¶

Suitable for DSH users who need to monitor the status of multiple subagents simultaneously, bind fixed tasks like review or translation to specific models and personas, or want to define roles as files within a project. It also works if you only need monitoring and not routing: the zero-intrusion design guarantees that when no roles or default models are configured, it behaves exactly like an uninstalled plugin.

Note a few points before using:

1. The plugin runs with the permissions of the current DSH process. Please check the source code and license (MIT) before installing.
2. npm has not been published yet, so installing by package name is unavailable. The key for allowBuilds contains the commit SHA, so you need to update it according to the error message after every plugin release.
3. Modifying the agent MD file itself will not trigger a host rescan. You need to save once in the settings panel (any field) or restart the DSH session where the plugin is mounted.

Conclusion¶

dsh-subagent-pro brings real-time subagent monitoring, role routing and default model fallback, and agent MD role definition into a single plugin, while maintaining the zero-intrusion baseline. If you frequently deal with subagents in DSH, it is worth a try.

• GitHub Repository: https://github.com/hyperion2144/dsh-subagent-pro
• Community Directory Page: https://www.skillhub.cn/plugins/hyperion2144/dsh-subagent-pro

Final Note: The Community Directory is an independent site and has no official affiliation with DeepSeek / Hypothesis.