Introduction¶

The philosophy of DSH is “everything is a plugin”. The multi-agent collaboration initially did not have a unified role layer. The manual approach involves writing several subagent bundles in the host, configuring prompts, models, and tools for each, and then having the main agent spawn them on demand. The problem is that role definitions are scattered across various tool configurations; changing a model or prompt requires sifting through the config. There is also no unified role directory and execution history among components.

The plugin introduced below is dsh-agent-roles, maintained by the community author Delthin. It provides a “Multi-Agent” entry on the left side of DSH Web, allowing users to manage role templates via the interface (responsibility prompts, model and thinking intensity, tool whitelist, Skills). The main agent then creates members, distributes tasks, and continues conversations via the native Agent Team interface, without requiring a preset fixed workflow. This plugin works with DSH Web 0.2.1-rc.5 and above, current version 0.4.0.

Positioning¶

One sentence: This is a role management plugin providing a role directory interface for DeepSeek Harness Web, and creating members and continuing conversations based on DSH’s native Agent Team interface.

There are two core concepts in the plugin. Role is a reusable configuration template that saves responsibility prompts, model and thinking intensity, tool whitelist, and Skills. Member is the specific running instance started by the main agent based on a role. The main agent can see the responsibilities, models, and selected Skills of all enabled roles in the session, and determine whether to call spawn_role to create a member for the current task.

The repository page also provides migration instructions: future source code development and maintenance will move into the scoped package @delthin/dsh-agent-roles under the Delthin/dsh-plugins monorepo. The old repository is retained for viewing historical commits and early version records. Note that the current source code uses the Apache-2.0 license, and the MIT license granted to historical versions <= 0.4.0 will not be revoked. The author’s listing information in the community directory shows 0 stars, indicating it is an early project.

Environment and Installation¶

Before installing, confirm three things: Node.js 22.18+, DSH Web 0.2.1-rc.5 and above, and at least one configured model provider. The underlying Agent Team interface is still in the experimental phase.

Install v0.4.0 via GitHub Release archive:

dsh plugin --profile web add https://github.com/Delthin/dsh-agent-roles/releases/download/v0.4.0/dsh-agent-roles-0.4.0.tgz

If the corresponding version is already published on npm, you can also execute:

dsh plugin --profile web add dsh-agent-roles@0.4.0

Before installing, you can check npm availability first:

npm view dsh-agent-roles@0.4.0 version

The installation process does not require compilation, nor does it execute install scripts. After installation, refresh the DSH Web page, and the “Multi-Agent” entry will appear in the left navigation bar; if the host does not automatically load it, restart the corresponding Web profile. The plugin market listing is independent of the two installation methods above.

What the Installation Changes¶

The plugin bundle will enable DSH native team service, team tools, and interface, and disable the old tool-subagent, tool-subagent-fork, tool-subagent-control, tool-subagent-list-agents entries. The switching method is consistent with the official experimental team profile. If your current environment already has a custom team bundle, check if there are configuration overrides with the same ID.

The first installation results in an empty role directory, not containing the author’s roles, prompts, or run records; upgrading from an old version preserves local data.

Creating Roles¶

Start by creating a role. Open “Multi-Agent → Roles → New Role” on the left and fill in the following steps:

1. Fill in the display name, distribution name (lowercase letters, numbers, hyphens, e.g., reviewer), and responsibility description. The responsibility description is used by the main agent to decide when to use this role.
2. Select a model provider, specific model, and thinking intensity for this role.
3. In “Prompts”, clearly write down the role’s responsibilities, work boundaries, and delivery standards; in “Tools”, only check the whitelist of tools required by this role.
4. Search and check DSH discovered Skills in “Skills”. By default, it is empty and does not automatically inherit the global Skills directory.
5. Set the role to enabled and save.

Task Distribution and Collaboration¶

After a role is enabled, describe the task directly to the main agent in the main session. The example given in the README is: after configuring the read-only reviewer role reviewer, say to the main agent:

Please hand this change over to the reviewer for review, requiring them to point out grounded issues; you summarize the results and decide how to handle them.

There are several points worth noting about the running mechanism. The main agent starts a member via spawn_role({role, name, prompt}), which internally uses the native agentTeams.spawnTeammate. When a member starts, it saves a snapshot of the role prompt, model settings, and Skills content at that time; subsequent modifications or deletions of the role will not affect already created members. Members start in a completely new, independent session and do not inherit the main agent’s context history, so task background and materials must be written in prompt. When follow-up questions are needed, the main agent can use the native send_message to continue communicating with the same member instance.

The member’s tool whitelist does not include recursive delegation tools, and members cannot actively communicate with each other. Task breakdown, result summarization, and cross-member coordination are all handled by the main agent, relying on the interface group list_agents, send_message, interrupt_agent, wait_agent. Here, list_agents queries the currently created member instances, not the role directory.

A member status showing inactive only means there are no currently executing rounds, which does not represent successful task completion. Conclusions and errors must be checked in the member’s output content. In the “Request Details” recorded by the member, the plugin records the actual model, thinking intensity, and tool list sent, and verifies if the DSH base system prompt, role prompt original text, and selected Skills content are fully loaded. The model field in DSH 0.2.1-rc.5 native member list may retain the parent session description, but the actual routing takes precedence over the “Request Details”.

