IgGM-WDL Skill (v1.0 · 单应用收窄版)

本 SKILL 是 omics-task-skill 的单应用收窄版：仅服务于 IgGM-WDL 这一个公共应用。所有命令拼接走 scripts/omics_cli.py，统一参数与输出格式。 能力范围严格 = omics-platform-cli 7 命令 ∩ 仅运行 IgGM-WDL 这一个 AppId；任何越界都视为越权。

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

| 字段 | 值 | | ------------------- | -------------------------------------- | | 应用名称 | IgGM-WDL | | AppId（锁定） | a9c8cb12-0a16-43f0-ab07-96ec5b41cc71 | | 应用类型 | WDL | | 分组类型 | STANDALONE_APP（独立应用） | | 标签 | AI 模型 |

应用简介：IgGM（Immunoglobulin Generative Model）是腾讯 AI Lab 姚建华团队联合复旦大学应天雷、上海交通大学赵沛霖、中国科学院大学高兴宇团队发布的抗体设计通用基础模型（ICLR 2025）。通过大规模免疫组库数据训练，IgGM 可针对给定抗原同时生成抗体序列与结构，支持抗体 / 纳米抗体的从头设计、CDR 重设计与亲和力成熟。模型由三个核心组件构成：用于提取序列特征的预训练语言模型、用于识别相关特征的特征学习模块、用于联合生成序列与结构的扩散模块。

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

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

login   whoami   config   run   status   debug

注意：omics list public-apps / omics list apps 均禁用——本 SKILL 已锁定单一 AppId，既不需要让用户在公共应用列表里挑，也不需要查项目内其它应用。

🚫 严令禁止

严禁运行除 IgGM-WDL 之外的任何应用：
- 禁止使用 omics run --wdl <path>（用户本地 WDL —— 注意区分：本 SKILL 跑的 IgGM-WDL 是公共应用，不是用户的本地 WDL 文件）
- 禁止使用 omics run --app <ApplicationId>（项目内已有应用）
- 禁止使用 omics run --public-app <其它 AppId>（其它公共应用）
- 唯一允许的 run 形态：omics run --public-app a9c8cb12-0a16-43f0-ab07-96ec5b41cc71 ...
严禁编造其他命令——例如 app list / app templates / import 等都已废弃，调用必失败。
严禁直接调用 omics 后端 HTTP API（CommonAppService.* / RunService.* / ImportApplication 等）、 SQL、文件系统写入等任何旁路通道。
严禁通过组合现有命令"模拟"出白名单外的语义——例如不能把"导入公共应用"作为独立动作执行；导入是 omics run --public-app 的内部步骤，必须随 run 一起发生。
omics login / omics config set 由用户在本机终端执行，SKILL 永远不主动调（OAuth 浏览器回调 + 交互式输入只能在用户本机完成）。
严禁让用户提供 AppId / PublicAppId / CommonAppUuid——AppId 已硬编码，用户提供其它 ID 一律拒绝。
严禁传入 --nf-version —— IgGM-WDL 是 WDL 类型，不是 NEXTFLOW；CLI 会忽略并提示。

✅ run 前置确认（必经）

SKILL 触发 omics run ... 前必须按 §4.2 模板完成二次确认：

拼出完整命令字符串（含所有 flag），AppId 必须是上方锁定值
输出参数摘要表（应用 / 项目 / 环境 / 输入 / 类型等关键项）
询问用户："以上命令是否执行？(y / 确认 / 继续)"
仅当收到明确肯定答复（y / yes / 确认 / 继续 / 是 / 执行 / OK）才调用
用户拒绝（n / no / 取消）→ 终止；模糊回复（嗯 / 好 / 可以）→ 再次明确询问
用户追加修改 → 回到 1 重拼

✅ 其他命令的确认要求

| 命令 | 是否需要确认 | | ----------------------------------------------------- | ------------------------- | | whoami / status / debug / config show / clear | 免确认（只读 / 本地操作） | | run | 必须 | | login / config set | 不调，引导用户本机执行 |

退出码 & 鉴权失败处理

