vantang-ComfyUI-MediaHub/docs/DEVELOPMENT.md

Development Guide

Scope

The implementation uses provider-specific config nodes and provider-neutral execution nodes. MiniMax CN and Agnes are supported. Agnes Image 2.0 is not supported; Agnes image integration targets Image 2.1 only.

Local Environment

• Repository: /Users/vantang/Projects/02_Study/ComfyUI-MediaHub
• Development symlink: ~/ComfyUI/custom_nodes/ComfyUI-MediaHub
• ComfyUI Python: ~/ComfyUI/.venv/bin/python
• ComfyUI URL: http://127.0.0.1:8000
• ComfyUI log: ~/ComfyUI/user/comfyui_8000.log
• ComfyUI source: /Users/vantang/ComfyUI-Installs/ComfyUI/ComfyUI
• Local API credentials: .api_env (git-ignored)

Changing Python INPUT_TYPES requires a ComfyUI backend restart. Changing js/mediahub.js requires a browser refresh.

Important ComfyUI Serialization Rules

ComfyUI UI workflow JSON stores widget values positionally. Changing widget order or allowing ComfyUI to insert an extra widget can shift all later values.

• Inputs with forceInput: true are not represented in widgets_values.
• Numeric seed widgets create an extra control_after_generate widget unless it is explicitly disabled.
• Do not use widget.hidden; some frontend versions omit hidden widgets during prompt serialization.
• Prefer an API-format test fixture for deterministic prompt validation.
• Keep API smoke fixtures deterministic even when the user-facing node default is random generation.
• A UI workflow sample must be re-imported and queued after widget-contract changes.

Architecture

• mediahub/core/: stable request/job/result contracts, registry, and generic image/video execution services.
• mediahub/providers/minimax_cn/: isolated MiniMax CN adapters.
• mediahub/providers/agnes/: isolated Agnes Image 2.1 and Video 2.0 adapters.
• nodes.py: provider config nodes and provider-neutral execution nodes.
• mediahub/images.py: URL/base64 image loading, tensor conversion, and tensor-to-base64 data URL conversion for I2I subject references.
• js/mediahub.js: provider-local dynamic UI and API-key password widget.
• examples/: UI workflows for every provider/task path.
• tests/fixtures/: deterministic API-format workflows.
• scripts/layout_examples.py: canonical user-input, portable MediaHub integration, and Preview/Save output layout for user-facing examples. API fixtures remain layout-free.
• scripts/probe_agnes.py: explicit paid/live Agnes behavior probe.

Verification Layers

Run all layers after changing node inputs, frontend widgets, or example workflows:

.venv/bin/python -m pytest -q
node --check js/mediahub.js
.venv/bin/python -m compileall -q .
for file in examples/*.json tests/fixtures/*.json; do
  .venv/bin/python -m json.tool "$file" >/dev/null
done

After restarting ComfyUI:

.venv/bin/python scripts/smoke_comfyui.py

The smoke test uses an empty API key. A passing smoke test means ComfyUI accepted the full prompt structure; the queued execution is expected to stop at the empty-key validation without making a paid MiniMax request.

For explicit live provider probes, fill .api_env and run:

.venv/bin/python scripts/probe_agnes.py --image
.venv/bin/python scripts/probe_agnes.py --video

Never print .api_env, include its values in logs, or commit it. Live mode must only run when explicitly requested because it consumes provider credits. Keep the local file permission at 0600.

Completion Criteria

A node/schema change is complete only when:

1. Unit and static checks pass.
2. The live smoke test passes against a restarted backend.
3. The UI example is imported and queues without parameter-validation errors.
4. docs/CURRENT_STATE.md reflects the result and any remaining gap.
5. User-facing workflow layout tests preserve the three-region responsibilities and left-to-right connection flow.