🧬 dsh-bio-genie

<div align="center">

中文 | English

</div>

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:

# Option 1: Install from npm (recommended, prebuilt code)
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)
dsh plugin --profile web add github:moonbowterfly/dsh-bio-genie

# Option 3: Install from a local directory (development)
dsh plugin --profile web add ./dsh-bio-genie

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

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 (22 total)

Master skill: dsh-bio-genie

Tool-layering decision tree + dual-engine routing table: check the semantic tool table first → use it if matched; otherwise pick the engine (Python/R) and write code.

21 Domain Recipes (15 Python + 6 R)

---

🧞 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 files (preset/bio-genie/preset.yml + agent.cordis.yml) — override the base persona, telling AI: "you have 23 tools + 51 skills + two engines at hand".
• Onboarding mantra (skills/dsh-bio-genie-expert.md) — a meta-skill: "1. Inspect workspace → 2. Pick tool / bio_python / bio_r → 3. Fail by ACR three-layer repair → 4. Report with traceable chain".
• One-shot install: pnpm install runs postinstall hook to copy the preset to ~/.dsh/.agent-presets/bio-genie/; no manual steps.

What it is not

• ❌ Does NOT own the 23 tools — every bio_* 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 postinstall, "生物基因精灵" 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 (postinstall handles the preset copy). 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 (when postinstall fails)
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 "生物基因精灵" → 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 → 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

| Dimension | Requirement | |-----------|-------------| | Node | ^22.19 \|\| >=24 (same as dsh) | | dsh | Peer deps @deepseek-ai/dsh-tools etc. at ^0.1.0-rc.6, matching the current dsh source-tree build. If your host dsh is the older npm latest (0.0.1-rc.1), two copies of dsh-tools may resolve and cause type mismatches — use a dsh built from the source repository | | Platform | Windows / macOS / Linux (x86_64 / arm64); platform-appropriate uv/Python is downloaded automatically |

---

🧩 Development

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

git clone https://github.com/dsh-bio/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](docs/ARCHITECTURE.md)
• Agent manuals: [docs/agent-guide/](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](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)
• R / Bioconductor ecosystem: GPL-2|GPL-3 (R core) / Artistic-2.0 / MIT / LGPL-3 / GPL-2 / AGPL-3 (phyloseq) — runtime-install + API-call model with zero source redistribution; per-package license table and compliance rationale in 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.