DeepSeek Research Harness

<p align="center"> <strong>Evidence-grounded paper reading, citation verification, and reproducible experiment planning for DeepSeek Harness.</strong> </p>

<p align="center"> English | <a href="./README.zh.md">简体中文</a> </p>

<p align="center"> <img alt="Version" src="https://img.shields.io/badge/version-0.1.0-2563eb"> <img alt="DeepSeek Harness" src="https://img.shields.io/badge/DeepSeek_Harness-0.1.0--rc.6-0f766e"> <img alt="Python" src="https://img.shields.io/badge/Python-%3E%3D3.11-3776ab"> <img alt="Node.js" src="https://img.shields.io/badge/Node.js-%5E22.19_%7C_%3E%3D24-339933"> <a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-MIT-111827"></a> </p>

DeepSeek Research Harness (DSRH) is an out-of-tree research capability bundle for DeepSeek Harness. It adds three model-invocable skills and a deterministic Python MCP sidecar while leaving model access, sessions, shell execution, jobs, sandboxing, and approvals under Harness control.

[!IMPORTANT] DSRH 0.1.0 is a developer preview. The npm and PyPI package names are release targets; install the current version from this repository.

News

Date	Update
2026-08-14	Completed end-to-end Harness invocation tests for PaperReader, CitationGuard, and ExperimentPilot. The profile exposes 3 skills, 3 native tools, and 21 MCP tools.
2026-08-14	Released the 0.1.0 developer preview with the installable Harness bundle, Python MCP sidecar, keyless CI, and workspace security boundaries.

What DSRH Adds

Skill	Purpose	Main outputs
PaperReader (dsrh-paper-reader)	Parse born-digital PDFs, index sections with SQLite FTS5/BM25, and retrieve source-grounded evidence.	Structured metadata, sections, search results, and stable evidence_id references.
CitationGuard (dsrh-citation-guard)	Parse BibTeX, detect duplicates, resolve metadata through Crossref/OpenAlex/arXiv, and review local claim support.	JSON and Markdown verification reports with explicit confidence and status.
ExperimentPilot (dsrh-experiment-pilot)	Validate versioned manifests, expand experiment matrices, and prepare approval-first execution plans.	Deterministic dry-run commands, run manifests, metrics summaries, and provenance.

DSRH does not contain a separate chat client and does not call an LLM API directly. You interact through dsh web or a headless Harness profile; Harness performs reasoning and synthesis.

Architecture

DeepSeek Harness
  agent loop + model + session + fs/shell/jobs + sandbox/approval
      |
      +-- DSRH Bundle
          +-- PaperReader / CitationGuard / ExperimentPilot skills
          +-- deterministic native experiment tools
          +-- official @deepseek-ai/dsh-mcp-client
                 |
                 +-- dsrh-mcp (Python stdio server)
                     PDF + SQLite FTS + BibTeX + metadata + aggregation
                             |
                             +-- <workspace>/.dsrh

DSRH is tested against DeepSeek Harness npm package 0.1.0-rc.6 and upstream commit 47f9438.

Quick Start

Requirements

• Node.js ^22.19.0 || >=24
• Corepack and pnpm 11.7.0
• Python >=3.11
• A model provider configured in Harness, or DEEPSEEK_API_KEY for DeepSeek

Windows PowerShell

Run from the DSRH repository root:

corepack enable pnpm
corepack pnpm install
corepack pnpm build

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".\python[dev]"
$env:DSRH_PYTHON = (Resolve-Path '.venv\Scripts\python.exe').Path

npx.cmd --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add .\packages\plugin
npx.cmd --yes @deepseek-ai/dsh@0.1.0-rc.6 --profile web --dump-config

Configure the model credential without committing it:

$env:DEEPSEEK_API_KEY = '<your-api-key>'
npx.cmd --yes @deepseek-ai/dsh@0.1.0-rc.6 web

macOS / Linux

corepack enable pnpm
corepack pnpm install
corepack pnpm build

python3 -m venv .venv
.venv/bin/python -m pip install -e './python[dev]'
export DSRH_PYTHON="$PWD/.venv/bin/python"

npx --yes @deepseek-ai/dsh@0.1.0-rc.6 plugin --profile web add ./packages/plugin
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 --profile web --dump-config

export DEEPSEEK_API_KEY='<your-api-key>'
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web

The configuration dump must contain dsrh-runtime, dsrh-skills, and dsrh-science-mcp. The Web UI is available at http://127.0.0.1:3080 by default. See the installation guide for profile setup, package release workflows, and troubleshooting.

Usage

Place input files inside the directory from which you start Harness. That directory becomes the DSRH workspace, and generated state is stored under <workspace>/.dsrh/.

Read a Paper

Use dsrh-paper-reader to deeply analyze papers/paper.pdf.
Focus on the research question, method, architecture, experiments,
ablations, results, and limitations. Explain each figure and cite
an evidence_id for every central technical claim.

PaperReader supports born-digital PDFs in V1. Scanned PDFs are reported as degraded-scan-unsupported; missing text is never invented.

Verify Citations

Use dsrh-citation-guard to verify references.bib.
Check metadata, duplicate entries, DOI mismatches, and nonexistent-reference risk.
Mark unresolved entries as UNRESOLVED rather than calling them hallucinations.
Generate both JSON and Markdown reports.

Local parsing and duplicate detection work offline. Metadata resolution is allowlisted to Crossref, OpenAlex, and arXiv. Reports are written to .dsrh/citations/reports/.

Plan Experiments

Start with examples/experiment.yaml or the experiment schema:

Use dsrh-experiment-pilot with examples/experiment.yaml.
Inspect the repository and produce a dry-run plan first.
Show every run's parameters, command, working directory, and artifact directory.
Do not modify source code or execute training until I approve the plan.

DSRH validates and expands the manifest but never bypasses Harness execution controls. Approved commands run through Harness shell/jobs, sandbox, and approval flows.

Verification

corepack pnpm typecheck
corepack pnpm build
corepack pnpm test
.venv\Scripts\python.exe -m ruff check python tests\end-to-end tests\fixtures\toy-training
.venv\Scripts\python.exe -m pytest python\tests tests\end-to-end -q
.venv\Scripts\python.exe -m dsrh_mcp doctor

Current acceptance coverage includes TypeScript unit tests, Python unit/integration tests, a toy end-to-end experiment pipeline, and official Harness profile loading. The suite uses generated PDFs and mocked scholarly APIs, so it requires neither model credentials nor large training jobs. See test results.

Safety

The Python sidecar canonicalizes paths, resolves symlinks, rejects workspace escape, bounds PDF and metadata response sizes, and only contacts allowlisted scholarly metadata providers. It exposes no shell, arbitrary subprocess, Git push, checkpoint deletion, or direct model API tool. Read the security model and known limitations before using DSRH with sensitive projects.

Documentation

• Architecture
• Installation
• Usage
• Development
• Test results
• Security
• Known limitations
• Changelog

License

DSRH is released under the MIT License.