comfyui-ts-nodes-vizard

TS Nodes Wizard

TS Nodes Wizard — встроенный русскоязычный справочник по нодам ComfyUI. Расширение добавляет пункт «Открыть в TS Nodes Wizard» в контекстное меню ноды и показывает связанную с ней статью: назначение, входы и выходы, практические замечания, примеры и готовые фрагменты workflow.

Сейчас это alpha-версия 0.1.0-alpha.1. Каталог покрывает все 601 серверную ноду для локальной работы из зафиксированной чистой установки ComfyUI 0.32.0, а также четыре системные frontend-only ноды. API-ноды временно исключены из редакционного охвата. Статьи и рецепты имеют статус in_review: техническая и языковая проверка выполнена, но человеческое утверждение и полное исполнение примеров остаются релизными условиями.

Как устроен проект

Расширение работает на стороне браузера. Python-файл регистрирует каталог web в ComfyUI, но не добавляет исполняемых нод и не участвует в обработке workflow.

• ui/src/ — React/TypeScript-интерфейс, интеграция с меню ComfyUI, поиск и просмотр статей.
• content/ — редактируемые статьи, реестр идентификаторов и зафиксированные снимки метаданных ComfyUI.
• tools/catalog.py — проверка схемы, семантических связей и сборка каталога.
• web/ — готовый браузерный bundle и собранные данные, которые загружает ComfyUI.
• __init__.py — минимальная точка входа с пустым NODE_CLASS_MAPPINGS и WEB_DIRECTORY = "./web".

Связь статьи с нодой строится по устойчивому node_id из реестра ComfyUI, а не по видимому названию или позиции в меню. Алиасы и замены хранятся отдельно: это позволяет отметить переименование, устаревание или преемника, не теряя историю статьи. Снимок /object_info служит входом для инвентаризации, но не считается готовым редакционным материалом.

Совместимость

Базовая версия — ComfyUI >=0.32.0. Клиентская часть опирается на frontend API ComfyUI, поэтому перед релизом её проверяют как минимум на базовой и текущей стабильной версиях. Изменение внутренних API ComfyUI может потребовать адаптера даже без смены Python-контракта.

Расширение не заменяет встроенную документацию ComfyUI и не связано с проектом ComfyUI официально.

Границы alpha

Редакционный реестр содержит 601 статью о серверных нодах для локальной работы и четыре статьи о системных frontend-only нодах. API-ноды не входят в текущую очередь. Каталог ещё не готов к выпуску 1.0: все материалы остаются черновиками до человеческого утверждения, а часть примеров прошла только проверку схемы или безопасные изолированные пробы без моделей.

Фрагмент workflow можно безопасно скопировать или скачать. Вставка в текущий граф одной отменяемой операцией ещё не реализована. Полный workflow открывается только в новой временной вкладке; если совместимый API ComfyUI недоступен, Wizard скачивает JSON и не меняет текущий граф.

Удалённое обновление catalog.json реализовано, но намеренно выключено до настройки реального HTTPS URL и публичного ключа. Установка архивов с локальными ресурсами, полный frontend inventory, автоматический E2E на реальном ComfyUI и матрица платформ остаются условиями следующего релизного этапа. Команда release-gate не позволяет принять нынешний каталог за stable.

Установка

Из исходников

1. Перейдите в каталог ComfyUI/custom_nodes.
2. Клонируйте этот репозиторий в отдельную папку.
3. В корне расширения выполните npm ci и npm run build.
4. Перезапустите ComfyUI и обновите страницу браузера без кеша.

Для пользовательского релиза собранный каталог web должен входить в архив, поэтому Node.js на машине пользователя не требуется. До первой публикации в ComfyUI Registry установка через comfy node install comfyui-ts-nodes-vizard недоступна.

После запуска откройте справочник через меню Extensions или команду TS Nodes Wizard. Для выбранной ноды также доступен пункт «Открыть в TS Nodes Wizard» (Open in TS Nodes Wizard в английском интерфейсе).

Разработка

Нужны Python 3.10+, Node.js 20.19+ и установленный рядом ComfyUI для ручной проверки интеграции.

npm ci
npm run typecheck
npm run test -- --run
python tools/catalog.py ci
npm run build

npm run dev запускает Vite на 127.0.0.1:5173. Сам ComfyUI по умолчанию ожидается на 127.0.0.1:8188; режим разработки использует его модули /scripts/app.js и /scripts/api.js.

Сборка создаёт web/nodes-wizard.js и копирует сгенерированный каталог в web/data. Не редактируйте эти файлы вручную: меняйте исходники в ui/src или content, затем пересобирайте проект.

Обновление статей и инвентаря

Обычная редакторская правка проходит так:

1. Найдите запись по node_id и проверьте, к какой версии и источнику ComfyUI она относится.
2. Измените исходную статью, сохранив сведения об авторе, источнике и лицензии примера.
3. Выполните python tools/catalog.py validate.
4. Обновите собранный каталог командой python tools/catalog.py build.
5. Убедитесь, что повторная сборка не меняет результат: python tools/catalog.py build --check.
6. Проверьте статью в интерфейсе, включая поиск, прямое открытие и состояние «статья не найдена».

Для нового снимка ComfyUI сначала сохраните /object_info как отдельный входной файл. Команда python tools/catalog.py diff --before <старый.json> --after <новый.json> показывает добавленные, удалённые и изменившиеся определения. Она не публикует статьи автоматически: редактор решает, является ли изменение переименованием, заменой или реальным удалением.

Полные правила и чек-лист находятся в CONTRIBUTING.md.

Границы безопасности

• Справочник не должен отправлять workflow, prompts, модели, пути и пользовательские статьи во внешние сервисы.
• Каталог поставляется вместе с расширением. Alpha-механизм обновления остаётся выключенным, пока сопровождающий не задаст URL манифеста и открытый ключ релиза. После настройки текущий клиент проверяет подпись манифеста, размер, SHA-256 и полную схему catalog.json, показывает изменения и применяет файл только после явного согласия пользователя. Обновление архива с локальными ресурсами относится к следующему этапу и пока не включено.
• Markdown считается недоверенным вводом. Рендерер обязан запрещать исполняемый HTML, javascript:-ссылки и небезопасные URL.
• Примеры workflow — данные для просмотра или явного импорта, а не команды. Расширение не загружает модели и не запускает очередь само.
• Снимки /object_info могут раскрывать названия установленных custom nodes. Не добавляйте в репозиторий приватный инвентарь без проверки.

Порядок сообщения об уязвимостях описан в SECURITY.md.

Лицензии

Исходный код распространяется по GNU GPL v3. Редакционные статьи, схемы, собственные примеры и прочий материал каталога — по CC BY-SA 4.0, если рядом с конкретным материалом не указана другая лицензия. Сторонние названия, цитаты, изображения и workflow сохраняют права своих авторов; одной ссылки на источник недостаточно, если лицензия не разрешает повторное использование.

Метаданные Registry настроены для издателя timesaver. Публикация выполняется workflow Publish to ComfyUI Registry: вручную либо по тегу, который точно совпадает с версией из pyproject.toml (v0.1.0-alpha.1 для текущей версии). Перед отправкой workflow повторяет проверки каталога, упаковки и frontend. Для публикации владелец репозитория должен добавить отдельный ключ ComfyUI Registry в GitHub Actions secret REGISTRY_ACCESS_TOKEN.