创建 Tool：完整操作指南

用途

本页供用户和 AI Agent 从头完成一个或多个全新 BioLine 工具的创建：名称查重、镜像与软件证据核实、配置准备、镜像拉取、工具创建、正式配置、读回核对，以及可选的云端任务验收。配置格式和检查规则全部包含在本页，创建过程不依赖本地 Skill、专用 Python/Shell 脚本或 Gateway。

必须区分命令与流程：fkit create-tool 本身只把本地 Docker 镜像导出、压缩、上传并创建远端工具；它不会自动拉取镜像、生成或应用工具配置、写入工具摘要、创建 Flow/Job，也不会自动执行本页的确认和检查步骤。以下步骤由操作者或 AI 依次执行，属于操作规范，不是 fkit 已强制实现的状态机。

语法

fkit create-tool [OPTIONS] <IMAGE_NAME> <TOOL_NAME>

参数与选项

• IMAGE_NAME：已经存在于本地 Docker 中、已核实来源的精确镜像引用。
• TOOL_NAME：当前项目中全新且唯一的工具名。
• -t, --tmp <TMP>：镜像导出和压缩的临时目录；应有足够磁盘空间。
• --json：输出创建结果，包含 toolId、toolVersionId、toolName、version。

create-tool 没有 --dry-run、--yes、--config 或 --summary 参数。正式配置使用下文的 tool config apply 和 tool summary apply。

影响范围

镜像拉取写入本地 Docker 存储；create-tool 创建云端工具并上传镜像；不带 --dry-run 的 config/summary apply 分别写入云端配置和说明。配置与摘要是两次独立写入，不保证原子性。Flow 创建和 Job 提交属于后续独立操作。

安全使用与适用边界

只处理此前不存在、初始平台版本为整数 1 的工具。软件版本、环境版本、数据库版本、镜像 tag 与平台工具版本是不同概念，不能混用。更新已有工具时停止此流程，另行读取 fkit update --docs，不得自动新增版本或覆盖现有工具。

没有具体工具名称时只提示“请告诉我工具名称”。名称支持逗号、中文逗号、分号、换行和编号列表分隔，按 Unicode 大小写不敏感方式去重并保留首次顺序。每个工具使用独立工作目录，按顺序执行。

用户确认完整创建计划一次，即授权计划内的镜像拉取（如需）、工具创建、正式配置、摘要写入和导出读回核对。确认后连续执行，不按内部阶段重复询问，不执行 config/summary dry-run。失败、用户取消或必须变更已确认内容时暂停；变更后的计划需重新确认。可选 Flow/Job 验收不包含在创建授权内，仍单独选择和确认。不得运行宿主生信程序、本地容器、镜像构建或 smoke 测试来代替云端验收。

不输出或保存密码、令牌、Cookie、STS 或镜像仓库凭证。不绕过服务端引用锁定，不擅自修改已有 Flow；若服务端因工具被引用而拒绝配置，报告原因，由用户处理引用。

一、名称查重与工作目录

先确认 fkit 可用、已登录且当前项目明确。需要登录时由用户完成 fkit login --host https://www.bioline.cloud；不要把密钥写进命令记录或生成文件，不用交互式 fkit project 作为无人值守的探测命令。

对一批名称先查询一次：

fkit tool list --json

对真实返回数组的 name 做大小写不敏感的精确或包含匹配。任意匹配均视为可能已存在：列出真实名称和版本，跳过该目标，告知用户可到网页检查或另行使用更新流程。不能用 Flow 列表、网页或镜像搜索结果代替工具查询。查询失败、未登录、项目不明确或结果不能解析时停止整个批次。

最终显示名默认取镜像仓库最后一段，不含 tag/digest；用户可以指定名称，但不能含路径分隔符、冒号、空白或控制字符。查重必须覆盖用户请求名和最终显示名；名称变化时重新核对。

为每个未匹配工具选择一个新的绝对工作目录 WORKSPACE，例如 /data/authoring/tool-<安全名称>-<本次唯一编号>/，先检查可写且不覆盖既有任务。后文的 WORKSPACE、IMAGE、TOOL_NAME、TOOL:VERSION 都是占位值，执行前替换为已核实的实际值。保存：

