tao-run-deft-aoi

技能：tao-run-deft-aoi

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

执行约定

将其视为由磁盘支持的状态机，而不是文字配方。

1. 保留用户明确指定的每个值。epoch 1 表示 num_epochs=1，iteration 1 表示 max_iterations=1；只有用户未提供该参数时，才应用启发式或规范默认值。在预检摘要中注明每个运行参数的来源（user、spec 或 default）。保留客户指定的指标名称、运算符、目标值、单位、评估器和约束。获批的 metric_contract 是评估、检查点选择、完成判定和报告的唯一事实来源。
2. 用户批准摘要后，设置 PYTHON=$(bash scripts/deft_python.sh)，然后通过 "$PYTHON" scripts/init_deft_state.py 初始化一次 deft_state.json，并传入 Preflight 中准确的 GPU 型号／显存、解析后的 --network-mode、激活源和所选绝对 Python 路径。 生成的 execution_policy 是不可变的运行状态。恢复运行时，绝不手动编写或重新初始化。
3. 启动时、上下文压缩后、每个阶段开始前，以及声明完成前，都运行 "$PYTHON" scripts/deft_context.py --state ... --stage ...。 使用该命令给出的持久化 next_stage，以及状态文件中的 status、current_iteration、iterations.*.status、stage_completed 和最新的 events 条目来恢复进度。不要根据助手文本或未记录在状态中的产物推断进度。
4. 阅读 DEFT 覆盖说明后，调用对应的底层技能。不得用猜测的 Shell 命令、内联 Python、其他输出目录，或根据 KPI 集编造的数据来替代缺失／未读取的阶段参考，或弥补失败的技能调用。
5. 初始化后，通过 "$PYTHON" scripts/deft_exec.py --state ... -- <command> 运行安装／获取／登录／容器命令。隔离模式会拒绝外连和安装、注入离线标志并强制禁止拉取。所选平台必须执行等效策略。
6. 每个阶段都必须通过 "$PYTHON" scripts/commit_stage.py 提交；该命令会验证阶段所需的输入，并原子地更新 deft_state.json 中的恢复快照和有序 events 数组。绝不使用内联 Python、jq、here 文档或编辑器修改状态文件。修复被拒绝的证据；绝不伪造状态。对于 evaluate，直接向 commit_stage.py 传入指标结果、检查点、推理 CSV 和阈值。 对已执行的阶段，通过后端耗时或主机计时器传入正数测得值 --duration-sec。有文档记录的 --skip 可记录 0；负时长一律拒绝。
7. 只有在 "$PYTHON" scripts/finalize_run.py 创建交接产物、成功提交 loop_stop，且重新读取 deft_state.json 后确认 status == "complete"、iterations.baseline.status == "complete"，并且最终迭代的 status == "complete"，才能声明循环完成。检查点、推理 CSV、报告或助手消息本身都不能作为完成证据。

上下文管理

• 按需加载参考资料。重新读取状态，然后只阅读当前阶段指定的部分并执行。 切勿预先加载或使用 cat 查看所有参考资料或底层技能、递归列出技能树，或重新读取当前上下文中已有的参考资料。
• 将冗长的训练、推理、Docker 和 SDG 输出重定向到文件。最多查看最后 40 行或单行状态／产物检查；切勿在对话中打印完整规格、状态文件、循环日志或生成的脚本。
• Skill 工具调用会加载阶段说明，但不会启动后台编排器。调用返回后，立即在父流程中继续执行文档所述阶段。切勿休眠或轮询等待 Skill 工具进程。对于实际的后台 Docker 任务，保存 PID，并以不超过 30 秒的间隔轮询。
• 在 Pre-Flight 开始时，先确定网络模式，再处理依赖项。只阅读一个分支：无网络模式读取 references/air-gap.md，启用网络模式读取 references/network-bootstrap.md。无网络运行时，切勿加载网络引导资料。

何时使用此技能

当用户希望 Agent 为 NVIDIA TAO VisualChangeNet / ChangeNet PCB 检测模型运行完整的 DEFT AOI 改进循环时，请使用此技能：基线评估、RCA、合成缺陷生成、数据挖掘、重新训练，以及持续进行部署门控，直到达到 KPI 目标。

• “运行 DEFT 循环”
• “微调模型，直到配置的质量指标达到目标”
• “在保留约束条件的同时，优化客户定义的指标”
• “使用 RCA 和合成缺陷改进我的 AOI ChangeNet 模型”
• “持续迭代训练，直到部署 KPI 达标”

