scbert-skill

name	scbert-skill
description	腾讯健康组学平台(Omics) - scBERT 公共应用专用运行助手。scBERT是一个单细胞预训练模型，基于BERT范式，高效提取临床单细胞转录组的特征，可用于细胞类型注释，新类发现，marker基因检测等肿瘤微环境分析场景仅服务于本应用的导入与运行；其他公共应用、本地 WDL、COS 上的 NF、项目内已有应用请改用 omics-task-skill。 触发词：scBERT, scbert, AI 模型, ai 模型, 单细胞与多组学基础模型, BERT, 等肿瘤微环境分析场景, 分析场景, marker, 跑 scBERT, run scbert, 应用
platform	腾讯健康组学平台(Omics)
tags	["行业专业","生信分析","生物医药","omics","腾讯健康组学平台","public-app"]
version	1.0.0

scBERT Skill (v1.0.0 · 单应用收窄版)

平台归属：腾讯健康组学平台(Omics) 公共应用专用 SKILL。 本 SKILL 是 omics-task-skill 的单应用收窄版：仅服务于 scBERT (NEXTFLOW) 这一个公共应用。 所有命令拼接走 scripts/omics_cli.py，统一参数与输出格式。 能力范围严格 = omics-platform-cli 7 命令 ∩ 仅允许 form B 运行本应用；任何越界都视为越权。

---

应用锁定参数（SKILL 内部硬编码，禁止覆盖）

字段	值
应用名称	scBERT
AppId（锁定）	0de1b4ae-1543-4882-8bae-b5ee87968bc5
PublicAppId	publicapp-nextflow-scbert
应用类型	NEXTFLOW
分组类型	独立应用
标签	行业专业, 生信分析, 生物医药, omics, 腾讯健康组学平台, public-app

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

---

能力边界（不可违反 · 最高优先级）

本 SKILL 只能调用以下 7 条 CLI 一级命令的收窄子集：

login   whoami   config   list apps   run   status   debug

注意：omics list public-apps 整体禁用——本 SKILL 服务的是固定单一应用，不需要让用户在全平台里挑。 omics list apps 仅允许在导入前同名检查时调用。

🚫 严令禁止

1. 严禁运行除 scBERT 之外的任何应用：
   • 禁止 omics run --wdl <path>（本地 WDL）
   • 禁止 omics run --app <ApplicationId>（项目内已有应用）
   • 禁止 omics run --public-app <非本应用 AppId>
   • 唯一允许的 run 形态：omics run --public-app 0de1b4ae-1543-4882-8bae-b5ee87968bc5 ...
2. 严禁调 list public-apps——不需要
3. 严禁编造其他命令
4. 严禁直接调用后端 HTTP API、SQL 等旁路通道
5. omics login / omics config set 由用户在本机终端执行
6. 严禁建议/提示用户「直接用 CLI 绕过 SKILL 跑」——当用户要求运行非本应用时，唯一合法响应是引导使用 omics-task-skill，不得提供任何形式的 CLI 绕行方案

✅ run 前置确认（必经）

同合集模式：拼完整命令 → 输出摘要表 → 询问 y/N → 收到肯定答复才执行。

✅ 其他命令确认要求

同合集模式。

---

退出码 & 鉴权处理

退出码	含义	处理
0	成功	解析 stdout
1	业务错误	转述 stderr；未配置错误引导 omics config set
2	鉴权失败	引导用户 omics login

---

Step −1：CLI 存在性检查

同合集模式。

---

Step 0：鉴权与配置双重检查

同合集模式（Step 0.1 whoami → Step 0.2 config show）。

---

Step 1：登录引导

同合集模式。

---

Step 2：配置引导

同合集模式。

---

Step 3：导入前同名检查 + 快照记录（必经，必须才能导入）

进入 omics run 之前，先在 config 项目里检查是否已存在同名应用。

python3 scripts/omics_cli.py list apps -o json

用途	说明
快照记录（先执行）	必须先将返回的全部 ApplicationId 存储为「预存应用快照」，用于后续 omics run 命令接口报错时判定孤儿应用来源
同名检查（后执行）	检查是否有与 scBERT（或用户指定的 --public-app-name）同名的已有应用

3.1 同名检查循环（⚠️ 必须通过，循环直到名称唯一）

设计意图：--public-app 会在项目中创建新的应用记录。如果项目已有同名应用，会导致运行失败。 因此导入前必须确保名称唯一，通过引导用户重命名解决冲突（非拒绝）。