WORKSPACE/intent.md
WORKSPACE/spec/duplicate_check.json
WORKSPACE/spec/tool_request.json
WORKSPACE/spec/tool_config.json
WORKSPACE/spec/README.md
WORKSPACE/spec/plan.md
WORKSPACE/spec/state.json
WORKSPACE/spec/pull_result.json
WORKSPACE/logs/
WORKSPACE/result.json

这些是本次任务的记录，不是需要安装的程序。记录每阶段时间、证据、确认范围和实际返回值；未发生的动作不能预写成功。保留查重结果，创建前和创建后还需要刷新列表核对，不受初始批量查询“一次”的限制。

二、核实镜像、命令与资源证据

软件版本、命令、输入输出、运行环境、数据库及资源依据来自对应版本的官网、官方文档、源码仓库或发布记录。搜索结果只用于定位原始证据；记录实际 URL 和它支持的具体结论，不能用示例链接或猜测代替。未证明时不能声称镜像含 SignalP 等依赖，也不能把“可能最后发布”写成“最终版本”。

按 official → BioContainers → Docker Trusted Content → linked GHCR 核实镜像来源。四个槽位均记录 available、unavailable 或 rejected、证据与原因，并单独标识唯一选中项；选择最早可用来源，不能伪造未查询槽位。GHCR 必须有官方源码仓库关联证据，BioContainers 保持 quay.io/biocontainers/... 原始来源。

必须使用精确 registry/repository:tag，不能使用 latest、无 tag 或猜测 tag。固定平台 linux/amd64 与完整小写 sha256: digest。对多架构镜像区分索引 digest 和 amd64 子 manifest digest；记录两者关系，比较 RepoDigest 时比较同一类对象，不能拿不同层级的 digest 直接比较。不能唯一确定目标平台及镜像身份时停止。

Docker Hub 缓存候选按以下顺序核实，保留原仓库路径和 tag；BioContainers/GHCR 保持原 registry：

https://docker.m.daocloud.io
https://docker.nju.edu.cn
https://do.nark.eu.org
https://docker.mirrors.ustc.edu.cn
https://docker.1ms.run
https://docker.1ms.run

不测速重排，不修改 Docker 全局代理或 daemon 配置。官方镜像若位于其他不支持的 registry，停止并请用户提供可核验、获批准的访问来源。一次计划只选择一个精确地址，拉取失败不能自动切换缓存、registry、tag 或自行构建镜像。

可通过 registry 的只读 manifest 接口或 docker manifest inspect --verbose IMAGE 获取实际元数据，不执行容器。记录所选 amd64 镜像的压缩层总字节数，并计算 字节数 / (速度 × 1000000)，分别展示 1、5、10 MB/s 的理论秒数；这不包含解压、重试及上传时间，不能作为完成承诺。

tool_request.json 至少记录请求名、最终名、原始来源、拉取地址、来源类别、软件/环境/数据库版本、架构、manifest 与预期 RepoDigest、四个候选槽位、证据、逐项资源依据、数据库兼容性及输出目录策略。无数据库时明确 not_applicable；有数据库时证据必须同时覆盖工具版本与数据库版本。依赖或版本无法证明时暂停该工具，不猜测补齐。

工具运行依赖参考数据库时，拉取镜像后、创建远端工具前，必须在镜像内检查数据库文件是否实际存在，并核对软件默认搜索路径或命令指定路径、数据库版本和必需的索引文件；不能仅凭镜像名称、软件已安装或文档示例认定数据库已内置。记录检查命令和结果。若数据库缺失，先向用户说明所需数据库、版本、预计下载量及存储需求、来源和接入方式（新镜像内置或作为独立输入挂载），询问是否下载；未得到明确答复前不得下载数据库或创建依赖它的工具。获准后完成下载与接入，并用最终镜像或挂载方式执行最小运行；不能把缺库错误作为可跳过的测试例外。

三、完整配置格式（无需另读子文档）

工具的配置格式按工具类型分为两类，创建前先判断用户要创建的是哪一类：

