🔬 DSH Open Deep Research
简体中文
DSH Open Deep Research is an open-source Deep Research agent and TypeScript framework built on DeepSeek Harness. It accepts a research question, produces a Markdown report with citation links, and exposes the same research service through a CLI, a DSH Tool, and a programmatic API.
Project status: 0.1.0-alpha.5 Alpha Public Preview, tested with published DSH 0.1.0-rc.8. It is distributed through GitHub Releases and is not published to npm.
What it does
- Plans one to three focused research units, runs them through DSH child Agents, and synthesizes their findings.
- Supports Web search in both dedicated Profiles and selected page or PDF reading in
research-jina.
- Returns a cited Markdown report, normalized links, terminal status, and run metadata.
- Provides CLI, DSH Tool, and TypeScript entry points over a replaceable
ResearchEngine.
🏗️ Architecture
flowchart TD
USER["User or application"] --> ENTRY{"Entry"}
ENTRY --> CLI["Dedicated research CLI"]
ENTRY --> TOOL["open_deep_research Tool"]
ENTRY --> API["createResearchClient()"]
CLI --> ENGINE["ResearchEngine"]
TOOL --> ENGINE
API --> ENGINE
ENGINE --> PLAN["Planning Agent<br/>brief and 1 to 3 units"]
PLAN --> RESEARCH["Research Agents<br/>bounded concurrent work"]
RESEARCH --> SYNTHESIS["Synthesis Agent<br/>final cited report"]
SYNTHESIS --> RESULT["Markdown report<br/>ResearchResult"]
RESEARCH --> SEARCH["DSH web_search"]
RESEARCH -. "research-jina only" .-> JINA["Jina read_url through MCP"]
DSH["DeepSeek Harness<br/>models, Tools, Presets, sessions, child Agents, cancellation"]
DSH -. "runs and manages" .-> PLAN
DSH -. "runs and manages" .-> RESEARCH
DSH -. "runs and manages" .-> SYNTHESIS
All entry points call the same ResearchEngine. The active Profile selects the source Tools available to Research Agents. See Architecture for lifecycle, Profile composition, configuration, and result semantics.
🚀 Quickstart
Download the prerelease package from GitHub. Contributors who want to build from source can follow Contributing.
| Profile | Source capabilities | Credentials | Network requirement |
|---|
research-jina | Search and page/PDF reading | DeepSeek Key and Jina Key | DeepSeek API and mcp.jina.ai |
research | Search only | DeepSeek Key | DeepSeek API |
Requirements: Node.js ^22.19.0 or >=24.0.0, pnpm 10.x available on PATH, and DeepSeek Harness 0.1.0-rc.8.
DSH also calls pnpm when it manages Profile plugins. Confirm that both npx and pnpm are available before installation:
node --version
pnpm --version
See the pnpm installation guide if the second command is unavailable.
1. Download the package
curl -fL -O \
https://github.com/songyang0603/dsh-open-deep-research/releases/download/v0.1.0-alpha.5/dsh-open-deep-research-0.1.0-alpha.5.tgz
This downloads dsh-open-deep-research-0.1.0-alpha.5.tgz into the current directory. The Release also includes SHA256SUMS for checksum verification.
plugin add can print host peer warnings. Continue with initialization when the command exits with code 0.
2. Full Research: search and read sources (recommended)
research-jina provides Web search and page reading. It sends selected public URLs to Jina without browser cookies. Use public, non-sensitive URLs and avoid signed, authenticated-session, private-network, or internal URLs.
Set both keys and check that the deployment network can reach Jina:
export DEEPSEEK_API_KEY='<your-deepseek-key>'
export JINA_API_KEY='<your-jina-key>'
curl --connect-timeout 10 --max-time 20 -I \
'https://mcp.jina.ai/v1?include_tools=read_url&max_tokens=8000'
Any HTTP response confirms that DNS, TCP, and TLS reached the endpoint. This check does not validate the Key or complete MCP startup. Use the search-only Profile below if the endpoint does not respond.
npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile research-jina add \
./dsh-open-deep-research-0.1.0-alpha.5.tgz
npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile research-jina exec \
dsh-open-deep-research-init --reader jina
npx @deepseek-ai/dsh@0.1.0-rc.8 --profile research-jina \
--breadth balanced \
--language English \
"Research the main changes in DeepSeek Harness rc.8. Search for relevant material, read important source pages, and produce a report with citation links."
Research Agents choose which source Tools to call. The Profile provides both Tools without requiring a fixed number of calls. The Reader returns at most 8,000 tokens per request, so long documents can be truncated. If Jina initialization does not complete, check whether the deployment network can reach mcp.jina.ai or use the search-only Profile below.
3. Search-only: DeepSeek Key only
Use the independent research Profile when a Jina Key or network path is unavailable. It keeps planning, Web search, multiple research units, synthesis, and report generation. It does not provide reliable access to full page or PDF bodies.
export DEEPSEEK_API_KEY='<your-deepseek-key>'
npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile research add \
./dsh-open-deep-research-0.1.0-alpha.5.tgz
npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile research exec \
dsh-open-deep-research-init
npx @deepseek-ai/dsh@0.1.0-rc.8 --profile research \
--language English \
"Research the main changes in DeepSeek Harness rc.8 and produce a report."
4. Save the output
Markdown mode writes the report to stdout, so it can be redirected to a file:
npx @deepseek-ai/dsh@0.1.0-rc.8 --profile research-jina \
"Compare two research approaches" > report.md
The first clean npx @deepseek-ai/dsh invocation can spend several minutes downloading and building dependencies with little output. Wait for it to exit before retrying. The two Profiles are independent and never overwrite or automatically downgrade into each other.
⚙️ Configuration
| Option | Values | Default |
|---|
--purpose | Free text | omitted |
--context | Free text | omitted |
--breadth | focused, balanced, broad | balanced |
--format | report, brief, memo | report |
--language | Language name or locale | question language |
--json | Canonical ResearchResult for completed or partial runs | off |
Breadth sets the maximum number of research units to one, two, or three. Planning can choose fewer. Provider settings such as model route, Preset, working directory, source Tool allow-list, and maximum research concurrency are documented in Architecture.
Completed and partial runs exit with code 0; a partial run also writes a concise notice to stderr. Execution failures use 1, argument errors use 2, and user interruption uses 130. Failed or cancelled runs leave stdout empty.
Use from DSH and TypeScript
Install the same tarball into stock DSH Profiles to expose open_deep_research as a Tool:
npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile headless add \
./dsh-open-deep-research-0.1.0-alpha.5.tgz
npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile web add \
./dsh-open-deep-research-0.1.0-alpha.5.tgz
Stock headless and web receive the Provider and Tool only. Their configured allowedTools determines source capabilities.
For ordinary Agent calls, the Tool binds the research question to the direct user text in the current DSH turn. It does not accept model-authored purpose or context. Use the dedicated CLI or TypeScript API when those fields must be supplied explicitly; ask the user to clarify a message that depends on unstated earlier context.
After a completed or partial run, the Tool asks the parent Agent to return the rendered Markdown report verbatim. The parent Agent still generates an ordinary assistant response and may add framing or make minor formatting changes. This reduces citation-rewrite risk but does not provide byte-level identity. Consume the Tool value or TypeScript result directly when the exact canonical report is required.
The TypeScript API calls the selected ResearchEngine directly:
import { createResearchClient } from 'dsh-open-deep-research'
const result = await createResearchClient(ctx).run({
question: 'How are Agent Presets composed in DeepSeek Harness?',
purpose: 'Prepare an architecture note for plugin authors.',
breadth: 'balanced',
output: { format: 'report', language: 'English' },
})
console.log(result.status)
console.log(result.report)
Use createResearchClient(ctx).start() for a cancellable ResearchRun. See the domain contract for the full API behavior.
Test in the local Web UI
Install the package into the DSH web Profile:
export DEEPSEEK_API_KEY='<your-deepseek-key>'
npx @deepseek-ai/dsh@0.1.0-rc.8 plugin --profile web add \
./dsh-open-deep-research-0.1.0-alpha.5.tgz
npx @deepseek-ai/dsh@0.1.0-rc.8 web
DSH starts the Web UI at http://127.0.0.1:3080. Start a new conversation and enter:
Call open_deep_research to investigate the main changes in DeepSeek Harness rc.8 and produce an English report with citation links.
This stock Web installation uses the search-only source configuration. The recommended search and page-reading combination is currently provided by the dedicated research-jina CLI Profile.
Compatibility and current limits
| Area | Current status |
|---|
DSH 0.1.0-rc.8 | Current supported and tested host line. |
| Jina Reader | A live smoke test has passed. Availability still depends on the deployment network. |
| Documents and Tool calls | Short pages and short PDFs are tested. Long inputs can be truncated. Source-call limits are prompt instructions. |
ResearchResult.sources | De-duplicated HTTP links from the final report. A link alone does not confirm page reading or source quality. |
| MCP startup | An unresponsive route can take multiple SDK timeout intervals. plugin add can also print host peer warnings. |
Project documents: Architecture · Changelog · Contributing · Security
License
MIT
