dsh-researchcraft

academic-harness

Academic Harness as a DeepSeek Harness profile: the DSH web UI and DSH agent, with its scientific skills, living lab notebook, and specialist subagents.

Install

Academic Harness 0.16+ requires DeepSeek Harness 0.2.1 or later. Install DSH first:

npm install -g @deepseek-ai/dsh
dsh --version   # should report 0.2.1 or later

Without a global install, npx @deepseek-ai/dsh web also works. You need a working dsh CLI for either installation option below.

Option A — Install from the DSH Web UI (recommended)

1. Start the DSH web UI (dsh web).
2. Open Plugins → Add plugin.
3. Paste one of these into the package field:

Source · Paste this GitHub (recommended) · github:raktim-mondol/academic-harness npm registry · academic-harness — not published in v0.16.0; install from GitHub or a local checkout Local checkout · the absolute path, e.g. /home/you/academic-harness

1. Click Install. Academic Harness is installed into the profile you are currently running, enabled by default, and appears under Installed plugins.
2. Start a new chat and confirm the preset selector reads Academic Harness.

The bundle patches the web-app layer, so the profile must already include @deepseek-ai/dsh-web-app; the standard web profile does. A local path must be absolute — the dialog does not expand ~ or resolve relative paths. Installing this way adds Academic Harness to your current profile; use Option B for a dedicated academic-harness profile. DSH only offers Update for its on-demand Official plugins, so update a UI-installed Academic Harness by removing and reinstalling it.

Option B — Install a dedicated profile from the CLI

dsh plugin --profile academic-harness add github:raktim-mondol/academic-harness

This creates the academic-harness profile if it does not exist yet and adds Academic Harness to it. Start it with:

dsh --profile academic-harness

To update this profile later:

dsh plugin --profile academic-harness update academic-harness

For local plugin development, the same command accepts an absolute checkout path:

dsh plugin --profile academic-harness add /absolute/path/to/academic-harness

Run

dsh --profile academic-harness
# or, if you use the shared launcher:
academic-harness

