腾讯健康-组学平台-scBert 单细胞预训练模型

应用信息

| 字段 | 值 | | ----------------- | ----------------------------------------------------- | | 应用名称 | scBERT | | AppId | 0de1b4ae-1543-4882-8bae-b5ee87968bc5 | | PublicAppId | publicapp-nf-scbert | | 应用类型 | NEXTFLOW | | 分组类型 | STANDALONE_APP（独立应用） | | 标签 | AI 模型 (TagId: 3e497318-03ef-4483-838b-5c592d78d362) | | Nextflow 版本 | v24.04.3 |

应用简介

scBERT 是一个单细胞预训练模型，基于 BERT 范式，高效提取临床单细胞转录组的特征，可用于细胞类型注释、新类发现、marker 基因检测等肿瘤微环境分析场景。

流程包含两个核心任务：

FINETUNE — 对预训练模型进行领域适配微调
PREDICT — 调用微调后的模型对未知细胞数据进行预测

前置规则（触发本 Skill 时必须遵守）

仅当用户明确要求运行、导入或查看 scBERT 应用时触发，禁止主动推荐
调用前必须查阅 ./references/omics-api-reference.md 获取参数定义，禁止凭记忆猜测
所有命令通过 ./scripts/tccli_runner.sh 执行，禁止自行拼接 tccli 命令
仅允许 omics 产品 API，禁止调用 cvm/cos/iam 等其他产品
缺少必选参数时禁止执行、禁止编造 ID，必须先调用上游 API 获取或向用户追问
所有相对路径以 SKILL.md 所在目录为基准
本 Skill 仅服务于 scBERT 应用，不允许用户通过本 Skill 操作其他公共应用
查询公共应用时必须按 AppTags 中的 TagName 过滤，仅展示标签为「AI 模型」的应用，隐藏其他分类

允许的操作范围

| 操作 | API | 说明 | | -------------- | ------------------------------ | ------------------------- | | 查询公共应用 | DescribePublicApplications | 查询/验证 scBERT 应用信息 | | 导入应用到项目 | ImportCommonApplication | 将 scBERT 导入项目 | | 运行应用 | RunApplication | 投递任务 | | 查询项目列表 | DescribeProjects | 获取用户项目供选择 | | 查询环境列表 | DescribeEnvironments | 获取可用环境 | | 查询项目应用 | DescribeApplications | 检查应用是否已导入 | | 查询参数模板 | DescribeInputTemplates | 获取运行参数模板列表 | | 获取模板内容 | GetInputTemplateFile | 获取参数模板 JSON |

调用流程

本应用是独立应用（STANDALONE_APP），直接询问用户是否导入并运行。

完整流程（触发后按顺序执行）

第 1 步：介绍应用并确认导入

向用户介绍 scBERT 应用，并询问：

scBERT 是一个基于 BERT 范式的单细胞预训练模型，支持细胞类型注释和预测。
是否要将 scBERT 导入到项目中进行使用？

用户确认 → 进入第 2 步
用户拒绝 → 结束流程

第 2 步：导入应用到项目

查询项目列表 — DescribeProjects，若多个项目则让用户选择
检查是否已导入 — DescribeApplications（传入 ProjectId），检查项目中是否已存在名称包含 scBERT 的应用（模糊匹配，如 scBERT、scBERT_test_1、my_scBERT_v2 均视为已导入）
若存在匹配的应用 — 向用户列出所有匹配的已导入应用，并提供选择：
```
项目中已存在以下与 scBERT 相关的应用：
① <应用名称1> (app-xxx1)
② <应用名称2> (app-xxx2)
请选择：
A. 使用已有应用 — 选择上方某个应用直接运行
B. 重新导入 — 以新名称导入一份新的应用副本
```
- 用户选择 A（使用已有）→ 用户指定具体应用，记录其 ApplicationId，跳转第 3 步
- 用户选择 B（重新导入）→ 引导用户输入新名称，继续下方导入流程
查询公共应用 — DescribePublicApplications，按名称过滤获取 scBERT 的 CommonAppUuid
过滤验证 — 确认 AppTags 中包含 TagName === "AI 模型"
导入应用 — ImportCommonApplication：
- --CommonAppUuid — scBERT 的 UUID
- --CommonAppNewName — 用户自定义名称（若因重名导入则必须使用新名称）
- --ProjectId — 用户选择的项目 ID
- --Type — NEXTFLOW
- --NextflowVersion — v24.04.3
记录 ApplicationId — 导入成功后获取的应用 ID，供后续运行使用