请勿将此技能用于单次独立的 TAO 训练、一次性推理、通用异常生成或仅限 RCA 的分析。用户只要求执行其中某个步骤时，请直接使用相应的 Agent。

基础模型

此循环使用 NVIDIA TAO Visual ChangeNet 分类模型，采用端到端 C-RADIOv2-B 或冻结的 DINOv3 主干网络。specs/baseline_spec.yaml 定义了架构。主干网络变体、暂存、HF_TOKEN 和挂载规则由 references/visual-changenet.md 管理；规格始终指向本地挂载文件。容器拉取需要 NGC_KEY。SigLIP 挖掘由 references/tao-mine-aoi-images.md 管理；AnomalyGen 资源以及网络／无网络规则由 references/tao-generate-anomalies.md 和 references/air-gap.md 管理。容器负责其基础资源列表；此工作流通过显式传入 --model_sizes 2B，确保引导阶段使用 Text2Image 2B。

训练 AutoML 策略

DEFT AOI 负责迭代式数据改进循环、重新训练节奏和 KPI 检查点选择。仅对于此工作流，即使底层 Visual ChangeNet 模型元数据中有 automl_enabled: true，也要绕过模型级 AutoML。

automl_policy: off 是传给 Visual ChangeNet 技能调用的工作流参数（父级通过 Skill 工具调用 tao-skill-bank:tao-train-visual-changenet 时传递的值），不是 TAO 规范字段。分两种情况：

• 直接运行 docker run visual_changenet train -e <spec>（此工作流实际采用的内联路径）：无需操作。默认情况下，TAO 入口点执行普通训练；AutoML 位于另一条由 SDK 编排的代码路径中。实际上，每次直接运行 docker run 都已是 automl_policy: off。
• 由 SDK 编排的调度（Brev/SLURM/k8s 由 SDK 构建命令）：向 VisualChangeNetSDK.train(...) 或等效的运行器参数传入 automl_policy: off。SDK 会据此选择普通训练命令，而非 AutoML 包装器。

绝不要在规范 YAML 中添加 automl_policy 或 workflow 键。 TAO 的 Hydra ExperimentConfig 架构不识别这些键，训练作业会在配置合并时失败，并显示 Error merging '<spec>.yaml' with schema: Key 'workflow' not in 'ExperimentConfig'。 这仅是工作流级覆盖；不要更改模型元数据，也不要将此策略用于其他工作流。

启动信息收集

用户确认要运行此工作流后，询问他们打算在哪个受支持的平台上运行。请从已安装的平台技能中查找执行平台（tao-run-on-docker / -slurm / -kubernetes / -brev，以及任何外部平台）；对于仅展示核心路由技能的运行时，请读取 skills/platform/tao-run-on-*/SKILL.md 的 frontmatter。

选择平台后，读取所选平台技能的 ## Credentials 部分和 references/skill_info.yaml（required_credentials / credential_groups）。

绝不要询问或打印凭据值。只检查变量是否已设置（[ -n "$VAR" ] && echo SET || echo UNSET）；如果未设置，请告知用户变量名，以便他们导出该变量，或将其写入经用户批准的环境文件（~/.tao/secrets.env、~/.config/tao/.env，或用户指定的文件），并通过 set -a; source /path/to/.env; set +a 加载。运行过程中绝不会创建或写入该文件。

Agent 行为

用户确认关卡只有一个：预检确认。 打印预检摘要 （参见 references/preflight.md → 预检摘要），然后停止并等待用户输入“go”、“yes”、 “looks good”或类似的明确批准。在获得批准前，不要启动任何会产生副作用的步骤 （docker run、训练、SDG、对 ${RESULTS_DIR}/ 的修改）——读取规格、列出文件、运行 docker image inspect 以及填写摘要表均可。“自主”描述的是通过此关卡之后的行为，而不是之前。 即使用户最初的提示听起来很急迫（“直接运行”、“继续 吧”），也不要跳过关卡——摘要本身就是用户在批准前需要查看的内容。

通过关卡后，该技能将完全自主运行。 无需再征求确认，运行完整流程。不要在步骤之间暂停，也不要询问“要我继续吗？”——直接继续。只有在步骤发生无法恢复的错误或触发硬性停止关卡时才停止。在每个步骤里程碑输出一行状态更新，让用户了解进度。

必须启用自动模式。 通过关卡后的流程会不断执行有副作用的调用 （docker run、写入 ${RESULTS_DIR}/）；如果未启用自动接受／绕过权限模式，流程会卡在第一个提示上。在预检摘要中提醒用户在批准前启用自动模式 （shift+tab）。

