dsh-bio-genie

中文 | English

Wish-style bioinformatics analysis plugin for DeepSeek Harness (dsh)

dsh bio analysis · dsh biology analysis · deepseek harness bioinformatics · Biopython · sequence analysis · genomics

Speak plainly, get results. Users describe their bioinformatics needs in natural language, and the dsh agent performs the analysis automatically.

Install and go — no Python or Biopython installation required. The plugin bootstraps a fully isolated Python environment on first run.

✨ Features

📦 Installation

This plugin is published as the npm package @dsh-bio/dsh-bio-genie. Install it with the standard dsh dsh plugin command (written below as npx -y @deepseek-ai/dsh, which needs no global install — only Node/npm; if you already installed the dsh CLI globally, replace the whole npx -y @deepseek-ai/dsh prefix with dsh):

# Option 1: Install from npm (recommended, prebuilt code)
npx -y @deepseek-ai/dsh plugin --profile web add @dsh-bio/dsh-bio-genie

# Option 2: Install from GitHub (fetches source; this plugin is pure ESM with no build step, loads directly)
npx -y @deepseek-ai/dsh plugin --profile web add github:moonbowterfly/dsh-bio-genie

# Option 3: Install from a local directory (local source)
npx -y @deepseek-ai/dsh plugin --profile web add ./dsh-bio-genie

--profile <name> is mandatory (required option '--profile <name>' not specified otherwise); use web for the web app.

Engine compatibility: on DSH 0.2.0+ (incl. the official desktop app) the plugin installs with zero version exemptions (relaxed peers ^0.1.0-rc.6 || ^0.2.0-rc.1) and the bio-genie preset ships with the plugin itself (no post-steps needed). On DSH 0.1.x everything keeps working through the postinstall file-based preset. Both engines verified on real machines (2026-10-01).

Restart the dsh web service to activate. On first startup the plugin bootstraps the Python environment in the background (download uv → Python 3.12 → venv → biopython, ~1-2 min); subsequent starts are ready in seconds.

Verify the plugin layer is active (no boot needed):

npx -y @deepseek-ai/dsh --profile web --dump-config   # output should contain a "# == dsh-bio-genie" layer

Troubleshooting: profile already contains local packages that break pnpm validation

If your profile already has locally installed packages not on the npm registry (e.g. skin plugins), dsh plugin add may fail with ERR_PNPM_FETCH_404 during the full pnpm resolution. In that case, mount manually (verified to work):

mkdir -p ~/.dsh/profiles/web/node_modules/@dsh-bio/dsh-bio-genie
cd /path/to/dsh-bio-genie
cp -r src index.js cordis.patch.yml package.json skills prompts python docs \
  README.md README.en.md LICENSE THIRD_PARTY_NOTICES.md \
  ~/.dsh/profiles/web/node_modules/@dsh-bio/dsh-bio-genie/

Then in ~/.dsh/profiles/web/package.json:

• Add to dependencies: "@dsh-bio/dsh-bio-genie": "file:.../dsh-bio-genie"
• Add to dsh.profile.bundles: "@dsh-bio/dsh-bio-genie"

Finally restart the dsh web service.

🛠 Tool Overview

Executor (covers 100% of Biopython)

Semantic Tools (high-frequency stable operations)

Automatic Sequence-Type Detection

bio_seq_analyze defaults seq_type to auto, auto-detecting three types:

• Contains U but no T → RNA
• Contains IUPAC ambiguity codes (R/Y/S/W/K/M/B/D/H/V), X (unknown/modified base), or alignment gap chars (-/.) → DNA (primer/probe/SNP/alignment safe)
• Contains non-nucleic letters → Protein

X and gaps are treated as unknown bases during translation (Biopython standard behavior); sequences containing X/gaps never crash on ambiguous codons.

📚 Skill System (52 total)

Master skill: dsh-bio-genie

Tool-layering decision tree: check the semantic tool table first → use it if matched; otherwise write Biopython code with the bio_python executor.

17 Domain Recipes + 5 Research Methods

Research-method skills: bio-survival-analysis, bio-variant-analysis, bio-literature-review (incl. PRISMA 2020 systematic-review workflow), bio-evidence-appraisal (evidence hierarchy / GRADE / claim-strength wording), bio-paper-writing. Plus 21 protocol templates and 8 agent guides bundled with the plugin.