Loading Skills and Communication Costs¶

Newly created and existing roles default to skills: []. After checking Skills, the plugin reads the content through DSH’s native Skills service when starting a member, and fully injects the new member’s system prompt in the native <skill_content> format (including resource base directory and literal body). Even if a role does not check any tools, it can still receive instructions from the selected Skills.

Two points need attention. Skills only provide text instructions and do not automatically grant tool permissions; external commands or software that skills depend on still need to be configured separately in the host and tool whitelist. If the selected skill is unavailable at startup, the member startup fails directly and reports the missing skill name; retry is possible after restoring or unchecking.

Regarding communication costs, the full body of checked Skills is counted as part of the member session input, so it is recommended to only check necessary Skills for a role. Simple and direct tasks can be completed directly by the main agent without needing to split into multi-agent collaboration.

Data Storage and Configuration¶

The default data directory is $DSH_HOME/agent-roles, and if DSH_HOME is not set, it is ~/.dsh/agent-roles. There are two files in the directory: roles.json saves the role directory, structure version number, and directory revision number; runs.json saves member startup snapshots, selected Skills body, request load verification results, and the latest output summary (up to 30,000 characters). The full conversation history is still saved by DSH’s native session storage.

To change the current profile’s cordis.patch.yml:

- id: agent-roles
  config:
    dataDir: ~/my-dsh-data/agent-roles
    fastProviders: []

dataDir supports absolute paths, ~, and paths relative to the current process working directory; using an absolute path is recommended. The current file storage does not provide cross-process write locks; multiple independently running DSH processes should be configured with different dataDir.

The public package defaults to fastProviders: [], and the Fast button next to the model selector cannot be enabled. The plugin only records the Fast/Standard mode selection and does not have a built-in specific vendor priority transmission implementation; only when the corresponding transmission adapter is installed in the environment and can read the role startup snapshot will the vendor ID be added to fastProviders. Enabling priority transmission may change billing standards on the provider side.

Restrict Models the Main Agent Can Delegate To¶

In “Multi-Agent → Settings”, you can add rules: select the main agent model, check the prohibited sub-agent models, and save; it takes effect immediately. The model options come from the DSH configured directory, with no rules by default. You can also use the generic delegationRules. Below is a README example ID, replace it with your own model ID:

- id: agent-roles
  config:
    delegationRules:
      - leaderModel: lead-model-id
        denyModels:
          - blocked-member-model-id

Model IDs match exactly and do not distinguish providers. The policy executes based on the main agent’s current request model, changing with the next round after switching models. The role directory will hide prohibited roles, and tool calls are rejected before startup. The restricted main agent must use spawn_role, and generic delegation tools will also be intercepted; sending messages to existing members with prohibited models is also rejected. Already running members will not be automatically interrupted.

Runtime Limits and Security Boundaries¶

• A single team has a maximum of 32 created members and 256 shared tasks. Concurrency and delegation depth are constrained by DSH’s native subagent configuration; if the host sets delegation depth to 0, you must first allow delegation in the host configuration. The plugin does not overstep to modify global quotas or system permissions.
• The plugin mounts model routing, system prompts, and tool whitelist guards via the native agent/created hook before the member’s first request is sent, and does not take over or replace DSH’s native model execution loop. The role management API reuses DSH Web connection service authentication and rejects unauthenticated requests.
• The role tool whitelist only constrains the set of tools the model can call; it is not an operating system-level file or directory sandbox. Specific file read/write and command execution are still controlled by DSH global permissions and file policies. The plugin code runs under the host process permissions; please do not expose the same logged-in DSH Web session to untrusted users.
• Member snapshots in runs.json contain prompts, full Skills text, and output summaries; protect them as private sensitive data when backing up. Uninstalling the plugin will not delete the data directory, and deleting a role will not clean up generated run records. Run records currently do not expire automatically, and the list API defaults to returning the most recent 200.

Applicable Scenarios and Notes¶

Suitable for developers and small teams who need to manage multiple collaborative roles with different model and tool combinations in DSH Web (e.g., one role each for review, retrieval, code generation), and who want the main agent to decide on-demand who to call. After the role directory is maintained centrally, changing prompts, switching models, and adding skills can be done in the interface without editing bundles one by one.

It is recommended to read the source code and license before installing. The plugin runs with the current DSH process permissions, will disable old subagent tool entries, and will inject Skills body into the system prompt when role members start; please evaluate based on your own permissions and file policies. Also pay attention to the repository migration status: future maintenance will be in Delthin/dsh-plugins, and the old repository will not accept new development.

Summary¶

The value of dsh-agent-roles lies in turning “roles” into maintainable configuration templates and reusing DSH’s native Agent Team interface: roles manage responsibilities and models, members are running instances created on demand, and coordination is still centrally handled by the main agent. For those who want to do multi-agent division of labor in the Web interface, it reduces repetitive work compared to manually configuring subagents.

• Community Directory Page: https://www.skillhub.cn/plugins/Delthin/dsh-agent-roles
• GitHub: https://github.com/Delthin/dsh-agent-roles