Local Env Setup

Local runtime setup

wisp-science needs three independent local toolchains:

| Layer | Tools | Purpose |

|---|---|---|

| Core | uv + managed Python venv | App bootstrap, python tool, bundled MCP servers |

| Literature | Node >= 20, npm, sci (scimaster-cli) | Bundled bear-* skills (real paper search) |

| Bioinformatics | pixi | Per-project conda/pip multi-env analysis (scanpy, nextflow-adjacent stacks, etc.) |

Core is required for the app. Literature and bioinformatics layers are optional until the user runs those skills — but Capabilities shows all of them; install what's missing for the user's goal.

Restart wisp-science after changing PATH or global config so bootstrap re-runs.

Step 0 — Detect platform, region, and current state

Read the Environment section in the system prompt (Operating system, Working directory).

0a — Region / network (mirror or not)

Before any install or pip/npm/pixi add, decide whether the user is on mainland China and needs mirrors.

Signals (use several; do not rely on one):

| Signal | Mainland likely |

|---|---|

| User writes in Chinese and mentions 国内 / 镜像 / 翻墙 / 清华 / 阿里 | yes |

| TZ / system timezone Asia/Shanghai, Asia/Chongqing, Asia/Urumqi | hint |

| Locale zh_CN, zh-Hans-CN | hint |

| curl -s --connect-timeout 3 https://pypi.org/simple/ fails or >5s; tuna mirror responds in <2s | yes |

| User explicitly says they are not in China / have full international access | no |

If ambiguous, ask once: "Are you on mainland China? I'll use domestic mirrors for pip/npm/conda if yes."

When mainland mirrors apply, set these before installs (user shell profile or session env):

# PyPI / uv (core bootstrap + pixi pip deps)
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

# npm (scimaster-cli)
npm config set registry https://registry.npmmirror.com

Windows (PowerShell, persist for user):

[Environment]::SetEnvironmentVariable("UV_INDEX_URL", "https://pypi.tuna.tsinghua.edu.cn/simple", "User")
[Environment]::SetEnvironmentVariable("PIP_INDEX_URL", "https://pypi.tuna.tsinghua.edu.cn/simple", "User")
npm config set registry https://registry.npmmirror.com

Pixi conda channels (global or per-project pixi.toml):

[project]
channels = ["https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/"]

[pypi-config]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

Or global:

pixi config set --global pypi-config.index-url https://pypi.tuna.tsinghua.edu.cn/simple

Alternatives if tuna is slow: Aliyun PyPI https://mirrors.aliyun.com/pypi/simple/, USTC conda mirrors.

If international access works, do not set mirrors — use defaults.

0b — Tool presence

Run with shell (PowerShell on Windows, sh -c elsewhere):

Windows:

Get-Command uv,node,npm,sci,pixi -ErrorAction SilentlyContinue | Select-Object Name,Source
uv --version 2>$null; node --version 2>$null; npm --version 2>$null; sci --version 2>$null; pixi --version 2>$null

macOS / Linux:

for c in uv node npm sci pixi; do command -v $c && $c --version 2>/dev/null; done

Capabilities (能力) shows: Python · uv · Node · sci · pixi · skills · MCP.

Layer 1 — Core: uv + Python

wisp-science does not ship Python. It needs uv on PATH (or UV_PATH) to create the managed venv.

What gets created automatically

• uv venv → virtualenv under app data
• uv pip install -r …/python/requirements-mcp.txt
• Marker .wisp_deps_ok when deps succeed

| OS | Desktop venv path |

|---|---|

| Windows | %APPDATA%\science.wisp-science\wisp-science\python\.venv |

| macOS | ~/Library/Application Support/science.wisp-science/wisp-science/python/.venv |

| Linux | ~/.local/share/science.wisp-science/wisp-science/python/.venv |

Dev checkout: <workspace>/.wisp/python/.venv

Install uv

International:

# Windows
powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Mainland China: prefer winget / Homebrew / distro package if the astral installer is slow or blocked; set UV_INDEX_URL (above) before uv pip install.

winget install --id astral-sh.uv -e          # Windows

brew install uv                               # macOS

Default binary: ~/.local/bin/uv (Unix) or %USERPROFILE%\.local\bin\uv.exe (Windows). Ensure that dir is on PATH.

