创建 Flow

用途

根据已经发布的 BioLine 工具版本，把多个工具组织成可复用的有向无环流程（DAG）。单节点（如一次性构建参考基因组索引）也按同一流程处理。Flow JSON 必须提供非空 desc 以及符合解析器 Schema 的必填 method 对象；desc 会写入网页显示的流程描述，未提供时 fkit 可从 method.purpose 兼容回退。

默认只规划在 BioLine Job 中运行的上游固定分析。统计整理、差异分析、绘图和报告等下游工作不作为 Flow 节点推荐或加入 Flow 图；上游 Job 完成后，应从项目 Tool 中动态选择合适的下游分析工具，使用 fkit pull 拉取到 AI 终端，并通过该工具镜像运行。只有用户明确要求将具体下游工作纳入 BioLine Flow 时，才检查对应工具版本、端口和运行条件，并按用户要求规划。不要因为平台上存在某个下游 Tool，就自动把它串进 Flow。

语法与命名约束

fkit flow create [OPTIONS] --file <FILE> <FLOW_NAME>

• 名称唯一性与长度上限：<FLOW_NAME> 在项目内必须唯一（同名再次创建会被拒绝），且长度严格不超过 24 个字符。
• 版本迭代限制：fkit flow 仅提供 create、list、inspect 子命令，不支持对已有同名 Flow 追加版本。当底层工具升级版本（如 metaphlan4:1 → metaphlan4:2）需要更新流程时，必须拟定新的唯一名称（≤24 字符，例如缩写前缀并附加 -v2）重新调用 fkit flow create。

AI 调用流程

当用户表达“创建流程”“把这些工具串起来”“制作一条分析流程”等意图时：

1. 读取工具清单：读取一次 fkit tool list --json，解析工具名称和版本；用户未指定版本时默认使用最新版。
2. 补齐缺失工具：如果用户指定的工具不存在，先读取 fkit create-tool --docs，按创建工具方案核实镜像、命令、参数和输入输出，并创建、配置和读回核对缺失工具。工具创建完成后重新读取工具清单；不得猜测工具版本或跳过工具配置。工具创建和 Flow 发布是两个独立的确认点；若任一工具创建失败，立即停止 Flow 创建，不发布不完整的流程。
3. 导出并核查工具配置与运行就绪度（关键防错步）：对每个已存在或刚创建的工具执行 fkit tool config export 和 fkit tool summary export，配置是端口契约的唯一依据。若工具摘要标注“最小运行验证未完成”或涉及大型外部数据库/双端输入，须在组流前重点核查以下三项（如发现缺陷，先走 fkit update <TOOL:VER> --mode new-version 发布新工具版本）：
   • 端口占位符路径语义：在 BioLine 容器运行时，file 型 I/O 端口占位符（如 #{io<:>profile}、#{io<:>cleaned_r1}）会被直接渲染为完整文件路径（如 /io/profile/profile、/io/cleaned_r1/cleaned_r1.fq.gz），而 folder 型端口占位符渲染为目录路径（如 /io/database/）。因此，file 型输出端口在命令中必须直接作为输出文件路径使用（如 -o "$4"），严禁写成 -o "$4/profile"（会导致多套一层目录）；若工具会自动追加扩展名（如 .txt），应在命令末尾追加兼容回移逻辑（如 && if [ -f "$4.txt" ]; then mv "$4.txt" "$4"; fi）。
   • 双端/多文件 CLI 参数语义核实：切勿猜测命令参数；对未实跑验证的工具，可通过 fkit pull 拉取镜像到本地核对 --help 或源码。以 metaphlan4 为例，其 -1/-2 参数仅在同时指定 --subsampling_paired 时生效，普通调用下会被静默忽略并改为从空 stdin 读取（触发 Error, input data has to be in fastq or fasta format）；常规双端 FASTQ 必须合并为逗号分隔的位置参数 "$1,$2"，且因包含逗号多文件，必须同时指定 --no_map 或 --bowtie2out（否则报错 Error! --bowtie2out needs to be specified when multiple FASTQ or FASTA files (comma separated) are provided）。
   • 容器内存与外部数据库体积匹配（防 OOM）：先用 fkit ls <数据库目录> --json 统计外部数据库/索引文件总大小，并核对工具配置的 memory 上限。例如 MetaPhlAn4 的 CHOCOPhlAnSGB（.bt2l）索引合计约 23 GB，若沿用 16 GB 内存上限，运行时会因内存耗尽触发 (ERR): bowtie2-align died with signal 9 (KILL)（并级联引发下游格式报错），必须提前将工具版本内存调高至充裕规格（如 64 GB，并按需匹配 CPU 与线程数）。