阻塞问题恢复。 在用户确认关卡之前，通过 deft_python.sh 选择一个完整可用的已安装主机解释器。如果不存在，则只遵循 已选定网络模式对应的参考文档。隔离网络模式下，若没有包管理器命令则必须硬性停止；启用网络的引导流程在 references/network-bootstrap.md 中隔离说明。 应用 references/air-gap.md 中的网络模式分支；将获准的获取操作和目录创建记录为 批准后的工作，或在隔离网络模式下验证暂存资源。获得批准后，自行解决可恢复的阻塞问题，然后 从之前所在的预检步骤恢复（<blocker> cleared → resuming step N）。 仅在无法自行解决时停止（缺少工作区／规格／CSV／凭据、资源池为空、数据泄漏）。 修复问题不需要再次征求用户确认。

非零退出命令规则。 不要原样重复执行失败的命令，也不要通过试错切换到未记录的 CLI／模块路径。阅读最终 错误块（而不只是容器横幅），将其对应到已加载的阶段参考文档／底层技能，进行一次有证据支持的修正，并重新运行文档规定的验证。如果参考文档未涵盖该故障，则提交 status=error 并停止，不得擅自改用精简版流程。

计划修订。 如果在展示原始摘要后运行参数发生任何变化（用户设置时限、覆盖轮数、更改 max_iterations 等），务必重新运行预检并展示更新后的摘要，然后再继续。

工作流

按以下顺序执行循环（完整详情见 references/pipeline-and-state.md → Pipeline + Stage Execution）：

1. 飞行前检查。 执行 references/preflight.md 中的所有检查。解析工作区、规格、CSV、检查点和容器镜像。只有在遇到无法自行解决的缺失输入时才硬性停止（见 ## Agent Behavior → Blocker recovery）。
2. 基线。 如果 deft_state.json 中已有 iterations.baseline.stage_completed == "train"，且 best_ckpt_path 指向一个现存文件（上游的 automl-deft-pipeline 会从其 Phase 1 AutoML 优胜者中预置这些内容 — 见其 Phase 1 → Phase 2 handoff），则跳过 train 子步骤，从预置检查点开始执行 inference -> evaluate。否则，通过调用 tao-skill-bank:tao-train-visual-changenet 技能执行 train -> inference -> evaluate。使用 references/metric-contract.md 中批准的契约和评估器进行评估。无论哪种情况，之后都通过调用 tao-skill-bank:tao-analyze-gaps-visual-changenet 执行 rca。首先阅读 references/visual-changenet.md、references/metric-contract.md 和 references/tao-analyze-gaps-visual-changenet.md，了解 DEFT 循环专用参数。
3. 迭代。 对每次迭代（最多 max_iterations 次），执行 Pipeline 步骤 1-7。每个步骤之间重新读取 deft_state.json，并从其 stage_completed 值所指示的位置继续；不要打印完整状态。
4. 当达到 KPI 目标或达到 max_iterations 时，运行 "$PYTHON" scripts/finalize_run.py 并指定相应原因，停止。硬性停止错误会作为错误提交，绝不会重新标记为成功的 loop_stop。
5. 自动生成报告。 scripts/init_deft_state.py 会写入初始的 results/DEFT_Loop_Report.html；每次成功调用 commit_stage.py 后， 都会通过 scripts/render_report.py 中实现的确定性报告钩子刷新该报告。因此，即使父上下文已饱和，loop_stop 提交也会生成最终报告。如果钩子报告错误，请修复其指出的演示输入后，直接运行 "$PYTHON" scripts/render_report.py --results-dir "${RESULTS_DIR}"；切勿手动编写报告 HTML。