Opens the Harness web UI (typically http://127.0.0.1:3080).

Renamed in v0.16.0

The repo, npm package, plugin, preset, profile, launcher, and product name were renamed from dsh-researchcraft / ResearchCraft to Academic Harness.

Old · New repo / package dsh-researchcraft · academic-harness profile researchcraft · academic-harness launcher dsh-researchcraft · academic-harness (old command stays as a transition alias) preset researchcraft · academic-harness (legacy preset removed) Settings → ResearchCraft API keys · Settings → Academic Harness API keys env RESEARCHCRAFT_* · ACADEMIC_HARNESS_* (old names still honored)

Existing dedicated profile:

node scripts/migrate-profile.mjs --profile researchcraft --to academic-harness --apply
dsh plugin --profile academic-harness install

The migration backs up the old profile, moves the dependency/bundle entries, merges the API-key config into the new entry, updates the preset default, and renames the profile directory. Sessions pinned to the removed legacy researchcraft preset do not resolve; start a new chat on Academic Harness. dsh plugin --profile academic-harness update academic-harness is the new update command.

One DSH surface at a time. dsh-web, dsh-tui, dsh-martty, and academic-harness share $DSH_HOME (including port 3080 and the zvec-grep daemon). Ctrl+C does not always wait for those to exit, so starting another launcher while one is still in the background will fail or pick up the wrong process. The shared launcher (scripts/dsh-launch, installed as those four commands plus the transition alias dsh-researchcraft) stops leftover DSH processes and zg server off before exec. If you invoke dsh --profile … directly, stop the previous one first:

# leftover web UI
ss -ltnp | grep 3080
# leftover zg daemon
zg server off

The Academic Harness profile's bundle patch sets agent-preset-registry default: academic-harness and inserts only preset-academic-harness (DSH 0.2+ no longer reads $DSH_HOME/.agent-presets/). New chats on this profile start on Academic Harness, and the selector lists no legacy preset. Confirm the preset selector at the top of the message box reads "Academic Harness"; if it still says Standard/PTC, the profile patch did not apply.

The persona, the longer research system prompt (notebook discipline, specialist roster, connector guidance, …), academic search (mcp__parallel__*, parallel_search, mcp__firecrawl__*, mcp__scite__*, consensus_search), PaperMemory (mcp__papermemory__*), workspace semantic search (mcp__zvec_grep__zvec_grep_search), and paper_mcp (Paper2Agent stdio mounts) are only present on this preset — a session left on Standard/PTC won't have them, and asking it to use e.g. the Parallel connector will fail with tools[name] is not a function. The general-purpose tools below (notebook, image_generate, sci_inspect, latex_compile, pdf_to_markdown, modal_run/runpod_run, workflow) are available on every preset regardless, since they're registered at the plugin/bundle level rather than inside the Academic Harness preset. Native grep / glob come from the Academic Harness preset's filesystem-search row.

What it adds

• Academic Harness agent preset — persona, research system prompt (notebook discipline, specialist roster, connector guidance), standard coding tools, and the academic search connectors below. This profile defaults to it — see Run.
• Scientific skills catalogue vendored into skills/ from open-source catalogues, bundled with the plugin like the specialist briefs below — no separate checkout or setup needed (see NOTICE for exactly what was changed vs. each source):
• 140 domain skills (chemistry, genomics/bioinformatics, imaging, stats, ML, writing, …) — scientific-agent-skills
• 16 research-discipline/methodology skills (question framing, pre-registration, verification-before-claiming, red-team review, …) — science-superpowers
• 503 profession-specific expert-reasoning skills (accelerator-physicist, zoologist, actuarial-scientist, …), converted from AGENTS.md profiles — scientific-agents
• 23 small-molecule/protein-therapeutics skills (autodock-vina, retrosynthesis, protein-binder-design, …) — drug-discovery-agent-skills
• a docx-editor-zotero skill (edit .docx files without breaking Zotero citations) — adapted from claude-scientific-writer
• an agentic-data-science-pipeline skill (plan/review/implement/verify/reflect loop for large multi-stage tasks) — adapted from agentic-data-scientist
• a hyperparameter-optimization skill (pre-registered, verify-before-claiming search loop for tuning a DL/LLM model) — adapted from karpathy
• a scientific-figure-making skill (publication matplotlib house style + helpers for bars/trends/heatmaps) — adapted from figures4papers
• a diagram-design skill (39 editorial HTML+SVG diagram types; no Mermaid slop) — vendored from diagram-design
• a generating-scientific-hypotheses skill (literature-grounded hypothesis generation: search-checked novelty, ranked falsifiable cards) — first-party, distilled from Gottweis et al. / Ghareeb et al. 2026 (see NOTICE)
• a paper2agent skill (turn a paper and/or its code repo into a reviewed paper skill and a tested FastMCP server) — vendored from Paper2Agent — see Paper agents

ACADEMIC_HARNESS_SKILLS_DIR (or a ~/scientific-agent-skills/skills checkout) still works as an override if you want a different catalogue instead — available on every preset; the old RESEARCHCRAFT_SKILLS_DIR name is still honored as a fallback

• notebook tool — log, read, and export a living lab notebook (JSONL under /.dsh/notebook/), shared across a subagent delegation tree, with a zip-bundle export alongside the plain Markdown one — every preset
• scientific_result tool — a structured, schema-validated "final finding" card (table or statistical-test), distinct from the notebook's running log — every preset
• Specialist briefs (code-reviewer, literature-researcher, …) for the DSH subagent tool, plus subagent_pro and subagent_vision — two more delegation tools pinned to a different model for unusually heavy reasoning and image-reading tasks respectively — see Subagent model routing — every preset
• image_generate tool for conceptual scientific figures (Gemini "nano banana" by default) — every preset
• sci_inspect tool for scientific file formats (chemistry, structure, mass spec, arrays, imaging, AnnData) — every preset
• latex_compile tool (.tex → PDF, bibtex/biber-aware) — every preset
• Academic Harness engine — writing oracle for LaTeX papers, grants, theses, literature reviews, and rebuttals: native ah_* tools, paper-state card, protected-path guard, post-edit checks, and a gate that settles a writing turn. The engine is vendored inside this plugin (vendor/academic-harness); Pi is not required. Inactive outside a tree with ah.yaml — Academic Harness preset only — see Academic Harness engine
• pdf_to_markdown tool (PDF → Markdown, via pdf-inspector) for literature-survey conversion of downloaded papers — every preset
• runpod_run (works with its API key) and modal_run (needs the optional modal SDK installed in the profile) for remote GPU/CPU compute offload, plus bundled modal/runpod skills covering the rest of each CLI (Serverless endpoints, volumes/secrets, Hub templates, …) — see Remote compute — every preset
• research_template tool over a ~330-template research-task catalogue (not DSH's Rhai workflow orchestrator) — every preset
• Literature and web search: a literature_search multi-source router plus OpenAlex, Semantic Scholar, Crossref, arXiv, PubMed/Europe PMC, CORE, Elicit, FutureHouse, Consensus, Parallel, Brave, Tavily, Exa, Perplexity, and Jina Reader (native REST tools), plus Parallel, Firecrawl, and Scite (MCP connectors), parallel_extract (URL extraction), and paper_download (Unpaywall open-access PDF resolver) — Academic Harness preset only
• paper_mcp tool — register a Paper2MCP stdio server from this workspace (/.dsh/paper-mcps.json) so its tools can appear as mcp____* — Academic Harness preset only — see Paper agents
• PaperMemory local academic memory: mcp__papermemory__* (search, ingest, cite, cite-check, recap, remember, claim). First Academic Harness start uses papermemory on PATH or installs the vendored package into ~/.dsh/papermemory. paper_download auto-ingests the saved PDF. Store: ~/.local/share/papermemory/papermemory.db — Academic Harness preset only — see Paper memory
• Workspace semantic search via zvec-grep: mcp__zvec_grep__zvec_grep_search (local BM25 + vectors). First Academic Harness start installs the zg CLI into ~/.dsh/zvec-grep. Indexing is off at session start by default (Settings → Index at session start); you can index later from chat, and the agent asks first when semantic search would help. While indexing, a progress bar with estimated time and Cancel is shown (no timeout) — exact lookup stays on native grep / glob — Academic Harness preset only — see Workspace search
• Bundled agent-browser skill for interactive web browsing (navigate, log in, fill forms, download datasets), with screenshots delegated to subagent_vision — see Browsing the web — every preset
• A Settings → Academic Harness API keys page for the connectors and models above — no shell env vars required. PaperMemory needs no key.

API keys

Every credential below (PARALLEL_API_KEY, FIRECRAWL_API_KEY, CONSENSUS_API_KEY, SCITE_API_KEY, BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, PERPLEXITY_API_KEY, JINA_API_KEY, CORE_API_KEY, ELICIT_API_KEY, FUTUREHOUSE_API_KEY, UNPAYWALL_EMAIL, OPENALEX_API_KEY, S2_API_KEY, CROSSREF_MAILTO, NCBI_API_KEY, NCBI_EMAIL, GEMINI_API_KEY, MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, RUNPOD_API_KEY, ZVEC_GREP_API_KEY) can be set two ways:

• Settings → Academic Harness API keys in the DSH web UI — type a key, Save. Persisted in the profile's settings.yaml; a blank field always means "keep the current value", Clear removes it.
• Shell environment variable — takes priority over Settings when both are set.

The same Settings page also has an Image model dropdown for IMAGE_MODEL — not a credential, so it isn't password-masked and applies immediately on selection rather than needing Save (see Image generation). It also has two more model-id dropdowns, Complex-task model (SUBAGENT_MODEL_COMPLEX) and Image-reading model (SUBAGENT_MODEL_VISION) — not credentials either, but these two behave like the MCP connectors below, not like Image model: they need a restart to apply (see Subagent model routing). zvec-grep embedding (ZVEC_GREP_EMBEDDING) is the same restart-needed dropdown: it is passed into zg server on at mount time. Index at session start (ZVEC_GREP_AUTO_INDEX, default No) is live for the next Academic Harness session — no restart (see Workspace search).

Tools that call resolveEnv() per invocation (image_generate, modal_run, runpod_run, consensus_search, parallel_search, parallel_extract, brave_search, tavily_search, exa_search, perplexity_search, jina_read, core_search, elicit_search, futurehouse_agent, paper_download, openalex_search, openalex_citations, s2_search, crossref_lookup, arxiv_search, pubmed_search, paper_resolve) pick up a Settings change on the very next call, no restart needed.

The MCP connectors (Parallel, Firecrawl, Scite, zvec-grep, PaperMemory) and the two subagent-model fields are different: the academic-harness agent preset mounts once as a standing composition shared by every chat session for the life of the running dsh process, so a change only reaches them after you stop and restart `dsh` itself — a new chat session on the same running process is not enough. consensus_search, parallel_search, and the academic database tools aren't MCP connectors — see below — so they don't have this restart requirement.

Also make sure the chat session is actually on the Academic Harness preset. The MCP connectors, native academic-search tools (literature_search, openalex_search, openalex_citations, s2_search, pubmed_search, arxiv_search, crossref_lookup, paper_resolve, consensus_search, parallel_search, parallel_extract, brave_search, tavily_search, exa_search, perplexity_search, jina_read, core_search, elicit_search, futurehouse_agent), mcp__zvec_grep__zvec_grep_search, and mcp__papermemory__* are wired into the academic-harness agent preset only; a session left on the default preset (Standard/PTC/etc.) has none of them, and calling one fails with tools[name] is not a function. Check the preset selector next to the session title (top of the message box for a new chat, top-left of an existing one) reads "Academic Harness" before asking the agent to search.

Workspace search

zvec-grep (zg) is the local-first hybrid search layer on the Academic Harness preset: BM25 + vectors over an on-disk index, exposed as mcp__zvec_grep__zvec_grep_search. Exact words, quotes, identifiers, filenames, regexes, and exhaustive hit lists stay on the preset's native grep / glob (@deepseek-ai/dsh-tool-fs-search). Open-web and literature search stay on the academic database tools (literature_search, openalex_search, s2_search, pubmed_search, arxiv_search, crossref_lookup), Parallel, Consensus, Firecrawl, and Scite — zg is workspace-only.

You do not install zg yourself. The first time the Academic Harness preset mounts after dsh plugin add, the plugin runs npm install --prefix ~/.dsh/zvec-grep @zvec/zvec-grep@^0.2.2, starts zg server on (the loopback daemon), and mounts search over Streamable HTTP at http://127.0.0.1:7999/mcp — no second restart. That first start can take several minutes (npm + later the ~130 MB Potion model). Later starts reuse ~/.dsh/zvec-grep, upgrade it if the bundled copy is older than 0.2.2, and start the daemon again. Stopping dsh runs zg server off, so the daemon does not stay up in the background. Override with ZVEC_GREP_CLI if you already have a zg binary you want to keep. If install or the daemon fails, the rest of the preset still loads and the search tool is absent (a warning is logged).

The plugin talks to the daemon over HTTP (DSH's MCP client is Streamable HTTP), not zg server --stdio. 0.2.2+ also fixes the stdio heartbeat race (zvec-grep#106); HTTP remains the mount we use.

Indexing is opt-in. Settings → Academic Harness API keys → Index at session start defaults to No. When No (the default), a new chat does not index; you can still type “index this workspace” in the chat, and whenever semantic search would help the agent asks first (and only indexes if you say yes). When Yes, opening an Academic Harness session indexes that workspace in the background if no index exists yet (zg index --embedding local/potion-retrieval-32m, local, no API key).

While an index runs — from session start or from chat — the UI shows a progress bar with estimated time in Settings and in the session header, and Cancel is always available. There is no timeout. Existing indexes are left alone (no silent rebuild/drop). Home directory and / are not indexed. Indexes live in /.zvec-grep/; the model cache is ~/.zvec-grep/models (~130 MB once).

zvec_index action=start accepts an exclude array of zg -g globs (for example ["!tmp/**", "!*.log"]). PaperMemory runtime paths under the index root — the store directory's corpus/, *.db* (SQLite + WAL/SHM), evidence/, and PAPERMEMORY_EVIDENCE_DIR — are excluded automatically. Still prefer a PAPERMEMORY_DB outside the indexed workspace; the automatic exclusions cover the accidental case. Exclusions apply when a job starts: if an index for the same root is already running, action=start joins it with its original globs rather than restarting.

zg is fail-soft, PaperMemory is fail-loud. If the zg install or daemon fails, semantic search is simply absent and a warning is logged; that says nothing about PaperMemory, which surfaces its own startup failure and 14-tool drift. Never read a missing zg tool as missing memory. Paper markdown in the workspace is indexed by zg for *discovery*; evidence for claims, numbers, and quotations always comes from PaperMemory (cite, quote_check, trace, get). Ingest stores a separate corpus copy, so keep the workspace file for zg and review — do not delete it after ingest.

# only if you want to index by hand or pick a different local model
zg index --embedding local/potion-retrieval-32m    # default — papers / notes / mixed
zg index --embedding local/potion-code-16m-v2      # smaller (~65 MB model), code-heavy trees
zg status --check-ready

Every MCP call needs an absolute root (the session working directory). Relative paths fail. The native zvec_index tool (start / status / cancel) is what the agent uses instead of shelling out to zg index.

Setting / env · What it does ZVEC_GREP_AUTO_INDEX · yes / no. Index this workspace when an Academic Harness session opens. Default no. Live for the next session (no restart). ZVEC_GREP_EMBEDDING · Default model id for *new* indexes. Unset means local/potion-retrieval-32m. Existing indexes keep their stored model. Restart dsh after changing — the next start brings up a fresh daemon with the new value. ZVEC_GREP_API_KEY · Not used with the default local Potion models. Only if you opt into a remote (Qwen) embedding provider. ZVEC_GREP_CLI · Absolute path to zg or to @zvec/zvec-grep's dist/cli/index.js. Env only.

The loopback daemon under ~/.zvec-grep/daemon/ is started with the Academic Harness preset and stopped when dsh exits. You do not need zg server off by hand.

Install, index, and routing details for the agent are in the bundled zvec-grep skill (skills/zvec-grep).

Academic and web search

Three literature/web MCP servers are wired into the academic-harness preset and surface as mcp__parallel__*, mcp__firecrawl__*, mcp__scite__* tools:

Connector · Key · Without it Parallel — mcp__parallel__web_search (search fallback, always basic) and mcp__parallel__web_fetch (read a URL) · PARALLEL_API_KEY (required) · Connector stays disabled. The key is always sent as a Bearer token so MCP calls are not on the anonymous rate limit. Firecrawl — firecrawl_scrape, firecrawl_search, firecrawl_parse · FIRECRAWL_API_KEY (required) · Connector stays disabled. Only these three tools are exposed; paper-index tools are not advertised. Scite — Smart Citations, retraction/correction checks, evidence datasets (patents, clinical trials, grants, drug safety, …) · SCITE_API_KEY (required) · Connector stays disabled

parallel_search is the primary Parallel search tool: a native REST call to POST /v1/search (x-api-key auth). It requires PARALLEL_API_KEY and a `mode` on every call. mcp__parallel__web_search is the same search job locked to basic — the agent is steered to use it only if parallel_search is missing or errors. mcp__parallel__web_fetch is for reading a specific URL, not for search. Pass objective, 1–5 keyword search_queries, and mode:

Mode · Latency · Best for turbo · ~250ms · Simple fact lookups, current numbers, high-volume pre-filtering. English and Japanese queries only. fast · ~700ms · Recommended default for most agent loops (interactive lookup, tool-calling). basic · ~1s · Longer excerpts per source; 2–3 high-quality queries. Same mode the MCP search tool always uses. advanced · ~3s · Multi-hop retrieval for literature surveys, deep research, code-review background.

The system prompt steers the agent to use both consensus_search and parallel_search (basic or advanced) for peer-reviewed literature, fast only for ordinary non-literature lookups, and mcp__parallel__web_search only as a fallback when parallel_search is unavailable. A Settings-changed PARALLEL_API_KEY takes effect on the next parallel_search call; the MCP connector s