DemonGatanjieu-Anomalous_Model_Browser/docs/architecture/recipes.md

Workflow Recipes and Parameter Notebooks

Read this document for recipe schemas, cards/detail behavior, package handling, result galleries, Parameter Notebooks, prompt roles, and the recipe-powered Node Assistant.

Package import/export availability

Recipe package import and export are temporarily closed pending validation. Topbar/card/detail buttons are disabled with a localized explanation. The registered POST /anomalous/export_recipe_package route returns HTTP 503 with code recipe_export_disabled before reading request JSON or recipe files. RECIPE_PACKAGE_EXPORT_ENABLED in api/recipe_packages.py is a release gate, not a user setting. RECIPE_PACKAGE_IMPORT_ENABLED likewise gates both POST /anomalous/import_recipe_package_inspect and POST /anomalous/import_recipe_package_commit: each returns HTTP 503 with code recipe_import_disabled before reading uploaded bytes, request JSON, inspection tokens or writing files. Package format helpers remain for compatibility tests; local saves are unaffected.

Reopening requires an explicit release decision, package round-trip and failure validation, then restoring the frontend export action and enabling the backend gates together. Do not reopen package transfers as a side effect of UX work. Workflow share-code import/export is a separate, verified feature available from Toolbox.

Product and data model

Workspace contains Prompt Notes, Workflow Recipes, and the Material Library. Recipe Parameter Notebooks are presented as Parameter Sets (参数方案). Internal notebook route and property names may remain stable for compatibility even when the user-facing presentation changes.

A Workflow Recipe stores the authoritative serialized graph plus bounded metadata for browsing and comparison. Summary adapters expose common model, LoRA, prompt, and sampling semantics; generic bounded widget summaries cover other nodes, including third-party nodes. Summaries are presentation only. Edit, apply, structural validation, and detailed values resolve from the contained serialized workflow by node ID and widget index.

The card API stays lightweight. Full workflow and history payloads are loaded on demand. Every update archives the previous full recipe locally, bounded to 20 versions. The structural fingerprint (sha256-structural-v1) is an integrity and version-comparison value, not model identity evidence.

Backend ownership is split by responsibility: workflow_schema.py owns graph validation, fingerprints, signatures and integrity receipts; recipe_schema.py owns recipe/model-reference normalization; recipe_images.py owns source images, covers and output-gallery inspection; recipe_store.py owns directory, record and history I/O. recipes.py maps HTTP requests and errors and retains narrow compatibility exports only. recipe_packages.py, parameters.py, and materials import those owners directly rather than reaching through the route facade.

The current persisted recipe schema is v7. Earlier schema steps introduced the structural fingerprint, explicit model-reference identity records, and optional recipe-owned preview descriptors; v5 separates model identity from editable official-origin fields. V6 records whether the saved graph is a partial or complete recipe. V7 adds bounded recipe-scoped model notes and makes Hash synchronization across local matching and partial append an explicit invariant. Normal save/update paths preserve compatible imported records rather than rebuilding identity from the current machine. An explicit save-time verification choice may replace missing identity with a freshly computed SHA-256 for supported model categories.

Recipe model references separate saved identity from current-machine availability and official origin metadata. Origin refresh is an explicit enrichment mode. A refresh-only request clones the stored recipe before enrichment so it cannot be rejected by complete-recipe validation or discard the workflow. Normal updates preserve imported identity/origin records when the current machine cannot resolve them.

Save, edit, and presentation

Save captures the live graph exactly once before opening the dialog; that fixed snapshot is the graph sent to the backend. The dialog records recipe identity, notes, tags, and cover/source image. It does not ask users to select presentation pins or a per-recipe snapshot policy. Existing params.pinned values survive an edit, while new recipes use an empty list.

Before the dialog opens, an advisory check reads only the captured workflow hash records and cached local metadata. Recognized model references without verified identity appear as an optional action. The checkbox is off by default; enabling it computes the exact full-file SHA-256 in a worker thread during persistence. Foundation components such as VAE and text encoders are included because Model Doctor requires their hash for automatic recovery and treats size-only evidence as a manual candidate at most. Inspection failure never blocks the workflow snapshot from being saved.

The detail view contains Overview, Parameters, Gallery, and Versions as applicable. Compact cards may ellipsize bounded values while preserving their full copy value. Detail rows provide visible expand/collapse and copy controls for long values and prompts; they do not silently truncate authoritative data.

ui_recipe_detail.js coordinates the detail session, active tab, and model composition. ui_recipe_overview.js owns the overview; ui_recipe_parameters.js owns prompt roles, parameter editing, raw nodes, and preset saving; and ui_recipe_model_matching.js owns preview resolution plus explicit local matching. Inline persistence is centralized in ui_recipe_metadata.js, with pure ordering/value helpers in ui_recipe_parameter_utils.js. The catalog shell lives in ui_recipe_catalog.js, cards and card actions in ui_recipe_cards.js, save/edit dialogs in ui_recipe_dialogs.js, and shared cover helpers in ui_recipe_media.js. ui_recipe_versions.js owns version comparison and restore, while ui_recipe_gallery.js owns result rendering and opens ui_gallery_detail.js directly for image inspection. Shared detail DOM/copy primitives live in ui_recipe_detail_dom.js; the subviews return refresh/finish decisions through callbacks instead of redrawing one another.

