deerflow-dsh

DeerFlow 2.0 (SuperAgent Harness) packaged as a DeepSeek Harness (dsh) plugin.

DeerFlow 2.0 is a task-agnostic agent runtime: a Lead Agent decomposes a task into sub-tasks, dispatches them to pluggable skills, runs them in isolated sub-agent contexts, and converges the results. This repository adapts that architecture into a Cordis-driven dsh plugin bundle that loads into a DeepSeek Harness host.

Based on github.com/bytedance/deer-flow (v2.0, MIT). This plugin is an independent re-implementation of the 2.0 design — not a fork — adapted to the dsh plugin contract (name / inject / Config / apply).

Architecture (DeerFlow 2.0)

            task (flash | standard | pro | ultra)
                          │
                          ▼
                   ┌──────────────┐
                   │  Lead Agent  │   decomposes → { title, subtasks[] }
                   │  (deerflow)  │   each subtask carries a skill + goal
                   └──────┬───────┘
        ┌─────────────────┼─────────────────────────────┐
        ▼                 ▼                             ▼
 ┌─────────────┐  ┌───────────────┐            ┌───────────────┐
 │  research   │  │ data-analysis │  …skills… │    image      │
 │ (web+crawl+ │  │ (sandboxed    │            │  (asset API  │
 │  python)    │  │  python)      │            │   or prompt) │
 └──────┬──────┘  └───────┬───────┘            └───────┬───────┘
        └─────────────────┼─────────────────────────────┘
                          ▼
                   ┌──────────────┐
                   │  Converge    │   reliability middleware wraps every call
                   │  (finalize)  │   (retry + per-attempt timeout + loop guard)
                   └──────────────┘

Core components

Module	Path	Responsibility
Lead Agent	src/agent/lead.ts	Task decomposition, mode routing (flash/standard/pro/ultra), sub-agent dispatch, HITL gate, convergence
Skills	src/skills/*.ts	research, report-generation, data-analysis, slide, web-page, image, video
Research skill	src/research/workflow.ts	Planner → searcher → reporter; falls back to a single search step when the planner returns no JSON
Base tools	src/tools/*.ts	deerflow_web_search, deerflow_web_crawl, deerflow_web_fetch, deerflow_run_python, deerflow_run_bash, deerflow_browser
Providers	src/lib/providers.ts	tavily / brave / duckduckgo / arxiv / doubao search; jina crawl
LLM seam	src/lib/llm.ts	Drives the host llm service (ctx.get('llm').stream()); extractJson, complete
Reliability	src/lib/middleware.ts	withReliability — retry + per-attempt timeout + back-off + loop guard; withGuardrails — output validation with structured GuardrailError
Memory	src/lib/memory.ts	Cross-session JSON persistence ($DEER_FLOW_HOME/.deerflow/memory.json)
Config	src/config.ts	Schemastery schema; four-tier TaskMode, sandbox mode, skill toggles, middleware & memory knobs

Four-tier task model

flash answers directly (no skill dispatch); standard runs a single tool/skill chain; pro decomposes into ordered sub-tasks executed sequentially; ultra decomposes and runs sub-tasks in parallel (bounded by maxSubAgents, results kept in order). The default tier is pro.

Host contract

The plugin expects a dsh host that provides (as Cordis services / packages):

• @deepseek-ai/cordis
• @deepseek-ai/dsh-llm (the llm service, accessed via ctx.get('llm'))
• @deepseek-ai/dsh-tools (defineTool, ctx.tools.register)
• @deepseek-ai/schemastery (config schema)

Tool registration is reversible (ctx.tools.register returns a disposer), so the plugin unloads cleanly.

cordis.patch.yml

A single insert row with id: deerflow carries the flat config object read by the Cordis loader. Edit defaultMode, maxSubAgents, skill toggles (skillResearch … skillVideo), humanInTheLoop, provider keys, middleware retries/timeouts, and memoryEnabled/memoryPath there.

Development

npm install            # installs @deepseek-ai/* host-simulating deps + tooling
npm run typecheck      # tsc against vendored dsh-spec.d.ts (no runtime deps)
npm run build          # tsdown → lib/index.js (+ types), externalizes @deepseek-ai/*
npm test               # zero-dependency runner (tsx + stubbed dsh runtime)
npm run test:host      # REAL-host smoke: cordis + dsh-tools ToolRegistry + schemastery
npm run test:e2e       # REAL-LLM end-to-end (needs DASHSCOPE_API_KEY / BAILIAN_API_KEY)
npm run hooks:install  # enable the pre-commit gate (git config core.hooksPath .githooks)

Real-host smoke. npm run test:host mounts the plugin on the REAL @deepseek-ai/cordis runtime with the REAL dsh-tools ToolRegistry and REAL schemastery Config validation, then executes deerflow through ToolRegistry.execute. Only the LLM abstraction is stubbed (no model key); this catches host-side incompatibilities that the stubbed unit suite cannot (e.g. the schema compiler rejecting required: false).

Real-LLM end-to-end. npm run test:e2e runs the full pipeline (decompose → planner → researcher → reporter → converge) with a REAL LLM (DashScope OpenAI-compatible, qwen3.7-max) and REAL duckduckgo network search on the real runtime core. Requires DASHSCOPE_API_KEY or BAILIAN_API_KEY; not part of the commit gate (slow + costs tokens).

Doubao search (mainland-friendly). Set searchProvider: doubao and ARK_API_KEY to use Volcano Ark's independent Doubao search API (open.feedcoopapi.com/search_api/web_search) — works from mainland networks where duckduckgo/jina are blocked. Verified live in the real dsh host: research returns fully cited reports.

Pre-commit gate. .githooks/pre-commit runs typecheck + the full test suite and blocks any commit that fails (use --no-verify only as a last resort). npm install auto-configures core.hooksPath via the prepare script; re-run npm run hooks:install after cloning to enable it.

Testing without a host. npm test runs through test/loader.mjs, a Node ESM loader that redirects every @deepseek-ai/dsh-* specifier to test/stub-dsh.mjs (an identity defineTool + dummy type exports). This lets the suite execute locally without installing the full dsh runtime peer-dependency chain. @deepseek-ai/schemastery and @deepseek-ai/cordis resolve to the real installed packages.

License

MIT — see LICENSE. DeerFlow is © ByteDance and released under MIT.