| 退出码 | 含义 | SKILL 处理 | | ------ | -------- | ------------------------------------------------------------------------------------------ | | 0 | 成功 | 解析 stdout | | 1 | 业务错误 | 把 stderr 转述给用户。如果是"未配置"错误，按 Step 2 引导用户去本机跑 omics config set | | 2 | 鉴权失败 | 按 Step 1 引导用户去本机跑 omics login，不要循环重试 |

stderr 中以 ❌ 开头的行为可读错误描述，可直接转述。

另外：scripts/omics_cli.py 启动时若在 PATH 与 OMICS_CLI_PATH 都找不到 omics 可执行文件，会以 FileNotFoundError 退出（非 0/1/2 业务退出码），SKILL 必须按下文 Step −1 引导用户安装 CLI，不要自动尝试下载、不要 pip/brew/curl 替用户装。

Step −1：CLI 存在性检查（最先执行）

任何业务命令之前，SKILL 必须先确认本机已安装 omics-platform-cli。最简单的方式是直接尝试 omics whoami / omics version：

如果 python3 scripts/omics_cli.py whoami / omics whoami 抛出 FileNotFoundError、 shell 提示 command not found: omics、Windows 提示 'omics' 不是内部或外部命令，或者 stderr 出现 未找到 'omics' 命令 —— 都视为 CLI 未安装。
命中以上任一情况，立即给用户下面这段话并终止流程，等待用户安装完成回执：

检测到本机尚未安装 omics-platform-cli，无法继续。

请前往下载页，按页面提供的安装脚本和使用指南完成安装： https://cnb.cool/tencenthealthcareomics/omics-platform-cli

安装完成后回到我这里告诉我「已安装 / done」，我会验一次 omics version 再继续。

强约束：

绝不在 SKILL 端用 curl / wget / brew / pip / npm 等任何方式自动下载或安装 CLI；也不要自行编写解压、加 PATH、导 OMICS_CLI_PATH 之类的操作步骤——下载页已提供官方的安装脚本和使用指南，按页面执行即可。
绝不继续调用任何 python3 scripts/omics_cli.py ... 命令（CLI 不存在时这些命令必失败）。
用户回执「已安装」后，重新跑一次 omics version 确认通过后才进入 Step 0；若仍失败，仅需再次把下载页链接给用户，让其参照页面指南排查，不要替用户猜路径。

Step 0：鉴权与配置双重检查（每次启动必做）

任何业务命令前必须先验证两个条件：

┌──────────────────────────┬──────────────────────────────┐
│ 检查项                   │ 命令 / 期望                  │
├──────────────────────────┼──────────────────────────────┤
│ 已登录                   │ omics whoami → exit 0        │
│ 已配置 region/proj/env   │ omics config show -o json    │
│                          │ → exit 0 且字段都不为空      │
└──────────────────────────┴──────────────────────────────┘

Step 0.1：whoami

python3 scripts/omics_cli.py whoami

退出码 0 → 进入 Step 0.2；退出码 2 → 跳到 Step 1（登录引导）。

Step 0.2：config show

python3 scripts/omics_cli.py config show -o json

判定：

退出码 0 + JSON 字段齐全（Region/ProjectId/EnvironmentId 都不为空）→ 进入业务流程， 复述当前配置给用户：

当前配置：地域 ap-guangzhou，项目 prj-xxx (xxx)，环境 env-yyy (yyy)，COS Bucket my-bucket。如需切换请告诉我。
退出码 1（文件不存在 / 字段缺失） → 跳到 Step 2（配置引导）。

Step 1：登录引导（鉴权失败时使用）

SKILL 不要自己调 omics login。 一旦 whoami 返回退出码 2 或任何业务命令报"鉴权失败 / session 过期 / 401"，立即给用户下面这段话：

检测到当前会话的登录状态已失效或不存在。

请在你本机的终端中执行下面这条命令完成授权：
omics login
完成后回到我这里告诉我「已登录」，我会继续后续操作。

强约束：

不要在 SKILL 端启动 omics login 子进程
不要循环 whoami 等待用户登录
不要给用户复制授权 URL 让其在远程粘贴（OAuth 回调地址 localhost:18000 必须落到用户本机的 CLI 进程上）

