dsh-roles-zeta
面向 DeepSeek Harness 的基于角色的子代理委派：通过一个委派工具管理角色文件夹，并提供可随时覆盖的内置角色列表
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:zeta987/dsh-roles-zeta#bbfa1eddf7e261906616b33efb72abd054a25908Roles Zeta 以 dsh-roles-zeta 发布，当前版本为 0.4.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
dsh-roles-zeta gives a dsh agent one delegate tool and a folder of role
files. A call names a role; the role file supplies the child's persona, model
route, reasoning effort, and tool surface. It sits on the same ctx.subagents
service the built-in subagent tool uses, so providers, delegation depth,
continuation, and background settlement keep working unchanged. The built-in
subagent and subagent_fork tools stay mounted: they let the model pick a
route per call, while a role is fixed when the file is written.
Around the tool sit three surfaces, each mounted only where its host service exists: one slash command per role in the Web input box, a Role agents page in the Web settings, and a watcher on the role directory so an edit reaches the next call without recomposing the profile.
dsh plugin --profile web add dsh-roles-zeta
# restart the host
Profiles are separate install roots, so install into each profile that should
have it. github:zeta987/dsh-roles-zeta and file:<path> specs work too. On
the first load the eight role files are written to $DSH_HOME/agents
($DSH_HOME defaults to ~/.dsh), and a new session has a delegate tool
whose description lists them.
~/.dsh/agents
├── code-mapper-lite.md explorer.md log-distiller.md triage.md
├── deep-coordinator.md hypothesis-debate.md reviewer.md worker.md
└── .seeded.json
Nothing updates on its own: dsh plugin forwards to pnpm inside the profile,
starting the host installs nothing, and no page checks a registry. To move to
a release:
dsh plugin --profile web add dsh-roles-zeta@0.4.0
# restart the host
Name the version. update stays inside the ^0.x range pnpm wrote at install
time, and pnpm 11+ hides a version published less than 24 hours ago from
outdated and @latest (minimumReleaseAge); an explicit version installs
right away. Role files you edited are left alone; shipped ones you never
touched are refreshed on the next load.
Every loaded role is a command in the Web input box. Type / to see them next
to /plan and /goal; /reviewer look at lib/index.js queues a turn asking
the agent to call delegate with role reviewer and that text as the task,
run it in the foreground, and relay the result. The delegation therefore stays
in the transcript as an ordinary tool call, where /plan <message> puts its
message too.
Commands follow the roster: adding, renaming, or removing a role re-registers
them and the menu refreshes. A role whose id collides with another plugin's
command is skipped as a command (logged) and still works through the tool.
commands: false mounts none; commandPrefix: "r-" gives /r-reviewer.
The Web input box with / typed: the roles listed as commands next to the built-in ones
Settings → Role agents lists the roster with a badge per role (shipped,
yours, edited) and edits one role at a time: id, the when line, the route
(with the session's allowed routes as suggestions), the effort, the tools as a
checklist of what is registered right now (or "inherit everything" plus the
delegation toggle), and the persona. Saving writes <id>.md into
$DSH_HOME/agents, the same file you would write by hand.
| Button | On disk |
|---|---|
| Delete, on a role you added | Removes the file |
| Delete, on a shipped role | Leaves a disabled: true stub so the packaged copy stops loading; listed under Disabled shipped roles until restored |
| Restore this role | Copies the shipped file back over yours |
| Restore the shipped roles | The same for all eight; roles you added are never touched |
The page is a browser module over JSON routes under /__dsh/roles-zeta/,
gated by the same browser-session cookie and Host/Origin fence as the rest of
the Web API. settingsPage: false mounts neither.
Settings → Role agents: the roster on top, the reviewer role open in the editor below
One Markdown file per role: frontmatter for the machine fields, body as the child's persona prefix.
---
id: reviewer
when: Deep read-only reviewer for correctness, regressions, edge cases, and missing tests.
route: deepseek-official/deepseek-flash
effort: high
allow: [read, glob, grep, web_search, web_fetch, skill]
---
Review like an owner.
Prioritize correctness, regressions, edge cases, and concurrency hazards.
| Field | Required | Meaning |
|---|---|---|
id | yes | Role id; the _ spelling resolves to the same role |
when | yes | One line; the model's menu entry and the command description |
route | no | A model id (deepseek-flash) or an exact provider/model |
effort | no | off/minimal/low/medium/high/xhigh/max, clamped per route |
allow | no | Tool names the child keeps; omitted inherits everything |
delegation | no | true keeps the delegation tools in a child without an allow list |
disabled | no | true removes a shipped role |
A role with an allow list can delegate only if the list names the delegation
tools; one without an allow list only with delegation: true.
Two roots, later winning: the package's own roles/*.md, then
$DSH_HOME/agents. The package seeds its roster into your directory on first
load and keeps it managed while you leave it alone:
| What you do | Next load |
|---|---|
| Nothing | Shipped files follow the package; a release that changes a role updates it |
| Edit one | It is yours and is never overwritten again |
| Delete one | It is not seeded again, but the packaged copy still loads; remove the role itself with a disabled stub or the settings page |
| Add one | It loads alongside the shipped roles |
.seeded.json records what the package wrote. A file you drop in replaces the
shipped role by id; a stub with only id and disabled: true removes it. The
directory is watched, so any change is re-read after a short quiet period.
seedRolesDir: false stops the package from writing into your directory;
watchRolesDir: false reads it once per composition.
- insert:
- id: roles-zeta
name: dsh-roles-zeta
config:
provider: spawn
toolName: delegate
backgroundMode: continuable
maxDepth: 2
No model and no path appears here: role files name their route and the plugin resolves it. The row is host plane, so every agent in every preset sees the tool.
| Field | Default | Meaning |
|---|---|---|
dshHome | $DSH_HOME, else ~/.dsh | Harness home the role directory is derived from |
rolesDir | $DSH_HOME/agents | Your role directory: seed target and override root |
seedRolesDir | true | Write the shipped roster into rolesDir and keep it current while unedited |
watchRolesDir | true | Reload the roster when a file in rolesDir changes |
commands | true | One /<id> slash command per role |
commandPrefix | (empty) | Text placed before every command name |
settingsPage | true | Mount the settings API and page |
provider | spawn | ctx.subagents provider name |
toolName | delegate | Model-facing tool name |
backgroundMode | continuable | continuable returns a durable child id; one-shot a job id |
enableRunInBackground | true | Expose run_in_background |
maxDepth | 2 | Delegation-depth cap for a started child |
defaultRoute | (empty) | Used when a role names no route: |
routes | {} | Alias table: deep: { provider: deepseek-official, model: deepseek-flash } lets roles say route: deep |
A route: is looked up in this order: the row's routes aliases; the
session's subagent-model-selection allowed list (the models ticked in the
DSH settings); the registered providers' catalogs; an inline
model: { provider, model } on the role. The catalog step is what lets a
headless profile resolve without any settings surface. When the allowed list
is enabled it also gates the role's route: a registered model the list
excludes is rejected with a message, not run quietly.
With no route named anywhere the child inherits the calling agent's provider
and model, and the result says so; the plugin never picks from the allowed
list by itself. A bare model id registered under two providers must be written
as provider/model.
Effort is clamped onto the levels the route advertises, the higher one on a
tie: deepseek-flash offers off/low/high/max, so medium becomes
high and xhigh becomes max. The shipped roles all say high. A
substitution is reported in the delegation result.
One tool schema per session: a roster line per role and the allowed routes in
the description; parameters role, description, prompt, an optional
route alias, provider/model when the session enables model selection,
and run_in_background. A call resolves the role, preflights the route,
narrows the tool filter against the live registry, and starts one child whose
persona prefix is the role body. A foreground call returns the child's final
text; a continuable background call returns started subagent <id> and
settles through the runtime's notice.
allow list. Under a preset
whose subagent row sets modelSelectionSettings: true, that row installs
itself per agent, and tools.restrict() never filters a scope's own layer:
a role allowing six tools received eight in the web profile (subagent and
list_subagent_models leaked) and six in headless. A read-only role in the
web profile can still start a child; the persona says not to, the filter
cannot enforce it.AGENTS.md/CLAUDE.md chain as its parent.tools.restrict() rejection narrows
the filter and retries up to three times, so a stale name costs one failed
start.