从脚本运行复杂的CLI工具，并用JSON报告确认是否成功

## 用结构化数据判断CLI是否成功，不看进度文字 当脚本、流水线或编码代理驱动复杂的命令行工具时，应将CLI视为有版本的机器接口，而不是交互式命令外壳。将规划、执行和验证分开，使每个阶段都接收结构化数据，并生成可供下一阶段验证的证据。 - 不得通过解析面向人的进度文本来判断一次运行是否成功。 - 不得凭记忆推断支持的任务、输出类别或许可证要求。 - 记录工具版本、解析后的运行时设置、请求范围和生成的制品。 - 必需的结构化证据缺失或相互矛盾时，应按安全失败方式处理。 ## 运行前先查看工具的任务和类别列表 在构建高成本任务之前，先使用工具的轻量信息命令或注册表命令。优先使用由验证主CLI的同一注册表生成的JSON视图，因为从源代码抄录的列表和硬编码名称可能与已安装版本发生偏差。 能力发现应提供： - 可用任务及其输入模态； - 每项任务是否需要许可证或使用资格； - 类别筛选器接受的准确索引与类别名称映射； - 已安装的工具版本以及各任务的特定限制。 优先选择不会加载重量级推理依赖项、不会初始化加速器、不会下载模型权重，也不会改变本地状态的发现路径。如果不需要完整注册表，应将查询范围限定为单个任务或单个类别视图。 ## 写明全部输入、输出和设置，让运行可以重复 每次运行都应明确指定输入、输出、任务、设备策略、可选类别子集、输出表示形式和报告路径。只接受文档规定的输入形式，例如体数据文件、有序切片目录或切片归档，并根据所选输出模式验证目标位置是否有效。 执行前： 1. 确认所请求的任务和类别存在于当前能力注册表中。 2. 确认输入形式受支持，且输出路径含义明确。 3. 在启动受限制任务前解决许可证问题。 4. 有意识地选择设备和性能模式。 5. 为机器可读的运行报告预留唯一的路径。 如果旧制品可能被误认为当前结果，不得重复使用原有输出目录。将解析后的命令参数与运行证据一起保存。 ## 选择设备和快速模式，需要许可证的任务先确认许可证 将设备选择和速度选项视为可复现性契约的一部分。记录实际解析到的设备，而不只是请求的设备，因为加速不可用时可能回退到CPU，从而显著改变运行时间。 资源受限时，通过文档规定的控制项降低成本： - 仅在可以接受精度折衷时使用较低分辨率的快速模式； - 只请求下游工作所需的类别； - 存在多个设备时，指定具体的加速器索引； - 必要时明确选择受支持的平台后端。 如果更快或更窄的模式会改变输出质量或范围，绝不能静默替换。任务受许可证限制时，除非已经配置有效授权，否则必须在开始推理前停止。 ## 检查JSON报告和其中列出的每个文件 要求CLI在成功完成后写入结构化报告。该报告是自动化流程的权威交接制品，应包括： - 工具、运行时、框架和依赖项版本； - 任务、模态和许可证要求； - 解析后的设备和性能标志； - 规范化的输入与输出位置； - 请求的类别子集以及最终的索引与类别名称映射； - 实际运行时间和准确的已生成输出文件列表。 验证报告确实存在、可解析为JSON、标识了预期任务，并列出了下一阶段需要的所有制品。随后验证每个列出的文件都存在。对于各类别的体积、强度、体素数、离散程度、极值、质心或边界框，应使用专门的统计输出；不得从文件名或进度文本推断这些值。 ## 按退出码区分失败，并在新的输出位置重试 读取任何可选制品之前，先解释进程退出状态。区分成功完成、运行时失败以及参数或用法失败，避免重试无效命令。 - 成功时，验证报告及其中声明的输出文件。 - 运行时失败时，保存诊断标准错误，并将原因归类为授权缺失、资源不可用、输入损坏或未处理的工具错误等。 - 参数失败时，在重试前修正任务、输入、输出或选项集合。 - 使用静默模式减少日常噪声，仅在需要更多诊断上下文时使用调试模式。 不得将部分文件、进度消息或空输出目录视为成功。重试必须使用新的目标位置，或使用已清理的目标位置，确保失败尝试留下的制品不能满足本次验证。 ## 通过公开API调用，并用报告中的文件列表衔接后续处理 需要进程内执行时，使用受支持的高级编程API，但仍须保持与CLI工作流相同的明确任务、输入、输出和验证契约。规划和验证时，优先使用无需导入完整推理运行时即可列出任务和类别的轻量注册表模块。 让编排逻辑独立于实现内部：从正式注册表发现能力，通过文档规定的CLI或API执行，并根据结构化报告中的输出列表连接下游处理。这样可避免脆弱的标准输出解析和重复的能力表，同时在版本变化后继续维持自动化。