收到用户「已登录 / done」类肯定答复后，重新跑一次 omics whoami 确认 → exit 0 才进入 Step 0.2。

Step 2：配置引导（config 缺失或字段不全时使用）

SKILL 不要自己调 omics config set。 它是交互式命令，会逐项提示输入 region/projectId/environmentId/bucketName， SKILL 跑在远程 agent 里无法替用户输入；同时 SKILL 也不应猜测或编造这三个 ID。

一旦 omics config show 返回退出码 1，立即给用户下面这段话：

检测到本地尚未完成 region / projectId / environmentId 的配置。

请在你本机的终端中执行下面这条命令完成配置：
omics config set
CLI 会依次提示输入 Region → ProjectId → EnvironmentId → COS BucketName。 COS BucketName 为必填项。

完成后回到我这里告诉我「已配置」，我会继续后续操作。

收到用户「已配置 / done」类肯定答复后，重新跑一次 omics config show -o json 确认 → exit 0 + 字段齐全才进入业务流程。

命令意图映射表（IgGM-WDL 收窄版）

| 用户说 | CLI 命令 | 场景 | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | -------- | | 「我没装 CLI / 提示 command not found」 | 告诉用户去 https://cnb.cool/tencenthealthcareomics/omics-platform-cli 下载安装，SKILL 不调 | Step −1 | | 「我登录了吗 / 当前账号是谁」 | omics whoami | Step 0.1 | | 「我没登录 / session 过期了」 | 告诉用户在本机终端跑 omics login，SKILL 不调 | Step 1 | | 「现在用的是哪个项目和环境」 | omics config show -o json | Step 0.2 | | 「配下默认项目 / 切到 xx 项目」 | 告诉用户在本机终端跑 omics config set，SKILL 不调 | Step 2 | | 「清掉本地配置」 | omics config clear | — | | 「跑 IgGM」「做抗体设计」「针对抗原生成抗体」 | omics run --public-app a9c8cb12-0a16-43f0-ab07-96ec5b41cc71 [--public-app-name <name>] -o json | §4 | | 「跑 IgGM-WDL，参数我自己改过」 | 上面命令 + --input <path> 显式覆盖自动模板 | §4 | | 「看任务进度」「查批次状态」 | omics status -o json | §5 | | 「rg-xxx 跑完了吗 / 看子任务」 | omics status <rgId> -o json | §5 | | 「rg-xxx 哪些子任务挂了」 | omics debug <rgId> -o json | §6.1 | | 「这个失败子任务到底为啥挂的」 | omics debug --run <runUuid> -o json | §6.2 | | 「钻下 plan-xxx 这个作业的 stderr」 | omics debug --run <runUuid> --job <jobId> -o json | §6.3 | | 「列下平台公共应用」「跑别的应用」 | ❌ 拒绝——本 SKILL 仅服务 IgGM-WDL；建议用户改用 omics-task-skill | — |

❌ 用户说「跑本地 WDL」「跑别的公共应用 X」「跑项目里那个 app-xxx」：本 SKILL 必须拒绝，引导用户：「我只能帮你跑 IgGM-WDL；如需运行其他应用，请使用 omics-task-skill。」

Step 3：导入前同名检查（必经）

IgGM-WDL 进入 omics run --public-app ... 之前，SKILL 必须先在 config 项目里检查是否已存在同名应用，避免：

service 端 CreateApplication 因 Name 唯一约束直接报错；
SKILL 自动加后缀（如 IgGM-WDL-1、IgGM-WDL-cli）替用户决策，污染应用列表。

检查方法（例外允许的 list apps 调用）

本 SKILL 整体禁用 omics list apps，但仅允许在导入前同名检查这一处调用，其结果只能用于"是否已有 IgGM-WDL 同名应用"的二选一判断，禁止用于让用户挑别的应用运行。

python3 scripts/omics_cli.py list apps -o json

在返回 JSON 的 Applications[] 中查找 Name == "IgGM-WDL"（或用户提供的自定义 candidateName）：