Python via uv

uv python install 3.11
uv python list

Target: Python 3.11+. With mainland mirrors, export UV_INDEX_URL first.

Manual bootstrap (auto-setup failed)

Set REQ to <repo>/python/requirements-mcp.txt or bundled copy. With mirrors:

export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple   # if mainland
uv venv "$APP_DATA/python/.venv"
uv pip install -r "$REQ" --python "$APP_DATA/python/.venv/bin/python"

Windows: same with $env:UV_INDEX_URL and Scripts\python.exe.

Verify core

uv --version
# managed venv:
python -c "import mcp, pandas; print('ok')"

Layer 2 — Literature: Node + scimaster-cli

Required for bundled bear-support, bear-counter, bear-map, bear-scoop, bear-trace, bear-review, bear-onboard, bear-propose.

Install Node >= 20

International: https://nodejs.org/ LTS, or winget install OpenJS.NodeJS.LTS, or brew install node.

Mainland China:

# Windows — winget often works; or npmmirror-hosted installer
winget install OpenJS.NodeJS.LTS

# macOS — brew or fnm with npmmirror
brew install node
# fnm alternative:
# export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node
# fnm install 20 && fnm use 20

After install, open a new terminal; verify node --version (v20+).

scimaster-cli

Set npm registry first if mainland (see 0a), then:

npm install -g scimaster-cli
sci init        # paste SciMaster API Key
sci --version
sci usage

API Key: SciMaster settings → API Key. Do not proceed with bear-* skills if sci --version fails.

In the wisp-science desktop app, you can also save the SciMaster key in

Settings -> Credentials -> SCIMaster. Wisp will sync that key into

~/.scimaster/config.json for scimaster-cli.

Layer 3 — Bioinformatics: pixi

pixi manages isolated per-project environments (conda + pip) — use for scanpy/single-cell, variant calling stacks, etc. The wisp python tool uses the core uv venv; run bioinfo code via shell: pixi run python … or pixi run … in the project directory.

Install pixi

International:

curl -fsSL https://pixi.sh/install.sh | bash

powershell -ExecutionPolicy ByPass -c "irm -useb https://pixi.sh/install.ps1 | iex"

Mainland China: if install script is slow, try brew install pixi (macOS) or download release from GitHub mirror; then configure mirrors (0a).

Typical project workflow

In the user's analysis directory:

pixi init
pixi add scanpy anndata          # example; adjust to task
pixi run python analysis.py

Multiple envs: use environments] / features in pixi.toml, or separate project dirs — see [pixi docs.

With mainland mirrors, set [pypi-config] and channels in pixi.toml (0a) before large pixi add.

Verify pixi

pixi --version
pixi info    # shows config paths and channels

Workarounds

| Issue | Fix |

|---|---|

| uv/node installed but app still says missing | Restart wisp-science; confirm tools on PATH for the GUI user (macOS: relaunch from Dock after shell profile update). |

| Cannot modify PATH | Set UV_PATH / PIXI_PATH to full binary paths before launching wisp-science. |

| Mainland: timeouts on pypi.org / registry.npmjs.org | Apply Step 0a mirrors; retry. |

| Corporate proxy / TLS | HTTPS_PROXY, trust store; still use mirrors if direct egress to US is blocked. |

| Corrupt core venv | Delete python/.venv under app data; restart (bootstrap recreates). |

| bear-* skill stops at CLI check | Install Node + scimaster-cli + sci init; do not fake citations. |

Agent workflow

• use_skill this file when Capabilities or bootstrap reports missing tools.
• Step 0a first — detect mainland vs international; configure mirrors before any download.
• Detect OS — PowerShell on Windows, sh elsewhere.
• Install missing layers in order: core (uv) → literature (Node+sci) → bioinfo (pixi) as needed.
• Verify each layer; tell user to restart wisp-science after PATH/config changes.
• Finish with attempt_completion: region/mirror choice, what was installed, paths checked, Capabilities expectations.

Not in scope

• Remote GPU or direct SSH → compute-env-setup; managed cloud backends are

unavailable until Wisp implements a matching execution-context backend

• Replacing pixi with conda/micromamba when pixi suffices locally
• SciMaster API billing / key provisioning beyond pointing to sci init