From 6d1b66167d9f08c2f53c9693901fbf4aa9f660b0 Mon Sep 17 00:00:00 2001 From: Egutierrez Date: Wed, 24 Jun 2026 17:10:47 +0200 Subject: [PATCH] docs(comfyui): cerrar doc_orphan comfyui-skill + cobertura Civitai + allowlist naming Aplica los 3 arreglos de orden de la auditoria 0120: - INDEX.md: anade la fila del grupo comfyui-skill (11 fns), cerrando el unico FAIL doc_orphan de fn doctor capabilities. - comfyui-skill.md: documenta las 2 funciones de cosecha Civitai (comfyui_extract_recipe_from_png, comfyui_harvest_civitai_skill_oneshot) en la tabla + seccion 'Cosecha Civitai -> skill candidata'. Cobertura 9/11 -> 11/11. - ids_naming.md: anade save/bump/harvest/judge/critique a la allowlist documentada (espejo del cambio en apps/registry_mcp/naming.go, en su sub-repo). No fn index (solo docs + rule). No renames. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/rules/ids_naming.md | 2 +- docs/capabilities/INDEX.md | 1 + docs/capabilities/comfyui-skill.md | 53 ++++++++++++++++++++++++++++++ 3 files changed, 55 insertions(+), 1 deletion(-) diff --git a/.claude/rules/ids_naming.md b/.claude/rules/ids_naming.md index 1b79f5a8..638ea238 100644 --- a/.claude/rules/ids_naming.md +++ b/.claude/rules/ids_naming.md @@ -13,7 +13,7 @@ IDs: `{name}_{lang}_{domain}` (ej: `filter_slice_go_core`). Predictibilidad alta Lista no exhaustiva pero cubre la mayoria. Anadir aqui (y al validator en `apps/registry_mcp/naming.go`) cuando se introduzca un verbo nuevo recurrente. -`get, set, list, find, search, show, read, load, fetch, scan, query, lookup, parse, format, encode, decode, marshal, unmarshal, serialize, deserialize, validate, check, ensure, verify, audit, diagnose, test, match, filter, map, reduce, sort, group, count, sum, aggregate, compute, calculate, score, rank, cluster, classify, detect, init, create, make, build, generate, scaffold, install, setup, configure, register, add, insert, append, prepend, update, upsert, modify, edit, patch, replace, delete, remove, clear, drop, prune, clean, copy, move, rename, sync, clone, extract, inject, import, export, send, post, put, call, dispatch, exec, run, launch, relaunch, start, stop, kill, restart, reboot, redeploy, deploy, open, close, connect, disconnect, login, logout, authenticate, enable, disable, toggle, lock, unlock, propose, promote, deprecate, approve, reject, emit, render, draw, paint, serve, host, pull, push, checkout, commit, tag, merge, rebase, watch, monitor, observe, log, trace, profile, benchmark, snapshot, backup, restore, archive, compress, decompress, hash, encrypt, decrypt, sign, taskkill, recopile, vault, propose, apply, gather, collect, fold, head, tail, take, drop, slice, chunk, batch, debounce, throttle, retry, await, sleep, ping, kill, prime, warm, refresh, invalidate, reload, reset, rollback, fork, spawn, daemon, observe, plot, draw, capture, replay, recopilate` +`get, set, list, find, search, show, read, load, fetch, scan, query, lookup, parse, format, encode, decode, marshal, unmarshal, serialize, deserialize, validate, check, ensure, verify, audit, diagnose, test, match, filter, map, reduce, sort, group, count, sum, aggregate, compute, calculate, score, rank, cluster, classify, detect, init, create, make, build, generate, scaffold, install, setup, configure, register, add, insert, append, prepend, update, upsert, modify, edit, patch, replace, delete, remove, clear, drop, prune, clean, copy, move, rename, sync, clone, extract, inject, import, export, send, post, put, call, dispatch, exec, run, launch, relaunch, start, stop, kill, restart, reboot, redeploy, deploy, open, close, connect, disconnect, login, logout, authenticate, enable, disable, toggle, lock, unlock, propose, promote, deprecate, approve, reject, emit, render, draw, paint, serve, host, pull, push, checkout, commit, tag, merge, rebase, watch, monitor, observe, log, trace, profile, benchmark, snapshot, backup, restore, archive, compress, decompress, hash, encrypt, decrypt, sign, taskkill, recopile, vault, propose, apply, gather, collect, fold, head, tail, take, drop, slice, chunk, batch, debounce, throttle, retry, await, sleep, ping, kill, prime, warm, refresh, invalidate, reload, reset, rollback, fork, spawn, daemon, observe, plot, draw, capture, replay, recopilate, save, bump, harvest, judge, critique` ### Excepciones diff --git a/docs/capabilities/INDEX.md b/docs/capabilities/INDEX.md index 40595c4e..4421fafd 100644 --- a/docs/capabilities/INDEX.md +++ b/docs/capabilities/INDEX.md @@ -71,6 +71,7 @@ Indice de grupos de capacidades del registry. Cada grupo agrupa >=3 funciones qu | [local-hub](local-hub.md) | 4 | Exponer los procesos locales como subdominios `*.localhost` (via Caddy, sin DNS) y reunirlos en una pantalla principal Glance con estado en vivo, refrescada a diario por dag_engine. Descubre servicios (manifiesto + registry), renderiza Caddyfile + config Glance (puras), y el pipeline `refresh_local_hub` regenera+recarga. Fuente de verdad: `apps/local_hub/local_services.yaml` | | [comfyui-judge](comfyui-judge.md) | 4 | Panel multi-juez de calidad de imagen: estético LAION-V2 (`comfyui_score_aesthetic`, 0-10) + fidelidad CLIP prompt↔imagen (`comfyui_score_clip_alignment`, 0-1) + crítica LLM-vision (`comfyui_critique_image_llm`, good/bad). Agregados por voto mayoría en `comfyui_judge_image`. Gate objetivo para tests/DoD y el bucle de mejora de skills ComfyUI; degrada con gracia si un juez cae. Jueces estético/fidelidad por subproceso al venv ComfyUI (torch+open_clip), crítico via claude-direct | | [comfyui](comfyui.md) | 29 | Controlar ComfyUI (Stable Diffusion por grafos) de dos formas: por API HTTP (build_txt2img_workflow puro → submit → wait → object_info; download_model con validación Civitai/HF) y por la UI web vía CDP sobre la pestaña abierta (load_workflow_ui, set_node_widget_ui para tunear prompt/steps/seed en vivo, queue_prompt_ui = botón Queue Prompt, export_workflow_ui, refresh_nodes_ui). El API format es el puente entre ambos caminos. Las funciones de UI componen `cdp_eval`. Incluye imagen→3D nativo (Hunyuan3D-2, tag `img-to-3d`): build_image_to_3d_workflow + fetch_output_mesh + install_3d_model + pipeline image_to_3d_oneshot | +| [comfyui-skill](comfyui-skill.md) | 11 | Tratar una configuración de generación ComfyUI como una skill: receta versionada en disco (checkpoint + LoRAs + params + scaffold de prompt + post-proceso) que se compila a un workflow cambiando solo el subject. Save/load/list de recetas, bucle de mejora genera→juzga→bump con gate objetivo (el score del juez decide qué se promueve), export de la skill a grafo cargable en el navegador, y cosecha de Civitai (extract_recipe_from_png + harvest oneshot) que destila el workflow embebido de una imagen pública en una skill candidata | ## Como anadir grupo diff --git a/docs/capabilities/comfyui-skill.md b/docs/capabilities/comfyui-skill.md index 2ee3a2eb..b1b8ca1e 100644 --- a/docs/capabilities/comfyui-skill.md +++ b/docs/capabilities/comfyui-skill.md @@ -67,6 +67,8 @@ de texto). `blocks[].type` ∈ {`facedetailer`, `hires_fix`}. | [comfyui_generate_with_skill_oneshot_py_pipelines](../../python/functions/pipelines/comfyui_generate_with_skill_oneshot.md) | `generate_with_skill_oneshot(slug, subject, *, server='127.0.0.1:8188', dest=None, seed=0, judge=True, recipe_patch=None, ...) -> dict` | One-shot del bucle: carga la skill, la compila para el `subject`, encola, espera, descarga el PNG y (si `judge`) lo puntúa con el panel `comfyui-judge`, acumulando el score en la media. `recipe_patch` prueba una variante en memoria sin guardar. | pipeline (impura) | | [comfyui_update_skill_score_py_ml](../../python/functions/ml/comfyui_update_skill_score.md) | `comfyui_update_skill_score(slug, new_score, *, library_dir=None) -> dict` | Acumula el score de un juicio en `score_mean`/`score_n` por media incremental, reescribiendo `recipe.json` en sitio (sin snapshot ni growth_log). | impura | | [comfyui_bump_skill_version_py_ml](../../python/functions/ml/comfyui_bump_skill_version.md) | `comfyui_bump_skill_version(slug, change, *, score_before, score_after, judge_run_id=None, recipe_patch=None, force=False, ...) -> dict` | Promueve una versión nueva **solo si el score sube** (gate objetivo): snapshot `versions/vN.json` + aplica `recipe_patch` + sube el semver + línea en `growth_log`. Gate bloquea si no mejora. | impura | +| [comfyui_extract_recipe_from_png_py_ml](../../python/functions/ml/comfyui_extract_recipe_from_png.md) | `comfyui_extract_recipe_from_png(png_path, *, slug=None, civitai_meta=None, image_url='', nsfw=False) -> dict` | Destila un PNG cosechado de Civitai en una receta de skill **candidata** (`score_n=0`, `provenance.source='civitai'`). Compone `comfyui_import_workflow_png` (workflow API embebido) + `comfyui_read_png_metadata` (params del KSampler); fallback a la `meta` de Civitai. Degradación honesta: `ok=False` sin inventar si no hay ni workflow embebido ni meta utilizable. | impura | +| [comfyui_harvest_civitai_skill_oneshot_py_pipelines](../../python/functions/pipelines/comfyui_harvest_civitai_skill_oneshot.md) | `comfyui_harvest_civitai_skill_oneshot(*, query=None, model_version_id=None, nsfw='None', dest_dir, library_dir='~/ComfyUI/skills_library', ...) -> dict` | One-shot Civitai → skill candidata: `search` → `fetch` (segrega NSFW) → `extract_recipe` → `save_skill`. Itera los items hasta hallar uno con receta destilable (preferentemente workflow embebido), descartando los PNG sin receta; 2º pase al feed global si filtró por modelo. **No baja modelos a ciegas**: los ausentes van a `missing_models`. | pipeline (impura) | `build_skill_workflow` compone los builders del grupo [`comfyui`](comfyui.md): `comfyui_build_txt2img_workflow`, `comfyui_build_flux_workflow`, @@ -201,6 +203,57 @@ hay trabajo sin guardar (título con `*`), respalda antes con `comfyui_export_workflow_ui(api_format=True, save_path=...)` y restáuralo después con `comfyui_load_workflow_ui`. +## Cosecha Civitai → skill candidata + +El registry crece también captando recetas que **ya existen en internet**, no solo escribiéndolas a +mano: doctrina del issue 0087 aplicada a la captación de assets. Cada imagen publicada en Civitai +suele llevar su workflow de ComfyUI embebido en el PNG (chunk `prompt`, API format); cosecharla +destila la receta entera (checkpoint + LoRAs + params + prompt) en una **skill candidata** lista para +juzgar. + +```python +import sys, os +sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions")) +sys.path.insert(0, os.path.join(os.environ["HOME"], "fn_registry", "python", "functions", "pipelines")) +from comfyui_harvest_civitai_skill_oneshot import comfyui_harvest_civitai_skill_oneshot + +res = comfyui_harvest_civitai_skill_oneshot( + query="cinematic portrait", nsfw="None", + dest_dir=os.path.expanduser("~/ComfyUI/civitai_harvest"), +) +print(res["ok"], res["slug"], "workflow_embebido=", res["has_workflow"]) +print("guardada en:", res["skill_path"]) # ~/ComfyUI/skills_library//recipe.json +print("modelos ausentes:", res["missing_models"]) # checkpoints/LoRAs a bajar (NO bajados) +``` + +Dos piezas, una composición: + +- **`comfyui_extract_recipe_from_png`** (paso puro de destilación, impura solo por leer disco) — + toma un PNG ya descargado y produce la receta candidata. Compone + `comfyui_import_workflow_png` (workflow embebido) + `comfyui_read_png_metadata` (params del + KSampler), con fallback a la `meta` de generación de Civitai y, para samplers no-KSampler + (flux/`SamplerCustomAdvanced`), heurística sobre los nodos `CLIPTextEncode`. **Degradación honesta**: + si no hay ni workflow embebido ni meta utilizable devuelve `ok=False` sin inventar la receta. +- **`comfyui_harvest_civitai_skill_oneshot`** (pipeline) — encadena + `search_civitai_images → fetch_civitai_image → extract_recipe_from_png → save_skill` en una sola + llamada. Itera los resultados del search hasta encontrar el primero con receta destilable + (descartando los PNG sin workflow), y si filtró por un modelo concreto y ninguno trae grafo, hace + un 2º pase al feed global "Most Reactions" (donde abundan los workflows ComfyUI de usuarios flux). + +Notas de uso: + +- **La skill nace CANDIDATA** (`score_n=0`, `provenance.source='civitai'`): no está validada. El + prompt cosechado es **concreto**, no un scaffold con `{subject}` — sustitúyelo a mano si quieres + reutilizar la skill para otros sujetos. La validación la da el bucle + `generate_with_skill_oneshot` (juzga) + `comfyui_bump_skill_version` (promueve si mejora). +- **No baja modelos a ciegas**: si la receta referencia un checkpoint o LoRA que no está en + `/models/`, lo lista en `missing_models` y no descarga nada. Bajarlos + (`comfyui_search_civitai_models` + `comfyui_download_model`) es una decisión aparte del caller. +- **NSFW segregado**: el PNG se descarga a `/nsfw/` si el item es NSFW (permitido pero + siempre separado). El `dest_dir` vive fuera del repo (`~/ComfyUI/`) y se trata como datos: no se + commitea ni se indexa. +- El token Civitai es secreto: viene de `pass civitai/api-token`, nunca hardcodeado. + ## Fronteras - **No genera ni descarga modelos**: una skill referencia checkpoints/LoRAs por nombre; deben