🧞 Genie Expert Persona (bio-genie preset)

This plugin also ships a dsh agent preset — bio-genie — that turns the AI into a biological-data genie expert from the moment a session starts.

What it is

• Persona source files (preset/bio-genie/: preset.yml + agent.cordis.yml + skills/) — override the base persona, telling AI: "you have 72 tools + 52 skills at hand"; the preset section of cordis.patch.yml is generated from this directory by scripts/build-preset-patch.mjs (single source of truth; do not hand-edit the generated file).
• Onboarding mantra (skills/dsh-bio-genie-expert.md) — a meta-skill: "1. Inspect workspace → 2. Pick semantic tool / bio_python → 3. Fail by ACR three-layer repair → 4. Report with traceable chain".
• One-shot install: on DSH 0.2.0+ the preset is shipped by the plugin’s own declaration (available immediately after install, zero post-steps); on DSH 0.1.x the postinstall hook copies the preset to ~/.dsh/.agent-presets/bio-genie/ (requires approving the build script — see the Chinese README’s 「安装后批准构建脚本」 section).

What it is not

• ❌ Does NOT own the 72 tools — every bio_* / design_* tool is still injected by the plugin's cordis.patch.yml; the preset does not redeclare any tool to avoid conflicts.
• ❌ Does NOT change the default persona — after installation, "生物基因精灵" appears in dsh's preset selector; users actively pick it to activate. agent-presets.default is not changed to bio-genie.
• ❌ Does NOT break other plugins — presets and plugins are two independent seams in dsh; they coexist without conflict.

How to use

1. Install this plugin: pnpm add @dsh-bio/dsh-bio-genie (on 0.2.0+ the preset comes with the plugin; on 0.1.x see the build-script approval note).
2. Restart dsh web.
3. Settings panel → select "生物基因精灵" persona.
4. The AI now opens each session with: "I'm the biological-data genie… your working directory is {{cwd}}… let me see what data you have first".

Manual install / uninstall

# Manual copy (for 0.1.x only; 0.2.0+ usually does not need this — the preset comes from the plugin declaration)
node scripts/install-preset.js

# Force overwrite (overrides user-edited preset files)
node scripts/install-preset.js --force

# Dry run (only show what would happen)
node scripts/install-preset.js --dry-run

# Uninstall: delete the directory
#   Windows: rd /s /q %USERPROFILE%\.dsh\.agent-presets\bio-genie
#   macOS/Linux: rm -rf ~/.dsh/.agent-presets/bio-genie

Troubleshooting

• Preset selector doesn't show "生物基因精灵":
  • 0.2.0+: make sure the plugin version is >= 0.6.37 and loaded (dsh --profile <p> --dump-config should contain a preset-bio-genie row); restart dsh once.
  • 0.1.x: check ~/.dsh/.agent-presets/bio-genie/preset.yml exists; otherwise run node scripts/install-preset.js manually.
• After switching to preset, tools are missing → tools are injected by the plugin, not the preset; double-check the plugin is in dependencies (pnpm ls @dsh-bio/dsh-bio-genie).
• Customize persona:
  • 0.2.0+: override by row id preset-bio-genie in the profile's cordis.patch.yml (override config.plugins).
  • 0.1.x: edit ~/.dsh/.agent-presets/bio-genie/agent.cordis.yml directly (not auto-overwritten unless --force).

🚀 Usage Examples

Scenario 1: Semantic tool path (high-frequency operations)

User: "Analyze the GC content and EcoRI sites of the sequences in this file: D:/data/genes.fasta"

Agent automatically:
1. bio_seq_io_read        → read FASTA
2. bio_seq_analyze        → GC content per sequence
3. bio_seq_restriction    → check EcoRI
4. Summary report + biological interpretation

Scenario 2: Executor path (features not covered by semantic tools)

User: "Draw a protein structure alignment of these two genes"

Agent automatically:
1. Load bio-align / bio-structure skills
2. bio_python writes and runs a Biopython program
3. Produce files + report

Scenario 3: Combined path (verified in practice)

User: "Read the FASTA and analyze each sequence's GC, longest ORF and EcoRI sites"