4. 核对云端数据库/索引依赖与建库策略：
   • 若用户指定了云端 /database/ 下的参考基因组或数据库，使用 fkit ls 或 fkit file search（只读）确认文件真实存在且格式匹配端口要求。严格区分“原始参考基因组 FASTA（如 .fna）”与“索引目录（如 bowtie2 要求的基名为 host_index 的 .bt2/.bt2l 目录）”，切勿将原始 FASTA 目录直接绑定给要求索引的 folder 端口。
   • 若云端仅有原始 FASTA 而无对应索引，优先规划一次性独立建索引 Flow（如单节点 bowtie2-build）+ Job，待索引产物生成后（存入 /database/ 或直接保留在建索引 Job 输出目录）供主流程绑定复用，避免将建索引节点串入主流程导致每次运行重复耗费算力。
5. 校验端口契约与连接关系：校验端口名称、类型、pattern、参数和连接关系。file 与 file_group 可互连，folder 只能连接 folder。未连接的输入和输出自动成为流程对外端口；至少保留一个外部输入和一个外部输出。每个输入端口最多一个来源，输出端口可以扇出。I/O 端口不能写进节点 params。
   • 内部连接与对外端口的取舍：单一输出端口不能既作为内部连线连给下游节点、又同时作为 Flow 对外输出端口暴露。对预计可能供其它下游复用的中间产物（如去宿主后的 unmapped_r1/unmapped_r2），须在计划中向用户说明“内部连给下一节点”与“暴露为对外输出端口”之间的取舍。
6. 拓扑与 DAG 校验：按工具语义检查拓扑顺序，确认图是 DAG；不得猜测端口或参数。
7. 生成 Flow 图并执行 --dry-run 预校验：生成包含非空 desc、nodes、connections 和必填 method 的 Flow 图文件，并生成中英双语摘要。在向远端正式创建前，必须先执行 fkit flow create --file <FILE> --dry-run <FLOW_NAME> 校验 JSON Schema 与图结构。
8. 展示计划并等待用户确认：先在聊天中展示简洁的上游 Flow 计划，等待用户确认；如需说明下游工作，将其列为 Job 完成后的独立阶段，而非 Flow 节点。确认后才调用正式 fkit flow create。
9. 读回核对：创建成功后必须用 fkit flow inspect <flowVersionId> --json 及 fkit flow list --json 读回核对版本、节点、端口、连接和 desc 描述。

Flow 文件要求

fkit flow create 解析器对 JSON 结构校验严格，desc、nodes、connections、method 均为必填顶层字段（缺失 method 会报 missing field method）：

{
  "desc": "宏基因组宿主去除与物种注释流程：fastp 质控清洗双端 reads；bowtie2 比对宿主参考基因组去除宿主序列；metaphlan4 对去宿主 reads 进行物种丰度注释。",
  "nodes": [
    {"id": "fastp", "tool": "fastp:1", "params": {"threads": 4}},
    {"id": "bowtie2", "tool": "bowtie2:1", "params": {"threads": 8}},
    {"id": "metaphlan4", "tool": "metaphlan4:4", "params": {"threads": 8}}
  ],
  "connections": [
    {"from": "fastp.cleaned_r1", "to": "bowtie2.r1"},
    {"from": "fastp.cleaned_r2", "to": "bowtie2.r2"},
    {"from": "bowtie2.unmapped_r1", "to": "metaphlan4.r1"},
    {"from": "bowtie2.unmapped_r2", "to": "metaphlan4.r2"}
  ],
  "method": {
    "purpose": "paired-end quality control, host depletion, and taxonomic profiling",
    "ordered_steps": [
      {"node": "fastp", "rationale": "Quality control and adapter trimming on raw paired-end reads"},
      {"node": "bowtie2", "rationale": "Align cleaned reads against host index and retain unmapped read pairs"},
      {"node": "metaphlan4", "rationale": "Taxonomic profiling on host-depleted paired-end reads"}
    ],
    "sources": [
      {
        "kind": "official",
        "title": "BioLine Flow Create Documentation",
        "url": "https://www.bioline.cloud/ai/commandLineAndFkit/commands/flow-create/"
      }
    ]
  }
}