• 上游分析工具：常见的生信上游分析工具，需要具体命令行代码的工具，上游分析在 BioLine 上执行；使用下文“上游工具的配置格式”，摘要不打工具标签。
• 下游分析工具：本质是一个大型分析环境，创建时不需要命令行配置——由 AI Agent 读取工具摘要后根据用户需求自己生成代码执行。下游分析工具需要配置机器资源参数，不需要配置命令行参数；使用下文“下游工具的配置格式”，摘要必须打上“工具标签：下游分析工具”。

无法唯一确定类型时先向用户确认；不得猜测归类，不得把下游工具按上游格式配置命令，也不得把上游工具按下游格式处理。

上游工具的配置格式

本节适用于在 BioLine 上执行固定命令行分析的上游分析工具，覆盖命令与参数的验证、运行门禁、占位符与端点、资源和完整配置示例；摘要不打工具标签。下游分析工具不需要命令行配置，使用后文“下游工具的配置格式”。

命令与参数的实际验证

参数、可选值和默认行为必须按选定工具版本能提供的证据核实。--help 只是可选证据之一，不是所有工具都支持。可按实际情况使用：镜像内的帮助、版本或 usage 命令；镜像内 README、man page、示例或自带文档；对应版本的官方文档、源码仓库、发布说明或官方示例；以及最小有效数据运行测试。

帮助或官方资料用于证明参数和可选值；最小运行用于证明最终命令、输出路径和后处理实际可执行。每个参数记录证据来源和版本，无法证明的参数、默认值或可选值不得写入配置。

可选参数表示默认或不启用时，按软件实际语义省略整个选项。不能把 default、空字符串或占位词当作通用默认值传给程序；如果软件的默认模式是不传 --presets，就必须从命令中省略 --presets。

最小运行必须覆盖工具计划声明的实际输入模式和关键运行分支：单端/双端、压缩/未压缩、文件/目录输入、是否使用数据库以及启用的可选参数。对于某种模式要求成对参数、配套开关或互斥选项的工具，必须从当前镜像的帮助、官方文档或实际报错中核实这些条件，并将必需参数写入最终命令；不能只验证程序能启动或只用另一种模式测试。若计划支持多个模式，应分别测试，或明确限制为已测试的模式。

这项检查必须使用最终端点展开后的完整命令：双端、成对、分组或多文件输入要提供与最终端点数量和类型一致的测试文件，并一次性验证相关参数组合；依赖数据库的工具要挂载已核实的数据库目录，使用最终数据库参数和路径运行。只有命令退出码为 0 且实际产生声明输出时，才算该输入模式通过；--help、单端示例、不带数据库或只验证程序启动均不能替代。

没有合适测试数据时，必须标注“参数证据已核实，最小运行尚未验证”，不能声称运行验证通过。命令包含建目录、复制、移动、管道或条件逻辑时，最小测试必须覆盖这些后处理步骤。

本地最小运行门禁

镜像拉取后，创建远端工具前必须优先在本地 Docker 中运行一次最小有效测试。测试使用最终配置展开后的真实命令，不能只运行主程序或只检查帮助信息；必须覆盖完整命令、参数默认值、输入路径、输出路径，以及建目录、复制、移动、重命名、管道和条件逻辑等后处理。

测试只有同时满足以下条件才算通过：程序退出码为 0；每个声明的输出文件或目录真实生成；文件名、扩展名、目录层级与端点的 type、path、pattern 一致；所有后处理命令成功；输出可以被预期的下游端口直接使用。测试日志、实际展开命令、镜像身份和产物清单写入工作目录，作为创建计划的证据。

本地测试失败时，先修正命令或端点配置，不得创建远端工具。没有合适测试数据、必须使用超大数据库、特殊硬件或本地无法运行的工具，可以记录例外，但计划必须明确写出“最小运行尚未验证”和风险；不得把帮助检查或配置读回当作运行通过。

创建前最小运行门禁

只要本机有 Docker 且镜像可以运行，远程 fkit create-tool 之前必须先做一次最小化 smoke test。测试不是只执行主程序，而是使用真实镜像、真实命令和小型有效输入，把所有占位符替换成临时目录中的实际路径，完整执行命令以及后续的 mkdir、cp、mv、重命名、管道和条件逻辑。

测试必须逐项检查：

