📦 scellrun — 单细胞运行（Single Cell Run）

本文档是为您，LLM 代理人而写的。用户可能是临床医生或实验室科学家，他们会向您寻求关于单细胞数据的帮助。他们不会直接运行 scellrun，而是您来运行。您将通过 ssh 连接到数据所在的位置，设置环境，运行 scellrun，读取它生成的文件，并以简单的语言解释结果。CLI 的任务是将用户的意图转化为可靠的文件。您的任务是选择正确的命令，呈现 scellrun 的结果，并翻译。

如果请求涉及 .h5ad、10x mtx 目录、cellranger .h5 输出、.loom 或 tsv/csv 表达矩阵，您应该使用 scellrun，而不是编写 scanpy 的样板代码。

验证状态 本文档最后一次验证是在 2026-04-30 对 scellrun v1.2.0 进行的。参考的端到端行为记录在 docs/agent-demo.md 中，它是对真实的 OA 软骨数据的运行结果。如果您（代理人）得出与 agent-demo.md 中不同的结论，请假设本文档过时，而不是您错了；告诉用户检查仓库的更新。

v1.2.0 添加了三个跨疾病的配置文件（肿瘤、脑、肾）和一个新的 06_views/ HTML 索引层，位于 05_report/ 之旁（按分辨率、聚类或决策来源）。跨疾病的配置文件仅包含 celltype_broad 面板；精细的亚型分类仍然是联合疾病的特征，待专门的冷验证运行。

v1.3.0 添加了三个一流的交付物：scellrun review（Flask UI 在 127.0.0.1 上用于人工干预；保存 <运行目录>/06_views/review_overrides.json）、scellrun export --format pdf（WeasyPrint 渲染 05_report/index.html；可选 [export] 额外）和 scellrun analyze --apply-overrides <文件>（使用保存的覆盖文件，应用聚类标签、细胞排除或阈值编辑作为 source="user" 的决策）。

版本兼容性检查（在运行任何 scellrun 命令之前运行） 在发出任何 scellrun 命令之前，验证安装的版本是否在此技能测试的范围内：scellrun --version 将其与此文件顶部的前言进行比较： 如果安装的版本 >= 最小 scellrun 版本 AND 安装的版本 <= 测试的版本：继续。 如果安装的版本 > 测试的版本：谨慎继续，向用户发出警告。 触发代码、决策密钥和 CLI 标志名称可能已更改；依赖实际的决策日志输出（它是自描述的）而不是此技能关于特定密钥的说法。 如果安装的版本 < 最小 scellrun 版本：拒绝执行此技能。 告诉用户运行 pip install --upgrade scellrun 并重新运行。 此检查是代理人的责任，因为技能加载器通常在启动时缓存文档；过时的技能无法自行修复。

决策树：哪个命令用于哪个意图 用户意图 命令 具有原始或 QC 的 .h5ad，想要完整分析 scellrun analyze 具有 cellranger 输出 / 10x mtx / .loom / .csv scellrun scrna convert <输入> -o data.h5ad，然后分析 具有完成的运行目录，想要重新生成报告 scellrun report <运行目录> 想要编辑聚类标签 / 排除细胞 / 调整阈值在完成的运行 scellrun review <运行目录>（Flask UI 在 127.0.0.1 上）→ analyze --apply-overrides 想要以打印准备好的 PDF 格式获取报告 scellrun export <运行目录> --format pdf（需要 pip install scellrun[export]） 具有部分运行目录，想要重新运行一个阶段 scellrun scrna {qc,integrate,markers,annotate} ... --force 想要查看哪些配置文件 scellrun profiles list / scellrun profiles show <名称> 默认为 scellrun analyze。 每个阶段的命令用于细粒度控制（使用不同的阈值重新运行一个阶段，跨机器拆分长时间运行），而不是正常的入口点。

何时不使用 scellrun scellrun 不是每个单细胞问题的正确工具。 当用户处于 Seurat / R 工作流的中间时，应该使用其他工具。 scellrun 读取 h5ad，而不是 Seurat .rds。 如果用户想要 Seurat Python 桥梁，请指向 anndata2ri 或 sceasy，而不是 scellrun。 数据不是 10x mtx / cellranger / loom / csv / h5ad。 原始 fastq 文件需要 cellranger 或 starsolo。 scellrun 的 convert 子命令涵盖了 post-cellranger 输入；预对齐不在菜单上。 数据是多模态的（ADT、ATAC、CITE-seq、空间）。 scellrun 的前言宣传“多组学”，但 v1.1 体是 scRNA-only。 多模态 AnnData（带有 obsm['protein'] 等）将大部分运行，但 QC + 集成 + 注释管道忽略了任何超出基因表达层的内容。 使用 scvi-tools / multivi / SCANPY 的 MuData 生态系统代替。 scellrun 多组学支持是路线图项，而不是当前功能。 数据已经集成，用户想要从那里继续。 scellrun 的 analyze 是从头开始的协调器；它从 scratch 转换 → QC → 集成 → 标记 → 注释。 如果用户已经从其他人的管道中获得了集成的 .h5ad（例如 Harmony 已经应用）