wisplab-cli

中文 | English · 上手指南 · Getting started

WispLab 的本地命令行与 MCP 接口，用于 Western blot、IHC/组织染色、IF 双通道共定位和 qPCR 分析。它调用你配置的三个 WispLab 仓库中的分析代码，让脚本和 AI 助手使用同一套引擎，并输出 JSON 结果。

English: A local CLI and MCP interface for Western blot, histology, immunofluorescence colocalization, and qPCR analysis, powered by the configured WispLab engine repositories. Read the full English documentation →

能做什么

CLI 与 MCP 共用 lib.mjs。WB/qPCR 由对应仓库的 tsx 运行；IHC/IF 通过本地 Vite 和 Playwright Chromium 调用浏览器引擎。桥接包本身没有 npm 运行依赖，但三个引擎及 Chromium 必须单独安装。运行的是本地配置的修订，更新本仓库不会自动更新引擎。

Related MCP server: DJAI Tools MCP

快速开始

需要 Git、Node.js ≥ 22.12，以及三个引擎所要求的运行环境。完整依赖安装与 AI 客户端设置见上手指南。

git clone https://github.com/Gaoyuan-0423/wisplab-cli.git
cd wisplab-cli
node scripts/setup-engines.mjs --root ../wisplab-verified-engines --config ./wisplab.config.json
node cli.mjs doctor --strict
node cli.mjs --help
npm link                 # 可选：启用 wisplab 命令

# WB：6 泳道，手工选定目标面板范围，以泳道 1 为对照
wisplab wb blot.png --strip "140,85,160,350" --lanes 6 --bg rolling:50 --control 1

# qPCR：先检查解析；内参和对照名称必须与数据表一致
wisplab pcr-preview plate.csv
wisplab pcr plate.csv --ref GAPDH --control C1,C2
wisplab pcr plate.csv --ref GAPDH --control C1 --eff "LDHA=92;GAPDH=99"

# IHC：对照片标定限 H-DAB；导出核中心和本地复核图
mkdir -p ./reviews
wisplab ihc section.tif --profile h_dab --nuclei --review-dir ./reviews
wisplab if duplex.png --channels R,B --review-dir ./reviews

# 已有 IHC 分析和参考值的离线比较；无需配置或安装引擎
wisplab ihc-validate result.json reference.json

安装脚本读取 engines.lock.json，在新目录安装固定修订及依赖，并创建新配置；已有目录或配置不会被覆盖。已有引擎可继续手工配置，详见固定版本安装。

--strip y,h,x0,x1 使用原图像素坐标，h 为高度，x1 为右边界；选区应保留背景余量并排除 marker、文字和其他面板。--control 对 WB 是从 1 开始的泳道号，对 qPCR 是逗号分隔的样本名。逐文件分析错误会使 CLI 退出码为 1，MCP 返回 isError: true，同时保留 JSON 结果。即使执行成功，也应检查 warnings。

配置

配置优先级：--config <path> → WISPLAB_CONFIG → 当前目录的 wisplab.config.json → CLI 目录的同名文件。显式指定的配置不存在时会报错。配置中的 repos 和 allowPaths 支持 ~；相对路径以配置文件所在目录为基准。

{
  "repos": {
    "wb": "../blot-workbench",
    "ihc": "../pathology-workbench",
    "pcr": "../pcr-workbench"
  },
  "ihc": { "devPort": 5173 },
  "allowPaths": ["~/data", "/tmp"]
}

allowPaths 限制 MCP 输入和图像复核输出目录，包括对照片和验证材料；校验解析符号链接后的实际路径。CLI 是直接执行的本地命令，不套用这层 MCP 限制。IHC/IF 启动的 Vite 只监听 127.0.0.1；端口冲突时修改 ihc.devPort。

MCP 与 AI 技能

ihc-validate 是独立的本地 CLI 命令，不读取 wisplab.config.json 或 WISPLAB_CONFIG。其 ungraded 状态仅表示比较完成，不能视为验证通过。

六个工具：wb_quantify、ihc_quantify、if_colocalize、pcr_preview、pcr_analyze、pcr_verify。使用 stdio 传输；IHC/IF 调用会等待分析完成后返回结果。支持 2026-07-28 的 server/discover 与请求元数据，并保留旧客户端的 initialize 协商。

{
  "mcpServers": {
    "wisplab": {
      "command": "node",
      "args": ["/path/to/wisplab-cli/mcp-server.mjs", "--config", "/path/to/wisplab.config.json"]
    }
  }
}