• 程序退出码为 0；
• 每个输入参数实际收到的是文件路径、目录路径或参数值；
• 每个声明的输出都按配置的 type/path/pattern 生成；
• 命令中引用的每个文件名确实存在，不能凭名称猜测 final.asm.fa、megahit.log 等结果；
• 输出文件不是被错误创建成目录，输出目录也不是被当成文件使用；
• 声明为下游连接的文件可以被单独取出并读取。

若 smoke test 失败，必须停在本地修正命令或端点配置，不能创建远程工具，也不能把失败测试写成“已验证”。只有 smoke test 成功后，才进入一次性的用户创建计划确认。若本机没有 Docker、没有可用测试数据或工具必须依赖真实大数据，必须明确标注“创建前运行测试未完成”并把风险展示给用户，由用户决定是否继续。

生成完整 JSON，顶层包含且仅包含 command、inputs、outputs、resources。不使用局部补丁；name、version、parameters、image 和 runtime_preflight 不得放在顶层。配置前必须有官方命令依据，推断项必须明确标注，在完整创建计划中一并确认。

命令占位符

组件内部使用 <:>，组件之间使用 <|>：

用途	语法
必需 I/O	#{io<:>input_file}
可选 I/O	`#{io<:>mask<
字符串参数	#{string<:>mode<:>fast}
数字参数	#{number<:>threads<:>8}
带前缀 I/O	`#{prefix<:>--out<
布尔标志	#{prefix<:>--verbose}

参数键以字母开头，只含字母、数字、下划线。option 最多一次且在最后。同一键重复出现时类型、默认值、前缀和可选性一致；每个 I/O 键必须对应一个端点的 directory，不能缺少或多出端点。

file_group 可能展开为多个路径，不能把整个占位符错误地引用为一个普通字符串。sh -c '脚本' sh 参数... 中，脚本后的 sh 占用 $0，真实参数从 $1 开始。根据工具证据确认传参方式和子目录保留行为，不猜测容器内路径。

输入输出端点

每个端点有 name、type、directory、pattern、path。name 是显示名；directory 是占位符匹配键及运行时 /io/<directory>/ 目录名；两者各自在所有输入输出中唯一。数组顺序决定端点顺序，不人为限制端点数量。

输入和输出的 name 都必须完整匹配 ^[A-Za-z0-9][A-Za-z0-9_-]{0,254}$：长度 1–255，以英文字母或数字开头，只能包含英文字母、数字、下划线和连字符，不能包含空格或中文。例如用 contigs_fasta，不能用 Contigs FASTA；中文用途说明放入 README。directory 仍须遵守上文占位符键规则，不要把显示名与命令匹配键混淆。

输入和输出端点的 pattern 默认优先使用 "*"，以便匹配实际文件名。平台会根据 path: "file"、inCmd: 1 和 pattern 自动把端点展开为 /io/<directory>/<pattern>；因此优先让平台拼接，只有平台无法表达时才使用 sh -c。输出文件组不能使用 path: "file"。实际格式要求写入 README。

Shell 包装不是默认步骤。 如果程序可以直接接收端点占位符，就必须优先生成普通命令，例如 megahit -r #{io<:>reads} -o #{io<:>assembly}。只有需要创建目录、移动或复制文件、设置环境变量、执行管道/条件/循环，或平台原生端点无法表达时，才使用 sh -c 或 bash -c；使用时必须核对 $0、$1 等参数位置。

type 只能为 file、file_group、folder，按实际用途选择；path 为 file 或 directory。folder 固定 path: "directory"。输入禁止 subpath；输出可用安全相对目录 subpath，非空时必须以 / 结尾，不能含绝对路径、反斜杠或 ..，不能用它填写文件名。

面向后续流程的输出拆分

端点类型 type 与 IO 显示类型 path 是两个独立设置。 type: "file" 只表示单文件端点，不保证命令占位符展开为文件路径。凡直接传给程序“输入文件/输出文件”参数的 I/O，必须显式设置 path: "file"（网页中的“文件路径”）；程序参数明确要求目录时才使用 path: "directory"（“目录路径”）。不能因为文件存放在端点目录中，就把显示类型设置为目录路径。path 对应接口的 inCmd（文件路径为 1，目录路径为 0）；paramType 的 2/3 表示输入/输出方向，不能用来判断路径类型。

