dsh-herdr
从 DeepSeek Harness 向由 Herdr 管理的编码代理委派子任务：选择模型、保留面板、获取准确结果，并在 DSH 中进行审查。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:ahqrt/dsh-herdr#642b2712270facc7ae584926357b4610bf602d29Herdr 以 dsh-herdr 发布，当前版本为 0.12.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
Delegate a subtask from DeepSeek Harness to a real coding agent in a Herdr pane — pick the model, keep the terminal, harvest the exact answer, review it in DSH.
dsh-herdr is the reference bridge between DeepSeek Harness and Herdr. It turns Herdr into an external subagent runtime: DSH stays the orchestrator and reviewer, while pi / agy / claude / codex / … do the work in visible, steerable panes.
Status:
0.11.x, validated on DSH0.2.1-rc.2(all nine tools activate in a headless profile) and Herdr0.9.4(server0.9.1); admitted on DSH0.2.1-rc.3by the host compatibility preflight. The public surface is the nineherdr_*tools; breaking changes follow semver and are listed in CHANGELOG.md.
DSH subagents run in-process and share the harness model. Sometimes you want the opposite:
dsh-herdr gives the DSH agent a small vocabulary: delegate, fetch, message, list, interrupt, close, plus an inbox and a transcript pager.
| Model routing | Short aliases from ~/.pi/agent/model-aliases.md (grok4.7[high], flash, …) resolve to provider/model + thinking. Billing boundaries stay where you put them. |
| Exact results | pi children are read from their session JSONL — the last assistant message, byte-identical. result.md is the second source; pane tail is only the fallback. |
| Review evidence | A git baseline at spawn, a patch at harvest, changed files, test line, token usage, session path. |
| Idempotency | client_task_id makes a retried tool call return the existing task instead of spawning a twin. |
| Ownership | The plugin only closes/steers panes it created. User panes are read-only. |
| Blocked ≠ approved | A blocked child is surfaced to the user, never auto-answered. |
| Cancellation | Turn-level interrupt (Escape) without destroying the pane or session. |
| Inbox | Children can report BLOCKED / REVIEW_REQUEST / COMPLETE; herdr_inbox consumes them, with a long-poll. |
| Queue | Over the cap, a spawn waits for a slot (queueTimeoutMs) instead of failing. |
| Isolation | isolated: true runs the task in a fresh git worktree and returns its path. |
| Transcript | herdr_read_agent pages the pi session instead of only the final message. |
| Run flow | The panel's flow tab replays the same session turn by turn: prompts, assistant text, every tool call with its argument preview, and each tool result with error/duration. It follows a running child. |
| Event waits | An opt-in socket transport waits on agent.wait server-side; a connect failure falls back to the CLI. |
| Remote machines | machine on spawn/list/result/message, via herdr --machine; SSH file bridge (machineTargets) removes the mount requirement. |
| Native subagent | A herdr subagent provider routes a dsh-tool-subagent row through Herdr for native cards, catalog, and cancellation. |
| Web panel | A Herdr right-sidebar tab: searchable/grouped fleet, run flow, read-only tails, per-file diff, packet templates/history, reveal/open-editor cwd, and bulk interrupt/close. |
| Diagnosis | herdr_doctor checks binary, server, kinds, aliases, directories, topology, and pi in one call. |
flowchart LR
DSH["DSH agent"] -->|tool call| T["herdr_* tools"]
T --> S["services<br/>spawn · harvest · message · lifecycle · doctor"]
S --> P["ports<br/>HerdrTransport · TaskStore · GitService"]
P --> CLI["Herdr CLI adapter"]
P --> FS["File store + audit"]
P --> GIT["Local git adapter"]
CLI --> H["Herdr server"]
H --> PI["pi pane<br/>model A"]
H --> AGY["agy pane"]
H --> OTHER["claude / codex / …"]
The dependency rule is one-way: tools → services → ports ← adapters. The domain (prompts, session parsing, aliases, lifecycle rules) imports nothing from DSH and nothing from the OS except node:fs/node:path. See docs/architecture.md.
The desktop profile is owned by the Electron app; dsh plugin --profile desktop … is rejected by design.
Open Plugins → Add plugin in the app.
Enter the npm package name:
dsh-herdr@0.11.1
For a local checkout, enter its absolute directory (run pnpm build first):
/Users/apple/Desktop/deepseekharness-herdr. A GitHub URL also works because
lib/ is committed.
Install. The plugin manager adds the dependency and the dsh.profile.bundles entry.
Start a new session; herdr_* tools should be listed. If the Herdr panel or
tools do not appear, restart the app to clear the module graph.
A local .tgz path is not a directory spec; use the npm name, or a .tgz URL if
the dialog offers one.
dsh-herdr@0.11.1 is live on npm. Tagged releases publish through the release workflow once the repository trusted publisher is configured (see CONTRIBUTING).
# from a checkout
dsh --profile herdr-dev --from-default-profile web --dump-config
dsh plugin --profile herdr-dev add file:$PWD
dsh --profile herdr-dev --port 0 --no-open
# once published
dsh plugin --profile herdr-dev add dsh-herdr
Full instructions, the skill install, and the local-development loop: docs/installation.md.
You: Use grok4.7[high] to review the current diff. Read-only, findings by severity.
DSH: → herdr_spawn_agent({ kind: "pi", model: "grok4.7", thinking: "high",
role: "reviewer", cwd: "/repo", prompt: "Review ..." })
← status=completed · 3 files · session path · final message
→ reads the diff, groups findings, decides
Fix round:
You: Send the findings back to the worker and make it fix the two majors.
DSH: → herdr_message_agent({ target: "worker-flash-a1b2", kind: "REVIEW_FINDINGS",
round: 1, message: "[MAJOR] ..." })
→ herdr_get_agent_result({ target: "worker-flash-a1b2", wait: true })
More: examples/review-a-diff.md, examples/implement-and-review.md.
| Tool | Purpose |
|---|---|
herdr_spawn_agent | Delegate one subtask; role=reviewer is read-only; isolated:true uses a worktree. |
herdr_get_agent_result | Harvest a result; wait:true blocks until settled. |
herdr_message_agent | Follow-ups, review findings, answers to blocked agents. |
herdr_list_agents | Fleet view: owned and foreign agents. |
herdr_interrupt_agent | Cancel the current turn, keep the pane. |
herdr_inbox | Read child messages; wait:true long-polls. |
herdr_read_agent | Page a pi transcript turn by turn. |
herdr_close_agent | Close an owned pane; session file survives. |
herdr_doctor | Environment self-check. |
The full parameter and result reference is in docs/tools.md; the result JSON contract is docs/result-contract.md.
The plugin also registers a DSH subagent provider named herdr. Point a
dsh-tool-subagent row at it to get native subagent cards, catalog entries, and
cancellation:
- id: tool-subagent-herdr
name: "@deepseek-ai/dsh-tool-subagent"
config:
provider: herdr
toolName: herdr_subagent
The native tool returns the child's final text. Use herdr_spawn_agent when you
need the full review packet (diff, session path, artifacts, blocked question).
The plugin contributes a Herdr tab to the right sidebar (also reachable from
the sidebar guide). It lists the live fleet and, for an owned task, shows the
run flow, the final message, result.md, and the diff split into per-file
sections. The flow tab reads the same pi session the transcript tool pages:
turns in order, each assistant message with the tool calls it made (name +
argument preview such as the bash command), and each tool result with its
error flag and duration. It opens on the newest turns, loads older ones on
demand, and keeps following a running child; a task that failed before its
agent started shows the recorded error instead of a silent empty pane. Agents
this plugin did not spawn show a read-only pane tail instead. Owned tasks can be
interrupted or closed from the detail header or in bulk; both actions reuse the
lifecycle service's ownership gates, and close asks for confirmation. Diff hunks
are highlighted, and the patch or a single file can be copied. The header can
copy a Markdown review packet in PR, issue, or summary form, copy the task cwd,
open it in a configured editor, or reveal it in the OS file manager; the fleet
can be searched by name, cwd, kind, model, and task id, grouped by machine +
status, and driven with ArrowUp/ArrowDown/Enter. Packet copies keep a
three-entry history.
It reads four same-origin endpoints under /herdr/api (health, fleet,
task, transcript); no extra config.
agent_session.value from Herdr points at the file; the last assistant message wins. A message older than the prompt is ignored (freshness check).result.md — every child is asked to write status / summary / tests / files frontmatter plus a body.agent read --source recent-unwrapped, the honest fallback for agy and other kinds with no session file.Git evidence is collected independently of the child: baseline HEAD at spawn, git diff <baseline> at harvest, bounded and saved to ~/.dsh/herdr/tasks/<taskId>/diff.patch.
allowCwd is the hard boundary.owned: true).blocked always goes back to a human; the plugin never approves.enabled: false is a spawn kill switch (it does not kill running agents).~/.dsh/herdr/audit.ndjson.Details and threat model: docs/security.md.
| Component | Tested | Notes |
|---|---|---|
| DSH | 0.2.1-rc.2 (validated), 0.2.1-rc.3 (preflight) | desktop runtime; tool + workingDirectory APIs |
| Herdr | 0.9.4 client / 0.9.1 server | hard floor >= 0.9.0 |
| Node | 22, 24 | ESM, no native deps |
| Kinds | pi (full), agy (launch-only), others via agent_args | model/thinking flags are pi-only by design |
See docs/compatibility.md for the support policy.
| Doc | What it answers |
|---|---|
| Architecture | How the layers fit, and why |
| Installation | Desktop, CLI profile, local checkout, uninstall |
| Configuration | Every key, defaults, examples |
| Tools | Parameters, results, protocol headers |
| Result contract | The AgentResult JSON, versioned |
| Security | Trust boundaries and threat model |
| Troubleshooting | Every error code and its fix |
| Compatibility | Version policy |
| Design notes | ADRs: CLI over socket, exact reads, topology |
Issues and PRs are welcome. Start with CONTRIBUTING.md; the short version is: pnpm install && pnpm test, keep the dependency rule, and add a test for every behavior change.
If you build a host adapter for another terminal multiplexer, the port to implement is src/ports/transport.ts — the services and tools should not need to change.
MIT. Core ideas and several modules are ported from @andrewjacop/pi-herdr (MIT, Copyright (c) 2026 Andrew) — see NOTICE.