简体中文

English

简体中文

English

创建 Job ​

用途 ​

根据已发布的 BioLine Flow 版本和 JSON spec 创建一次云端 Job。本命令只负责提交和查询 BioLine Job；统计分析、绘图、表格和报告由独立下游 skill 处理。

语法 ​

bash
fkit job create [OPTIONS] <SPEC>

SPEC 格式 ​

SPEC 是本地 JSON 文件。推荐使用下面的精简格式：fkit job create 会读取所选 Flow 版本的服务端任务模板，再套用外部输入和参数覆盖。无需复制整张任务图。

先读取真实节点名、端口和参数，不得猜测：

bash
fkit flow inspect <FLOW_VERSION_ID> --json
fkit job template <FLOW_VERSION_ID> --json

job template 只读取、不创建 Job。返回的 tasks[].name 是节点名，tasks[].cmdParams[] 是 Flow 保存的参数及默认值；它不是必须原样提交的 CLI spec。模板可能只有 inputFiles 而没有顶层 inputs，因此不能直接保存后就提交。

字段修改规则
nameJob 名称。建议沿用模板生成的 <流程名>_<时间戳> 形式，便于用 fkit job list 检索。
flowVersionId必填，使用查询确认的精确 Flow 版本 ID。
outputDir只写输出目录名（例如 metagenome_20261013_0651）；不要带 /output/ 前缀，写成 /output/xxx 会变成 /output/output/xxx；也不要保留模板默认值 /output/（服务端会报输出目录错误），必须替换为具体目录名。
inputsfkit CLI 必填，每条为 {"fileId": ..., "taskName": ..., "taskPortName": ...}。无外部输入的 Flow 也要写 "inputs": []；有必填输入的 Flow 必须提供绑定。
params可省略。只写要覆盖的参数，每条为 {"taskName": ..., "paramKey": ..., "paramValue": "..."}；未列出的参数保留 Flow 保存值。

inputs[].taskName 必须是 Flow 内的真实节点名（如 SOAPnuke、fastq2fa），taskPortName 是该节点的端口显示名，可从 fkit flow inspect --json 的 inputs[]（taskName + name）对照得到；不能把流程级输入名当作 taskName。fileId 来自 fkit file search --json、fkit ls --json 或 fkit upload --json。如果已有模板的 inputFiles 绑定，将需要的绑定填入 CLI spec 的 inputs，不需要维护两份列表。

I/O 端口必须通过 inputs 绑定，不能写进参数覆盖；文件、文件组和目录必须匹配 Flow 端口类型及 pattern。不要给 tasks[] 里的节点写 outputDir。

示例：把 sleep 180 秒改成 30 秒 ​

先从真实模板中确认：哪个节点的哪个参数控制等待秒数，并确认其保存值是 "180"。下面的 <真实节点名>、<真实参数键> 和 <FLOW_VERSION_ID> 都必须替换成查询结果，不能根据命令 sleep 猜节点名或参数键。

对于没有外部输入的等待流程，推荐的 job_spec.json：

json
{
  "name": "sleep_20261016120000",
  "flowVersionId": "<FLOW_VERSION_ID>",
  "outputDir": "sleep_20261016120000",
  "inputs": [],
  "params": [
    {
      "taskName": "<真实节点名>",
      "paramKey": "<真实参数键>",
      "paramValue": "30"
    }
  ]
}

这里只把该参数的保存值 "180" 覆盖为 "30"，不修改已发布 Flow。若所选流程有外部输入，应在 inputs 中提供真实绑定。

兼容写法：tasks[].cmdParams ​

也支持将相同覆盖写在 tasks[].cmdParams 中：

json
{
  "name": "sleep_20261016120000",
  "flowVersionId": "<FLOW_VERSION_ID>",
  "outputDir": "sleep_20261016120000",
  "inputs": [],
  "tasks": [
    {
      "name": "<真实节点名>",
      "cmdParams": [
        {
          "paramKey": "<真实参数键>",
          "paramValue": "30",
          "isSelect": 1
        }
      ]
    }
  ]
}
  • tasks[].name 按模板中的节点名匹配，cmdParams[].paramKey 按该节点的参数键匹配；未知节点或参数会报错。
  • 同一节点有多个相同 paramKey 时，附上真实模板中的 index 消除歧义，不要猜序号。
  • 嵌套参数可覆盖 paramValue（字符串，包括空字符串）和 isSelect（0 表示不选，1 表示选中）；缺失的字段保留模板值，null 不表示“保留”。只修改选中状态时可省略 paramValue。
  • 原有顶层 params[] 继续支持。两种写法同时指定同一参数时，相同值可以合并，相冲突的覆盖会报错，不按出现顺序决定谁生效。通常只用一种写法。
  • 参数类型、前缀等元数据，命令、端口连线和节点资源均以服务端模板为准；本地 tasks 不会替换整张任务图。完整模板中的 I/O 参数保持原样，文件仍通过 inputs 提供。

AI 调用流程 ​

  1. 用 fkit flow list --json 确定精确 Flow 版本。
  2. 用 fkit flow inspect --json 读取输入输出、节点和参数契约。
  3. 用 fkit job template --json 读取真实任务模板、保存参数和资源。
  4. 用 fkit ls 或 fkit file search 定位并校验用户文件。
  5. 根据查询结果生成精简 job_spec.json，补齐 inputs 并填写显式参数覆盖。
  6. 展示 Job 计划并等待确认。
  7. 确认后执行 fkit job create <SPEC> --json。
  8. 用 fkit job get <JOB_ID> --json 查询状态；失败停止，不盲目重试。
  9. 成功后返回 Job ID、状态、输出目录和外部输出。下游统计、绘图和报告交给独立 skill。

用户确认 ​

只展示 Flow、输入文件、参数、资源、输出目录和风险；不展示原始 API、命令输出或下游 Docker 细节。

参数与选项 ​

  • --json — 输出机器可读的 Job 创建结果。

影响范围 ​

正式执行会向 BioLine 提交 Job，不会修改 Flow，也不会执行本地下游分析。

输出 ​

成功结果包含 Job ID、名称、Flow 版本、状态和输出目录。创建结果不明确时先用 fkit job list 或 fkit job search 确认；不要用同一名称重复提交（同名会被拒绝）。

读取本页 ​

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