scenario-asset-analysis

场景素材分析

概述

四种工具可从现有素材中提取说明文字、风格描述、分析结果或控制图：三种用途固定，一种用途开放。配合 search（默认工具集），它们可以回答一批素材导入后随之而来的问题，而这正是大部分实际工作所在：这是否符合需求、这是什么风格、这展示了什么、下一个模型可以以此为条件输入什么、上周批准的版本去哪儿了。

这些工具都不在默认工具集中。通过 scenario_tools_search 获取工具架构，然后使用与返回的 permission 相匹配的执行器运行每种工具：read 使用 scenario_tool_execute_read，write 使用 scenario_tool_execute_write。估算和实际运行都使用实时结果；不要根据未发生变化的输入素材推断执行通道。在 name 中填写工具名称，并将输入放在 parameters 下。或者使用 ?toolsets=full 重新连接。有关连接和范围的信息，请参阅此仓库中的 scenario 技能。如果此处提到的同级技能不在你可用的技能中，请让用户安装它（npx skills add scenario-labs/skills --skill <name>）；若无人值守，则根据工具架构继续操作，并指出这一缺口。

快速参考

需求	工具	形式
为一张图片生成说明文字	asset_caption	details_level：action 或 action+style
根据一张图片生成可复用的风格描述	asset_describe	返回完整描述以及可用于合成的提示词
其他需求，用自己的话描述	asset_analyze	instruction，以及最多 10 个 images 和 10 个 text_inputs
为另一个模型生成条件输入图	asset_detect	modality，十种模式之一，包括 canny、depth、pose、segmentation

四种工具都会消耗积分，并且都支持在 parameters 中设置 dry_run: true 以先行估算。 对于 OAuth，估算和运行时都传入用户选择的 team_id 和 project_id。重复运行可能会创建另一个计费任务；使用某个执行通道并不会使其免费。

会改变计划的四个事实

• asset_analyze 支持批处理。 一次调用可根据同一条 instruction 处理最多 10 张图片，因此审核 200 个素材需要 20 次调用，而不是 200 次。num_outputs（1 到 5）与此无关：它会针对同一条指令返回多个不同答案，而不是每张图片返回一个答案。在 instruction 中要求固定的逐图输出格式，以便答案保持易于解析。
• asset_detect 默认会移除背景。 remove_background 默认为 true，因此深度图或姿态图返回时，画面的背景环境已经被移除。只要地图需要覆盖整张图片，就将其设为 false。
• 它读取的是渲染结果，而不是文件。 对于矢量或分层源文件，它无法确认文件内容或报告精确值：某次调用将一个包含 16 条路径的 SVG 称为栅格图，把 #101614 填充色偏移成了 #131A18，还漏掉了一条不在调色板中的路径。要获取精确的颜色和结构，请解析文件；该工具判断的是渲染结果所呈现的内容。
• 条件适用时，固定用途工具优于灵活工具。 asset_caption 和 asset_describe 是专为特定用途打造的工具，速度比指示大模型完成同一任务更快。分类、提取、比较、翻译或根据需求给出判断时，再使用 asset_analyze。有一种例外：对于根据已配置品牌需求给出结构化的通过／警告／失败判断，安装了 Quality Gate 插件的团队有专用工具，可保存判断结果并免费重新读取（参见 scenario-quality-gate）；若未安装该插件，或需求仅以文字形式存在，则仍应使用 asset_analyze。

asset_analyze 和 asset_detect 最多等待 180s，之后会返回 job_id；接下来使用 jobs_wait，与其他任务的处理方式相同。

再次查找素材

检索时使用 search，并设置 target="assets"，且必须至少设置 query、filters、filter、image 或 images 中的一个：空调用会返回 400，而不是列出所有内容。

• 按文本查找。 默认情况下，query 会进行关键词匹配；query_semantic_ratio 可提高语义匹配的比重（0.5 到 0.8 适合“dark medieval atmosphere”这类氛围查询，1 表示纯语义匹配）。当该比重高于 0 时，sort_by（例如 ["createdAt:desc"]）会被忽略，因此按最新优先排列需要使用关键词模式。
• 按相似度查找。 image 接受一个素材 ID 或图片 URL，并返回相似素材；images 接受 {"like": [...], "unlike": [...]}，以正例和反例引导搜索（这两个字段不能同时使用）。image_semantic_ratio 决定相似的含义：默认值 1 会匹配主题和氛围；0 会匹配图片特征，适合查找近似重复图片和裁剪图。还可以附加 query，表达“与这些相似，但风格化程度更高”。
• 按结构查找。 filters 可根据 kind、tags、model_id、collection_ids 和 created_after/created_before 缩小范围，并与以上条件取交集。

示例：根据需求审查一批素材

1. 从运行结果中收集素材 ID（jobs_wait 会返回这些 ID）。
2. 对第一批素材调用 asset_analyze，设置 dry_run: true，以估算处理费用。
3. 调用 asset_analyze，将 images 设为 10 个 ID，并通过 instruction 写明需求，同时固定输出格式：“按顺序为每张图片回复 <index>: pass|fail, <reason in under 12 words>，每行都要给出理由，包括通过的图片。未居中、背景不是纯色或带有文字的图片都判定为失败。”逐批重复此操作。回答会以文本素材的形式返回（一份，或每张图片一份）：使用 asset_download 下载并查看判定结果。
4. 对表现最好的通过项调用 asset_describe。其可用于提示词的综合描述可直接用于下一批素材的提示词，无需训练即可保持视觉风格（参见 scenario-consistency）；如果综合描述只有一个简短标题，则改用详细描述作为提示词。
5. 整理结果：调用 collection_create，然后调用一次 collection_add_assets 并传入所有 ID（它会自动分批处理超过 49 个的情况，并跳过已归档的 ID）。asset_add_tags 是追加操作，因此只需给失败项添加标签，而不必重建整组标签。之后可通过 search 和 filters={"collection_ids": [...]} 找回这组素材，也可通过 images={"like": [...]} 查找相似素材。

常见错误

• 每个素材单独调用一次 asset_analyze，而实际上一次调用可处理 10 个。
• 将 num_outputs 当作 images 的批次大小。
• 对必须与源帧匹配的 asset_detect 映射使用 remove_background 的默认值。
• 重用记忆中的执行器通道：请使用最新 scenario_tools_search 结果中的 permission，dry_run 也不例外。如果通道拒绝请求，应刷新发现结果并使用其执行器，而不是重试相同调用。
• 要求 asset_analyze 生成图片。它返回的是文本；控制映射由 asset_detect 生成，最终渲染图由 model_run 生成。