前言¶
抗体、纳米抗体与抗原的复合体结构预测，通常要在腾讯健康组学平台（Omics）上选对公共应用、配好地域与 COS、再拼 omics run 参数。tFold Collection (Nextflow) 是一个包含四个 Nextflow 子应用的合集，平台规则还要求不能直接用合集 AppId 提交任务，必须先落到具体子应用。通用组学任务 Skill 能跑很多应用，但在 tFold 这条链路上容易多走 list public-apps、误用合集 ID 或越界调用命令。
下面介绍 SkillHub 上的 @tencent-adm/tfold-collection-skill：它是 omics-task-skill 的单合集收窄版，把子应用 AppId、Nextflow 版本和 CLI 白名单写死在 Skill 里，由 Agent 按固定步骤完成登录、配置、选子应用、同名检查与运行确认。
这是什么¶
一句话定位：腾讯健康组学平台（Omics）上 tFold Collection (Nextflow) 公共应用合集的专用运行助手，面向腾讯自研 tFold 抗体/纳米抗体与抗原复合体结构预测模型系列。
维护方：腾讯健康组学平台（SkillHub 坐标 @tencent-adm/tfold-collection-skill，来源 enterprise，分类 professional；当前 SkillHub 页面版本 v1.0.5，标签 requires_api_key=false）。
解决的问题：在对话式 Agent 里，把「只跑本合集四个子应用」约束成可执行流程；其他公共应用、本地 WDL、COS 上的 NF 或项目内已有应用应改用 omics-task-skill。
核心功能¶
Skill 内通过 scripts/omics_cli.py 拼接 omics-platform-cli 命令，能力范围等于 CLI 七类命令与子应用运行的交集。已核实要点如下。
合集与子应用（硬编码）¶
| 字段 | 值 |
|---|---|
| 合集名称 | tFold Collection (Nextflow) |
| 合集 AppId | 807fc9ae-6197-43c0-a7a8-993c09ec1ee2 |
| 类型 | NEXTFLOW / APP_COLLECTION |
合集 不能直接 omics run；须选用下表之一作为 --public-app：
| 子应用 | AppId | NF 版本 | 说明 |
|---|---|---|---|
tFold_ab_predict |
31d80b72-6fea-44d3-9eb5-4725584199ef |
v24.04.3 | tFold 抗体预测 |
tFold_ag_predict |
864d13a9-b162-432a-bfda-7f0b6bf137e7 |
v24.04.3 | tFold 抗原预测 |
tFold_ag_predict_icf |
2286b426-09eb-47d4-9608-325651d11157 |
v24.04.3 | tFold 抗原 ICF 预测 |
tFold_tcr_predict |
0ba6d880-27f1-475e-b4ec-d28885ab2b81 |
v24.04.3 | tFold TCR 预测 |
运行时 无需 再调用 list public-apps --parent-app 展开合集；Agent 按用户描述从清单匹配子应用即可。
允许的 CLI 能力¶
白名单内命令包括：version / login / whoami、config show|set|clear、list region|project|env|cos-bucket、list apps --type <selectedAppType>（导入前同名检查）、run --public-app <子应用 AppId>（须带 --public-app-name，Nextflow 须 --nf-version）、status / debug。未列出命令不得调用。
流程约束¶
- 鉴权与配置：
whoami→config show；C 端体验用户（Role == "trial_user"）在配置就绪后须执行quota首检，提交run前再次配额检查。 - 子应用选择：按编号、名称或功能描述匹配，唯一匹配后需用户确认。
- 导入前同名检查：
list apps --type <selectedAppType>，同名则引导重命名直至唯一。 - 运行前二次确认：展示合集、子应用、AppId、NF 版本、导入名与完整
omics run命令，用户明确回复「确认 / 继续 / y」后才执行。 - 本地输入文件：参数为本地路径时，须先
omics cos upload得到 COS URL，再写入--input；不得用本地路径直接跑容器任务。 - 越界请求：用户要跑合集外应用时，Skill 只引导改用
omics-task-skill，不提供绕过方案。
常见触发词包括：tFold Collection (Nextflow)、跑 tFold Collection (Nextflow)、蛋白质结构预测、run tfold collection (nextflow) 等（以 Skill 元数据为准）。
安装与启用¶
1、安装 SkillHub CLI（若尚未安装）¶
command -v skillhub && skillhub --version
未安装时可按 SkillHub 安装文档执行完整安装或仅 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
2、安装本 Skill¶
安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/ 可能不会被识别。
skillhub install @tencent-adm/tfold-collection-skill --dir <skills 目录>
常用路径示例：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
SkillHub 页面也支持将下列提示交给 AI，让其按 SkillHub 安装说明 完成安装：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@tencent-adm/tfold-collection-skill`。
3、组学 CLI¶
Skill 执行前会检查本机能否运行：
python3 scripts/omics_cli.py version
若未安装，按 Skill 包内 references/omics-cli-setup.md 引导安装 omics-platform-cli 并完成 omics login、omics config set（地域、项目、环境、COS 桶等）。
典型用法¶
标准对话链路¶
经过上面的步骤，典型会话为：鉴权与配置通过 → 从硬编码清单选定子应用（例如用户说「跑 tFold 抗体预测」对应 tFold_ab_predict）→ 同名检查通过 → 二次确认 → 执行 run → 必要时 status 或 debug 查失败原因。
Nextflow 子应用运行命令形态¶
Skill 内部构造的公共应用运行形态（子应用均为 NEXTFLOW，须传 --nf-version）如下。实际由 Agent 通过 omics_cli.py 调用，此处展示等价 CLI 便于对照：
omics run --public-app 31d80b72-6fea-44d3-9eb5-4725584199ef \
--public-app-name tFold_ab_predict \
--app-type NEXTFLOW \
--nf-version v24.04.3 \
[--input /path/to/input.json] \
[--name my_run] \
-o json
注意：--public-app 必须是上表中的 子应用 AppId，不能填合集 AppId 807fc9ae-6197-43c0-a7a8-993c09ec1ee2。未传 --input 时，CLI 可使用该子应用第一个 InputTemplate 作为默认参数基线。
本地文件先上传 COS¶
当输入为 Agent 本地生成的 FASTA 等文件时，先上传再替换参数：
python3 scripts/omics_cli.py cos upload \
--file /tmp/generated_protein.fasta \
--cos-path uploads/protein_sequence.fasta \
-o json
再将返回的 CosUrl 写入 run 的 input JSON，继续 omics run 流程。
状态与排错¶
python3 scripts/omics_cli.py status -o json
python3 scripts/omics_cli.py debug <rgId> -o json
若参数含 outdir，任务终态后 Skill 会按模板提醒用户到输出目录查看结果；异步失败可结合 references/runtime_error_kb.md 做三段式 debug。
适用场景与注意¶
适合谁：已在或计划使用腾讯健康组学平台、需要反复导入并运行 tFold 四个 Nextflow 子应用的分析人员；希望用 Cursor 等 Agent 减少手工拼 CLI、避免合集/子应用 ID 混用的人。
边界与注意：
- 仅覆盖 tFold Collection (Nextflow) 下四个子应用；其他 Omics 公共应用、form A/C 运行方式、项目内已有应用一律走
omics-task-skill。 - 合集增删子应用后，需重新生成/更新 Skill，清单以当时安装的 Skill 包为准。
- C 端体验用户受
quota限制，到期或当日次数用尽会阻断 run。 - Skill 标签标明无需单独 API Key，但 Omics 仍依赖账号 OAuth 登录与平台资源配置。
- SkillHub 统计（页面抓取）：下载约 941 次；评分字段为平台展示值，以 SkillHub 页面实时数据为准。
结尾¶
@tencent-adm/tfold-collection-skill 把 tFold 合集的运行规则收敛成 Agent 可执行的固定剧本：子应用 ID 内置、命令白名单、同名检查与运行前确认，降低在 Omics 上跑抗原抗体复合结构预测任务的操作成本。官方入口：
- SkillHub：https://www.skillhub.cn/skills/tencent-adm/tfold-collection-skill
- API 坐标页：https://api.skillhub.cn/tencent-adm/tfold-collection-skill