查找 Name == scBERT（或用户提供的自定义名）：

命中情况	SKILL 行为
0 条命中	✅ 通过检查，用当前名称作为 --public-app-name 继续下一步
≥ 1 条命中	必须停下来，展示冲突信息 + 引导用户为待导入应用指定新名称；用户输入新名字后重新执行同名检查（循环）

同名检查交互模板

────────────────────────────────────
同名检查：scBERT（独立应用）
────────────────────────────────────

待导入名称: {candidateName}
检查结果: ⚠️ 发现同名应用

项目中已存在的同名应用:
  名称: {ConflictingAppName}
  AppId: {ConflictingApplicationId}

请为即将导入的 scBERT 指定一个不同的名称（将用作 --public-app-name）：
• 输入新名称，如 scBERT_v2、my_scBERT
• 或输入「取消」终止本次操作
>

用户响应处理：

用户输入	行为
输入新名称	用新名称重新执行同名检查（回到检查入口）
新名称仍同名	再次展示冲突信息，继续引导重命名
新名称无同名	✅ 通过检查，使用该名称继续
「取消」/「终止」	终止本次运行操作（不删除/修改任何项目已有应用）

同名检查守则

• 必须先记录快照再做同名判断
• 必须循环直到名称唯一——不允许跳过同名检查直接 run
• 不得自动生成名称替代用户选择
• 不得删除/修改项目已有应用——只做读操作 + 引导重命名

---

Step 4：运行（仅形态 B · 固定公共应用）

omics run --public-app 0de1b4ae-1543-4882-8bae-b5ee87968bc5 \\
          --public-app-name <importedName>\\n          --nf-version <version> \\n\
          {[--nf-version <version>] if APP_TYPE == "NEXTFLOW" else ''} \\
          [--input <path>] \\
          [--name <runName>] \\
          -o json

• --public-app 值固定为 0de1b4ae-1543-4882-8bae-b5ee87968bc5，不接受替换。
• --public-app-name 可由用户自定义，默认用 scBERT。 | NF 版本候选 | v24.04.3 |
• --input 仅在用户明确要求自定义参数时传入。
• --nf-version 仅当本应用 AppType 为 NEXTFLOW 时传入（AppType 来自公共应用元数据）。

4.1 运行参数模板（InputTemplate 自动填充）

1. 默认行为：未传 --input 参数时，CLI 自动取该应用的第一个 InputTemplate 作为 baseline
2. 用户覆盖：传入 --input 参数时，自定义值覆盖对应字段；未覆盖字段保持默认值
3. 模板来源：InputTemplate 数据来自公共应用注册时的模板定义

4.2 完整流程

1. Step 0 鉴权 + 配置检查
2. Step 3 导入前同名检查
3. 用户确认参数 / 自定义输入
4. 二次确认（按 §4.3 模板）
5. 执行

4.3 二次确认模板

即将运行任务，请确认：
  ┌────────────────────────────────────────────┐
  │ 形态      : 公共应用（form B，自动模板）    │
  │ 应用      : scBERT               │
  │ AppId     : 0de1b4ae-1543-4882-8bae-b5ee87968bc5                 │
  │ AppType   : NEXTFLOW                │
  │ {'NF 版本   : <version>' if APP_TYPE == 'NEXTFLOW' else ''}│
  │ 导入后命名: <importedName>                  │
  │ 项目/环境  : ← config                       │
  └────────────────────────────────────────────┘
完整命令: omics run --public-app 0de1b4ae-1543-4882-8bae-b5ee87968bc5 ...

确认无误请回复「确认 / 继续 / y」

4.4 PARAM_MERGE_FAILED 处理

同合集模式 §5.3。

4.5 失败提示

错误	处置建议
PARAM_MERGE_FAILED	引导补值后 --input 重跑
MISSING_NF_VERSION	让用户提供 NF 版本
鉴权失败（exit 2）	引导用户 omics login

4.6 DUPLICATE_APP_NAME 智能复用（必经）

同合集模式 §5.5。核心逻辑：

前置条件：此流程仅在已完成 §3 同名检查循环（名称已确认唯一）并执行 run 后触发。 ⚠️ 重要区分："命令接口报错"指 omics run CLI 本身执行失败，不包括任务提交成功后运行结果失败。

