单细胞分析工作台 Sculptor815/scrna-seq-workbench

scRNA-seq Workbench

版本 0.4.0 — 带知识库 · 研究预览版。

面向 Codex、Claude Code 和 DeepSeek Harness 的单细胞 RNA-seq 分析插件。Workbench 把可执行的分析工具和内置知识库结合起来，知识库覆盖研究设计、质量控制、scVI、细胞注释和差异表达。

分析工作流

从你的数据或一个生物学问题开始。智能体会检查样本之间的关系，确定哪些数据集要放在一起分析，然后运行相应的阶段。

| 阶段 | 技能 | 主要输出 |
| 研究筛选与探索 | scrna-research | 相关研究、实验背景和表达汇总 |
| 测序报告审查 | sequencing-report-review | 测序指标和交付检查 |
| 质量控制 | scrna-qc | QC 图、过滤记录、适用时的双细胞评估，以及过滤后的 counts |
| 表征与聚类 | scrna-scvi-umap | scVI 模型或选定的 Harmony 嵌入、细胞周期诊断、候选聚类和 UMAP |
| 细胞注释 | scrna-cell-annotation | Marker 表达、候选细胞类型和人工复核记录 |
| 条件比较 | scrna-condition-de | 供体水平的 pseudobulk counts 和差异表达结果 |

新的表征工作流默认使用 scVI 加细胞周期协变量，有无技术批次都适用。如果技术批次已经过验证，用户可以明确选择 Harmony；这条路线在 PCA 之前回归掉细胞周期得分。原始 counts 和完整保留的基因集都会保留下来。

会给出多个邻居数和 Leiden 分辨率供选择。注释依据组织特异的 marker 证据和 HPA 引导的复核，对未解决的细胞群还会做进一步排查。最终标签需要人工复核；条件 DE 需要生物学供体重复和已复核的注释。

用 scrna-research 规划分析，或者当合适的中间结果已经存在时，直接进入某个具体阶段。

运行环境与后端选择

完整流程可能耗时超过 1 小时。scVI 仍是默认选项。 运行时间取决于细胞/基因数量、硬件、训练、参数比较和注释复核；这不是完成时间的估计值。

| 你的环境或偏好 | 路线 |
| PyTorch 能用上兼容的 CUDA GPU | 用 scVI；--device auto 会选择可用的 GPU。 |
| 没有兼容的 GPU，愿意等更久 | 继续用 CPU 跑 scVI。这条路受支持，但训练可能慢得多。 |
| 更想用 CPU 替代方案 | 通过 Python 包 harmonypy 明确选择 Harmony（--backend harmony）。技术批次必须已经过验证。 |

后端绝不会因为缺少 GPU 或包、训练太慢、或某次运行失败就自动切换。没有别的选择时，就用 scVI。Harmony 调整 PCA 坐标，通常耗时更少，但不保证一个一小时以内跑完，或得到等效的生物学结果。没有合理的技术批次时，保留无批次 scVI；不要凭空造一个批次，也不要把普通 PCA 改标成 Harmony。

scVI 装 requirements-scvi.txt，Harmony 装 requirements-harmony.txt。
见后端示例与输出。

为什么默认用 scVI，而不是直接 PCA + UMAP？

Workbench 的 scVI 用负二项似然对原始计数建模，学习细胞的非线性表示，同时考虑文库大小和已登记的批次／细胞周期因子。这些能力有助于把生物学结构与计数波动区分开。普通 PCA 只总结预处理后表达量里的线性变异，没有这套计数模型。两条路线最终都要用邻居图，再用 UMAP 做可视化。

scVI 更慢，也不保证在每个数据集上都优于 PCA。要看标记基因支持和生物学保守性，不能只看 UMAP 好不好看。
见方法对比与来源。

内置知识库

知识库定义了智能体如何对数据集分组、如何选参数、如何排查不确定的注释、如何报告结果。六个技能都指向相应章节。

知识库随插件一起发布。同步检查会拦住过期副本，每次运行都会把策略哈希连同参数和软件版本一起记录下来。
见智能体如何使用知识库。

快速上手

1. 安装插件和依赖，然后把它接到你的智能体上。
2. 跑一遍400 细胞示例，检查环境是否正常。
3. 按研究工作流操作，或者分析你自己的数据。

计算在你本地或服务器的 Python 环境里跑。默认 scVI 装 requirements-scvi.txt，选定 Harmony 则装 requirements-harmony.txt；条件 DE 还有额外依赖。

示例请求：

用 scRNA-seq Workbench 分析这些数据集。读知识库，确定分析分组，跑 QC 和 scVI。给我看可选聚类方案，以及用于注释复核的标记基因表达图。
把分析记录和图保存到我的项目目录。

分析报告与验证

GSE144024：分析结果

人工分析

FL

人工 FL UMAP 与注释

YS

人工 YS UMAP 与注释

hESC

人工 hESC UMAP 与注释

Workbench v0.4.0 — scVI

FL

Workbench v0.4.0 FL UMAP 与注释

YS

Workbench v0.4.0 YS UMAP 与注释

hESC

Workbench v0.4.0 hESC UMAP 与注释

Workbench v0.3.0 — 分析 1：联合

Workbench v0.3.0 联合 UMAP 聚类

Workbench v0.3.0 联合 UMAP 与注释

Workbench v0.3.0 — 分析 2：独立

FL

Workbench v0.3.0 独立 FL UMAP 与注释

YS

Workbench v0.3.0 独立 YS UMAP 与注释

hESC

Workbench v0.3.0 独立 hESC UMAP 与注释

质量控制

FL、YS 和 hESC Day0/Day6 质量控制总览

当前软件检查

0.4.0 版本通过了 50 项本地测试，涵盖带批次和不带批次的 CPU scVI 训练、真实 Harmony、count/表达量保留、细胞周期处理、模型保存/重载、候选图以及后端/设备分发。分发测试中 GPU 可用性是模拟的；实际 GPU 训练未测试。包检查覆盖知识库同步、技能入口点和独立安装文件。

这些合成测试评估的是执行情况，不是生物学注释准确度。
参见验证记录、验证详情和 CI 结果。
更早的五项研究分析仍作为历史结果保留。

开发

开发指南 · 更新日志 ·协作 · 数据与出版物来源

代码采用 MIT 协议。