# 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](https://github.com/deepseek-ai/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

```text
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`](./UPSTREAM.md).

## 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:

```powershell
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:

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

### macOS / Linux

```sh
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](./docs/installation.md) 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

```text
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

```text
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`](./examples/experiment.yaml) or the [experiment schema](./schemas/experiment.schema.json):

```text
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

```powershell
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](./docs/test-results.md).

## 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](./docs/security.md) and [known limitations](./docs/known-limitations.md) before using DSRH with sensitive projects.

## Documentation

- [Architecture](./docs/architecture.md)
- [Installation](./docs/installation.md)
- [Usage](./docs/usage.md)
- [Development](./docs/development.md)
- [Test results](./docs/test-results.md)
- [Security](./docs/security.md)
- [Known limitations](./docs/known-limitations.md)
- [Changelog](./CHANGELOG.md)

## License

DSRH is released under the [MIT License](./LICENSE).