English | 中文

dsh-explore

Trajectory-level parallel exploration for DeepSeek Harness agents.

When you need more than one answer, dsh-explore forks your agent into N parallel branches — each inherits your full conversation context and independently explores a different approach — then returns all their answers, or (with a verifier) picks and explains a winner.

✨ Features

• explore tool — fork N subagents in parallel and get N genuinely different answers.
• Execution-grounded verification (verify) — run a real command against each branch and keep the one that passes. Never trusts an agent's self-report.
• Winner diff — explains why the winner won: shared prefix → divergent tool calls → error counts.
• MCTS tree search (mode: 'mcts') — iterate: fork → verify → backprop → re-select → branch deeper from the best partial trajectories.
• Deterministic isolation — branches share no mutable state; dsh's fork seeds each child from the parent's exact completed-turn prefix.

🚀 Quick start

# from npm (recommended)
dsh plugin --profile web add dsh-explore

# or from a local checkout
dsh plugin --profile web add ./packages/plugin

# restart dsh web, then in a session ask the model:
#   "用 explore 工具，探索 3 种不同的方案解决 …"

🧭 How it works

flowchart TD
  P["parent agent + task"] --> F{"explore tool"}
  F -->|fork| B1["branch 1"]
  F -->|fork| B2["branch 2"]
  F -->|fork| B3["branch 3"]
  B1 --> V1["answer / diff A"]
  B2 --> V2["answer / diff B"]
  B3 --> V3["answer / diff C"]
  V1 & V2 & V3 --> D{"verify?"}
  D -->|"no"| R["return all N"]
  D -->|"yes"| W["apply to worktree → run verify → pick winner + diff"]

• Without verify — branches answer the inherited task in one message (v0, tool-free, reliable today).
• With verify — branches propose a unified diff (read-only); each diff is applied to an isolated git worktree, verified, and the winner is selected (v1).

📦 Packages

Package	What it is
packages/core	Pure, dependency-free algorithms: bestOfN, mcts, UCT, verdictFromRun, diffTrajectories, extractPatch, selectBest. 18 unit tests.
packages/plugin	The dsh bundle wiring core to ctx.subagents / ctx.tools / ctx.shell. Bundled to a single dist/index.js with zero @deepseek-ai/* import at runtime.

❓ Why a tool, not a slash command

dsh's own subagent tool forks children from exec.agent inside the agent loop — the only context where child.whenIdle() reaches quiescence. A slash-command handler forking subagents never resolves SubagentRun.result in the current preview, so this plugin follows the same contract: it's a tool.

📚 Grounding

LATS (MCTS over language-agent trajectories) · Agent Q (environment reward; self-critique only as a guide) · best-of-N with execution verifiers (EvoScale / μ Code / SWE-bench) · ParallelEnv (tree-forking over isolated environments).

🗺️ Roadmap

• M0 — fork mechanism verified (tool path)
• M1 — core search library (bestOfN / mcts / UCT)
• M2 — explore tool, fork N in parallel
• M3 — execution verifier (ctx.shell → verdict)
• M4 — winner diff + propose-mode + worktree verifier (v1)
• MCTS — real tree search (mode: 'mcts', mid-trajectory branching)
• live — worktree + MCTS end-to-end (needs live test)
• M5 — npm publish (dsh-explore + dsh-explore-core) + dsh plugin add dsh-explore

⚠️ Status

Developer preview. dsh pins SESSION_FORMAT_VERSION = 0 with no compatibility promise; dsh-explore tracks the preview line.

License

MIT