例如 fastp 的 -i、-I、-o、-O、-j、-h 都接受文件路径。r1、r2 输入，以及 cleaned_r1、cleaned_r2、json_report、html_report 输出均应设置 type: "file"、path: "file"。输入和输出优先使用 pattern: "*"；如果程序需要固定输出文件名，输出端点使用该文件名作为 pattern，由平台自动拼接。fastp 应直接使用 -o #{io<:>cleaned_r1} 等占位符，不需要 sh -c。输出端点示例：

{"name":"cleaned_r1","type":"file","directory":"cleaned_r1","pattern":"*","path":"file"}

创建计划必须列出每个端点的 type、path 和对应程序参数，并在本地检查及配置读回时逐项核对。检查命令展开语义：直接作为输出文件参数的值必须通过 path: "file" 和具体 pattern 让平台展开为实际文件名，不能只是以 / 结尾的端点目录。例如 -o /io/cleaned_r1/ 会让 fastp 尝试把目录当文件写入，产生 Failed to write。输出文件名、扩展名和压缩方式也必须符合程序与下游要求，不能把占位符示意路径当作真实文件名。读回后必须比较 type、path、pattern、directory、subpath 与命令；发现差异必须报告未验证完成，禁止宣称配置成功。此检查不要求运行任务或恢复 dry-run。

输出端点必须按后续 Flow 节点实际消费方式设计，优先保证可连接性。不同语义、不同文件名或下游可能分别使用的结果必须拆成独立输出端点；不要把多个关键结果塞进一个 folder 端点。例如 fastp 的双端清洗结果应使用两个 file 输出：cleaned_r1 和 cleaned_r2，而不是一个同时包含 cleaned_R1.fq.gz、cleaned_R2.fq.gz 的 cleaned_reads folder。下游节点需要哪一个文件，就连接对应端口。

只有确实是目录集合、文件数量不固定、必须保持目录结构或下游整体消费的结果才使用 folder；一组同类且需要作为集合传递的文件才使用 file_group。HTML/JSON 报告等辅助产物如果下游会分别读取，也拆成独立 file 输出；如果只是给用户查看且不参与流程，可合并到一个报告 folder。计划中必须说明每个输出端点的下游连接对象和选择 file、file_group 或 folder 的理由。

对组装、比对、注释等会产生多个固定结果文件的工具，必须优先为每个后续可能单独连接的文件建立独立 file 输出，例如 contigs、assembly_graph、contig_paths、json_report。不能只建立一个 assembly_output folder 再把所有结果留在里面。只有文件名或数量无法预先确定、必须保持目录结构，或下游确实整体消费时，才保留 folder。创建计划必须列出固定文件名、pattern、下游用途和连接对象。

资源

resources 必须包含正数 cpu、memory、disk，disk_type 为 normal 或 high，network_mbps 只能是 0、1、5、10、50、100。可选 gpu 为 {"spec":"实际规格名称","count":1}，名称非空且数量为正整数。

逐项解释 CPU、内存、磁盘、磁盘类型、网络及可选 GPU 的依据；推荐值在完整创建计划中一并确认。CPU、内存和磁盘表示最低需求；fkit 会从当前可用机器中选择满足需求的最小规格，GPU 型号和数量必须匹配，由正式 config apply 执行平台校验；本流程不执行 dry-run，不能把本地检查称为平台已接受。资源不匹配时可能已经创建远端工具，必须报告部分完成并停止。

完整配置示例

以下示例优先展示不使用 Shell 包装的直接命令；实际命令和资源必须替换为已核实内容。除非存在特殊 Shell 需求，不得把 sh -c 或 bash -c 作为模板。

{
  "command": "megahit -r #{io<:>input_a} -o #{io<:>output_a}",
  "inputs": [
    {"name":"input_a","type":"file","directory":"input_a","pattern":"*","path":"file"},
    {"name":"input_b","type":"file","directory":"input_b","pattern":"*","path":"file"}
  ],
  "outputs": [
    {"name":"output_a","type":"folder","directory":"output_a","pattern":"*","path":"directory"},
    {"name":"output_b","type":"folder","directory":"output_b","pattern":"*","path":"directory"}
  ],
  "resources": {"cpu":2,"memory":4.0,"disk":20,"disk_type":"normal","network_mbps":0}
}

