tao-launch-workflow

TAO 工作流启动检查

独立安装？ 如果此会话不是由 TAO skill bank 插件初始化的，请先运行 tao-setup 技能（主机预检、凭据、跨技能发现）。

在启动任何 TAO 工作流或模型操作前，请使用此技能。

直接调用时，请在步骤 0 或任何辅助程序运行前，按照 references/platform-preflight.md 执行完整检出检查。 单独安装的技能缺少共享脚本；如果检查失败，请停止。所有辅助程序都使用经验证的 TAO_SKILL_BANK_PATH。

步骤 0 — 执行模式：卡片包（先检查）

在此对话中运行多阶段应用工作流前，请检查应用技能旁是否附带编译好的卡片包：

ls "${TAO_SKILL_BANK_PATH}/skills/applications/<skill>/cards/" 2>/dev/null

• 存在卡片包 → 优先使用节省令牌的路径：卡片包的 driver.sh 会以全新会话逐阶段运行工作流（经测量，比在对话中执行便宜 74-91%， 且是唯一经过小型模型验证的模式）。 请阅读卡片包的 README.md，了解所需环境变量，完成此关卡的第 1-9 项启动审核，然后分离启动卡片包驱动程序，而不是在此对话中执行各阶段。通过驱动程序日志和运行目录中的进度标记进行监控。
• 不存在卡片包 → 按照此关卡正常执行。如果工作流会重复运行，建议使用强大的模型编译一次卡片包——请参阅 skills/core/tao-token-efficient-execution（编写提示词 + 合约）。

卡片路径只替代在对话中执行各阶段的方式；绝不会跳过此关卡。启动卡片包驱动程序会产生副作用，因此需要经过同样的启动审核确认。

快速开始

运行平台辅助程序，询问平台和监控偏好，然后在询问凭据前运行所选平台的详细信息辅助程序。

不可妥协的启动关卡

此关卡与模型无关。启动会产生副作用的工作前，必须将其应用于每个 TAO 模型、数据操作和应用工作流。

在启动预检通过之前，不要创建运行器脚本、启动脚本、兼容性填充程序、工作区文件夹、状态文件、日志，也不要执行会产生依赖安装副作用的操作。

只有满足以下所有条件，预检才算通过：

1. 已通过打包的平台辅助程序选择执行平台。
2. 已满足平台凭据和所需的凭据组要求。
3. 已满足特定模型的凭据要求。
4. 已根据打包的模型/操作元数据解析默认容器镜像、向用户展示，并得到确认或通过明确的 image=<override> 替换。
5. 从启动主机成功通过平台访问检查。
6. 已将数据集输入映射到具体的规范键，并从所选平台的视角完成验证。
7. 已知模型/工作流技能要求的计算资源规格字段。
8. 所选数据/平台路径所需的本地工具均已就绪；或者用户已批准安装最少的缺失依赖，且已重新运行预检。
9. 已向用户展示并确认启动审核，其中包含镜像、平台、数据集、计算资源规格、预期运行时间，以及任何生成的/默认配置更改。对于 AutoML，即使使用默认值，启动审核也必须明确说明建议数量/预算、最大并发数、算法、指标、优化方向以及搜索参数/范围。

如果任何一项缺失，请询问缺少的信息，并在生成产物前停止。此要求适用于 AutoML、常规训练/评估/推理/导出/TRT，以及 DEFT/应用工作流。

预检工作解除阻碍后，请继续跟进用户最初的请求。修复后，重新运行相关预检并继续完成该请求；除非用户明确只要求修复，否则不要止步于“阻碍已解决”。

四动词执行契约

启动门槛通过后，负责产出结果的模型／数据技能编写 spec-bundle（架构：tao-artifacts），执行过程就只有四个动词。每个平台技能都通过其原生 CLI 实现这些动词——该技能库内置五个（tao-run-on-docker、-slurm、-kubernetes、-brev、-virtualenv），任何外部安装的平台技能也遵循同一契约（§ 外部平台技能）；除此之外，没有其他平台特定内容。 $BANK = ${TAO_SKILL_BANK_PATH}。