Agent automatically (measured behavior):
1. Load dsh-bio-genie master skill (decision guidance)
2. bio_seq_io_read reads the file
3. bio_python completes GC + ORF + restriction analysis in one pass
4. Output summary table (GC 48.28%, ORF 7 aa, EcoRI nt 3-8) + biological interpretation

🔧 Environment Bootstrap (Zero-Dependency Self-Provisioning)

On first tool call (or background warm-up at dsh startup) the plugin automatically:

1. Download uv            → $DSH_HOME/dsh-bio-genie/bin/uv
   (official GitHub; auto-fallback to Tsinghua PyPI uv wheel on failure, ~18MB/2s)
2. uv python install      → $DSH_HOME/dsh-bio-genie/python/ (private CPython 3.12)
   (auto-fallback to npmmirror python-build-standalone on failure)
3. uv venv --seed         → $DSH_HOME/dsh-bio-genie/python-env/ (pip preinstalled for on-demand packages)
4. uv pip install         → biopython + numpy + matplotlib + reportlab (auto-fallback to Tsinghua PyPI on failure)

• Auto network adaptation: each step tries official sources first, then automatically switches to domestic mirrors — zero configuration required. Power users can override mirrors via DSH_BIO_UV_BASE / DSH_BIO_PYTHON_MIRROR / DSH_BIO_PYPI_INDEX (uv's official UV_PYTHON_INSTALL_MIRROR / UV_DEFAULT_INDEX / UV_INDEX_URL are respected too)
• Everything lives under $DSH_HOME/dsh-bio-genie/ (default ~/.dsh/dsh-bio-genie/); delete it to fully uninstall
• Assumes no system Python/uv (self-provisioning); falls back to system python (if present) on bootstrap failure
• Plugin upgrades don't lose the environment: it lives in the DSH_HOME private directory, separate from the plugin itself (node_modules)
• Idempotent: ready environments reuse in seconds; failed bootstraps auto-retry
• First bootstrap needs network; semantic tools work offline afterwards

🔄 Compatibility

🧩 Development

Pure ESM JavaScript, no build step, edit-and-run:

git clone https://github.com/moonbowterfly/dsh-bio-genie
# Invoke the bootstrapper directly (first run downloads the environment, ~1-2 min):
node --input-type=module -e "import('./src/runtime.js').then(m => m.ensureEnvironment({}))"

• Architecture: see docs/ARCHITECTURE.md
• Agent manuals: docs/agent-guide/ — 8 guides (overview / tool reference / skill navigation / bio_python programming / workflows / plotting / troubleshooting / rigor), registered as dsh-bio-genie-guide-* skills for the dsh agent
• Add a semantic tool: add an op in python/bio_ops.py + a bioTool entry in src/tools.js
• Add a domain skill: skills/bio-xxx.md + a SKILL_MANIFEST entry in src/skills.js
• Skill language convention: every skill (domain/protocol/guide) must declare a language: field in its leading frontmatter (python / r / mixed / none); enforced by test-skills.mjs

📄 License

• dsh-bio-genie itself: MIT License
• Biopython: Biopython License Agreement / BSD 3-Clause (permissive, see THIRD_PARTY_NOTICES.md)
• numpy: BSD License
• scipilot-figure-skill (figurelib plotting scripts): MIT (Copyright Haojae, see THIRD_PARTY_NOTICES.md)
• K-Dense scientific-agent-skills (figurelib style assets + knowledge protocol sources): MIT (Copyright K-Dense Inc., see THIRD_PARTY_NOTICES.md)
• BioSQL intentionally excluded (LGPL)

🙏 Acknowledgements

All of this project's biological computing power stands on Biopython — our thanks to the biopython/biopython project and all its contributors for 25 years of outstanding work. The high-quality implementations they maintain — sequence analysis, alignment, structural biology, phylogenetics and more — make "wish-style bioinformatics" possible. Biopython is released under the permissive Biopython License Agreement (BSD 3-Clause compatible), which allows free copying, modification and redistribution, so this plugin can rely on and promote it with confidence.

We also thank DeepSeek Harness for its plugin-based agent framework, and the numpy community for its foundational contributions.

The publication-grade plotting stack (figurelib) is inspired by Haojae/scipilot-figure-skill (MIT) — its "visualization consultant" workflow and visual QA design — while style assets and some knowledge protocols reference K-Dense-AI/scientific-agent-skills (MIT). Our thanks to both.