输出目录兼容性与说明文档

BioLine 可能预创建 folder 输出目录。对每个 folder 输出在 tool_request.json.runtime_preflight.outputs 中记录已验证策略：application_accepts_existing（程序接受现有目录）、dedicated_child_directory（写端点下独立子目录）、force_flag（官方明确支持的强制参数）。策略必须与实际命令一致；子目录策略还要核对结果收集路径。Prokka 若直接使用预创建的 --outdir，必须包含 --force。缺少兼容性证据则阻止创建。

生成中英双语 spec/README.md，包含概述、镜像及软件版本、输入、输出、参数、资源、数据库、限制和证据链接。事实必须来自已审阅配置和证据，不宣称未经执行的效果。将完整配置与说明一起展示给用户。

本地逐项检查四顶层键、占位符与端点一一对应、所有输入输出名称符合上述正则、输入输出优先使用 pattern: "*"，并检查命令中的文件名拼接、端点类型/路径、资源与目录策略。不合规则先修正再展示创建计划，不要等创建远端工具后才检查。可使用通用 JSON 工具检查语法，但不依赖专用本地校验程序。本流程省略 config/summary dry-run，不从空配置工具先行导出配置。

下游工具的配置格式

下游工具没有固定分析命令，创建时需要配置机器资源参数，不需要命令行配置：以命令为中心的“命令与参数的实际验证”及其派生的最小运行门禁、占位符与端点到命令的映射等内容均不适用。下游工具的能力与使用方式通过摘要完整描述，摘要即 AI Agent 后续选取功能的配置文件。名称查重、镜像与来源证据核实、镜像拉取、fkit create-tool 创建、正式配置与读回核对（第四至六部分）与上游一致，不因类型而省略。

摘要标签

下游工具的摘要必须打上工具标签：

工具标签：下游分析工具

该标签用于与在 BioLine 上执行固定命令的上游工具区分；上游工具不打此标签，下游工具摘要必须始终包含该标签。

摘要内容格式

摘要是供 AI Agent 选取功能的配置文件，必须能让 Agent 判断：这个镜像能做什么、当前任务应选用哪些能力、怎么执行、有什么限制。按以下部分组织：

1. 工具名（中文 / English）及简短定位。
2. 工具标签：下游分析工具（见上）。
3. 用途与执行方式：说明工具适用于哪类数据、覆盖什么分析范围；明确它是“需要根据数据和用户目标实时编写脚本的分析环境，没有固定的分析命令”；说明 Agent 的使用方式（先读取摘要、确认所选功能的输入确实存在，再拉取镜像，在宿主机容器内运行本次任务生成的脚本）；说明数据来源与暂存方式（BioLine 上的数据按需下载到任务目录，宿主机已有数据直接暂存到任务目录）；写明容器内的路径约定（输入、分析结果、脚本与复现材料各自的位置）与输入只读挂载等运行约定；写明与其他 skill、参考脚本或模板文件的依赖边界。
4. 可按需选择的能力：按编号逐项列出镜像实际支持的功能；每项写明能力名称、适用条件（需要哪些输入、分组、注释或数据齐全性前提）、执行方法与要点、输出与限制。能力条目必须足以支撑 AI Agent 依据用户需求与数据情况从中选取；不满足条件的条目跳过，并在报告中写明原因。
5. 默认执行规则：用户未指定具体功能时，先检查实际数据，再执行适用的标准分析组合及顺序；缺输入时的跳过规则；每次任务必须保存的溯源信息（输入清单、数据来源、所选与跳过的模块、脚本、实际参数、随机种子、软件版本、运行日志及结果索引）；镜像未安装的方法不得被静默替代或宣称已经执行。
6. English overview：与中文内容对应的英文概要，开头点明下游分析工具的定位。

摘要编写要求

• 能力清单必须与镜像实际环境一致：镜像未安装的软件、方法或数据库不得写入摘要，也不得在描述中暗示其可用。
• 演示性、不完整或不可用的功能必须标注真实范围（例如内嵌的小型演示字典、模拟或空模板输出），不得描述为完整数据库或真实分析。
• 使用合成数据或近似方法的步骤必须写明标注要求（例如合成整数计数不是实测计数），避免被后续任务当作真实结果。
• 摘要全文随创建计划一并展示并确认；正式配置后按导出原文全文核对，标签、能力清单与限制说明均须一致。