• submit(spec-bundle) — 先确定数据问题：如果输入已可从计算框架读取（本地路径、现有挂载——原位 Tier A，这是常见的本地情形，也是唯一的隔离网情形），就无需暂存——记录 Tier A 后继续。只有在框架不匹配时才调用 tao-data-io（远程 URI、跨主机路径、PTM 获取、Tier C 结果上传）。然后使用 redact_secrets.py lint 检查组装好的命令，并按以下顺序打开记录，然后启动：

  BANK="$TAO_SKILL_BANK_PATH"
  if ! JOB_ID=$("$BANK/scripts/tao_job_record.py" open --platform <p> --image <img> \
    --network-arch <arch> --action <action> --storage-tier <A|B|C> --results-root <root>); then
    echo "TAO job-record creation failed; do not submit" >&2; exit 1
  fi
  [ -n "$JOB_ID" ] || { echo "TAO job-record returned no ID; do not submit" >&2; exit 1; }
  # <native launch, naming the backend object after $JOB_ID>
  "$BANK/scripts/tao_job_record.py" mark "$JOB_ID" --state RUNNING --backend-ref <ref>
  

• status(id) — 轮询原生后端，映射到固定词汇 PENDING RUNNING COMPLETE ERROR CANCELED UNKNOWN；原生子状态（ImagePullBackOff、资源导致的 PENDING、slurm COMPLETING）通过转换 message 传递。绝不要从记录中读取“正在运行什么”——应轮询后端。
• logs(id, tail) — 获取原生日志。
• cancel(id) — 原生取消并清理孤立项，然后执行 mark <id> --state CANCELED。

先记录再启动是顺序不变量。 open 会在任何启动操作之前生成 ID 并绑定 results_dir，它返回的 ID 是启动操作唯一可用的句柄——跳过门槛或 open 的提交操作没有 ID，因此无法启动。这样，即使上下文中断，运行仍可恢复：后端对象（之后可能会被 K8s TTL 或 docker --rm 删除）创建之前，results_dir 就已记录。

如果产出方的 spec-bundle 声明了 execution，那么所有复用该模型技能的应用都必须保留其中由模型定义的操作语义。选定的平台负责生命周期；应用不得将其中的命令复制到私有启动器中。平台无关的前置／后置命令、运行时证明、辅助依赖、分布式执行意图和完成证据都属于产出方的 spec-bundle。调度器语法、挂载、密钥、超时、进程数以及子进程退出状态的保留则由平台负责。

外部平台技能

没有注册表，也没有接口文件：平台技能只需通过文档声明这四个动词的契约，首次使用前由你阅读验证。如果某个技能只有原生原语，可以通过推断来使用其映射（技能库的不变量仍然适用；应在启动审查中说明映射，并持久化记录有效做法）。规则和不可缺少的最低要求（无等效项时）：references/external-platforms.md。

故障分析与重试

当 status 达到 ERROR 时，先读取日志尾部并分类，然后才能重试——基础设施故障可以重试（新建记录，使用 --retry-of，最多 10 次），程序故障绝不能重试。完整标准、两项需自行判断的情况（设备端断言、下游回溯）以及轮次结束后的轮询器规则：references/failure-analysis-retry.md。

初始问题

用户确认想要执行的操作后，询问要使用哪个执行平台来运行。请从本会话中已安装的平台技能中查找可选项——你已经能看到它们的名称和说明（tao-run-on-docker、-slurm、-kubernetes、-brev、-virtualenv，以及任何外部安装的技能，例如官方 brev-cli 技能）。没有可读取的中央平台注册表。如果你的运行环境只显示核心路由技能，请读取 ${TAO_SKILL_BANK_PATH} 下的 skills/platform/tao-run-on-*/SKILL.md frontmatter（名称 + 一行说明），列出技能库中的平台技能。

然后询问：

• 要使用哪个受支持的平台来运行此工作流？
• 是否要我在此聊天中监控运行？监控意味着我会在启动后持续轮询后端/作业日志并报告进度，直到作业完成、失败或你要求我停止，即使作业排队数小时或数天也是如此。如果禁用，我会启动作业、提供作业 ID/日志路径，然后停止轮询。默认：在聊天中监控。
• 我应该多久发布一次状态？默认：每 5 分钟一次。冒烟测试使用 1–2 分钟，常规训练使用 5 分钟，长时间运行使用 10–15 分钟。

用户接受默认值时，使用 long_running_enabled=true 和 status_interval_minutes=5。

启用监控后，不要仅仅因为已经轮询多次或作业仍处于 PENDING 状态就发送最终摘要。保持当前轮次继续进行，并每隔 status_interval_minutes 发布状态，直到作业进入终态，或用户明确要求停止/分离。如果运行环境无法保持聊天轮次持续打开，请明确说明，并留下可持久访问的监视器/日志路径；不要暗示轮次结束后聊天更新仍会继续。