Model names in compact recipe presentation use a basename or official model name, never a full filesystem path. Saved paths and hashes belong behind advanced information. A preview or exact path can locate current-machine presentation only after the reference is already understood; it cannot establish identity.

Import matching is a separate explicit recovery action. Unresolved references are sent to the hash/size/category resolver. A discovered candidate remains presentation-only until the user chooses Apply match; that action updates the authoritative workflow widget, model reference, and node-scoped Hash index through the full-recipe update path and archives the previous recipe. The author's saved filename or path is never match evidence. Model-reference user_note is recipe-scoped presentation metadata and never match evidence.

Recipe-owned model preview snapshots are bounded, content-addressed WebP files below .assets/<recipe-stem>/. They are at most 320 px or 96 KiB each, limited to 12 images and 1.25 MiB per save/update. Static local preview files are accepted; original videos are never packaged, though a bound local video may contribute a bounded first-frame thumbnail. Deleting a recipe removes only its contained assets after the recipe file is deleted. History may share an asset ID.

Canvas actions

Recipe cards and details expose a scope-aware canvas action. A live graph with an active output node and no unconnected required inputs is saved as a complete recipe and opens as a new workflow canvas. A graph without an output node or with required connection boundaries is saved as a partial recipe and appends to the current canvas. Append clones saved nodes, assigns collision-free IDs, remaps links, places/selects the inserted content, treats groups as first-class items, remaps node-scoped model Hash records, and rolls back nodes/groups/Hash records together on failure. Legacy recipes without scope metadata are complete recipes because earlier releases only documented and captured complete workflows.

Structural editing is separate from composition. It may load a recipe into a new canvas after explicit confirmation and saves back through the full-recipe update path. It is not presented as an ambiguous “Open to canvas” recipe action.

All list/detail actions await the shared transaction before reporting success or restoring controls. A failure must leave the button usable and the host graph in its prior state.

Result galleries

Recipe result discovery uses sha256-node-types-v1: the sorted node class composition and count. It intentionally ignores seeds, prompts, model values, and other parameters, so ordinary generation variations can match. This is separate from the structural integrity fingerprint.

Opening detail scans at most the newest 200 PNG files below the ComfyUI output directory and reads only bounded embedded workflow or API prompt metadata. There is no persistent output index or background polling. A chosen result may become the recipe-owned compressed cover; its original output path remains a local convenience reference rather than package content or identity evidence.

The main output Gallery performs its page-one scan when opened and exposes a manual Refresh action. It does not poll in the background and preserves scroll position across manual refresh.

Parameter Notebooks

Parameter Notebooks are immutable generation-value snapshots owned by a recipe. Saving or updating a recipe creates a new snapshot. The Parameters tab uses a two-pane history browser: the left pane selects a notebook and the right pane prominently identifies the active name and timestamp. Selection requests carry a token so an older gallery response cannot overwrite a newer selection. Parameter result matching uses the separate sha256-params-v1 signature.

“New parameter note” clones the selected recipe/snapshot into an editable draft and saves a new immutable snapshot. Rename uses the dedicated parameter endpoint and atomic persistence. Delete accepts only the validated notebook filename, invalidates in-flight requests, reloads the list, and selects the newest remaining note when necessary. The recipe's current baseline is not a deletable stored row.

Runtime-volatile values such as sampler seeds remain visible by field name but their values are excluded from summaries, copying, editing, matching, and apply. The serialized workflow retains the slots for compatibility.

“Read current and create” and “Apply to current workflow” share a skeleton preflight. Every saved node must match a local node by type and shape, preferring stable ID/title evidence; extra local nodes are allowed. Read-current refuses to create a draft if the skeleton is incomplete. Apply validates all widget slots before mutation, resolves serialized records to live nodes, invokes ComfyUI callbacks, and rolls values back if a callback fails.

The Node Assistant queries bounded notebook presets by selected node type. Its cache is invalidated by save/delete and bypassed by an explicit refresh. Applying a preset is a single-node transaction; it does not apply the full workflow.

Prompt roles

Automatic prompt roles are conservative. recipe_parser.js traces backward from allowlisted official sampler/Guider conditioning inputs through allowlisted conditioning pass-through nodes to native CLIPTextEncode nodes. Unknown third-party nodes are opaque; titles, type-name guesses, prompt content, and a default-positive rule are not semantic evidence.

Saved role metadata joins to assistant records by string-safe node ID. Legacy recipes may recover a role only from an exact, unambiguous full prompt value in the saved positive/negative arrays. The same value in both arrays remains unknown.

Manual overrides live in params.promptRoleOverrides, keyed by string-safe node ID and guarded by saved node type. Values are positive, negative, both, ignored, or unknown. An override wins over automatic/legacy metadata; removing it restores the saved automatic result. Updates retain it only while ID and type still match.

Recipe-to-model navigation

Opening a resolved local model from Recipe Overview keeps the outer browser open and temporarily replaces all main content surfaces with model detail. A compact return token retains the recipe payload, active tab, scroll position, and prior Workspace return state.

Model-detail Back, or reopening Workspace and selecting Workflow Recipes, consumes that token and reconstructs the exact recipe detail. Navigating directly to another main panel or closing Workspace abandons the transition and clears stale media/DOM/return state. Opening Workspace during the transition must not overwrite the earlier outer-panel return state.

Workflow Recipes and recipe-powered Assistant parameter presets remain beta surfaces until an explicit stability decision changes that status. Localized notices identify their data directories and distinguish single-node preset apply from full-skeleton Parameter Notebook apply.