四、计划确认、拉取与阶段记录

在 plan.md 保存最终名称、初始版本 1、镜像身份、命令、端点、资源、README、证据和准确执行命令。用已确认文件快照和逐项核对代替原有脚本专用的计划哈希协议；不要求生成 pullPlanDigest、publishPlanDigest 或配置 checkpoint digest。可额外记录文件 SHA-256，但不能因此省略内容审阅。任何已确认字段变化都先更新计划并重新取得该动作授权。

依次记录如下阶段，阶段名只是任务记录，不是 fkit 参数：

PLANNED → IMAGE_VERIFIED → CREATED → CONFIGURED_VERIFIED

进入 PLANNED 前完成查重、证据和本地配置检查。一次展示面向用户的创建计划：工具作用与主要特点、工具名称和版本、命令、输入输出端点、参数、资源建议、下游连接方式和已知限制。镜像 digest、worker type、workspace、内部校验命令和清理步骤只记录在内部证据，不在主展示中展开。计划末尾只询问一次“是否按此方案创建并完成配置？”；确认后连续完成全部流程。

用户确认后不再等待阶段确认。若本地已有镜像且身份核实匹配则直接复用并记录；否则执行计划内的一次拉取，再检查镜像：

docker pull --platform linux/amd64 IMAGE
docker image inspect IMAGE

检查实际 Os、Architecture、RepoDigests 与计划中的身份一致，记录本地 image ID、选中平台及 tag 到 digest 的对应证据，再进入 IMAGE_VERIFIED。RepoDigest 必须匹配预期对象，不能仅凭 tag 或退出码认定成功。缺失、架构错误、tag 漂移或 digest 不匹配均停止；保留实际结果，不能修改计划来掩盖不匹配。

五、连续创建工具

在已确认计划内，镜像达到 IMAGE_VERIFIED 后直接继续。创建前刷新 fkit tool list --json 再次查重，并用只读 inspect 核对本地镜像未改变；出现同名、身份变化或查询失败即停止，不重新询问正常阶段的执行许可。

fkit create-tool IMAGE TOOL_NAME --json

记录真实 toolId、toolVersionId、toolName 和 version，要求名称符合计划且版本严格为 1。随后再次执行 fkit tool list --json，按真实 ID 和名称定位，要求 versionList 为 [1]。不编造 ID，不从软件版本推导平台版本。

工具创建已产生远端对象，记录 CREATED 并直接进入正式配置；不执行配置或摘要 dry-run，不停在等待配置确认状态，也不能提前称为“创建配置成功”。

六、正式配置与读回核对

沿用完整计划的一次确认，核对文件与已确认快照一致，并确认仍是同一工具及初始版本。以下命令逐条连续执行，不再询问“是否继续正式配置”；上一条失败则不执行下一条。正式 apply 不支持 --yes：

fkit tool config apply TOOL:VERSION --file WORKSPACE/spec/tool_config.json
fkit tool summary apply TOOL:VERSION --file WORKSPACE/spec/README.md
fkit tool config export TOOL:VERSION --output WORKSPACE/spec/tool_config.after.json
fkit tool summary export TOOL:VERSION --output WORKSPACE/spec/README.after.md

导出目标必须是新文件，不能覆盖原配置或先前证据。配置比较 JSON 解析后的结构和值，忽略对象键顺序、缩进与数值书写差异，保留数组顺序并检查缺失/多余字段；摘要按导出的原始 Markdown 全文比较，不用 --section 或 JSON 包装替代全文，不忽略实际内容变化。

全部一致才记录 CONFIGURED_VERIFIED，并写 result.json：真实工具 ID、版本 ID、名称、版本、镜像 tag/digest、配置/摘要及读回文件路径、核对结果。配置成功但摘要失败属于部分成功，保留已写入事实并停止，不自动重试、回滚、更新版本或进入验收。读回失败或不一致也不能报告验证通过。

七、创建完成后的状态

清理本次拉取的本地镜像

