Preface

The design philosophy of DeepSeek Harness (DSH) is “everything is a plugin.” Most existing deep research plugins behave as fixed-prompt pipelines, lacking closed-loop control over the research process and validation of results. The dsh-socrates plugin introduces a Socratic clarification mechanism and adaptive research logic to address this issue.

Plugin Positioning

dsh-socrates is a DeepSeek Harness deep research plugin, maintained by Cruciforms and released under the MIT license. It emphasizes pre-investigation clarification + adaptive multi-round research + cross-validation + citation closed-loop. Unlike fixed-prompt pipelines, it is a live, convergent research closed-loop.

Core Features

1. Pre-investigation Clarification

Before research begins, the Planner generates no more than 3 clarification questions on the topic and asks the user via userQuestions.ask. After user confirmation, the research plan enters the execution stage. It supports planReview intent cards for plan approval.

2. Adaptive Multi-round Research

The research process is not completed in one pass, but executed round by round.
* Parallel research: In each round, multiple researchers (Flash models) search, read closely, and record verbatim excerpts into the evidence store.
* Gap-driven: At the end of each round, high-priority gaps are collected. If marginal gain validation is negative, the process stops early.
* Stop-loss mechanisms: Triple safeguards include consecutive zero gain, a hard round cap, and a token budget.

3. Cross-validation

The Verifier makes a claim-level three-way judgment for each claim: entailed, contradicted, or baseless. If a claim is unverified, it is marked as ⚠️ UNVERIFIED in the report. The system supports single-hop backfill tasks and conditional revision rounds.

4. Citation Closed-loop

Numbered citations must come from verbatim snippets in the evidence store (≤100 characters, including paragraph anchors). Non-original content is marked as model_knowledge. Programmatic citation audit checks citation existence, adjacent excerpt format, verbatim consistency, and length limits.

5. Academic Three Sources and Source Curation

The plugin includes built-in retrieval interfaces for arXiv, PubMed, and Semantic Scholar, requiring no API key. When depth ≥ 2, an LLM curation sub-agent is enabled to filter out weakly relevant low-quality sources.

6. Model Tiering for Cost Reduction

The plugin supports model-tiered scheduling: Planner, Synthesizer, and Reviewer use Pro models; Researcher uses Flash models to reduce cost.

Installation and Enablement

Install using the official command:

dsh plugin --profile web add dsh-socrates

After installation, restart the DSH process to activate the plugin.

Usage

Use natural language directly in the conversation. The model will automatically trigger the research workflow based on tool descriptions.

  • General research: “Conduct a deep dive into the current state of the MCP ecosystem, focus on comparing several mainstream implementations, and produce a cited report.”
  • Existing checklist: “Conduct research based on this question list: 1. … 2. …” (Once the checklist is provided, the plugin skips automatic decomposition and performs parallel research directly.)
  • Explicit purpose: “Investigate options A and B; the purpose is to decide which one we should choose.” (The more explicit the purpose, the more precise the answer space.)

For more complex topics, the plugin automatically expands the number of rounds; simple topics converge in a single round. For more rigorous output, pass the parameter depth: 3; to enable citation correction and coverage audit, pass review: true.

Parameter Description

Parameter Required Default Description
topic Yes — Research topic
purpose No — Research purpose, used to define the answer space
questions No — Existing question list (one question per line)
depth No 2 Precision level: 1 = preliminary (3 sub-questions / 2 rounds), 2 = in-depth (4 sub-questions / 3 rounds), 3 = exhaustive (6 sub-questions / 4 rounds)
synthesize No true Whether to generate a final synthesis report
verify No true Whether to enable cross-validation
review No false Whether to enable adversarial review (citation correction, coverage audit)
clarify No true Whether to ask clarification questions before investigation
planReview No false Whether to perform plan approval before research

Output and Architecture

Output Directory

Evidence and reports for each research run are persisted on the host side. The default path is runs/<topic-slug>/ under the plugin installation directory.

Output Files

  • evidence.jsonl: Verbatim excerpt evidence store, including URL, paragraph anchors, and quality grades.
  • report.md: Final report with numbered citations.
  • state.json: Runtime state, coverage, and validation statistics.
  • review.md: Review comments (generated when review=true).

Architecture Design

The plugin uses index.js as a thin shell and invokes the official DSH workflow engine for orchestration.
* Orchestration: Uses ctx.workflows, supporting concurrency control and cancellation propagation.
* Search/fetch: Directly calls DSH’s built-in web_search / web_fetch; the plugin itself contains no network logic or custom orchestration.
* Evidence storage: Managed by the host’s src/evidence-store.js; workflow scripts have no direct filesystem access.

Comparison with Similar Plugins

Feature dsh-socrates dsh-deepresearch dsh-raven-research dsh-research-report
Core Difference Socratic clarification + adaptive closed-loop + verification + citation audit Evidence management + Web workspace Mid-course steering correction Content-addressed evidence ledger + sealed report
Multi-round Orchestration ✅ Adaptive closed-loop ❌ No self-scheduled search ❌ Single-task progressive ❌ No research closed-loop
Cross-validation ✅ Claim-level three-way adjudication + backfill ❌ ❌ ✅ Validation adjudication
Citation Audit ✅ Programmatic (verbatim consistency) ❌ ✅ Byte comparison ❌
Academic Search ✅ arXiv / PubMed / S2 ❌ ❌ ❌
Model Tiering ✅ Automatic Pro/Flash tiering ❌ ❌ ❌

Other Information

  • Former name: The project was originally named dsh-deep-research. To avoid confusion with the same-named repository dsh-external/dsh-deep-research on GitHub, it was renamed to dsh-socrates in 2026-08.
  • Dependency: Requires @deepseek-ai/dsh-tools (v0.1.0-rc.6+).

The plugin source code and documentation are available on GitHub.