| 命中情况 | SKILL 行为 | | -------------- | ----------------------------------------------------------------------------------------------------------- | | 0 条命中 | 不传 --public-app-name 走 CLI 原名兜底；或按用户指定的新名传入 | | ≥ 1 条命中 | 必须停下来，把命中条目的 ApplicationId / Name / Type / VersionCount / CreateTime 列给用户，二选一询问 |

命中同名时的话术

项目里已经存在一个叫 IgGM-WDL 的应用：

ApplicationId：app-xxxx

Type：WDL，版本数：3，创建时间：2026-05-20 10:11

我不会自动改名，请你二选一：

A. 重命名后导入（推荐）：给一个新的导入名，比如 IgGM-WDL-v2 / IgGM-WDL-2026q2 → 我会用你给的新名字重新导入这个公共应用并运行。

B. 终止本次运行：本 SKILL 仅服务于公共应用 IgGM-WDL 的导入与运行；如需直接复用项目里已有的 app-xxxx 应用，请使用 omics-task-skill（form C：omics run --app app-xxxx）。

你选哪个？或者直接告诉我新名字。

强约束：

SKILL 不要自动给候选名加 -1 / -2 / -cli / 时间戳之类的后缀。命名是用户的项目治理空间，必须由用户拍板。

如果用户在本 SKILL 内选 B（复用已有应用），必须拒绝——本 SKILL 不能调 omics run --app <已有 AppId>，请引导用户去 omics-task-skill。

Step 4：运行（仅形态 B · 公共应用 · 自动模板路径）

omics run 在本 SKILL 中只接受以下命令骨架：

omics run --public-app a9c8cb12-0a16-43f0-ab07-96ec5b41cc71 \
          [--public-app-name <importedName>] \
          [--input <path>] \
          [--name <runName>] \
          -o json

--public-app 值固定为 IgGM-WDL 的 AppId，不接受替换。

不传 --nf-version（WDL 应用无 NF 版本概念；CLI 会忽略并提示）。

--public-app-name 按 §3 同名检查决策；独立公共应用允许走 CLI 原名兜底（不传也可）。

--input 仅在用户明确要求自定义参数时显式传入（覆盖自动 InputTemplate）。

CLI 内部链路：ImportCommonApplication → DescribeInputTemplates → GetInputTemplateFile → baseline+override → RunApplication。

4.1 完整流程

Step 0 鉴权 + 配置双重检查（必经）
Step 3 导入前同名检查（必经）
决定 --public-app-name：用户原话 / 默认走 CLI 原名兜底
二次确认（按 §4.2 模板）

一步直达运行：

python3 scripts/omics_cli.py run --public-app a9c8cb12-0a16-43f0-ab07-96ec5b41cc71 \
  [--public-app-name <name>] [--name run-1] -o json

若 CLI 报 PARAM_MERGE_FAILED：按 §4.4 处理。

如果用户主动要求改参数 → 显式传 --input 覆盖自动模板：

python3 scripts/omics_cli.py run --public-app a9c8cb12-0a16-43f0-ab07-96ec5b41cc71 \
  --public-app-name <name> --input ./run.json -o json

4.2 二次确认模板（必经）

向用户汇总后等"确认/继续/OK/y"再执行。

即将运行任务，请确认：
  ┌──────────────────────────────────────────────────┐
  │ 形态        : 公共应用（form B，自动模板）        │
  │ 公共应用    : IgGM-WDL                            │
  │ AppId       : a9c8cb12-0a16-43f0-ab07-96ec5b41cc71│
  │ AppType     : WDL                                 │
  │ 导入后命名  : IgGM-WDL（或用户指定）               │
  │ 项目        : prj-yyy (..., ap-guangzhou) ← config│
  │ 环境        : env-zzz (...)               ← config│
  │ 参数模板    : 自动取该应用第一个 InputTemplate    │
  │ 运行名称    : <Name>                              │
  └──────────────────────────────────────────────────┘
完整命令:
  omics run --public-app a9c8cb12-0a16-43f0-ab07-96ec5b41cc71 \
            --public-app-name IgGM-WDL \
            --name run-1 -o json