所有 Pipeline 阶段都在父上下文中内联运行。优先通过 Skill 工具直接调用底层 tao-skill-bank:* 技能，并根据对应的 references/*.md 文件叠加 DEFT 循环规范。如果映射的 Skill 工具不可用，但 Docker、技能源代码树和阶段参考模块均已就绪，则使用 references/scripts-and-agents.md 中记载的直接容器回退方案；首次执行回退阶段之前，在记录中写入 execution_path=direct-container，并为每个回退阶段记录映射的底层技能名称以及所用的确切直接命令。保持相同的 deft_state.json、制品和脚本生成报告契约。HTML 渲染不得委派。

使用捆绑脚本

每次工具调用时，设置 PYTHON=$(bash <skill_root>/scripts/deft_python.sh)； 然后使用 "$PYTHON" <skill_root>/scripts/<name>.py。先将所有路径参数解析为绝对主机路径。每个阶段开始前使用 deft_context.py，执行外部操作时使用 deft_exec.py，所有状态写入都使用 commit_stage.py。有关脚本调用、自动报告钩子、阶段映射、直接容器回退和路径不变式，请参阅 references/scripts-and-agents.md。

阶段参考模块

每个流水线阶段都对应技能库中的一个底层技能；匹配的 references/*.md 文件会在该技能的通用说明之上补充 DEFT 循环约定（挂载、输出目录和 commit_stage.py 参数）。**只阅读当前阶段的相关章节，然后通过 Skill 工具或文档说明的直接容器备用方式调用技能；切勿预先加载所有阶段参考文件。**如果参考文件缺失，请停止并要求用户重新安装插件。完整的阶段→参考文件→技能→归属关系表位于 references/scripts-and-agents.md → Stage Reference Modules。各阶段：train/evaluate（references/visual-changenet.md）、anomalygen（references/tao-generate-anomalies.md）、rca（references/tao-analyze-gaps-visual-changenet.md）、routing（references/tao-route-visual-changenet-samples.md）和 data_mining（references/tao-mine-aoi-images.md）。

**路径规则（不变量）。**在 ${RESULTS_DIR} 下记录绝对主机工件路径。对于 ChangeNet 直接容器，挂载 "$WORKSPACE:/data/workspace" 和 "$RESULTS_DIR:/results"；规格使用 /results/baseline/<stage> 或 /results/iterN/<stage>。其他阶段保留其参考模块要求的工作区挂载。切勿将运行目录重新映射到 /results/iterN。

数据、预检、流水线和状态参考

主题	参考文件	内容
气隙模式激活与离线执行	references/air-gap.md	全局模式触发条件、优先级、禁止的网络操作、分阶段资产要求和预检证据
自带数据、数据约定、输出布局、增强池	references/data-layout.md	无公开 AOI 数据集；完整的 <workspace> 输入目录树、ChangeNet 四列必需 CSV 架构、${RESULTS_DIR}/ 输出目录树，以及双来源挖掘池表
客户指标约定与评估器适配器	references/metric-contract.md	主要指标架构、比较方向、评估器 JSON、约束、evaluate 提交以及兼容行为
预检、默认值、预检摘要模板、运行时间估算	references/preflight.md	按顺序排列的 10 项预检、必需输入 max_iterations、所有默认值、完整的预检摘要表及填充命令，以及每次迭代的运行时间估算
流水线步骤、状态、阶段执行、报告、运行时行为	references/pipeline-and-state.md	基线预置/跳过训练逻辑、7 个迭代流水线步骤、deft_state.json 快照及事件架构、阶段后检查、每次迭代的 HTML 渲染，以及循环结束序列
捆绑脚本、报告钩子、阶段模块、AutoML 陷阱	references/scripts-and-agents.md	可用脚本表、确定性报告渲染器及提交后钩子、阶段参考模块表、路径规则不变量、AutoML 策略规格陷阱

**必需输入 — max_iterations。**没有默认值；如果用户未提供，请询问，并且在预检完成前不得继续。如果用户改为提供时间限制，则根据 references/preflight.md 中的每次迭代运行时间估算 max_iterations，并将估算值告知用户确认。所有其他运行参数都有默认值——绝不要询问有默认值的参数。完整默认值列表以及用户在唯一确认关卡中批准的预检摘要，见 references/preflight.md。

门控

运行完整的 Pre-Flight（references/preflight.md），打印 Pre-Flight 摘要，然后在唯一的用户门控处停止。获得批准后，运行基线（包含预置种子／跳过训练逻辑）和 7 步迭代工作流，详见 references/pipeline-and-state.md。

遇到以下任一情况时，必须立即停止且不得自动重试：任何阶段的 status=error；训练集／验证集泄漏；挖掘池缺失或行数为零；CSV 存在性检查失败；静默丢弃；AMP 分配不匹配；与 PAIDF 不兼容的 AnomalyGen 微调检查点；AnomalyGen Guardrail 检查点缺失；或 SDG 日志显示筛选已禁用。达到 KPI 目标、达到 max_iterations 或触发不可恢复的门控时，循环停止。每条终止路径都通过 commit_stage.py 提交 loop_stop，然后按照 references/pipeline-and-state.md 中的循环结束顺序执行。