最终答复规则：final 响应会结束聊天端监控。当 long_running_enabled=true 且任何已启动的作业仍未进入终态时，必须发送进行中的状态消息并继续轮询。只有在工作流进入终态、用户明确要求分离/停止监控，或运行环境确实无法保持轮次持续打开时，才发送最终答复；在最后一种情况下，请说明这是运行环境的限制，并提供准确的持久状态命令/日志路径。

缺少输入时的提示格式

如果缺少接收所需的输入，请使用 references/intake-prompts.md 中的准确提示格式（合并为一次提问，提供具体示例，不自行设定默认值）。

实现后端解析

确定模型归属后，检查所选模型的 references/skill_info.yaml。如果其中声明了 backend_contracts，请在选择镜像或编写规范之前解析实现后端。若明确指定的后端支持该模型/操作，则优先使用；否则应用打包的 backend_selection 策略并说明理由。所选后端在 skill_info.yaml 中的元数据决定其镜像。引用的后端契约决定入口点、配置架构、数据映射、拓扑、检查点格式、输出布局和状态行为。对于多后端前端，切勿使用顶层旧版镜像回退，也切勿将一个后端视为另一个后端的版本。

将操作、后端和工作负载提示传递给模型解析器。元数据声明了后端规划器时，使用该规划器。例如，共享的 Cosmos 前端使用 scripts/cosmos_workflow.py plan 生成后端原生 TOML 和启动序列。

容器镜像确认

在创建规格文件、运行脚本、工作区、日志、状态文件或提交作业之前，先解析所选模型／操作对应的镜像：

"$TAO_SKILL_BANK_PATH/scripts/resolve_tao_image.py" \
  --skill-bank "$TAO_SKILL_BANK_PATH" \
  --model <network> --action <action> --backend <auto-or-explicit> \
  --workload <workload-hint> --format text

如需手动检查，请读取打包在 $TAO_SKILL_BANK_PATH/skills/models/<network>/references/skill_info.yaml 中的信息。 如果无法使用辅助工具，请在启动前停止。按以下顺序解析镜像字段：

1. backend_contracts.<selected-backend>.container_image（如果存在）
2. actions.<action>.container_image
3. actions.<action>.image
4. 顶层 container_image
5. 顶层 image

显示确切的镜像，并询问：

Container image for <network>/<action>:
default=<resolved image>

Use this image, or provide image=<override>?

如果用户接受，将解析出的镜像作为作业的 image 参数传入。如果用户指定其他镜像，则要求其提供非空的镜像引用，并改为传入该值。不得在用户不知情的情况下使用默认镜像启动。此确认适用于训练、AutoML 推荐、评估、推理、导出、TensorRT 引擎生成，以及会提交 TAO 容器的应用工作流。

凭据筛选

用户选择平台后，只从所选技能本身获取该平台的凭据列表，包括其 ## Credentials 部分，以及（如果存在）references/skill_info.yaml 中的 required_credentials、credential_groups 和 optional_credentials。启动前检查工具（check_tao_launch_preflight.py）会读取同一份技能专属的 skill_info.yaml 来执行凭据检查；不需要凭据的平台（例如 Docker）可能只提供说明文档，此时请依据其 Preflight 部分。

只询问该平台实际需要的凭据，以及所选模型技能要求的特定模型凭据。使用 SLURM、Kubernetes 或 Docker 时，不要询问 Brev 凭据。使用 Brev、Kubernetes 或 Docker 时，不要询问 SLURM 凭据。只有当所选平台以及数据集／结果 URI 需要访问 s3:// 时，才询问 S3 凭据。 凭据可能已存在于进程环境中，或用户批准的秘密环境文件中，例如 ~/.tao/secrets.env 或 ~/.config/tao/.env；仅在需要时读取此类文件，且绝不要打印、grep、cat、粘贴或记录其内容。只验证变量是否存在。

初次收集启动信息时，只询问必需凭据和必需凭据组。将辅助工具的可选凭据／设置部分视为参考资料；除非其 only_when 条件适用、所选工作流无法在缺少这些值的情况下继续，或用户要求自定义该设置，否则不要索取这些值。

如果辅助工具的输出包含“Required credential groups”部分，则每个凭据组都必须至少满足一项，之后才能继续。请根据辅助工具提供的说明和“How to get it”文本解释所需的各项值。

对于 SLURM，面向用户的提示应先询问 SSH_KEY_PATH。只有在用户表示已在使用 SSH Agent 时，才提及 SSH_AUTH_SOCK。

依赖项处理