确认无误请回复「确认 / 继续 / y」；如需自定义参数请告诉我（可改走 --input 模式）。

用户回复识别

| 用户回复 | SKILL 行为 | | --------------------------------------------------------------- | ------------------------------------------ | | y / yes / 确认 / 继续 / OK / 是 / 执行 / 开始跑 | 调用 cli.execute(...) | | n / no / 取消 / 等等 / 先别 | 终止流程，等待用户进一步指示 | | 任何含修改意图的句子（"改下 X" / "把 Y 换成 Z"） | 解析修改意图 → 重拼命令 → 重走确认 | | 模糊回复（"嗯" / "好" / "可以" / "试试") | ⚠️ 不算肯定 → 再次明确询问"是否执行 y/N？" |

4.3 运行参数：合并模式

CLI 的 omics run 内部按 final = baseline + override 合并参数 JSON：

baseline = WDL 中显式声明的默认值（ValidateApplication.Inputs[].Default）

override = form B 默认自动取该应用第一个 InputTemplate；用户给 --input 时则替换

| 场景 | SKILL 行为 | | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | omics run 直接 exit 0 + 输出 RunGroupId | 一切顺利，转述结果给用户即可 | | stderr 出现 ❌ 参数模板校验失败 或 JSON 输出 Error: PARAM_MERGE_FAILED | 解析其中的 Report.MissingRequired / TypeErrors / ExtraFields，把缺失字段及类型告诉用户；用户给值后 SKILL 写入本地 run.json 再 --input <path> 重跑 |

4.4 PARAM_MERGE_FAILED 处理

JSON 报错的关键字段：

Error：固定为 "PARAM_MERGE_FAILED"
ApplicationId / WorkflowName：定位上下文
Specs[]：每项 { Name, Optional, TypeName, Default }
Baseline / UserOverride / FinalParsed：合并各阶段快照
Report.MissingRequired[] / EmptyRequired[] / ExtraFields[] / TypeErrors[]
PartialSkeleton：CLI 已拼好的"可保存即用"的 JSON
Hint[]：CLI 给的下一步重跑命令模板

典型话术：

跑这次任务时 CLI 已经把 WDL 的默认值和模板拼好，但还有 N 个必填项缺值：

<workflow>.antigen_pdb：File（必填，抗原结构）

<workflow>.antigen_chain：String（必填，抗原链 ID）

<workflow>.design_mode：String（必填，例如 de_novo / cdr_redesign / affinity_maturation）

请把这些值告诉我，或者直接给我一份本地 JSON 路径，我帮你按 --input 传回去重跑。

4.5 流水线失败提示

| 错误 | 处置建议 | | ----------------------------------------- | ----------------------------------------------------------------------------------------- | | 参数模板校验失败 / PARAM_MERGE_FAILED | 解析 Report.MissingRequired / TypeErrors，按 §4.4 引导用户给值后通过 --input 传回重跑 | | 用户误传 --nf-version | 提醒用户 IgGM-WDL 是 WDL 类型，无需 NF 版本；CLI 会忽略此参数 | | 环境 X 不可用 / 不存在 | 提示用户重跑 config set 或去控制台检查 | | 环境 X 下未绑定默认缓存卷 | 提示用户去控制台为该环境配置默认 Volume | | Result=CONFLICT 反复出现 | CLI 内部已尝试回退；说明应用被并发修改，提示用户等待或换新名重新导入 | | 鉴权失败（exit 2） | 不重试，引导用户在本机跑 omics login |

Step 5：状态查询

# 列批次（固定走 config 项目）
python3 scripts/omics_cli.py status -o json

# 列子任务
python3 scripts/omics_cli.py status rg-xxx -o json

status 不支持跨项目查询。如需查别的项目，先重新 omics config set。

JSON 关键字段：

列批次：RunGroupId / Name / Status / TotalRun / RunStatusCounts / ExecutionTime
列子任务：RunUuid / RunGroupId / UserDefinedId / Status / ExecutionTime / ErrorMessage

紧凑总结：最近 N 个 IgGM 批次：✅ 已完成 X / ❌ 已失败 Y / 🔄 运行中 Z。