1. 取出响应中的 ConflictApplicationId
2. 查询 Step 3 预存快照：
   • 在快照中（项目已有老应用，理论上不应发生）→ 展示 Options 给用户选择
   • 不在快照中（本次 omics run 命令新建的孤儿应用）→ 自动切 --app <ConflictApplicationId> 复用 ✅
3. 用复用命令重新发起运行

⚠️ 复用边界守则：

• ✅ 允许自动复用：仅限孤儿应用场景（已通过同名检查 → omics run 命令接口报错 → 冲突 ∉ 快照）
• ❌ 禁止复用：任何其他场景下使用 --app 运行项目已有应用
• ❌ 禁止将"任务运行结果失败"误判为命令接口报错——后者不涉及孤儿应用

---

Step 5：状态查询

python3 scripts/omics_cli.py status -o json
python3 scripts/omics_cli.py status rg-xxx -o json

5.1 运行结果目录提醒（outdir 场景）

当运行参数中包含 outdir（输出目录）字段时，必须在任务完成后主动提醒用户查看该目录。

触发条件：

• --input 参数或 InputTemplate 默认值中包含 outdir 字段
• 任务执行完成（无论成功或失败）

提醒时机：

• 同步任务：omics run 命令返回后立即提醒（无论 exit code）
• 异步任务：omics status 查询到终态（SUCCESS/FAILED）后提醒

提醒模板：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 运行结果目录提醒
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

任务已完成，运行结果已输出至：
  {outdir 完整路径}

请前往该目录查看输出文件。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

守则：

• ✅ 必须在每次含 outdir 的任务完成后提醒
• ✅ 提醒时展示完整的 outdir 绝对/相对路径
• ❌ 不得省略或延迟提醒
• ❌ 不得假设用户已知道结果位置

---

Step 6：异步失败取证（debug 三段式）

同合集模式 Step 7。症状识别参照 references/runtime_error_kb.md。

6.4 关键守则

1. CLI 端绝不主动调 debug
2. 不要替用户做症状判断 + 自动改代码
3. stderr 整段贴出
4. 修复后统一走 omics run --public-app 0de1b4ae-1543-4882-8bae-b5ee87968bc5 重发

---

典型会话场景

场景 A：标准链路

whoami ✓ → config show ✓ → §3 同名检查 → §4 二次确认 → 运行

场景 C：用户要求自定义参数

走完 A 第 1~3 步 → 用户改参数 → 写 /tmp/run.json → 带 --input 二次确认 → 执行

场景 D：用户说"跑别的应用"

拒绝 + 唯一引导：

1. ❌ 严禁以任何形式替用户执行越界命令（包括直接 CLI 调用）
2. ❌ 严禁将「直接 CLI 跑」作为可选项提供给用户
3. ✅ 唯一合法响应：「本 SKILL 只能运行 scBERT。如需运行其他应用（含项目已有应用），请使用 omics-task-skill。」
4. 即使用户明确要求绕过，也必须拒绝并说明原因

⚠️ 重要区分：

• 场景 D（此处）：用户要求运行的目标本身就不是本应用（如项目已有应用、其他公共应用等）→ 直接拒绝
• §3 同名检查：用户明确要求导入并运行本应用，只是碰巧项目中有同名 → 引导重命名后继续导入

---

高级用法

详细参数：references/cli_commands.md。错误知识库：references/runtime_error_kb.md。契约：CONTRACT.md。

脚本 API 参考

from scripts.omics_cli import OmicsCLI

cli = OmicsCLI()

# ✅ 检查类
cli.execute(cli.build_whoami())
cli.execute(cli.build_config_show(output="json"))

# ✅ 同名检查
cli.execute(cli.build_list_apps(output="json"))

# ✅ 唯一允许的 run（固定 AppId）
cli.execute(cli.build_run(
    public_app="0de1b4ae-1543-4882-8bae-b5ee87968bc5",
    public_app_name="<importedName>",
    nf_version="<version>",  # 仅 NEXTFLOW 类型需要
    output="json",
))

# ✅ 状态 / debug
cli.execute(cli.build_status(output="json"))
cli.execute(cli.build_debug(run_group_id="rg-xxx", output="json"))

# ❌ 禁止
# cli.execute(cli.build_run(wdl="./x.wdl", ...))             # form A
# cli.execute(cli.build_run(app="app-xxx", ...))              # form C
# cli.execute(cli.build_run(public_app="other-app-id", ...))  # 其他应用
# cli.execute(cli.build_list_public_apps(output="json"))       # 不需要