{"slug":"local-env-setup","title":"local-env-setup","summary":"Configure the local wisp-science runtime — uv/Python bootstrap, Node+scimaster-cli for bear-* literature skills, pixi for bioinformatics multi-env analysis. Detect mainland-China network and apply mirrors. Use when Capabilities shows missing Python/uv/Node/sci/pixi, bootstrap err","platform":"Claude","tags":["linux"],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-23T08:58:31.091905Z","repo":{"url":"https://github.com/xuzhougeng/wisp-science","stars":1170,"forks":122,"license":"AGPL-3.0","updatedAt":"2026-09-25T06:13:53Z"},"bodyHtml":"
\n

name: local-env-setup\ndescription: Configure the local wisp-science runtime — uv/Python bootstrap, Node+scimaster-cli for bear-* literature skills, pixi for bioinformatics multi-env analysis. Detect mainland-China network and apply mirrors. Use when Capabilities shows missing Python/uv/Node/sci/pixi, bootstrap errors, or the user asks to 配置环境 / install Python / uv / Node / pixi / set up the local environment. Not for remote GPU/SSH compute (use compute-env-setup).\nlicense: Apache-2.0\ntags: bootstrap, uv, python, node, npm, pixi, scimaster, mirror, china, install, macos, windows, linux

\n

Local runtime setup

\n

wisp-science needs three independent local toolchains:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
LayerToolsPurpose
Coreuv + managed Python venvApp bootstrap, python tool, bundled MCP servers
LiteratureNode >= 20, npm, sci (scimaster-cli)Bundled bear-* skills (real paper search)
BioinformaticspixiPer-project conda/pip multi-env analysis (scanpy, workflow engines like snakemake/nextflow/oxo-flow)
\n

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.

\n

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

\n

Step 0 — Detect platform, region, and current state

\n

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

\n

0a — Region / network (mirror or not)

\n

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

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
SignalMainland likely
User writes in Chinese and mentions 国内 / 镜像 / 翻墙 / 清华 / 阿里yes
TZ / system timezone Asia/Shanghai, Asia/Chongqing, Asia/Urumqihint
Locale zh_CN, zh-Hans-CNhint
curl -s --connect-timeout 3 https://pypi.org/simple/ fails or >5s; tuna mirror responds in <2syes
User explicitly says they are not in China / have full international accessno
\n

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

\n

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

\n
# PyPI / uv (core bootstrap + pixi pip deps)\nexport UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple\nexport PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple\n\n# npm (scimaster-cli)\nnpm config set registry https://registry.npmmirror.com\n
\n

Windows (PowerShell, persist for user):

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

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

\n
[project]\nchannels = [\"https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/\"]\n\n[pypi-config]\nindex-url = \"https://pypi.tuna.tsinghua.edu.cn/simple\"\n
\n

Or global:

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

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

\n

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

\n

0b — Tool presence

\n

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

\n

Windows:

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

macOS / Linux:

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

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

\n

Layer 1 — Core: uv + Python

\n

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

\n

What gets created automatically

\n
    \n
  1. uv venv → virtualenv under app data
    2. \n
  2. uv pip install -r …/python/requirements-mcp.txt
    3. \n
  3. Marker .wisp_deps_ok when deps succeed
    4. \n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
OSDesktop 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
\n

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

\n

Install uv

\n

International:

\n
# Windows\npowershell -ExecutionPolicy Bypass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n
\n
# macOS / Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n
\n

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

\n
winget install --id astral-sh.uv -e          # Windows\n
\n
brew install uv                               # macOS\n
\n

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

\n

Python via uv

\n
uv python install 3.11\nuv python list\n
\n

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

\n

Manual bootstrap (auto-setup failed)

\n

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

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

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

\n

Verify core

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

Layer 2 — Literature: Node + scimaster-cli

\n

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

\n

Install Node >= 20

\n

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

\n

Mainland China:

\n
# Windows — winget often works; or npmmirror-hosted installer\nwinget install OpenJS.NodeJS.LTS\n
\n
# macOS — brew or fnm with npmmirror\nbrew install node\n# fnm alternative:\n# export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node\n# fnm install 20 && fnm use 20\n
\n

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

\n

scimaster-cli

\n

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

\n
npm install -g scimaster-cli\nsci init        # paste SciMaster API Key\nsci --version\nsci usage\n
\n

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

\n

In the wisp-science desktop app, you can also save the SciMaster key in\nSettings -> Credentials -> SCIMaster. Wisp will sync that key into\n~/.scimaster/config.json for scimaster-cli.

\n

Layer 3 — Bioinformatics: pixi

\n

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.

\n

Workflow engines

\n

For multi-step analysis pipelines (many rules, parallel execution, resume after failure), pair pixi with a dedicated workflow engine — pixi manages the environments, the engine schedules the steps. Run engines from shell in the project directory.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EngineWhat it isWhen to choose
snakemakePython-defined rules, mature conda/mamba integrationEstablished rules; Python-centric teams
nextflowGroovy DSL, container-firstnf-core ecosystem; HPC/cloud portability
oxo-flowRust-native, TOML-defined DAG engine; CLI + web UILightweight single-binary install; rule-level conda/mamba/pixi/docker/singularity backends; checkpoint/resume
\n

Install pixi

\n

International:

\n
curl -fsSL https://pixi.sh/install.sh | bash\n
\n
powershell -ExecutionPolicy ByPass -c \"irm -useb https://pixi.sh/install.ps1 | iex\"\n
\n

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

\n

Typical project workflow

\n

In the user's analysis directory:

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

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

\n

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

\n

Verify pixi

\n
pixi --version\npixi info    # shows config paths and channels\n
\n

Workarounds

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
IssueFix
uv/node installed but app still says missingRestart wisp-science; confirm tools on PATH for the GUI user (macOS: relaunch from Dock after shell profile update).
Cannot modify PATHSet UV_PATH / PIXI_PATH to full binary paths before launching wisp-science.
Mainland: timeouts on pypi.org / registry.npmjs.orgApply Step 0a mirrors; retry.
Corporate proxy / TLSHTTPS_PROXY, trust store; still use mirrors if direct egress to US is blocked.
Corrupt core venvDelete python/.venv under app data; restart (bootstrap recreates).
bear-* skill stops at CLI checkInstall Node + scimaster-cli + sci init; do not fake citations.
\n

Agent workflow

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

Not in scope

\n\n","files":[{"path":"SKILL.md","sizeBytes":13360,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-09-08T11:59:44.271845Z","sha256":"EFC5D6693274CABF432AC249E68A427FC040216BB94D2E77D6343A4A5BF2F037","sizeBytes":5758},"review":null,"source":{"repositoryUrl":"https://github.com/xuzhougeng/wisp-science","path":"skills/local-env-setup","license":"AGPL-3.0","commit":"79e64163262196611dd390d06713c465b906b299","subtreeSha":"A2748BB13E260D839204DFA82888E7251AF35FF11DF4687EB83A712112F384D5","lastSyncedAt":"2026-09-25T07:37:55.552497Z"},"reviewedAt":"2026-09-08T12:03:02.892933Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/xuzhougeng/wisp-science/tree/main/skills/local-env-setup"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install xuzhougeng-wisp-science@llmmart"},{"target":"git","command":"git clone https://github.com/xuzhougeng/wisp-science.git"}]}