如果缺少必需的 CLI／库，请准确说明缺少什么以及为什么需要，然后在安装前征求同意。例如：

• S3 数据集或结果路径 → 需要支持 S3 的客户端，例如 aws。
• 本地 Docker 路径 → 需要 Docker CLI 和已配置的 Docker 网络。

获得用户批准并完成安装后，重新运行同一项启动前检查。在检查失败与重新检查之间，不要创建运行文件或启动作业。

运行时下载

运行时下载规则请遵循 references/runtime-downloads.md。本地检查点并不意味着软件包已缓存。

数据集接入

接受以下任一模式的数据集输入：

• 数据集根目录模式： 用户提供训练/评估/校准根目录，模型技能按约定映射所需文件。例如，Cosmos-RL 训练： custom.train_dataset.annotation_path=<root>/annotations.json 和 custom.train_dataset.media_path=<root>。
• 直接指定模式： 如果标注文件、媒体存档、视频或图像文件夹位于不同位置，用户提供确切的配置项路径。直接保留这些配置项，例如： custom.train_dataset.annotation_path=<TRAIN_ANNOTATION_PATH> 和 custom.train_dataset.media_path=<TRAIN_MEDIA_PATH>。

根据所选平台，询问用户提供符合要求的数据集示例：

• SLURM：由用户提供明确的共享集群路径，并在已分配的计算节点上验证；此技能没有特定站点的存储默认设置。
• Brev、Kubernetes：通常使用 s3://bucket/path/train 和 s3://bucket/path/eval，除非平台配置文件挂载了共享存储。
• 本地 Docker：Docker 主机可见的本地路径，例如 /data/tao/<model>/train；也可以使用计划挂载到容器中的、容器内可见的直接配置项路径。
• 远程 Docker：由 DOCKER_HOST 指定的远程 Docker 主机上可见的绝对路径，而不是本地 Agent 机器上的路径。

不要假设“数据集根目录”是唯一可接受的输入。用户提供直接配置项路径时，应验证确切的配置项路径，而不是追加默认文件名。

平台预检

在创建任何启动产物之前，运行所选平台的预检；优先使用随附的辅助脚本 scripts/check_tao_launch_preflight.py（--platform <p> --container-image <img> --path <label>=<path> ...）。它会验证凭据、客户端工具、平台/集群/对象存储访问权限、从计算环境访问数据集路径的情况、GPU/运行时健康状况，以及镜像与架构的兼容性；任何失败都应视为阻断问题。实际启动时，绝不要使用 --skip-platform-access。

有关各平台的完整说明，请参阅 references/platform-preflight.md（包括 SLURM SSH/密钥设置及资源默认值、Docker/远程 Docker 的 GPU 与绑定挂载检查、Brev/Kubernetes API 与对象存储检查、标注内容字段检查，以及数据暂存）。

运行时与配置审查

执行任何会产生副作用的启动操作前，先展示简明审查内容：

• 所选平台和确切的容器镜像
• GPU ID/数量和节点，包括因已被占用而避开的 GPU
• 数据集根目录或直接配置项路径，以及可用时的数据样本数
• 与模板默认值不同的重要模型/工作流覆盖项
• 预计运行时间及其假设
• 监控间隔，以及聊天端监控是否会持续连接
• 实现后端；当模型提供多个后端时，说明选择依据

对于 AutoML，还要根据 skills/applications/tao-run-automl/SKILL.md 中的说明，展示算法、指标/方向、推荐预算、搜索参数、范围，以及生成的/默认的推荐详情。完成审查后，请求用户确认。如果用户提供了时间限制，则标出任何超出限制的计划，并在启动前提出具体的缩减方案。

成功完成启动审查后，绝不要只以“未启动任何任务”结束。最后应直接提示用户采取一个操作，例如：准备好物化已封存的计划并提交任务。回复“launch”“go ahead”或“yes”即可继续。 用户接下来在聊天中明确表示同意，即授权物化计划、创建任务记录、提交任务，并采用此前审查过的监控模式；应立即执行，不要再次收集信息或请求确认。

结构化训练指标

当模型契约声明了结构化状态路径或指标提取器时，应将其与原生后端同时轮询。调度器／容器完成本身并不代表训练成功：必须要求模型生成终态结构化成功记录，收集具体的检查点事件，并返回最终训练损失以及每个 epoch 的验证完成损失。不要将验证心跳／批次指标或训练损失行提升为 epoch 验证损失。如果进程在原生日志记录器生成前失败，请调用打包的状态终结器，或报告实际的进程退出失败；仅将原始日志解析作为后备方案。