From 7d4e3941ed262fdf32c09032488ec70d2bf83184 Mon Sep 17 00:00:00 2001 From: leefer Date: Fri, 30 Oct 2026 00:50:16 +0800 Subject: [PATCH] HEL-892: add explicit PreviewAny and promoted scalar reference conversion Co-authored-by: multica-agent --- .../scripts/audit_reference_conversion.py | 52 ++- .../comfyui/serialization_reference.py | 172 +++++++- .../calliope/comfyui/structure_reference.py | 202 +++++++++- .../src/calliope/comfyui/ui2api.py | 77 +++- .../tests/test_promoted_preview_reference.py | 379 ++++++++++++++++++ 5 files changed, 848 insertions(+), 34 deletions(-) create mode 100644 calliope-backend/tests/test_promoted_preview_reference.py diff --git a/calliope-backend/scripts/audit_reference_conversion.py b/calliope-backend/scripts/audit_reference_conversion.py index 9ba4437f..cb1e4046 100644 --- a/calliope-backend/scripts/audit_reference_conversion.py +++ b/calliope-backend/scripts/audit_reference_conversion.py @@ -19,12 +19,14 @@ from calliope.comfyui.companions import load_companions from calliope.comfyui.delivery_scope import exclusion_for from calliope.comfyui.serialization_reference import ( AUX_PROFILE, + PREVIEW_PROFILE, PRIMITIVE_PROFILE, PROFILE, resolve_reference_link, + serialize_promoted_node, serialize_reference_widgets, ) -from calliope.comfyui.structure_reference import STRUCTURE_PROFILES +from calliope.comfyui.structure_reference import PROMOTED_PROFILES, STRUCTURE_PROFILES from calliope.comfyui.ui2api import convert, convert_reference @@ -41,7 +43,7 @@ def audit(repo: Path, profile: str = PROFILE) -> dict: source, api = json.loads(raw), json.loads(record["raw"]) assert convert(api).prompt is not None selected = profile - if profile == "structure-batch-reference": + if profile in ("structure-batch-reference", "promoted-batch-reference"): version = source.get("extra", {}).get("frontendVersion") structural = f"comfy-frontend-{version}-structure-reference" selected = ( @@ -52,6 +54,15 @@ def audit(repo: Path, profile: str = PROFILE) -> dict: if any(n.get("type") == "PrimitiveNode" for n in source["nodes"]) else AUX_PROFILE ) + if profile == "promoted-batch-reference": + selected = ( + selected.replace("-structure-reference", "-promoted-reference") + if selected.replace("-structure-reference", "-promoted-reference") + in PROMOTED_PROFILES + else PREVIEW_PROFILE + if selected == PRIMITIVE_PROFILE + else selected + ) candidate = convert_reference(source, selected) projected = candidate.diagnostic_graph or source nodes = {str(n["id"]): n for n in projected["nodes"]} @@ -65,7 +76,14 @@ def audit(repo: Path, profile: str = PROFILE) -> dict: if node.get("type") in ("Reroute", "Note", "MarkdownNote"): continue try: - values = serialize_reference_widgets(node, selected) + values = ( + serialize_promoted_node(node, PROMOTED_PROFILES[selected]) + if selected in PROMOTED_PROFILES + else serialize_reference_widgets(node, selected) + ) + for boundary in candidate.resolved_boundaries: + if boundary["node_id"] == nid: + values[boundary["input_name"]] = boundary["value"] except ValueError as exc: unsupported.append({"node_id": nid, "type": node["type"], "reason": str(exc)}) else: @@ -77,7 +95,12 @@ def audit(repo: Path, profile: str = PROFILE) -> dict: "field": name, "source_reference": value, "api": expected, - "differences": differences(expected, value), + "differences": ( + differences({}, {name: value}) + if selected in (PREVIEW_PROFILE, *PROMOTED_PROFILES) + and name not in api.get(nid, {}).get("inputs", {}) + else differences(expected, value) + ), } ) linked = {s["name"] for s in node.get("inputs", []) if s.get("link") is not None} @@ -139,6 +162,9 @@ def audit(repo: Path, profile: str = PROFILE) -> dict: "source_frontend_version": source.get("extra", {}).get("frontendVersion"), "export_frontend_version": binding["frontend_version"], "whole_prompt_available": candidate.prompt is not None, + "candidate_prompt": candidate.prompt + if profile == "promoted-batch-reference" + else None, "whole_prompt_differences": differences(api, candidate.prompt) if candidate.prompt is not None else None, @@ -149,6 +175,17 @@ def audit(repo: Path, profile: str = PROFILE) -> dict: "unsupported_widget_nodes": unsupported, "diagnostic_graph": candidate.diagnostic_graph, "unresolved_boundaries": candidate.unresolved_boundaries, + "resolved_boundaries": [ + { + **v, + "api": api.get(v["node_id"], {}).get("inputs", {}).get(v["input_name"]), + "differences": differences( + api.get(v["node_id"], {}).get("inputs", {}).get(v["input_name"]), + v["value"], + ), + } + for v in candidate.resolved_boundaries + ], "node_types": node_types, "metadata": metadata, "api_only_fields_for_supported_nodes": api_only, @@ -164,6 +201,10 @@ def audit(repo: Path, profile: str = PROFILE) -> dict: "diagnostic structures never prove widget values, full equivalence or execution", "reference_conditions": { "unmodified_frontend_widgets_assumed": True, + "promoted_named_positional": "1.53.6 requires both representations to agree when named values exist; 1.48.7 ignores unknown named keys", + "promoted_missing_or_null": "no silent default; typed scalar consumption rejects null", + "primitive_inside_promoted_profile": "unsupported; whole prompt remains closed", + "combo_availability": "not evaluated; fixed scalar constructor only", "ue_extension_serializer_match": "unknown", "aux_release_artifact_commit_match": "unknown" if profile == AUX_PROFILE @@ -189,7 +230,10 @@ def main(): PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE, + PREVIEW_PROFILE, *STRUCTURE_PROFILES, + *PROMOTED_PROFILES, + "promoted-batch-reference", "structure-batch-reference", ), default=PROFILE, diff --git a/calliope-backend/src/calliope/comfyui/serialization_reference.py b/calliope-backend/src/calliope/comfyui/serialization_reference.py index 385387b5..5283a006 100644 --- a/calliope-backend/src/calliope/comfyui/serialization_reference.py +++ b/calliope-backend/src/calliope/comfyui/serialization_reference.py @@ -1,6 +1,7 @@ """Small, explicit public-reference contract, never a target object_info snapshot. -Sources and limits: docs/hel-892/{serialization-evidence,controlnet-reference}/sources.json. +Sources: docs/hel-892/{serialization-evidence,controlnet-reference, +promoted-reference,structure-reference}/sources.json. Only explicitly pinned scalar layouts are covered. The subtitle opt-in also folds direct Primitive STRING bindings. No seed controller, bypass, dynamic extension or target installation is inferred. @@ -13,6 +14,7 @@ from typing import Any PROFILE = "comfy-frontend-1.37.11-core-reference" AUX_PROFILE = "comfy-frontend-1.37.11-controlnet-aux-e8b689a-reference" AUX_COMMIT = "e8b689a513c3e6b63edc44066560ca5919c0576e" +PREVIEW_PROFILE = "comfy-frontend-1.37.11-preview-reference" PRIMITIVE_PROFILE = "comfy-frontend-1.37.11-qwen-b037d7be-reference" # Explicit earlier Qwen schema, not a claim about the installed plugin. Its # 14 widgets differ from the newer reference's added normalize_text field. @@ -77,7 +79,7 @@ def reference_definitions(profile: str = PROFILE) -> dict[str, Any]: "output": outputs, } - if profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE): + if profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE, PREVIEW_PROFILE): raise ValueError("未知参考版本") definitions = { "Canny": spec( @@ -105,7 +107,7 @@ def reference_definitions(profile: str = PROFILE) -> dict[str, Any]: ["IMAGE"], {name: "INT" if kind is int else "COMBO" for name, kind in layout}, ) - if profile == PRIMITIVE_PROFILE: + if profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE): definitions["LoadAudio"] = spec({"audio": "COMBO"}, ["AUDIO"], {"audioUI": "AUDIO_UI"}) definitions["AILab_Qwen3ASRSubtitle"] = spec( {"audio": "AUDIO"}, @@ -125,15 +127,22 @@ def reference_definitions(profile: str = PROFILE) -> dict[str, Any]: for name, kind in _SUBTITLE_LAYOUT }, ) + if profile == PREVIEW_PROFILE: + definitions["PreviewAny"] = spec({"source": "*"}, []) return definitions def serialize_reference_widgets(node: dict[str, Any], profile: str = PROFILE) -> dict[str, Any]: """Apply only the pinned identity serializers; reject any extra/missing value.""" - if profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE): + if profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE, PREVIEW_PROFILE): raise ValueError("未知参考版本") - if profile == PRIMITIVE_PROFILE and node.get("type") in ("LoadAudio", "AILab_Qwen3ASRSubtitle"): + if profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE) and node.get("type") in ( + "LoadAudio", + "AILab_Qwen3ASRSubtitle", + ): return _serialize_subtitle(node) + if profile == PREVIEW_PROFILE and node.get("type") == "PreviewAny": + return _serialize_preview(node) if profile == AUX_PROFILE and node.get("type") in _AUX_LAYOUTS: return _serialize_aux(node) if node.get("mode", 0) != 0: @@ -239,7 +248,7 @@ def fold_reference_primitives(source, profile): primitives = [n for n in nodes.values() if n.get("type") == "PrimitiveNode"] if not primitives: return graph - if profile != PRIMITIVE_PROFILE: + if profile not in (PRIMITIVE_PROFILE, PREVIEW_PROFILE): raise ValueError("Primitive 需要显式字幕/具名字符串参考契约") # Validate all links before removing a virtual node or consuming a value. for lid in links: @@ -387,3 +396,154 @@ def resolve_reference_link(nodes, links, link_id) -> list[Any]: link_id = upstream["inputs"][0].get("link") if link_id is None: raise ValueError("Reroute 无上游连线") + + +def _serialize_preview(node): + """v1.37.11 configure skips the two serialize=false DOM widgets. + + graphToPrompt instead checks options.serialize, so both named preview DOM + widgets participate (the second overwrites the first) and previewMode is + retained. The first persisted element restores previewMode; the two trailing + nulls are legacy workflow placeholders, NOT three fields to omit from API. + No DOM interaction or extension override is modelled by this profile. + """ + properties = node.get("properties") or {} + if ( + node.get("mode", 0) != 0 + or properties.get("cnr_id") != "comfy-core" + or properties.get("ver") != "0.11.0" + ): + raise ValueError("PreviewAny 提供方/版本/模式不符合固定参考") + if any(k in node for k in ("widgets", "widgets_values_named", "serializeValue")): + raise ValueError("PreviewAny 自定义控件/具名恢复未证明") + values = node.get("widgets_values") + if ( + not isinstance(values, list) + or len(values) != 3 + or values[1:] != [None, None] + or (values[0] is not None and type(values[0]) is not bool) + ): + raise ValueError("PreviewAny 仅覆盖布尔/null模式和两个null旧式占位") + sockets = node.get("inputs", []) + if ( + len(sockets) != 1 + or sockets[0].get("name") != "source" + or sockets[0].get("type") != "*" + or sockets[0].get("widget") is not None + ): + raise ValueError("PreviewAny source 绑定不符") + return {"preview": "", "previewMode": values[0]} + + +# Direct scalar contracts proved by fixed core 0.31.0/0.38.0 schemas and +# corresponding frontend constructors. Binding a field is deliberately weaker +# than proving the whole node's serializer (e.g. TextGenerate dynamic combo). +_DIRECT = { + "UNETLoader": {"unet_name": "COMBO", "weight_dtype": "COMBO"}, + "CLIPLoader": {"clip_name": "COMBO", "type": "COMBO", "device": "COMBO"}, + "VAELoader": {"vae_name": "COMBO"}, + "EmptyLatentImage": {"width": "INT", "height": "INT", "batch_size": "INT"}, + "KSampler": { + "seed": "INT", + "steps": "INT", + "cfg": "FLOAT", + "sampler_name": "COMBO", + "scheduler": "COMBO", + "denoise": "FLOAT", + }, + "ComfySwitchNode": {"switch": "BOOLEAN"}, + "PrimitiveStringMultiline": {"value": "STRING"}, + "PrimitiveBoolean": {"value": "BOOLEAN"}, + "TextGenerate": {"prompt": "STRING", "thinking": "BOOLEAN"}, + "TextEncodeQwenImage21": {"prompt": "STRING", "negative_prompt": "STRING", "resolution": "INT"}, + "QwenImage21Cache": {"device": "COMBO", "dtype": "COMBO"}, +} +_SIMPLE_LAYOUTS = { + "UNETLoader": ("unet_name", "weight_dtype"), + "CLIPLoader": ("clip_name", "type", "device"), + "VAELoader": ("vae_name",), + "EmptyLatentImage": ("width", "height", "batch_size"), + "PrimitiveStringMultiline": ("value",), + "PrimitiveBoolean": ("value",), + "QwenImage21Cache": ("device", "dtype"), +} +_SIMPLE_OUTPUTS = { + "UNETLoader": ["MODEL"], + "CLIPLoader": ["CLIP"], + "VAELoader": ["VAE"], + "EmptyLatentImage": ["LATENT"], + "PrimitiveStringMultiline": ["STRING"], + "QwenImage21Cache": ["MODEL"], + "PrimitiveBoolean": ["BOOLEAN"], +} + + +def direct_widget_type(node, socket, version): + """Prove a named scalar binding, never infer one from source array order.""" + props = node.get("properties") or {} + expected = "0.31.0" if version == "1.48.7" else "0.38.0" + ct, name = node.get("type"), socket.get("name") + if ( + props.get("cnr_id") != "comfy-core" + or props.get("ver") != expected + or node.get("mode", 0) != 0 + ): + raise ValueError("内部节点提供方/版本/模式不符合固定参考") + if ct in ("TextGenerate", "TextEncodeQwenImage21", "QwenImage21Cache") and expected != "0.38.0": + raise ValueError("此节点未在固定0.31.0来源中证明") + kind = _DIRECT.get(ct, {}).get(name) + if kind is None or socket.get("type") != kind or socket.get("widget") != {"name": name}: + raise ValueError(f"未证明内部字段绑定:{ct}.{name}") + if any(k in node for k in ("widgets", "serializeValue")): + raise ValueError("自定义控件或具名恢复不在参考契约内") + return kind + + +def validate_direct_value(value, kind): + expected = {"COMBO": str, "STRING": str, "BOOLEAN": bool, "INT": int, "FLOAT": float}[kind] + if (expected is float and type(value) not in (float, int)) or ( + expected is not float and type(value) is not expected + ): + raise ValueError(f"边界值类型不符:{kind};null不等于缺项/false/0") + + +def promoted_definitions(): + return { + ct: { + "input": {"required": {n: [t] for n, t in _DIRECT[ct].items()}, "optional": {}}, + "output": _SIMPLE_OUTPUTS[ct], + } + for ct in _SIMPLE_LAYOUTS + } | { + "QwenImage21Cache": { + "input": {"required": {"model": ["MODEL"], "device": ["COMBO"], "dtype": ["COMBO"]}}, + "output": ["MODEL"], + } + } + + +def serialize_promoted_node(node, version): + """Only complete simple scalar layouts; no seed/dynamic/autogrow serializer.""" + ct = node.get("type") + layout = _SIMPLE_LAYOUTS.get(ct) + values = node.get("widgets_values", []) + if layout is None or not isinstance(values, list) or len(values) != len(layout): + raise ValueError("未证明完整内部控件构造/序列化布局") + named = node.get("widgets_values_named") + if version == "1.53.6" and named is not None: + if ( + not isinstance(named, dict) + or set(named) != set(layout) + or any(type(named[n]) is not type(v) or named[n] != v for n, v in zip(layout, values)) + ): + raise ValueError("具名/位置控件不一致;namedValuesRestore开关未知") + result = {} + for name, value in zip(layout, values): + # A widget can exist without an exposed input socket; its definition is + # pinned independently of the stored sockets. + kind = direct_widget_type( + node, {"name": name, "type": _DIRECT[ct][name], "widget": {"name": name}}, version + ) + validate_direct_value(value, kind) + result[name] = value + return result diff --git a/calliope-backend/src/calliope/comfyui/structure_reference.py b/calliope-backend/src/calliope/comfyui/structure_reference.py index 37d38d91..af6e4655 100644 --- a/calliope-backend/src/calliope/comfyui/structure_reference.py +++ b/calliope-backend/src/calliope/comfyui/structure_reference.py @@ -1,7 +1,8 @@ -"""Pinned frontend structural projection, for diagnostics only. +"""Pinned frontend structure and opt-in direct promoted scalar projection. -Sources: docs/hel-892/structure-reference/sources.json. Does not serialize -promoted widgets, interpret third-party nodes, or establish execution eligibility. +Sources: docs/hel-892/{structure-reference,promoted-reference}/sources.json. +Structure profiles remain diagnostic. Direct values never prove complete ordinary +node serializers, third-party behavior, target versions or execution eligibility. """ from __future__ import annotations @@ -17,12 +18,16 @@ STRUCTURE_PROFILES = { } +PROMOTED_PROFILES = {f"comfy-frontend-{v}-promoted-reference": v for v in ("1.48.7", "1.53.6")} + + @dataclass class Structure: graph: dict[str, Any] | None issues: list[dict[str, Any]] = field(default_factory=list) # These are boundary inputs whose frontend widget store cannot be reconstructed. unresolved: list[dict[str, Any]] = field(default_factory=list) + resolved: list[dict[str, Any]] = field(default_factory=list) def _id(value): @@ -39,7 +44,7 @@ def _uuid(value): return False -def expand_reference_subgraphs(source: dict, profile: str) -> Structure: +def expand_reference_subgraphs(source: dict, profile: str, *, widgets: bool = False) -> Structure: """Expand scoped nodes/links without consuming positional boundary widgets. A returned graph is diagnostic data, never an executable prompt. Unbound @@ -47,12 +52,12 @@ def expand_reference_subgraphs(source: dict, profile: str) -> Structure: returns no graph, including malformed unused branches/definitions. """ try: - return _expand(source, profile) + return _expand(source, profile, widgets) except (ValueError, TypeError, KeyError, AttributeError, IndexError, RecursionError) as exc: return Structure(None, [{"code": "reference_structure_invalid", "message": str(exc)}]) -def _expand(source, profile): +def _expand(source, profile, widgets=False): version = STRUCTURE_PROFILES.get(profile) if version is None or (source.get("extra") or {}).get("frontendVersion") != version: raise ValueError("源前端声明与结构参考版本不符") @@ -237,6 +242,152 @@ def _expand(source, profile): return resolve(child, link[1], link[2], seen) return [":".join((*path, str(nid))), slot] + resolved = [] + if widgets: + from .serialization_reference import direct_widget_type, validate_direct_value + + def targets(key, slot, stack=()): + marker = (key, slot) + if marker in stack: + raise ValueError("递归控件绑定") + definition = definitions[key] + found = [] + for lid in definition["inputs"][slot]["linkIds"]: + edge = networks[key][1][str(lid)] + target = networks[key][0][str(edge[3])] + socket = target["inputs"][edge[4]] + if target["type"] in definitions: + found.extend(targets(target["type"], edge[4], stack + (marker,))) + elif socket.get("widget") is not None: + try: + kind = direct_widget_type(target, socket, version) + except ValueError: + kind = None + found.append((target, socket, kind)) + return found + + host_cache = {} + + def host_values(path): + if path in host_cache: + return host_cache[path] + key, _, parent, instance = contexts[path] + definition = definitions[key] + props = instance.get("properties") or {} + if ( + props.get("proxyWidgetErrorQuarantine") + or props.get("proxyWidgets") + or any(k in instance for k in ("widgets", "serializeValue")) + ): + raise ValueError("隔离/代理/自定义控件覆盖不在promoted参考契约内") + names = [s["name"] for s in definition["inputs"]] + if len(names) != len(set(names)): + raise ValueError("重名稳定输入标识") + bindings = [] + for slot, socket in enumerate(instance.get("inputs", [])): + bound = targets(key, slot) + if not bound: + if socket.get("widget") is not None: + raise ValueError("实例控件缺少可证明的内部绑定") + continue + kind = bound[0][2] + if kind is None: + raise ValueError( + f"首个内部绑定 {bound[0][0]['type']}.{bound[0][1]['name']} " + "无固定构造契约;无法重建host控件顺序" + ) + compatible = all( + t == kind + and (n["type"], s["name"]) == (bound[0][0]["type"], bound[0][1]["name"]) + for n, s, t in bound + ) + # Differently constrained fanouts need their own compatibility + # proof; never propagate a value just because types coincide. + if socket.get("widget") != {"name": names[slot]} or socket.get("type") != kind: + raise ValueError("实例稳定widget.name或类型不符") + bindings.append((slot, kind, compatible)) + values = instance.get("widgets_values", []) + if not isinstance(values, list) or len(values) != len(bindings): + raise ValueError("promoted控件数量不符;不静默回退内部默认值") + # Array offset is justified only after reconstructing every host + # widget via interior named bindings (SubgraphNode._resolveInputWidget). + result = {} + local_nodes = list(networks[parent[0]][0]) + prefix = "/nodes/" + str(local_nodes.index(str(instance["id"]))) + if parent[0] is not None: + prefix = ( + "/definitions/subgraphs/" + str(list(definitions).index(parent[0])) + prefix + ) + for index, (slot, kind, compatible) in enumerate(bindings): + value = values[index] + # Retain the persisted value for provenance. Type validation + # happens on scalar consumption; external links always win. + result[slot] = { + "value": value, + "value_pointer": prefix + "/widgets_values/" + str(index), + "binding_name": names[slot], + "binding_type": kind, + "compatible": compatible, + "boundary_instance": ":".join(path), + } + named = instance.get("widgets_values_named") + if version == "1.53.6" and named is not None: + if ( + not isinstance(named, dict) + or set(named) != {v["binding_name"] for v in result.values()} + or any( + type(named[v["binding_name"]]) is not type(v["value"]) + or named[v["binding_name"]] != v["value"] + for v in result.values() + ) + ): + raise ValueError("具名/位置host值不一致;namedValuesRestore开关未知") + for v in result.values(): + name = v["binding_name"].replace("~", "~0").replace("/", "~1") + v["named_value_pointer"] = prefix + "/widgets_values_named/" + name + host_cache[path] = result + return result + + def scalar(endpoint, node, socket): + path = tuple(endpoint["boundary_instance"].split(":")) + values = host_values(path) + slot = endpoint["slot"] + if slot not in values: + raise ValueError("无稳定promoted控件绑定;不采用内部现值") + value = values[slot] + if not value["compatible"]: + raise ValueError("多目标控件约束未知或不兼容") + kind = direct_widget_type(node, socket, version) + validate_direct_value(value["value"], kind) + if kind != value["binding_type"]: + raise ValueError("边界到内部字段类型不兼容") + return value + + store_keys = {} + for path in contexts: + if not path: + continue + try: + values = host_values(path) + for value in values.values(): + # Pinned store identity uses local instance ID, not the + # composite execution path. Conflicting nested definitions + # must not be advertised as isolated store values. + key = (path[-1], value["binding_name"]) + previous = store_keys.get(key) + identity = (value["binding_type"], type(value["value"]), value["value"]) + if previous is not None and previous != identity: + raise ValueError("嵌套host的局部widgetId冲突;存储值优先顺序未证明") + store_keys[key] = identity + except ValueError as exc: + issues.append( + { + "code": "promoted_host_unverified", + "node_id": ":".join(path), + "message": str(exc), + } + ) + projected = [] for full, node in flat.items(): path = tuple(full.split(":")) @@ -249,9 +400,40 @@ def _expand(source, profile): original = networks[ctx[0]][1][str(lid)] endpoint = resolve(ctx, original[1], original[2], set()) if isinstance(endpoint, dict): - unresolved.append( - {"node_id": full, "input_slot": slot, "input_name": socket["name"], **endpoint} - ) + boundary = { + "node_id": full, + "input_slot": slot, + "input_name": socket["name"], + **endpoint, + } + if widgets: + try: + value = scalar(endpoint, node, socket) + except ValueError as exc: + unresolved.append({**boundary, "reason": str(exc)}) + else: + local = list(networks[ctx[0]][0]).index(full.split(":")[-1]) + prefix = "/nodes/" + str(local) + if ctx[0] is not None: + prefix = ( + "/definitions/subgraphs/" + + str(list(definitions).index(ctx[0])) + + prefix + ) + resolved.append( + { + **boundary, + **deepcopy(value), + "target_pointer": prefix + "/inputs/" + str(slot), + "precedence": [ + "external_link", + "promoted_value", + "internal_serializer", + ], + } + ) + else: + unresolved.append(boundary) continue new_id = len(projected) + 1 projected.append([new_id, *endpoint, full, slot, original[5]]) @@ -285,4 +467,4 @@ def _expand(source, profile): "links": projected, "extra": deepcopy(source.get("extra", {})), } - return Structure(graph, issues, unresolved) + return Structure(graph, issues, unresolved, resolved) diff --git a/calliope-backend/src/calliope/comfyui/ui2api.py b/calliope-backend/src/calliope/comfyui/ui2api.py index b8fae510..17e0a229 100644 --- a/calliope-backend/src/calliope/comfyui/ui2api.py +++ b/calliope-backend/src/calliope/comfyui/ui2api.py @@ -15,15 +15,18 @@ from typing import Any from .serialization_reference import ( AUX_PROFILE, + PREVIEW_PROFILE, PRIMITIVE_PROFILE, PROFILE, fold_reference_primitives, + promoted_definitions, reference_definitions, resolve_reference_link, + serialize_promoted_node, serialize_reference_widgets, validate_reroute, ) -from .structure_reference import STRUCTURE_PROFILES, expand_reference_subgraphs +from .structure_reference import PROMOTED_PROFILES, STRUCTURE_PROFILES, expand_reference_subgraphs @dataclass @@ -33,6 +36,7 @@ class Conversion: reference_only: bool = False diagnostic_graph: dict[str, Any] | None = None unresolved_boundaries: list[dict[str, Any]] = field(default_factory=list) + resolved_boundaries: list[dict[str, Any]] = field(default_factory=list) def convert(source: Any, object_info: dict[str, Any] | None = None) -> Conversion: @@ -46,7 +50,15 @@ def convert_reference(source: Any, profile: str = PROFILE) -> Conversion: Public reference definitions cannot establish target execution eligibility. """ if ( - profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE, *STRUCTURE_PROFILES) + profile + not in ( + PROFILE, + AUX_PROFILE, + PRIMITIVE_PROFILE, + PREVIEW_PROFILE, + *STRUCTURE_PROFILES, + *PROMOTED_PROFILES, + ) or not isinstance(source, dict) or "nodes" not in source ): @@ -56,34 +68,51 @@ def convert_reference(source: Any, profile: str = PROFILE) -> Conversion: True, ) try: - if profile in STRUCTURE_PROFILES: - structure = expand_reference_subgraphs(source, profile) + if profile in (*STRUCTURE_PROFILES, *PROMOTED_PROFILES): + promoted = profile in PROMOTED_PROFILES + structure_profile = profile.replace("-promoted-reference", "-structure-reference") + structure = expand_reference_subgraphs(source, structure_profile, widgets=promoted) if structure.graph is None: return Conversion(None, structure.issues, True) # Structural scope never supplies widget contracts for newer versions. # List the concrete remaining node gaps instead of one subgraph error. - result = _convert(structure.graph, {}, reference=True, reference_profile=profile) + result = _convert( + structure.graph, + promoted_definitions() if promoted else {}, + reference=True, + reference_profile=profile, + boundary_values=structure.resolved, + ) result.issues = structure.issues + result.issues for boundary in structure.unresolved: result.issues.append( { "code": "boundary_widget_unverified", **boundary, - "message": "边界无外部连线;不按位置猜 promoted widget 值", + "message": boundary.get( + "reason", "边界无外部连线;不按位置猜 promoted widget 值" + ), } ) - result.prompt = None + if not promoted or result.issues: + result.prompt = None result.reference_only = True result.diagnostic_graph = structure.graph result.unresolved_boundaries = structure.unresolved + result.resolved_boundaries = structure.resolved return result + if ( + profile == PREVIEW_PROFILE + and (source.get("extra") or {}).get("frontendVersion") != "1.37.11" + ): + raise ValueError("PreviewAny 需要显式1.37.11前端声明") original = source - if profile == PRIMITIVE_PROFILE: + if profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE): source = fold_reference_primitives(source, profile) result = _convert( source, reference_definitions(profile), reference=True, reference_profile=profile ) - if profile == PRIMITIVE_PROFILE and source != original: + if profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE) and source != original: result.diagnostic_graph = source except (ValueError, TypeError, KeyError, AttributeError, IndexError) as exc: return Conversion(None, [{"code": "invalid_reference_contract", "message": str(exc)}], True) @@ -91,7 +120,9 @@ def convert_reference(source: Any, profile: str = PROFILE) -> Conversion: return result -def _convert(source, object_info=None, *, reference=False, reference_profile=PROFILE) -> Conversion: +def _convert( + source, object_info=None, *, reference=False, reference_profile=PROFILE, boundary_values=() +) -> Conversion: issues: list[dict[str, Any]] = [] def fail(code: str, message: str, node_id: Any = "") -> None: @@ -141,7 +172,9 @@ def _convert(source, object_info=None, *, reference=False, reference_profile=PRO links[str(link[0])] = link if reference: frontend_version = (source.get("extra") or {}).get("frontendVersion") - expected_version = STRUCTURE_PROFILES.get(reference_profile, "1.37.11") + expected_version = {**STRUCTURE_PROFILES, **PROMOTED_PROFILES}.get( + reference_profile, "1.37.11" + ) if frontend_version is not None and frontend_version != expected_version: fail("reference_frontend_mismatch", "源图声明的前端版本与固定参考不一致") # Validate every stored link, even unused branches: never silently drop @@ -194,12 +227,16 @@ def _convert(source, object_info=None, *, reference=False, reference_profile=PRO inputs = {} if reference: try: - inputs.update(serialize_reference_widgets(node, reference_profile)) + inputs.update( + serialize_promoted_node(node, PROMOTED_PROFILES[reference_profile]) + if reference_profile in PROMOTED_PROFILES + else serialize_reference_widgets(node, reference_profile) + ) if [s.get("type") for s in node.get("outputs", [])] != spec["output"]: raise ValueError("源输出槽不符合固定参考契约") names = [s.get("name") for s in node.get("inputs", [])] allowed = set(declared) | ({"upload"} if ct == "LoadImage" else set()) - if reference_profile == PRIMITIVE_PROFILE and ct == "LoadAudio": + if reference_profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE) and ct == "LoadAudio": allowed |= {"upload", "audioUI"} if len(names) != len(set(names)) or set(names) - allowed: raise ValueError("额外或重复输入槽不在固定参考契约内") @@ -217,6 +254,12 @@ def _convert(source, object_info=None, *, reference=False, reference_profile=PRO nid, ) continue + # graphToPrompt writes resolved promoted widgetInfo after the ordinary + # serializer, before/alongside resolved links. Values bypass the inner + # custom serializeValue; external links still take priority below. + for boundary in boundary_values: + if boundary["node_id"] == nid: + inputs[boundary["input_name"]] = boundary["value"] for name, socket in sockets.items(): lid = socket.get("link") if lid is None: @@ -249,7 +292,13 @@ def _convert(source, object_info=None, *, reference=False, reference_profile=PRO expected = declared[name][0] if declared[name] else None actual = outputs[link[2]] # Custom unions/wildcards need frontend evidence; do not guess coercions. - if expected != actual: + if expected != actual and not ( + reference + and reference_profile == PREVIEW_PROFILE + and ct == "PreviewAny" + and name == "source" + and expected == "*" + ): fail( "link_type_unverified", f"输入 {name} 的槽类型不一致:{actual} → {expected}", diff --git a/calliope-backend/tests/test_promoted_preview_reference.py b/calliope-backend/tests/test_promoted_preview_reference.py new file mode 100644 index 00000000..34bd9b54 --- /dev/null +++ b/calliope-backend/tests/test_promoted_preview_reference.py @@ -0,0 +1,379 @@ +"""Mutation fixtures are synthetic; real source/API comparisons are separate.""" + +import json +from copy import deepcopy +from pathlib import Path + +import pytest + +from calliope.comfyui.serialization_reference import PREVIEW_PROFILE +from calliope.comfyui.ui2api import convert, convert_reference + + +def real(case): + repo = Path(__file__).resolve().parents[2] + cases = json.loads((repo / "docs/hel-892/golden-cases.json").read_text())["cases"] + row = next(c for c in cases if c["id"] == case) + return json.loads((repo / row["source_path"]).read_text()) + + +PROFILE = "comfy-frontend-1.53.6-promoted-reference" +D = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" +E = "aaaaaaaa-bbbb-cccc-dddd-ffffffffffff" + + +def fixture(value="external", *, boolean=False): + kind = "BOOLEAN" if boolean else "STRING" + ct = "PrimitiveBoolean" if boolean else "PrimitiveStringMultiline" + definition = { + "id": D, + "inputNode": {"id": -10}, + "outputNode": {"id": -20}, + "inputs": [{"name": "stable", "type": kind, "linkIds": [10]}], + "outputs": [{"name": "out", "type": kind, "linkIds": [11]}], + "nodes": [ + { + "id": 3, + "type": ct, + "properties": {"cnr_id": "comfy-core", "ver": "0.38.0"}, + "widgets_values": [True if boolean else "internal"], + "inputs": [ + {"name": "value", "type": kind, "widget": {"name": "value"}, "link": 10} + ], + "outputs": [{"type": kind, "links": [11]}], + } + ], + "links": [[10, -10, 0, 3, 0, kind], [11, 3, 0, -20, 0, kind]], + } + return { + "nodes": [ + { + "id": 5, + "type": D, + "widgets_values": [value], + "inputs": [ + { + "name": "stable", + "label": "value", + "type": kind, + "widget": {"name": "stable"}, + "link": None, + } + ], + "outputs": [{"name": "out", "type": kind, "links": []}], + } + ], + "links": [], + "definitions": {"subgraphs": [definition]}, + "extra": {"frontendVersion": "1.53.6"}, + } + + +def test_real_preview_candidate_keeps_all_proven_serializer_differences(): + source = real("02") + before = deepcopy(source) + result = convert_reference(source, PREVIEW_PROFILE) + assert result.prompt is not None and result.reference_only + for nid in ("1", "2", "3", "4"): + assert result.prompt[nid]["inputs"]["preview"] == "" + assert result.prompt[nid]["inputs"]["previewMode"] is None + assert result.prompt[nid]["inputs"]["source"][0] == "9" + assert result.prompt["6"]["inputs"]["audioUI"] == "" + assert "normalize_text" not in result.prompt["9"]["inputs"] + assert "7" not in result.prompt and source == before + assert convert(source).prompt is None + + +@pytest.mark.parametrize("value", [True, False, None]) +def test_preview_first_persisted_element_restores_mode_not_a_dom_text(value): + source = real("02") + source["nodes"][0]["widgets_values"][0] = value + result = convert_reference(source, PREVIEW_PROFILE) + assert result.prompt["2"]["inputs"]["previewMode"] is value + assert result.prompt["2"]["inputs"]["preview"] == "" + + +@pytest.mark.parametrize( + "mutation", + [ + "count", + "bad_mode_type", + "bad_placeholder", + "provider", + "version", + "frontend", + "missing_frontend", + "custom", + "port", + ], +) +def test_preview_unknown_contract_fails_entire_graph(mutation): + source = real("02") + node = source["nodes"][0] + if mutation == "count": + node["widgets_values"].pop() + elif mutation == "bad_mode_type": + node["widgets_values"][0] = 0 + elif mutation == "bad_placeholder": + node["widgets_values"][1] = "saved text" + elif mutation == "provider": + node["properties"]["cnr_id"] = "override" + elif mutation == "version": + node["properties"]["ver"] = "0.38.0" + elif mutation == "frontend": + source["extra"]["frontendVersion"] = "1.53.6" + elif mutation == "missing_frontend": + source["extra"].pop("frontendVersion") + elif mutation == "custom": + node["serializeValue"] = "override" + else: + node["inputs"][0]["name"] = "other" + assert convert_reference(source, PREVIEW_PROFILE).prompt is None + + +@pytest.mark.parametrize("value,boolean", [("changed", False), ("", False), (False, True)]) +def test_promoted_wins_over_internal_value_and_keeps_exact_scalar(value, boolean): + source = fixture(value, boolean=boolean) + before = deepcopy(source) + result = convert_reference(source, PROFILE) + assert result.prompt["5:3"]["inputs"]["value"] == value + assert type(result.prompt["5:3"]["inputs"]["value"]) is type(value) + row = result.resolved_boundaries[0] + assert row["value_pointer"] == "/nodes/0/widgets_values/0" + assert row["binding_name"] == "stable" + assert row["target_pointer"] == "/definitions/subgraphs/0/nodes/0/inputs/0" + assert source == before and convert(source).prompt is None + + +def test_zero_and_boolean_are_not_conflated(): + source = fixture(0) + inner = source["definitions"]["subgraphs"][0]["nodes"][0] + inner.update(type="EmptyLatentImage", widgets_values=[64, 64, 1]) + inner["inputs"][0].update(name="width", type="INT", widget={"name": "width"}) + inner["outputs"][0]["type"] = "LATENT" + definition = source["definitions"]["subgraphs"][0] + definition["inputs"][0]["type"] = "INT" + definition["outputs"][0]["type"] = "LATENT" + definition["links"][0][5] = "INT" + definition["links"][1][5] = "LATENT" + source["nodes"][0]["inputs"][0]["type"] = "INT" + source["nodes"][0]["outputs"][0]["type"] = "LATENT" + assert convert_reference(source, PROFILE).prompt["5:3"]["inputs"]["width"] == 0 + source["nodes"][0]["widgets_values"] = [False] + assert convert_reference(source, PROFILE).prompt is None + + +def test_external_link_has_priority_over_both_host_and_internal_scalars(): + source = fixture("host") + inner = deepcopy(source["definitions"]["subgraphs"][0]["nodes"][0]) + inner.update(id=9, widgets_values=["upstream"], inputs=[]) + inner["outputs"][0]["links"] = [1] + source["nodes"].append(inner) + source["nodes"][0]["inputs"][0]["link"] = 1 + source["links"] = [[1, 9, 0, 5, 0, "STRING"]] + result = convert_reference(source, PROFILE) + assert result.prompt["5:3"]["inputs"]["value"] == ["9", 0] + assert result.resolved_boundaries == [] + + +def test_multi_instance_and_nested_boundary_values_do_not_cross_scopes(): + source = fixture("left") + other = deepcopy(source["nodes"][0]) + other.update(id=6, widgets_values=["right"]) + source["nodes"].append(other) + outer = source["definitions"]["subgraphs"][0] + nested = deepcopy(outer) + nested["id"] = E + outer["nodes"] = [ + { + "id": 3, + "type": E, + "widgets_values": ["nested-default"], + "inputs": [ + {"name": "stable", "type": "STRING", "widget": {"name": "stable"}, "link": 10} + ], + "outputs": [{"name": "out", "type": "STRING", "links": [11]}], + } + ] + source["definitions"]["subgraphs"].append(nested) + result = convert_reference(source, PROFILE) + assert result.prompt["5:3:3"]["inputs"]["value"] == "left" + assert result.prompt["6:3:3"]["inputs"]["value"] == "right" + source["nodes"][1]["widgets_values"][0] = "mutated" + second = convert_reference(source, PROFILE) + assert second.prompt["5:3:3"]["inputs"]["value"] == "left" + assert second.prompt["6:3:3"]["inputs"]["value"] == "mutated" + + +@pytest.mark.parametrize( + "mutation", + [ + "null", + "missing", + "extra", + "binding", + "duplicate", + "version", + "provider", + "named_conflict", + "quarantine", + "host_custom", + "unknown", + ], +) +def test_bad_promoted_contract_never_falls_back_to_internal_default(mutation): + source = fixture() + instance = source["nodes"][0] + inner = source["definitions"]["subgraphs"][0]["nodes"][0] + if mutation == "null": + instance["widgets_values"] = [None] + elif mutation == "missing": + instance["widgets_values"] = [] + elif mutation == "extra": + instance["widgets_values"].append("extra") + elif mutation == "binding": + instance["inputs"][0]["widget"]["name"] = "value" + elif mutation == "duplicate": + inner["inputs"].append(deepcopy(inner["inputs"][0])) + elif mutation == "version": + inner["properties"]["ver"] = "0.31.0" + elif mutation == "provider": + inner["properties"]["cnr_id"] = "third-party" + elif mutation == "named_conflict": + instance["widgets_values_named"] = {"stable": "different"} + elif mutation == "host_custom": + instance["widgets"] = [{"name": "stable", "serializeValue": "override"}] + elif mutation == "quarantine": + instance["properties"] = {"proxyWidgetErrorQuarantine": [{"hostValue": "override"}]} + else: + inner["type"] = "Unknown" + assert convert_reference(source, PROFILE).prompt is None + + +def test_same_binding_fanout_and_type_constraint_conflict(): + source = fixture("fanout") + d = source["definitions"]["subgraphs"][0] + other = deepcopy(d["nodes"][0]) + other["id"] = 4 + other["inputs"][0]["link"] = 12 + other["outputs"][0]["links"] = [] + d["nodes"].append(other) + d["inputs"][0]["linkIds"].append(12) + d["links"].append([12, -10, 0, 4, 0, "STRING"]) + result = convert_reference(source, PROFILE) + assert result.prompt["5:3"]["inputs"]["value"] == "fanout" + assert result.prompt["5:4"]["inputs"]["value"] == "fanout" + other["type"] = "PrimitiveBoolean" + other["inputs"][0]["type"] = "BOOLEAN" + other["outputs"][0]["type"] = "BOOLEAN" + other["widgets_values"] = [True] + assert convert_reference(source, PROFILE).prompt is None + + +def test_real04_resolves_proven_boundaries_without_completing_unknown_nodes(): + source = real("04") + result = convert_reference(source, PROFILE) + assert result.prompt is None + values = {(v["node_id"], v["input_name"]): v for v in result.resolved_boundaries} + assert values["459:474", "switch"]["value"] is True + assert values["459:471", "thinking"]["value"] is False + assert {(v["node_id"], v["input_name"]) for v in result.unresolved_boundaries} == { + ("459:458", "seed"), + ("459:471", "sampling_mode.seed"), + } + # Change both representations: setting namedValuesRestore is deliberately unknown. + instance = source["nodes"][1] + instance["widgets_values"][1] = False + instance["widgets_values_named"]["switch"] = False + changed = convert_reference(source, PROFILE) + assert ( + next( + v["value"] + for v in changed.resolved_boundaries + if v["node_id"] == "459:474" and v["input_name"] == "switch" + ) + is False + ) + + +def test_real03_keeps_missing_core_version_contract_explicit(): + result = convert_reference(real("03"), "comfy-frontend-1.48.7-promoted-reference") + assert result.prompt is None and result.unresolved_boundaries + assert any(i["node_id"] == "37:13" for i in result.issues) + + +def test_parent_boundary_does_not_overwrite_unrelated_same_name_root_field(): + source = fixture("parent") + root = deepcopy(source["definitions"]["subgraphs"][0]["nodes"][0]) + root.update(id=9, inputs=[], widgets_values=["root"]) + root["outputs"][0]["links"] = [] + source["nodes"].append(root) + result = convert_reference(source, PROFILE) + assert result.prompt["5:3"]["inputs"]["value"] == "parent" + assert result.prompt["9"]["inputs"]["value"] == "root" + + +def test_simple_named_restore_disagreement_rejects_and_agreement_is_safe_for_both_settings(): + source = fixture("host") + inner = source["definitions"]["subgraphs"][0]["nodes"][0] + inner["widgets_values_named"] = {"value": "internal"} + source["nodes"][0]["widgets_values_named"] = {"stable": "host"} + assert convert_reference(source, PROFILE).prompt["5:3"]["inputs"]["value"] == "host" + inner["widgets_values_named"]["value"] = "other" + assert convert_reference(source, PROFILE).prompt is None + + +def test_promoted_link_resolution_bypasses_inner_dynamic_prompt_serializer(): + source = real("04") + instance = source["nodes"][1] + names = [s["name"] for s in instance["inputs"]] + index = names.index("negative_prompt") + instance["widgets_values"][index] = "{raw|not sampled}" + instance["widgets_values_named"]["negative_prompt"] = "{raw|not sampled}" + result = convert_reference(source, PROFILE) + resolved = next( + r + for r in result.resolved_boundaries + if (r["node_id"], r["input_name"]) == ("459:452", "negative_prompt") + ) + assert resolved["value"] == "{raw|not sampled}" + assert result.prompt is None # unknown whole node/dynamic serializers remain closed + + +def test_primitive_inside_promoted_profile_remains_a_concrete_blocker(): + source = fixture() + inner = source["definitions"]["subgraphs"][0]["nodes"][0] + inner["type"] = "PrimitiveNode" + result = convert_reference(source, PROFILE) + assert result.prompt is None + assert any(i["code"] == "reference_node_unsupported" for i in result.issues) + + +def test_conflicting_nested_store_identity_is_not_assumed_to_be_scoped_by_execution_id(): + source = fixture("outer-a") + base = source["definitions"]["subgraphs"][0] + nested_a = deepcopy(base) + nested_a["id"] = E + nested_b = deepcopy(base) + nested_b["id"] = "aaaaaaaa-bbbb-cccc-dddd-111111111111" + outer_b = deepcopy(base) + outer_b["id"] = "aaaaaaaa-bbbb-cccc-dddd-222222222222" + for outer, inner, value in ((base, nested_a, "a"), (outer_b, nested_b, "b")): + outer["nodes"] = [ + { + "id": 3, + "type": inner["id"], + "widgets_values": [value], + "inputs": [ + {"name": "stable", "type": "STRING", "widget": {"name": "stable"}, "link": 10} + ], + "outputs": [{"name": "out", "type": "STRING", "links": [11]}], + } + ] + instance_b = deepcopy(source["nodes"][0]) + instance_b.update(id=6, type=outer_b["id"], widgets_values=["outer-b"]) + source["nodes"].append(instance_b) + source["definitions"]["subgraphs"].extend([outer_b, nested_a, nested_b]) + result = convert_reference(source, PROFILE) + assert result.prompt is None + assert any("widgetId冲突" in i["message"] for i in result.issues)