Publish current ComfyUI O1Key code baseline

Replace the prior release tree with the current plugin, frontend, tests, and documentation. Document retired node IDs and the public Gitea update source.
2026-09-24 19:56:48 +08:00
parent 3e337722ab
commit ba920f2b66
183 changed files with 49496 additions and 9934 deletions
@@ -0,0 +1,25 @@
+# NNNN: Decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+- Owners: Maintainers
+
+## Context
+
+What problem, constraint, or compatibility risk requires a durable decision?
+
+## Decision
+
+What will the project do?
+
+## Consequences
+
+What becomes easier, harder, required, or intentionally unsupported?
+
+## Alternatives considered
+
+Which realistic alternatives were rejected, and why?
+
+## Validation
+
+Which tests, measurements, or operational checks prove the decision works?
@@ -0,0 +1,39 @@
+# 0001: AI-native repository guidance and documentation
+
+- Status: Accepted
+- Date: 2026-08-29
+- Owners: Maintainers
+
+## Context
+
+The plugin accumulated implementation notes, local tool state, root-level tests, and stale scripts. Important knowledge was scattered between code and temporary reports, making it difficult for a new maintainer or coding agent to identify runtime boundaries, compatibility constraints, and the correct validation commands.
+
+Codex supports layered `AGENTS.md` files from repository root to working directory. ComfyUI also auto-loads frontend files, so generic repository assumptions can be unsafe for `web/` and node-schema work.
+
+## Decision
+
+- Use a concise root `AGENTS.md` for repository-wide executable rules.
+- Use scoped `AGENTS.md` files only in `nodes/`, `web/`, and `tests/`, where local constraints materially differ.
+- Use `docs/` as the structured maintainer knowledge base.
+- Keep user documentation in root `README.md` and durable design choices in numbered ADRs.
+- Keep one-off cleanup reports under `docs/maintenance/`.
+- Keep tests in `tests/` and run them in isolated processes through `tests/run_all.py`.
+
+## Consequences
+
+- Agents receive the right constraints close to the files they edit without overloading the root instruction file.
+- Architecture and operational knowledge becomes reviewable and versioned.
+- Changes that affect configuration, compatibility, or runtime boundaries must update documentation in the same work unit.
+- Maintainers must keep links and commands synchronized as the portable layout evolves.
+
+## Alternatives considered
+
+- One large root instruction file: rejected because it mixes executable rules with background knowledge and approaches instruction-size limits as the project grows.
+- Documentation only in README: rejected because user guidance and maintainer internals have different audiences and change rates.
+- Tool-specific hidden configuration directories: rejected because they are not portable across agents and should not be runtime project state.
+
+## Validation
+
+- Verify root and scoped instruction files are discoverable from their directories.
+- Verify every path linked from `docs/README.md` exists.
+- Run the full isolated test suite and the plugin import smoke test after structural changes.
@@ -0,0 +1,37 @@
+# 0002: Save-node ownership of generated image formats
+
+- Status: Superseded by [0003](0003-generator-owned-image-save-configuration.md)
+- Date: 2026-08-30
+- Owners: Maintainers
+
+## Context
+
+The unified background generator previously decoded provider results and permanently re-encoded Nano Banana output as PNG. This obscured whether `output_format` was a provider capability or a local save choice, and discarded the original PNG/JPEG container returned by Nano Banana. The released `O1keyImageSave` node also delegated to ComfyUI's PNG-only helper.
+
+## Decision
+
+Generation paths retain provider bytes and detected format. Panel-triggered jobs place those bytes in ComfyUI temp storage and return `type=temp` descriptors. `O1keyImageSave` is the only component that promotes them into output storage, through its append-only `格式` widget and the batch-bound `/o1key/image/save` route.
+
+`格式=原始` preserves PNG/JPEG/WebP compressed image data; workflow metadata may be inserted into the container without recompressing pixels. Explicit PNG and WebP use lossless encoding. Explicit JPEG uses quality 100 with 4:4:4 subsampling. If pixels were modified after generation or original bytes are unavailable, `原始` falls back to PNG.
+
+Nano Banana payloads never contain `output_format`. GPT Image keeps its API-level `output_format`, which determines provider output but does not bypass the save node.
+
+## Consequences
+
+- Nano Banana PNG and JPEG responses remain distinguishable and recoverable.
+- API output options and local save options have separate owners and labels.
+- Background generation must retain temp results until the save route succeeds.
+- Original-format preservation requires private in-memory tensor metadata on the direct execution path; ordinary downstream tensor operations may invalidate it and trigger the PNG fallback.
+- Existing workflows gain only one appended save-node widget and migrate to `原始` idempotently.
+
+## Alternatives considered
+
+- Continue saving every background result as PNG. Rejected because it destroys the provider container and implies a Nano Banana capability that does not exist.
+- Let the generator select the permanent local format. Rejected because it duplicates the output responsibility and leaves the save node semantically misleading.
+- Store original bytes inside workflow JSON. Rejected because large binary payloads do not belong in workflows and would make saved graphs unsafe and impractical.
+
+## Validation
+
+- `tests/test_o1key_image_save.py` verifies original JPEG/PNG preservation, metadata injection, explicit conversions, and PNG fallback.
+- `tests/test_o1key_image_jobs.py` verifies Nano Banana ignores GPT-only fields, jobs produce temp descriptors, and save-route path binding.
+- `tests/test_o1key_image_generator_frontend.mjs` verifies temp promotion, workflow metadata submission, result restoration, and idempotent widget migration.
@@ -0,0 +1,40 @@
+# 0003: Generator-owned image save configuration
+
+- Status: Accepted
+- Date: 2026-09-02
+- Owners: Maintainers
+- Supersedes: [0002](0002-save-node-image-format-ownership.md)
+
+## Context
+
+The unified image workflow exposed naming, local format conversion, and output location on every `O1keyImageSave` result node. A single generator may create several result nodes, so this duplicated settings and made model-level behavior hard to understand. GPT Image's API `output_format` is also semantically different from Nano Banana's optional local save conversion.
+
+Moving released positional widgets between nodes risks silently changing saved workflows. Multiple old save nodes may also carry different settings even though the new design has one shared generator configuration.
+
+## Decision
+
+`O1keyImageGenerator` owns four append-only save inputs at indexes 19–22: `命名规则`, `filename_prefix`, `格式`, and `保存位置`. `命名规则` keeps the serialized value `自定义前缀` for compatibility but displays `自定义`. `O1keyImageSave` removes all configuration widgets and remains the sole permanent file writer and result renderer.
+
+Direct execution attaches validated save settings to the output tensor. Panel jobs snapshot them in the server-side job record at submission, and the save route prefers that immutable snapshot. The frontend migration finds the generator connected to each legacy save node, moves the first connected save node's positional settings into the generator, clears migrated save-node values, and is safe to repeat.
+
+Local `格式` is visible and effective only for Banana models. GPT Image always uses local `原始`; its independent API `输出格式` displays `JPEG / PNG / WebP`, stores lowercase values, and defaults new nodes to `jpeg`. Legacy generators retain saved API-format values and use the historical `png` default only when migrating workflows that predate that field.
+
+## Consequences
+
+- One generator controls naming and destination for all of its current and future result nodes.
+- Multiple legacy save nodes with different settings cannot all be represented; migration deterministically uses the first connected save node.
+- Existing node IDs, image ports, and the first nineteen generator widget positions remain unchanged.
+- Save-node preview and retry behavior remains independent from save configuration.
+- GPT provider format and Banana local conversion have separate controls and cannot accidentally override one another.
+
+## Alternatives considered
+
+- Keep configuration duplicated on every save node. Rejected because it conflicts with generator-wide settings and obscures provider capabilities.
+- Keep only `filename_prefix` on the save node. Rejected because the default custom naming rule would then be split across two nodes.
+- Rename the serialized `自定义前缀` value to `自定义`. Rejected because the visible label can change without breaking saved workflows or backend validation.
+
+## Validation
+
+- `tests/test_o1key_image_generator.py` verifies schema positions, defaults, tensor-carried settings, GPT lowercase `jpeg`, and the parameter-free save node.
+- `tests/test_o1key_image_jobs.py` verifies immutable job save settings and GPT's forced local `原始` behavior.
+- `tests/test_o1key_image_generator_frontend.mjs` verifies model-dependent visibility, temp promotion settings, zero-widget result nodes, and idempotent cross-node migration.
@@ -0,0 +1,36 @@
+# 0004: Native-recoverable image workflow metadata
+
+- Status: Accepted
+- Date: 2026-09-04
+- Owners: Maintainers
+
+## Context
+
+`O1keyImageSave` already serialized ComfyUI's `prompt` and `extra_pnginfo`, but original JPEG provider results were kept as JPEG and stored those values in EXIF. The current ComfyUI frontend restores embedded workflows from PNG and WebP only; its file metadata parser has no JPEG workflow branch. Large workflows can also exceed JPEG's APP1 segment length, causing the EXIF payload to be omitted even though the image itself still saves.
+
+Panel-triggered generation bypasses the native prompt executor. It previously obtained the API prompt from `app.graphToPrompt()` but serialized the workflow through a separate `graph.serialize()` call, allowing the two metadata values to describe different graph snapshots.
+
+## Decision
+
+Use ComfyUI's native `SaveImage` field names and PNG container behavior for every JPEG target that carries a workflow. Store the API prompt as PNG text key `prompt` and the serialized graph as PNG text key `workflow`. This conversion applies to original JPEG provider bytes and to an explicit JPEG save choice. It is skipped when ComfyUI's global metadata setting disables metadata or when no workflow is present.
+
+PNG and WebP sources retain their existing metadata paths. Panel saves take both `output` and `workflow` from one `app.graphToPrompt()` result, with direct graph serialization retained only as a compatibility fallback for older frontends.
+
+## Consequences
+
+- Saved o1key output images can be loaded or dragged into ComfyUI to restore their workflow using the native parser.
+- Workflow-bearing JPEG requests produce a `.png` permanent artifact, so recoverability takes precedence over preserving the requested JPEG container.
+- Large workflow JSON is no longer constrained by JPEG APP1 length.
+- JPEG bytes remain untouched when no workflow metadata is being written.
+- Existing JPEG files that were saved without readable workflow metadata cannot be repaired retroactively.
+
+## Alternatives considered
+
+- Add a custom JPEG workflow parser to the frontend. Rejected because it would create an o1key-only recovery path and would still require nonstandard chunking for large metadata.
+- Keep JPEG and silently omit oversized EXIF. Rejected because the saved image appears successful but cannot restore its workflow.
+- Convert every result format to PNG. Rejected because ComfyUI already restores WebP metadata and non-workflow saves should keep their requested container.
+
+## Validation
+
+- `tests/test_o1key_image_save.py` verifies that a JPEG carrying a workflow larger than 64 KiB becomes PNG with complete native `prompt` and `workflow` fields, while a metadata-free JPEG retains its exact provider bytes.
+- `tests/test_o1key_image_generator_frontend.mjs` verifies that panel save metadata uses the prompt and workflow returned by one `app.graphToPrompt()` call without invoking the fallback serializer.
@@ -0,0 +1,35 @@
+# 0005: Persistent image-job history summaries
+
+- Status: Accepted
+- Date: 2026-09-04
+- Owners: Maintainers
+
+## Context
+
+Panel-triggered o1key image jobs do not pass through ComfyUI's native prompt executor. Their native task-queue rows are virtual records assembled by the frontend from the process-local `ParallelImageJobManager`. Restarting ComfyUI clears both that manager and the browser bridge, so completed o1key rows disappear even though their saved images remain.
+
+Output-directory scanning cannot rebuild a complete history: users may choose custom prefixes, natural-number naming, subfolders, or absolute destinations. Persisting entire job snapshots would retain prompts and manifests that the history UI does not need.
+
+## Decision
+
+Persist at most 200 terminal job summaries in `<ComfyUI user directory>/o1key/image_job_history.json` using atomic replacement. A summary contains only batch and node IDs, terminal state, counts, millisecond timestamps, bounded error/warning fields, failed request indexes, and sanitized ComfyUI image descriptors.
+
+Expose the summaries through `GET /o1key/image/jobs/history`. The frontend loads up to 64 recent records before returning its first merged native history page. `POST /o1key/image/jobs/history` synchronizes single deletion and clear-history actions. History write failures are non-fatal to generation and image saving.
+
+## Consequences
+
+- Completed, failed, and cancelled o1key rows survive ComfyUI and browser restarts.
+- History remains available independently of the currently loaded workflow and output naming rule.
+- Prompts, reference manifests, provider bodies, absolute paths, credentials, Base64 data, and signed URLs are intentionally unrecoverable from the history index.
+- Existing rows created before this decision cannot be reconstructed reliably and begin appearing only after the first new terminal job is indexed.
+
+## Alternatives considered
+
+- Scan output filenames at startup. Rejected because supported naming and destination choices do not preserve batch identity.
+- Persist complete `JobRecord` objects. Rejected because prompts, manifests, and transient execution data exceed the history UI's needs and security boundary.
+- Store only in browser local storage. Rejected because it is browser-profile-specific and does not survive browser data clearing or serve multiple connected clients consistently.
+
+## Validation
+
+- `tests/test_o1key_image_jobs.py` recreates the store from disk, verifies terminal manager persistence, and checks that prompt, Base64, and signed URL fields are absent.
+- `tests/test_o1key_image_generator_frontend.mjs` verifies first-page hydration into native history and independent concurrent retry-batch lifetime.
@@ -0,0 +1,46 @@
+# 0006: Grok Video API and workflow migration
+
+- Status: Accepted
+- Date: 2026-09-05
+- Owners: Maintainers
+
+## Context
+
+The released `O1keyGrokVideo` node used the legacy `/v1/videos` API, retired model names, and a positional widget layout containing a per-node network route. The current O1Key Grok Video API has separate generation, edit, and extension endpoints, new model identifiers, different duration and resolution limits, and one shared task-status endpoint.
+
+ComfyUI stores widget values by position. Replacing the schema without migrating `widgets_values` would assign old prompts, models, durations, and resolutions to the wrong controls. Renaming the optional reference-image sockets would also make old connections harder to restore reliably.
+
+## Decision
+
+- Keep the released `O1keyGrokVideo` node ID and the existing `VIDEO` output position.
+- Use `O1keyGrokVideo` for text, image, and multi-reference generation, and `O1keyGrokVideoEdit` for edit and extension operations.
+- Keep API transport, payload validation, polling, and response parsing in `clients/grok_video_client.py`.
+- Validate all user-controlled parameters before temporary uploads or paid generation calls.
+- Migrate legacy generation workflows before ComfyUI maps positional widget values:
+  - remove the legacy per-node network route through the shared route migration;
+  - map `grok-imagine-video-1.5-preview` to `grok-imagine-video-1.5`;
+  - map `grok-imagine-1.0-video` to `grok-imagine-video`;
+  - infer multi-reference mode when a legacy reference-image socket is connected, otherwise use text mode;
+  - rename `参考图1` through `参考图7` sockets to `图片1` through `图片7`;
+  - clamp legacy durations above the new API maximum to 15 seconds;
+  - append new controls rather than shifting values in workflows already saved with the intermediate schema.
+- Never write temporary upload or result URLs to logs or workflows.
+
+## Consequences
+
+Existing workflow node IDs and output links remain valid, while old parameter values are converted to the new API contract. A legacy 16- or 20-second selection becomes 15 seconds because the replacement generation API has a hard 1–15 second range.
+
+The frontend migration remains required runtime code as long as pre-migration workflows are supported. Future Grok widget additions must remain append-only or include another idempotent migration and regression test.
+
+## Alternatives considered
+
+- Register entirely new node IDs and leave the old node untouched. Rejected because it would strand saved workflows on an obsolete API.
+- Reinterpret old widget arrays in backend execution only. Rejected because ComfyUI assigns widget values before execution, so the visible controls and saved values would still be corrupted.
+- Preserve retired model names as aliases in the node dropdown. Rejected because those identifiers are not valid for the current endpoints and would allow avoidable failed requests.
+
+## Validation
+
+- `tests/test_grok_video.py` protects payload construction, capability limits, schema defaults, media locators, edit duration preflight, and secret-safe error formatting.
+- `tests/test_o1key_image_generator_frontend.mjs` protects legacy Grok widget and socket migration, including idempotency.
+- `tests/test_temp_media_uploads.py` verifies that temporary upload URLs are returned to callers without being printed.
+- `tests/run_all.py`, compile checks, and the package import smoke test validate the bundled Windows environment.
@@ -0,0 +1,33 @@
+# 0007: Panel-driven independent video jobs
+
+- Status: Superseded by [ADR 0008](0008-native-video-save-outputs.md)
+- Date: 2026-09-07
+- Owners: Maintainers
+
+## Context
+
+Video generation is asynchronous and long-running. The unified video node must support repeated clicks that run independently, while saved workflows still need a durable node that can preview a completed artifact and feed native ComfyUI video consumers. The user explicitly does not want these generation requests represented by ComfyUI's native queue.
+
+## Decision
+
+`O1keyVideoGenerator` is a panel-only V3 node with no outputs and a side-effect-free native `execute`. Every click creates an `O1keyVideoResult` node and submits an independent server-side job through `/o1key/video/jobs`. Every accepted job starts immediately; the plugin does not impose a semaphore, concurrency ceiling, or internal waiting slot on video-job scheduling. A job may still bound its own prerequisite media preparation. Provider-side quotas and rate limits remain authoritative.
+
+The result node stores only safe ComfyUI file descriptors and bounded status/request metadata. Once a job completes, its native execution resolves the already-downloaded file and emits `VIDEO` plus optional `LAST_FRAME`; it cannot initiate or retry generation. Existing released video nodes and their mapping keys remain registered unchanged.
+
+For Seedance automatic mode, both domestic and overseas routes use the same material-service boundary as `SeedanceElementCreate`; the route selects the Doubao or HC namespace. Material preparation is bounded to three concurrent items without limiting independent video jobs. Safe resolved IDs and content fingerprints may be persisted so retries and repeated content reuse existing Active material, but temporary upload URLs and local paths may not be persisted.
+
+Prompt assistance is a separate, non-job operation at `/o1key/video/prompt-write`. It uses a dedicated video default preset rather than the image preset. Only sanitized input-image descriptors and scalar generation context cross the browser/server boundary; reference video and audio are represented by counts, not media payloads. This operation does not create a result node or enter either job system.
+
+## Consequences
+
+Repeated submissions remain available while earlier videos run, and every job has its own visible result node, status, cancellation, and retry lifecycle. Native queue controls do not display or control these jobs. A burst of clicks can therefore create the same number of simultaneous provider requests and may encounter upstream rate limits. Cancelling after provider acceptance cannot retract the remote request. New providers must be added through the shared catalog/job adapter boundary rather than by adding paid work to the generator node's `execute` method.
+
+## Alternatives considered
+
+- Represent jobs in ComfyUI's native queue: rejected because it conflicts with the required click-driven independent workflow.
+- Return `VIDEO` directly from the generator: rejected because native execution would either duplicate paid work or require a blocking queue run.
+- Reuse one result node for all clicks: rejected because concurrent completions could overwrite one another and obscure per-request state.
+
+## Validation
+
+`tests/test_o1key_video_generator.py` verifies the side-effect-free schema, Seedance matrix and validation, request-body roles, safe descriptors, and immediate unbounded independent execution. `tests/test_o1key_video_generator_frontend.mjs` verifies one-result-per-click wiring, the jobs API/event bridge, repeated-submit behavior, and absence of native queue submission calls.
@@ -0,0 +1,30 @@
+# 0008: Native save nodes for panel video outputs
+
+- Status: Accepted
+- Date: 2026-09-12
+- Owners: Maintainers
+- Supersedes: [ADR 0007](0007-panel-driven-video-jobs.md) for result presentation
+
+## Context
+
+The dedicated `O1keyVideoResult` made every panel submission visible and recoverable, but duplicated capabilities already provided by ComfyUI's native save nodes and occupied a large result card. Users expect the generator's outputs to be visible through ordinary graph connections. Saved workflows containing the released result node must remain loadable, and native graph execution must never submit a second paid generation request.
+
+## Decision
+
+`O1keyVideoGenerator` exposes `VIDEO` followed by `LAST_FRAME`. Every panel submission creates and connects one native `SaveVideo`; it additionally creates and connects one native `SaveImage` when the submitted `return_last_frame` value is enabled. The independent background job keeps saving the provider result atomically, then dispatches its safe file descriptor to the exact native save node for preview. Batch identity, generator association, terminal state, and safe descriptors are stored on the native node so workflow reload can restore completed previews or resume polling unfinished jobs.
+
+The generator's appended result-manifest widgets allow native execution to resolve the latest completed local video and image without contacting the provider. `O1keyVideoResult` remains registered and executable as a deprecated compatibility node for existing workflows, but the frontend no longer creates it.
+
+## Consequences
+
+New jobs use familiar native save nodes and visible typed connections. Returning a last frame produces two clearly separated native outputs. Repeated clicks remain independent and may create multiple save-node pairs. The panel job has already persisted the artifact before its preview is dispatched, so executing a native save node again is unnecessary and may create another copy of the generator's latest completed output.
+
+## Alternatives considered
+
+- Remove the released result-node registration: rejected because saved workflows would fail to load.
+- Route paid video generation through ComfyUI's native queue: rejected because it would remove immediate independent submissions and risk duplicate provider calls.
+- Reuse one native save node across every click: rejected because concurrent jobs would overwrite each other's visible result association.
+
+## Validation
+
+`tests/test_o1key_video_generator.py` verifies append-only manifest inputs, typed generator outputs, side-effect-free local resolution, and deprecated result compatibility. `tests/test_o1key_video_generator_frontend.mjs` verifies native node creation, conditional last-frame saving, typed connections, descriptor dispatch, recovery, and the absence of new `O1keyVideoResult` creation or native queue submission.
@@ -0,0 +1,25 @@
+# 0009: Remove the unified image generator's external prompt input
+
+- Status: Accepted
+- Date: 2026-09-24
+- Owners: Maintainers
+
+## Context
+
+`O1keyImageGenerator` offered both an in-panel prompt editor and a separate `external_prompt` STRING socket. The socket added a second prompt source, changed panel behavior when connected, and required a separate execution path when the panel button was used. The requested node interaction uses the in-panel editor only.
+
+## Decision
+
+Keep the serialized `prompt` widget and its existing index. Remove `external_prompt` from the V3 schema, execution signature, and frontend panel behavior. On workflow load, remove an old `external_prompt` input and its specific graph link while retaining the saved in-panel prompt and unrelated links.
+
+## Consequences
+
+Older workflows that relied on an upstream STRING value must place their prompt text in the panel. The upstream node remains in the graph, and any other connections from it remain intact. Standard ComfyUI execution and panel jobs now read the same prompt widget.
+
+## Alternatives considered
+
+Hiding the socket while retaining the backend override would leave an invisible second prompt source in saved workflows. Keeping the socket solely for old workflows would preserve the interaction the user requested to remove.
+
+## Validation
+
+The image generator schema and execution tests verify the single prompt source. Frontend tests verify empty-prompt validation and idempotent removal of old socket links while preserving unrelated graph links.
@@ -0,0 +1,23 @@
+# 0010: Sync unified GPT Image controls and remove moderation
+
+- Status: Accepted
+- Date: 2026-09-24
+- Owners: Maintainers
+
+## Context
+
+The standalone GPT Image node supports two additional GPT Image 2.5 quality levels and counts 1–8. The unified panel used four quality levels, counts 1/2/4/9, and exposed moderation after the background control. Removing a middle widget would otherwise shift saved batch and save settings.
+
+## Decision
+
+`O1keyImageGenerator` uses the standalone GPT Image quality resolver for GPT Image 2 and 2.5. The panel offers counts 1–8 for GPT models and retains the older 9-image value when loading a saved workflow. New GPT panel selections default to PNG and smart resize; existing saved output and resize values remain intact. Other model families keep their count and default behavior.
+
+The unified generator no longer exposes or submits `内容审查强度` / `moderation`. Its old positional widget at index 14 is removed after the existing old-layout migrations finish, preserving batch and save widget values at their new positions. Legacy panel job payloads that contain `moderation` are ignored. The provider client retains optional low-level support for callers outside the unified node.
+
+## Compatibility
+
+The node ID, earlier widget positions, model-to-route mapping, and provider request scheduler stay stable. The workflow migration is idempotent for both old 24-value arrays and new 23-value arrays. GPT Image continues to send one provider request per selected output image with `n=1`.
+
+## Validation
+
+Offline node, job, standalone GPT, and frontend tests cover quality conversion, count options, omission of moderation, and the saved-workflow migration.
@@ -0,0 +1,21 @@
+# 0011: Remove Nano Banana prompt optimization and batch colour correction
+
+- Status: Accepted
+- Date: 2026-09-24
+- Owners: Maintainers
+
+## Context
+
+The standalone and batch Nano Banana nodes added a browser-side prompt optimization button. The batch node also offered optional colour correction after generation. The batch control was the last serialized widget, so removing it requires migration for saved workflows.
+
+## Decision
+
+Remove the Nano-specific prompt optimization extension and the batch node's colour correction input and post-processing. Keep the unified image generator's `AI帮写` action and the GPT Image batch node's colour correction behavior.
+
+## Compatibility
+
+`migrateWorkflow.js` removes the retired batch correction value before ComfyUI configures widgets. It then adds the `不缩放` default only when an old workflow lacks a resize value. Running the migration twice leaves the same values. Existing batch image quality, naming, and resize values stay in place.
+
+## Validation
+
+Node schema and execution tests cover the absent correction input and unchanged generated image. Frontend tests cover removed extension and old batch workflow values with both default and smart resize.
@@ -0,0 +1,21 @@
+# 0012: Place batch Nano Banana save settings and seed last
+
+- Status: Accepted
+- Date: 2026-09-24
+- Owners: Maintainers
+
+## Context
+
+The batch Nano Banana node displayed seed before file-save controls and displayed resize after them. Saved workflows serialize these widgets by position, so changing their order without migration would assign the old values to the wrong inputs.
+
+## Decision
+
+Place resize after the dynamic reference inputs, followed by output format, quality, naming rule, and save path. Place seed last. Keep all input IDs, defaults, and execution behavior.
+
+## Compatibility
+
+The frontend first applies earlier colour-correction removal, missing-resize defaults, and string-quality conversion. It then recognizes the old six-value tail and rewrites it into the new order. The new tail is not changed on later loads. The rule uses the tail pattern so the number of dynamic folder paths does not matter.
+
+## Validation
+
+Schema and frontend tests cover final widget order, old workflows without resize, saved string quality, smart resize, three folder paths, preserved save settings, and repeat migration.
@@ -0,0 +1,21 @@
+# 0013: Remove batch Nano Banana random image selection
+
+- Status: Accepted
+- Date: 2026-09-24
+- Owners: Maintainers
+
+## Context
+
+The batch Nano Banana path selector exposed `图片随机抽取`. A selected path became a random image pool instead of participating in ordinary image pairing. Removing the control changes both serialized dynamic widgets and task assembly.
+
+## Decision
+
+Remove the random-selection widget and its pool-loading and image-draw logic. All filled folder paths now participate in the selected pairing mode. Keep the node ID, path selector, pairing choices, fixed references, save controls, and seed.
+
+## Compatibility
+
+The frontend drops the former widget value after applying older layout migrations. It removes a connected random-selection input and its graph link and shifts later target slot indices. API workflows that still send the retired value have it ignored. An old workflow with multiple paths and `不配对` must select a pairing mode before running; the node reports this rather than silently choosing one.
+
+## Validation
+
+Offline node tests cover schema and execution forwarding. Frontend tests cover saved one-path and multi-path widget arrays, idempotence, and connected-input link cleanup.
@@ -0,0 +1,25 @@
+# 0014: Publish the current code as a new release baseline
+
+- Status: Accepted
+- Date: 2026-09-24
+- Owners: Maintainers
+
+## Context
+
+The public Gitea release tree still reflects the older GitHub package. The maintainer requested that the current working code replace it as the new published baseline. The current registry contains 39 node IDs, while the previous release contains 37. Twelve old IDs have no implementation in the current code.
+
+## Decision
+
+Publish the current worktree as a new commit on top of the existing Gitea `main` history. Keep the current node registry and do not restore retired implementations solely for this release. The retired IDs are `KlingVideo`, `KlingFirstLastFrame`, `KlingMotionControlTest`, `AspectRatioPreset`, `Seedance`, `KVideoFirstLast`, `KVideoImage2Video`, `K3VideoFirstLast`, `K3MotionVideoCheck`, `NanoBananaV2`, `NanoBananaV2Batch`, and `O1keyColorRemoveBG`.
+
+## Consequences
+
+Saved workflows containing those retired IDs will report missing nodes. Users should keep a copy of such workflows and either use the previous release in a separate installation or replace the missing nodes manually. Existing IDs retained in the new registry remain unchanged; migrations for their widget changes remain in `web/js/migrateWorkflow.js`. Later releases should not remove additional published IDs without a separate compatibility decision.
+
+## Alternatives considered
+
+Restoring all retired providers and nodes would reintroduce code the current package intentionally removed. A semantic mapping from those IDs to newer nodes is not established, so an automatic migration could silently change workflow behavior.
+
+## Validation
+
+Compare the old and new `NODE_CLASS_MAPPINGS` keys, run the offline tests, compile the Python files, and import the package in the bundled ComfyUI environment before publication.
@@ -0,0 +1,28 @@
+# Architecture decision records
+
+Use ADRs for decisions that constrain future changes: node ID compatibility, package boundaries, frontend loading strategy, persistent storage, dependencies, and supported migration paths.
+
+## Process
+
+1. Copy `0000-template.md` to the next available four-digit number.
+2. Use a short kebab-case title, for example `0002-split-server-routes.md`.
+3. Set status to `Proposed` while discussion is open.
+4. Change status to `Accepted`, `Superseded`, or `Rejected` when decided.
+5. Link superseding ADRs in both directions; do not rewrite old decisions as if history changed.
+
+## Current decisions
+
+- [0001: AI-native repository guidance and documentation](0001-ai-native-repository-guidance.md)
+- [0002: Save-node ownership of generated image formats](0002-save-node-image-format-ownership.md)
+- [0003: Generator-owned image save configuration](0003-generator-owned-image-save-configuration.md)
+- [0004: Native-recoverable image workflow metadata](0004-native-recoverable-image-workflow-metadata.md)
+- [0005: Persistent image-job history summaries](0005-persistent-image-job-history-summaries.md)
+- [0006: Grok Video API and workflow migration](0006-grok-video-api-and-workflow-migration.md)
+- [0007: Panel-driven independent video jobs](0007-panel-driven-video-jobs.md)
+- [0008: Native save nodes for panel video outputs](0008-native-video-save-outputs.md)
+- [0009: Remove the unified image generator's external prompt input](0009-remove-unified-image-external-prompt.md)
+- [0010: Sync unified GPT Image controls and remove moderation](0010-unified-gpt-parameters-and-moderation-removal.md)
+- [0011: Remove Nano Banana prompt optimization and batch colour correction](0011-remove-nano-prompt-optimization-and-colour-correction.md)
+- [0012: Place batch Nano Banana save settings and seed last](0012-batch-nano-save-and-seed-widget-order.md)
+- [0013: Remove batch Nano Banana random image selection](0013-remove-batch-nano-random-image-selection.md)
+- [0014: Publish the current code as a new release baseline](0014-new-release-code-baseline.md)