完整创建计划须提前列明：创建、配置和读回核对全部成功后，自动清理本次新拉取的本地镜像。这项清理包含在创建计划的一次确认中，不再单独询问。拉取前记录目标引用是否已存在及其 image ID；拉取后记录实际引用、image ID 和 RepoDigest，作为清理依据。原本已存在、仅被本次复用的镜像不自动删除；无法证明是本次新增时也保留并说明。

仅在 CONFIGURED_VERIFIED 后清理，不能在刚上传完但配置或读回尚未完成时删除。再次只读检查目标引用仍指向本次记录的 image ID；身份变化则跳过。对本次新增的精确镜像引用执行 docker image rm IMAGE，不使用 --force，不按 image ID 删除其他引用，不执行全局 image/system prune，也不停止或删除容器。其他标签或容器仍引用镜像时，可能只解除本次标签或无法释放空间，应如实报告，不强制清理。

清理后只读确认本次引用是否仍存在，在 result.json 记录清理目标、结果及未清理原因。镜像清理失败不改变远端工具创建配置成功的事实：报告“工具创建配置成功，本地镜像清理未完成”，保留错误供后续处理，不自动重试创建。创建、配置或读回失败时保留镜像排查。删除本地引用不删除 BioLine 已上传的远端工具镜像。

读回核对成功后直接报告 BioLine 工具已创建并完成配置。当前流程到此结束，不主动提示或启动 Flow/Job 验收；用户后续明确提出验收需求时，再读取对应在线文档并执行独立流程。

清理本地临时工作目录

工具已达到 CONFIGURED_VERIFIED 并完成镜像清理后，删除本次创建专用的 WORKSPACE 及其中的配置草稿、摘要、导出文件、日志和临时压缩文件；同时清理本次流程在 --tmp 下创建的临时文件。清理前先把最终状态、工具 ID、版本 ID、清理结果写入对话结果或外部持久化记录。不得删除其他任务的目录、用户原有镜像或共享缓存。

创建、配置、读回核对或镜像清理失败时保留 WORKSPACE、日志和证据文件，报告路径，不能为了清理而删除排查证据。

输出与失败处理

每阶段报告“结论、证据、风险、下一步”，证据使用文件路径、镜像身份、预览或真实返回标识，不输出内部推理、原始协议、调试转储或凭证。logs/error.md 记录阶段、不匹配内容、原因和可选处理方式：补充证据、修正请求、人工审阅或取消。

失败或取消保留工作目录、日志及已产生的云端对象，不手写成功状态。创建命令中途失败也可能已创建远端对象；记录真实情况，后续先只读核对，禁止盲目重跑。某工具失败后继续下一个独立工具，除非用户要求停止全部；项目/认证查询失败则停止批次。最终分别汇总已存在跳过、创建失败、创建配置成功未验收、验收成功、验收失败。

读取本页

fkit create-tool --docs
fkit create-tool --docs --docs-json --docs-lang zh

fkit 在解析业务必填参数、登录或执行创建之前，读取官方索引 https://www.bioline.cloud/ai/commandLineAndFkit/，找到 create-tool 映射后返回本页全文；不会递归读取链接。--docs-json 只是文档输出包装。当前 AI 服务发布中文内容，--docs-lang en 也不会自动翻译或切换为英文网站。读取文档不创建工具，更新本地文档也不代表线上已发布。

输出目录生命周期规则

创建工具前必须根据程序实际行为确定输出目录生命周期：如果程序要求 -o 目录在执行前不存在，命令中禁止先执行 mkdir -p；只有证据证明程序接受已存在目录时才允许预创建；只有程序明确支持时才允许使用覆盖参数。mkdir -p、--force、rm -rf 都不是通用模板，未经该工具版本证据核实不得加入命令。

本地测试必须从干净工作目录开始：确认输出目录不存在，运行完整命令并检查退出码和全部产物；必要时再重复运行，记录程序对已存在输出目录的行为。测试命令不得为了“让它通过”擅自添加建目录、覆盖或清理逻辑。

文件端点硬性规则

type: file 且 path: file 的占位符是最终文件路径，不能拼接子目录、不能传给 mkdir；只有 directory 端点才能拼接文件名。最小测试必须使用 /io/目录/文件名 的真实展开路径，并验证完整命令和所有 cp/mv 后处理。