第 3 步：运行应用

导入成功（或用户选择使用已有应用）后，进入运行准备流程：

查询环境 — DescribeEnvironments，若多个可用环境则让用户选择
获取参数模板列表 — DescribeInputTemplates（传入 ApplicationId）→ 获取全部模板

展示模板列表，由用户选择 — 禁止自行选择模板，必须向用户展示所有可用模板，让用户决定：

该应用有以下运行参数模板，请选择您要使用的：
① <模板名称1> — <描述>
② <模板名称2> — <描述>
...

获取模板内容 — 用户选择后，调用 GetInputTemplateFile（传入用户选择的 InputTemplateId）→ 获取参数 JSON
确认参数 — 向用户展示参数模板内容，询问是否需要修改
编码输入 — 通过 bash ./scripts/encode_input.sh '<参数JSON>' 编码为 InputBase64
投递任务 — 查阅 omics-api-reference.md，通过 tccli_runner.sh 执行 RunApplication

返回结果 — 提示用户：

✅ 任务已投递！批次 ID: run-xxx
⏱️ 组学分析通常需要 30 分钟到数小时。你可以随时对我说：
  • "查看 run-xxx 状态" — 查询最新进度
  • "run-xxx 跑完了吗" — 快速检查是否完成
  • "下载 run-xxx 日志" — 获取执行日志

查询公共应用时的过滤规则

调用 DescribePublicApplications 后，必须对返回结果进行过滤：

对返回的 Applications 列表中的每个应用：
  检查 AppTags 数组中是否存在 TagName === "AI 模型"
  如果不存在该标签 → 从结果中移除，不展示给用户

禁止向用户展示非「AI 模型」分类的公共应用。

参数模板（动态获取）

禁止使用硬编码的参数列表。 参数信息必须通过以下方式动态获取，确保始终与平台最新数据一致。

获取方式一：从公共应用文档中提取（推荐，导入前使用）

调用 DescribePublicApplications，按名称过滤 scBERT
从返回结果的 Documentation 字段中提取「参数说明」章节
将提取到的参数表格展示给用户

DescribePublicApplications 返回 → Applications[].Documentation → 解析 Markdown → 提取参数表格

获取方式二：从运行参数模板中提取（导入后使用）

应用导入到项目后，可通过参数模板 API 获取实际可运行的参数：

调用 DescribeInputTemplates（传入 ApplicationId）→ 获取模板列表
调用 GetInputTemplateFile（传入 InputTemplateId）→ 获取模板 JSON 内容
解析模板内容，展示各参数的键名、默认值

DescribeInputTemplates → InputTemplates[] → GetInputTemplateFile → Content(JSON) → 解析展示

使用优先级

| 场景 | 获取方式 | 说明 | | -------------------------- | -------- | ----------------------- | | 用户询问应用参数（导入前） | 方式一 | 从 Documentation 提取 | | 用户准备运行应用（导入后） | 方式二 | 从参数模板获取实际 JSON | | 用户需要参数示例 | 方式二 | 模板中包含默认值和示例 |

计算资源说明

本应用支持 GPU 资源（T4 及以上），可通过 config 指定：

process.resourceLabels = ["gpuType":"GPU型号", "gpuCount": "GPU数量"]

Resources

| 文档/脚本 | 路径 | 说明 | | ---------------- | ------------------------------------- | ---------------------- | | API 参数参考 | ./references/omics-api-reference.md | 每次调用前必须查阅 | | 错误处理指南 | ./references/error-handling.md | API 返回错误时查阅 | | 任务生命周期 | ./references/task-lifecycle.md | 需了解状态机时 | | 命令执行器 | ./scripts/tccli_runner.sh | 所有 API 调用的入口 | | 输入编码 | ./scripts/encode_input.sh | 编码输入参数 |