⚠️ omics status 列出的是当前项目所有批次（不限于 IgGM），SKILL 转述时应优先突出 IgGM 相关批次，但不强制过滤——这是平台原生能力。

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

触发条件：omics status 看到子任务 Status=Failed / Aborted / Error，或用户问「rg-xxx 为啥挂了」。

工具：omics debug 三段式（CLI 端只取证，不做规则匹配；症状判断由 SKILL 模型对照 references/runtime_error_kb.md 决定）。

6.1 段 1：列批次失败子任务

python3 scripts/omics_cli.py debug <runGroupId> -o json

输出关键字段：

TotalRuns / FailedCount
FailedRunUuids[]
Runs[]：完整子任务列表

SKILL 行为：

FailedCount == 0 → 告诉用户"该批次没有失败子任务，可能是运行中或已成功"
FailedCount == 1 → 直接进入段 2
FailedCount > 1 → 询问用户先看哪一个，或主动取前 1~2 个钻一遍找共性

6.2 段 2：单子任务现场

python3 scripts/omics_cli.py debug --run <runUuid> -o json

输出关键字段（详见 references/cli_commands.md debug 段）：

Status：顶层 RunMetadata（RunType / Status / JobId / ErrorMessage / Input / Output / Command）
Calls[]：cromwell call 元数据
JobLogs[]：CLI 已自动钻取最多 5 个失败 call 的真实 stderr 与 K8s 事件
- Stderr / StderrTruncated：实际日志正文（已截尾，头 4KB + 尾 24KB）
- PodEvents[]：保留 FailedMount（前端会过滤但 AI 排障必须看）

症状识别流程：

优先看 Status.ErrorMessage
逐个看 JobLogs[].Stderr 末尾
看 JobLogs[].PodEvents
对照 references/runtime_error_kb.md 决策快速表
都不命中 → 走兜底，把现场原文贴给用户做透明分析

6.3 段 3：精确钻取某个 Job

python3 scripts/omics_cli.py debug --run <runUuid> --job <jobId> -o json

输出与段 2 同结构，但 Calls / JobLogs 都按 JobId 过滤。

6.4 关键守则

CLI 端绝不主动调 omics debug —— 用户问"为啥挂了"才用
不要替用户做症状判断 + 自动改代码 —— 看到 OOMKilled 不要直接改 memory，要先告诉用户"目测内存不足"并询问是否调整
stderr 内容是用户应用代码 —— 转述时整段贴出来，不要总结/二次加工
修复后统一走 omics run 重发 —— 本 SKILL 的重发仍然只能走 form B：
```
omics run --public-app a9c8cb12-0a16-43f0-ab07-96ec5b41cc71 \
          --public-app-name <newName> --input <fixed.json> -o json
```
⚠️ 严禁本 SKILL 用 --app <已导入的 ApplicationId> 复用——那会越界进入 form C，请引导用户去 omics-task-skill。

典型会话场景

场景 A0：用户没装 CLI

任意命令报 FileNotFoundError / command not found: omics / 未找到 'omics' 命令 → 告知用户去 https://cnb.cool/tencenthealthcareomics/omics-platform-cli 下载页按页面安装脚本和使用指南安装，SKILL 不自动装；
等用户回执「已安装」→ 跑 omics version 验证 → 通过后进入场景 A。

场景 A：用户首次使用本 SKILL

whoami → 退出 2 → 告知用户去本机终端跑 omics login，等用户回执「已登录」
重新 whoami ✓ → 跑 config show → 退出 1 → 告知用户去本机终端跑 omics config set，等用户回执「已配置」
重新 config show ✓ → 进入业务流程

场景 B：跑 IgGM-WDL（标准链路）

whoami ✓ + config show ✓ → 复述当前配置
用户："跑 IgGM" 或 "做抗体设计" 或 "针对这个抗原生成抗体"
同名检查（§3）：执行 list apps -o json，匹配 Name == "IgGM-WDL"
- 0 条命中 → 通过
- ≥1 条命中 → 停下，请用户选「重命名」或「终止改用 omics-task-skill」
二次确认（按 §4.2 模板）