scenario-quality-gate

场景质量门禁

概述

一个工具 asset_quality_gate_run，用于为完成的图像素材评分，并返回 pass／warn／fail 判定，以及 0 到 100 的分数和按维度列出的 reasons 与 suggestions：始终执行 AI 质量检查；如果团队或项目配置了简报，还会检查是否符合品牌简报。仅支持图像素材。质量门禁是 Enterprise 附加功能：如果团队未启用，调用会正常失败，因此请识别这种情况，改用 asset_analyze 进行审核（参见 scenario-asset-analysis），并说明原因。重试无法解决此问题。

该工具仅列于目录中，且属于写入类：使用 scenario_tools_search 获取架构，然后通过 scenario_tool_execute_write 执行，参数为 {name: "asset_quality_gate_run", parameters: {...}}，并将作用域 ID 放在 parameters 中（读取执行器会按通道拒绝此调用，并指出正确的执行器）。或者使用 ?toolsets=full 重新连接。连接和作用域信息请参见 scenario 技能。如果此处提到的某个相关技能不在你可用的技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若无法等待，请根据工具架构继续操作，并指出这一缺失。

快速参考：调用费用

调用	发生的情况	费用
普通调用，已存有可用判定	返回已存储的判定，source: "stored"	免费（响应中不含 creativeUnitsCost）
普通调用，没有可用判定	执行新分析并存储判定，source: "new_analysis"	计费；响应中包含 creativeUnitsCost（截至本文撰写时为 1 CU）
rerun: true	执行新分析并替换已存储的判定	计费
dry_run: true	不会执行任何操作；返回新分析的价格，作为 creativeUnitsCost	免费

只有在已存在可用判定时，普通调用才是读取操作；否则，同一调用会悄然升级为计费分析。“没有可用判定”包括从未评分和已存储的 error 结果。如果支出需要先获批准，请先进行免费查询：使用 dry_run: true，或调用 asset_get；其 qualityGate 字段会在已存储判定时附带判定和分数（仅摘要；已存储的 reasons 和 suggestions 可通过该工具获取，仍然免费）。sensitivity（low、medium、high；默认使用团队或项目设置）仅影响新分析，读取已存储结果时会忽略此设置。rerun: true 仅用于简报或灵敏度设置发生变更之后；其他情况不要使用：它会再次计费并覆盖原结果。

读取判定结果

响应包含 source 和 quality_gate：其中有 verdict、overallScore、aiQualityScore、briefComplianceScore、sensitivity、appliedBriefIds 和 details。如果未配置简报，则完全不包含合规维度（appliedBriefIds: []，且 overallScore 等于 aiQualityScore）；如果配置了简报，details.briefCompliance 会与 details.aiQuality 并列，二者各自包含一个 score，以及 reasons 和 suggestions 列表，通常每个列表中都有多项内容。

将判定转化为更好的图像

判定本身只能筛选素材。只有当反馈能指导下一次尝试时，这道关卡才值得付出成本：

• reasons 会指出具体缺陷（“左手手指解剖结构被拉长了”，“背景渐变偏离了简报中的配色”）。根据每项缺陷选择修复路径：对于其他方面已获批准的图像上的局部瑕疵，使用蒙版进行局部修补（scenario-image）；对于全局问题，则重新生成。
• suggestions 是以编辑指令的形式编写的，通常面向手动修图。应用所有适用的建议，而不只是第一条：将它们转化为下一次 model_run 的提示词或参数，或转化为编辑指令。
• 重新生成的图像是新素材，因此普通调用会对它评分。rerun 绝不是循环的一部分。它甚至可能免费获得预评分：启用了自动检测的团队（其 teams_list 行中的 qualityGateAutoDetect: true）会自动为新生成的图像评分。
• 如果某一轮重复出现相同类别的缺陷，且分数没有变化，改写提示词也无法解决问题：切换模型（再次调用 recommend），或在投入下一轮之前通过蒙版编辑修复缺陷。
• 预先设定通过门槛和轮次上限：默认使用 verdict: "pass"，也可使用用户指定的分数目标（例如 overallScore 达到或超过 90；此时指定的门槛优先于单独的 pass）；除非另有说明，否则设为三轮，因为每一轮都要支付一次生成和一次分析的费用。达到上限或某轮分数不再提升时，就应停止：报告最佳素材及其剩余缺陷，并在投入更多轮次前征求同意；若无人跟进，则交付最佳素材并指出未达标之处。