字段校验细则

• desc：用户可见的流程描述，应说明流程目的、主要节点和关键输出，不能为空。创建后必须用 flow inspect 或 flow list --json 读回并核对描述。
• nodes：节点 id 必须唯一，不含 . 或 #；tool 引用必须是清单中存在的精确 TOOL:正整数；I/O 端口严禁写入 params。
• connections：有向边数组，单节点流程无内部连线时传空数组 []。
• method：必填对象，用于记录设计依据和顺序校验。注意子字段必须严格遵循以下对象结构（严禁将 ordered_steps 或 sources 写成字符串数组）：
  • purpose：非空字符串，描述流程设计目的。
  • ordered_steps：对象数组，每个元素必须为 {"node": "<节点ID>", "rationale": "<步骤顺序与设计理由>"}。
  • sources：对象数组，每个元素必须为 {"kind": "official" | "literature", "title": "<来源标题>", "url": "<来源URL>"}（kind 枚举值仅限 "official" 或 "literature"）。

工具更新、锁版本与运行排障联动规范

在 Flow 规划或关联 Job 验证过程中，若发现节点工具配置有误或运行失败，按以下规范闭环处理：

1. 工具锁版本（locked=true）与新版本发布：
   • 工具版本一旦被任何已创建的 Flow 引用，其状态即变为 locked=true（可通过 fkit tool info <TOOL:VER> --json 核查），平台禁止原地修改（in-place）。
   • 修复命令、参数或资源时，必须以原版本为基线，通过 fkit update <TOOL:VER> --mode new-version --config <PATCH_JSON> --json 发布新工具版本（如 metaphlan4:2 → :3 → :4），并在创建 Flow 新名称（≤24 字符）中引用该新版本。
2. Job 失败可观测性缺口与日志取证：
   • 当 Flow 提交的 Job 失败（status = -1）时，fkit job get <pipelineId> --json 返回的 Job 级与 Task 级 errMsg 往往为空字符串（""）。
   • 排障铁律：不得仅凭 fkit job get 输出猜测原因；必须执行 fkit ls /output/<outputDir>/<nodeName>/ --json 定位对应失败节点的日志文件（如 <nodeName>.log），再用 fkit download 下载到本地读取实际执行的 shell 命令、完整报错堆栈以及容器资源统计（最大内存占比、CPU 使用率），区分是命令/参数语法错误还是容器内存不足（OOM signal 9 KILL）。

用户确认

计划只展示工具、节点顺序、连接、对外输入输出（及内部连接与对外端口的取舍）、参数、资源配置、顺序理由和风险（如数据库/索引是否就绪、工具是否完成最小运行验证）。不要展示命令原文、原始 CLI 输出、内部 workspace 路径或调试过程。用户确认后连续完成 --dry-run 校验、正式创建和 flow inspect 读回核对，不在中间再次确认。

参数与选项

• --file <FILE> — 必填；Flow JSON 图文件。
• --dry-run — 只校验图 Schema 与连接并预览生成结果，不创建远端 Flow。正式创建前推荐先执行一次 --dry-run。

影响范围

正式执行会在 BioLine 创建一个新的 Flow（及其初始版本 v1）；--dry-run 不写入远端。

输出

成功时返回 Flow 名称、Flow ID 和版本（及 latestFlowVersionId）。创建后必须读取 fkit flow inspect <flowVersionId> --json 进行核对。

读取本页

添加 --docs 可从 BioLine 官方 AI 文档读取本页；--docs-json 返回 JSON 包装。