ba39cb3658
* refactor(nodes): drop keyframe_batch alias from Easy Image Batch The keyframe_batch input was a deprecated alias of keyframes_insert, added in 0.4.1 during PR #246 review to keep pre-rename workflows loading. The old name only ever existed in unreleased dev builds before the rename, so no published workflow depends on it and the alias only cluttered the node with a second IMAGE input. Remove the input, its parameter, and the alias-routing fallback; the node now exposes a single keyframes_insert insert input. Tests and the behavior spec updated; CHANGELOG notes the removal under [Unreleased]. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs(policy): make backward compatibility opt-in for Koolook nodes Invert the default: backward compatibility is no longer a standing constraint for Koolook-created nodes (the root k_*.py custom nodes). By default, make the cleanest change — rename/drop/reorder IDs, inputs, and outputs freely, no deprecation aliases or _v2 suffixes. Compatibility with saved workflows is only preserved when the maintainer explicitly says "check backward compatibility". Forks are explicitly excluded: anything under forks/ (including the Koolook-original nodes exposed via SKIP_VERSION_SUFFIX) keeps full back-compat discipline by default, no request needed. The __koolook_vX_Y_Z collision suffix always applies. Scoped across the binding instruction files and skills: CLAUDE.md, copilot-instructions, node-versioning.md, versioning.md, and the preflight-release / add-external-fork / tdd skills. The preflight workflows check is reframed as a drift detector for Koolook IDs and a hard back-compat gate for fork IDs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * docs: clarify keyframe_batch alias removal * fix: retain keyframe_batch compatibility alias --------- Co-authored-by: AI Machine <ai.machine@x.baconcph.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
80 lines
4.6 KiB
Markdown
80 lines
4.6 KiB
Markdown
# GitHub Copilot — repo orientation
|
|
|
|
Thin pointer. The canonical agent context lives in [`CLAUDE.md`](../CLAUDE.md)
|
|
at the repo root — read that first for source-of-truth conventions, dev-sync
|
|
rules, release rules, fork policy, and trigger phrases. This file only carries
|
|
the high-stability orientation that helps Copilot place a request before it
|
|
follows links.
|
|
|
|
## What this repo is
|
|
|
|
ComfyUI-Koolook is a custom-node pack for ComfyUI. Two shipped surfaces:
|
|
|
|
1. **Kforge Labs sidebar** — the main user-facing experience. A ComfyUI
|
|
sidebar tab that saves favorite nodes, workflows (with subdirectories +
|
|
archive + tags + reusable modules), and full-state snapshots to a
|
|
configurable on-disk library.
|
|
- Front-end entry: [`web/koolook_sidebar.js`](../web/koolook_sidebar.js);
|
|
module bodies under [`web/sidebar/`](../web/sidebar/).
|
|
- Back-end snapshot/preset routes: [`koolook_routes.py`](../koolook_routes.py)
|
|
(registers `/koolook/presets/*` aiohttp routes on ComfyUI's PromptServer).
|
|
- Bundled visual onboarding guide: [`web/guide/index.html`](../web/guide/index.html)
|
|
(also opened in-app via the sidebar's Tools-row Help button).
|
|
|
|
2. **Koolook custom nodes** — Python node classes at the repo root, each
|
|
exposing the standard ComfyUI node contract (`INPUT_TYPES`, `RETURN_TYPES`,
|
|
`RETURN_NAMES`, `FUNCTION`, `CATEGORY`):
|
|
- [`k_easy_wan22_prompt.py`](../k_easy_wan22_prompt.py) → `EasyWan22Prompt`
|
|
(reads [`config.json`](../config.json) at import time — edits to
|
|
`config.json` need a ComfyUI restart).
|
|
- [`k_easy_resize.py`](../k_easy_resize.py) → `EasyResize_Koolook`
|
|
(deprecated alias `EasyResize` still registered for back-compat).
|
|
- [`k_ai_pipeline.py`](../k_ai_pipeline.py) → `EasyAIPipeline` (paired
|
|
with front-end widgets in [`web/ai_pipeline.js`](../web/ai_pipeline.js)).
|
|
- [`k_easy_image_batch.py`](../k_easy_image_batch.py) → `easy_ImageBatch`.
|
|
- [`k_easy_track.py`](../k_easy_track.py) → `KoolookLoadCameraPosesAbsolute`.
|
|
- [`k_video_combine.py`](../k_video_combine.py) → `Easy_VideoCombine`
|
|
(runtime subclass of VHS `VideoCombine`; self-skips if VHS not installed).
|
|
- Radiance VAE wrappers under
|
|
[`forks/radiance_koolook/versions/v2_3_3/`](../forks/radiance_koolook/versions/v2_3_3/)
|
|
→ `Easy_hdr_VAE_encode`, `Easy_hdr_VAE_decode`.
|
|
|
|
[`__init__.py`](../__init__.py) imports each module's `NODE_CLASS_MAPPINGS` /
|
|
`NODE_DISPLAY_NAME_MAPPINGS` and exposes the merged set plus `WEB_DIRECTORY`.
|
|
|
|
## Things that bite if you don't know them
|
|
|
|
- **Backward compatibility is opt-in for Koolook-created nodes only** (the root
|
|
`k_*.py` custom nodes). For those, make the cleanest change by default —
|
|
rename/drop/reorder IDs, inputs, and outputs freely, no aliases or `_v2`
|
|
suffixes — unless the maintainer says `check backward compatibility`.
|
|
**Fork nodes are different: anything under `forks/` keeps full back-compat
|
|
discipline by default** (never rename a fork ID in saved workflows, version
|
|
via new suffix/namespace, keep the `__koolook_vX_Y_Z` collision suffix). See
|
|
[`docs/maintainers/node-versioning.md`](../docs/maintainers/node-versioning.md)
|
|
and [`CLAUDE.md`](../CLAUDE.md) → *Change management*.
|
|
- **Third-party code stays out of MAIN.** Modified fork code lives under
|
|
`forks/<name>/versions/<vX_Y_Z>/`; raw upstream checkouts live in
|
|
`../ComfyUI-Forks/`. See [`forks/README.md`](../forks/README.md) and
|
|
[`forks/THIRD_PARTY.md`](../forks/THIRD_PARTY.md).
|
|
- **`dev-sync` is user-triggered only.** Never run it automatically (e.g.
|
|
after a commit, after a merge, on session end). The maintainer runs
|
|
parallel worktrees and an unsolicited sync overwrites whatever they're
|
|
reviewing in their live ComfyUI. Wait for the explicit phrase. Full rules
|
|
in [`CLAUDE.md`](../CLAUDE.md).
|
|
- **UI work needs visual QA.** See [`AGENTS.md`](../AGENTS.md) — open the
|
|
changed page in a browser, take a screenshot, verify before claiming done.
|
|
- **Three independent version axes** (pack version / fork wrapper version /
|
|
upstream pinned commit) — see [`docs/reference/versioning.md`](../docs/reference/versioning.md)
|
|
before any version bump.
|
|
|
|
## Where to look next
|
|
|
|
- [`CLAUDE.md`](../CLAUDE.md) — full project conventions and protocols
|
|
- [`docs/maintainers/`](../docs/maintainers/) — release procedure, dev-sync
|
|
loop, registry API, sidebar starter preset, workflows-sidebar reference
|
|
- [`docs/reference/`](../docs/reference/) — glossary, versioning model
|
|
- [`docs/user_guide/`](../docs/user_guide/) — per-node end-user docs
|
|
- [`README.md`](../README.md) — public landing page + install
|
|
- [`CHANGELOG.md`](../CHANGELOG.md) — what changed, in detail
|