scenario-refine-loop 将这种循环纪律延伸到关卡之外：每轮只调整一个变量、从已批准的基准图重新生成，并在标准超出简报范围时选择合适的修复方式。

判定无法覆盖的内容

这道关卡用于检测瑕疵。在真实素材上的测试表明，设计时需要考虑以下三项局限：

• 检测瑕疵，而非判断合理性。 一幅画中，汽车装有两种不同的车轮，只有一侧是白边轮胎，后轮上方也没有轮拱；它在 sensitivity: "high" 时得分为 92 且判定为 pass，reasons 还赞扬了作为缺陷的镀铬轮圈。对于不可能而非仅仅难看的内容，需要自行进行结构检查：数量和连接关系（双手、每只手的手指数量、四肢、车轮，以及每个部件都连接到一个主体上）、局部与整体的关系（车轮位于轮拱内、护手位于自己的刀刃上方、倒影位于产生倒影的物体下方），以及承重部件。
• 它从未见过你的参考图。 briefCompliance 需要配置简报，而简报是文本，因此任何调用都无法判断图像中的汽车或服装是否与其生成所依据的参考板上的相同。你需要逐项将素材与参考图进行对照。
• 合成图会对各部分取平均。 一张包含 12 个面板的故事板得分为 88 且判定为 pass，其中一个面板却在物理上不可能。要对你愿意拒收的单位进行评分：使用 model_scenario-image-slicer 拆分合成图，对各部分分别评分，只修复不合格的部分，再使用 model_scenario-compose-image 重新合成。

分数也只是结构修复是否奏效的微弱信号：损坏的面板及其修正后的替换版本都得分为 92，变化的只有 reasons。请重新阅读缺陷列表，不要只盯着分数。

实例：迭代主视觉道具直至通过

1. 按照 scenario-image 生成：执行 model_run、jobs_wait，并收集资源 ID。
2. 使用 query="quality gate" 执行一次 scenario_tools_search 以获取架构，然后对第一个资源设置 dry_run: true，查看每次分析的价格。
3. 评分：使用 {name: "asset_quality_gate_run", parameters: {asset_id, team_id, project_id}} 执行 scenario_tool_execute_write。它会返回 source: "new_analysis" 和一个 quality_gate，其中包含 verdict: "warn"、 briefComplianceScore: 58，以及 details.briefCompliance.suggestions，建议将徽标放在左上角，并使用更平坦的背景。
4. 将两条建议都纳入提示词，重新生成，然后通过普通调用对新资源评分（不使用 rerun）。
5. verdict: "pass"：交付并归档（集合和标签参见 scenario-asset-analysis）。 之后读取任何已评分资源，均可免费读取已存储的结果。
6. 下个冲刺周期简报发生变化时，再对需要重新评判的资源设置 rerun: true。

常见错误

• 把普通调用当作免费读取：如果没有可用的已存储判定结果，系统会静默运行并收取分析费用。费用较重要时，请先使用 dry_run 或 asset_get 探查。
• 习惯性地传入 rerun: true：这会对原本可免费读取的判定结果再次收费。它唯一的用途是在简报或敏感度发生变化后刷新结果。
• 未配置简报却期待获得 briefComplianceScore：只有当 appliedBriefIds 非空时，quality_gate 才会包含该字段和 details.briefCompliance。
• 每次只应用一条建议并重新评分：建议列表通常包含多项修正，一次重新生成就能全部纳入。
• 通过 scenario_tool_execute_read 运行：这是写入类操作，会被执行通道拒绝。
• 对视频、3D 或音频资源评分：仅支持图像资源。
• 认为新上传的文件没有判定结果：上传会按内容去重，因此字节完全相同的文件无论文件名如何，都会返回相同的长期资源 ID；如果团队之前评过该文件，重新上传时也会带有其已存储的判定结果。
• 对返回已存储判定结果的调用设置 sensitivity：该参数仅适用于新分析；要对已评分资源采用更严格的评分，必须设置 rerun: true。
• 重试权限失败：Quality Gate 是 Enterprise 附加组件。请改用 scenario-asset-analysis 中的 asset_analyze 进行审核，并向用户说明原因。