仓库的 skills/ 提供四个可选 AI 技能。安装方法见上手指南。AI 助手可以把自然语言转换成命令，但仍需正确的内参、对照、图像通道和实验设计信息。

分析计算在本机执行；AI 客户端可能把工具返回的结果、提示词或你附加的图像发送给模型服务商。MCP 路径限制并不控制客户端的数据传输，请按所用客户端的设置管理这些内容。

核查、更新与复现

0.8 能力与限制见下方专题指南和 CHANGELOG；2026-10-30 核查报告 保留为历史记录。真实人工 IHC 准确性验证仍待独立标注完成，不能用合成测试或厂商图回归替代。

npm test
npm run check
wisplab doctor > environment.json

doctor 区分依赖可用性 ready 和匹配干净锁定修订的 verified；doctor --strict 要求后者。它不联网判断“是否最新”，也不代替科学算法验证。更新引擎前保存当前 Git 修订和输入/参数，阅读对应仓库的变更；更新后重新安装其锁定依赖，再执行诊断和自己的参考数据回归。

最初 README 中的 2026-10-18 M1/M3/M4 数字是历史验证记录，依赖特定数据、参数和引擎版本，不能作为当前任意版本全部通过校准的证明。本仓库的自动化测试验证桥接行为；科学数值一致性应结合固定输入和对应引擎的验证材料重新检查。

wisplab verify-pcr /path/to/validation 需要另行获取可信的 dump_app.ts、reference_check.py、相应数据和 Python 环境；它会执行这些脚本。wisplab grade <pcr|ihc|wb|synthetic16> submission.json 需要旁边的 ../wisplab-benchmark/grade.mjs 及其基准材料。它们均不包含在本仓库内。

当前边界

• WB 输出相对指定泳道的比值，不自动完成目标蛋白/上样内参的双重归一化。需要原始 PNG/TIFF；JPEG 转成 TIFF 不能恢复压缩时丢失的信息。

• IHC 支持从清单导入原图像素矩形 ROI、--mpp 和 --nuclei；未暴露全部分割设置或模型选择。IF 仍为整图，不支持 ROI。核强度 H-score 不是通用临床评分；没有可信 mpp 时不能解释每 mm² 密度。

• 病理引擎对超过 4096 像素边长的图像降采样，16 位 TIFF 转为 8 位工作像素；WB 的 8/16 位图像流程与此不同。

• IF 用 --channels R,B 等参数选择两个不同 RGB 通道，默认 R/G；不提供任意光谱通道或手工阈值。伪彩图需核实实际通道含义。

• qPCR 显式分组仍限单文件；非配对用 Welch，显式 --paired --pair-ids 用完整配对的 t 检验，不推断配对、不提供一般重复测量模型或跨板校正。95% 区间未作多重校正，p 值另作 Holm 校正。优先解读 primaryAnalysis；分组失败不得回退到逐孔统计。Excel 可按名称选表，省略时默认首表，不自动合并。

• IHC/IF 可导出本地 PNG、HTML 和结果 JSON；叠加显示阳性染色/通道信号，不是核轮廓。WB 复核图仍使用上游界面。原图点选标注包目前支持 PNG/JPEG，TIFF 须使用符合坐标/哈希规范的外部标注流程。空间比较不提供 Dice/IoU；compared 只表示比较完成，不表示精度达标。

分析默认整批时限 5 分钟，IHC/IF 单图 2 分钟，可用 --timeout-ms / --file-timeout-ms 调整。进度写 stderr；MCP 仅在请求提供进度 token 时通知，支持取消且 ping 保持响应。超时、部分失败与清理边界见运行控制。

问题与变更通过 Issues 和 Pull requests 记录。许可证见 LICENSE。

质控参数与排除规则 / QC and exclusion policy: 说明 / Guide.

分析追溯 / Analysis provenance: 格式与边界 / Format and limits.

真实引擎回归 / Real-engine regression: 安装、固定版本与合成数据 / Setup, pinned revisions and fixtures.

单个内参即可进行 qPCR 分析（例如 --ref GAPDH）；多个内参为可选功能。 / One reference gene is sufficient (for example --ref GAPDH); multiple reference genes are optional.

生物学分组 / Biological groups: Guide.

0.8.1 计算修正：逐基因效率与缺失结果边界。单个内参继续支持。

IHC 参考值与本地厂商图复核 / Reference comparisons and local vendor checks: Guide.

0.8 使用说明 / 0.8 guides: 导入与配对 / Import and pairing · 图像 ROI 与复核 / Image review · 独立核标注 / Independent annotations · 时限与取消 / Runtime controls · 锁定引擎安装 / Verified engines.