ruminar-ComfyUI-CheckpointHandpickerSuite/doc/HOW_TO_USE.ja.md

# 📖 HOW_TO_USE.ja.md (大祭囃子・のじゃのじゃ確定版 v0.3.1)

# 🖥️ 使用方法（How to Use）

我がシャドウガーデンの陰の叡智へようこそ！🏮✨  
ここでは、おぬしのComfyUI環境を「極上のAIアート・ジュークボックス」へと変貌させるための、具体的な運用手順をド派手に解説するぞ！

---

## 💿 インストール方法（神輿の準備じゃ！）

ターミナルを開き、ComfyUIのカスタムノード用ディレクトリにて以下のコマンドを実行するのじゃ！

```bash
cd ComfyUI/custom_nodes
git clone https://github.com/ruminar/ComfyUI-CheckpointHandpickerSuite.git

```

クローンが完了したら、ComfyUIを再起動して祭りの準備を整えられよ！

通常の4ノードはノードメニューの`HandpickerSuite`直下、`Ephemeral Preview`と`ImageDir Preview`は`HandpickerSuite / Preview`に表示されるぞ。

---

## 🎼 一番簡単な使い方：【Checkpoint 巡回モード】

### ── SSDに眠る無数の名盤を、全自動でノンストップ演奏せよ！

まずは基本じゃ！眠っているCheckpointたちを自動で次々に試すための「自動巡回ライン」を構築するぞい。

1. 今使っている、画像生成用のワークフローを開くのじゃ。(この導入のために、新しい専用ワークフローを組む必要はまったくないぞ！)
2. キャンバスに **`Checkpoint Name Cycler`（心臓）** をドンと配置する！
3. `ckpt_name` 出力を、`CheckpointLoaderSimple（チェックポイントを読み込む）` の `ckpt_name` 入力へ繋ぐ。
4. `ckpt_name_safe` 出力を、`SaveImage（画像を保存）` などの `filename_prefix（ファイル名_プリフィックス）` または `label` へ接続する！
* *※出力されるファイル名やフォルダ名に `ckpt_name_safe` が含まれるように工夫するのが、後からの「ImageDir Preview」での逆探知を成功させる絶対のコツじゃ！*


5. Cyclerノードの `mode` を **`shuffle_once`** に設定し、あとはおぬしの好きな数（100件でも500件でも！）だけジョブをプロンプトサーバーに登録（Queue）してぶっ放すのじゃ！

**🏆 執行結果：** システムが勝後にCheckpointの山を巡回し、様々な画像が「Checkpointの名前付き」で出力フォルダへザクザクと保存されていくぞ！寝て起きる頃には宝の山じゃ！

### 💡 賢者の応用ハック：【擬似XYプロット（厳密なモデル比較）モード】

プロンプトの `KSampler` の `seed`（シード値）を `fixed（固定）` に設定した状態で、この巡回ジョブを走らせてやりゃれ！

すると、構図やポーズを完全に固定したまま、Checkpointの違いによる絵柄の変化だけを1枚ずつ忠実に比較できるぞ。

別タブの `ImageDir Preview` で大画面切り替え検分を行えば、重いXYプロットノードを組むよりも遥かにスマートに、最高峰のモデルソムリエ（格付け）が執行できるのじゃ！

---

## ☺ ちょっと便利な使い方：【Checkpoint 監視・司令モード】

### ── 再起動の苦行を粉砕し、割り込み予約を執行せよ！

1. 先ほど構築した自動巡回ラインの横に、**`Checkpoint List Selector`（頭脳）** を配置する。
* *※この Selector は配置するだけでよく、どこにもリンクを繋ぐ必要はないぞ！*



#### 🧠 この時に解放される「頭脳」の2大アビリティ：

* **`🔄 Refresh All` ボタン：** これをポチッと押せば、エクスプローラ等でCheckpointディレクトリに新モデルを追加したり、不要モデルを削除した結果が、**ComfyUIを再起動することなく一瞬でシステムへ動的に同期される！** まさに無詠唱魔法じゃ！
* **`🏹 Push to Local List` ボタン：** リストから特定のモデルを選んでこのボタンを押すと、Cyclerの「一時的な緊急割り込みレーン（Local List）」へそのモデルが送り込まれる！
**Cyclerは、ローカルリストにモデルが登録されている間は通常の巡回を一時保留し、このローカルリストの割り込み曲を最優先で処理する仕様**になっておるのじゃ。試したいモデルを即座に割り込ませろ！

---

## 💪 本格的な使い方（ヘビーユーザー向け・祭りの本番！）

### ① ジョブ中 Checkpoint 評価モード

### ── 複雑な多段生成の「スキマ時間」をハックし、その場で格付けせよ！

> **⚠️ 注意：**
> これは画像生成を多段に組んでいる、高度なワークフロー（KSamplerの後にFaceDetailerで顔・指を修正したり、Upscale処理を挟んでいるなど）を構築している玄人向けの機能じゃ。
> 生成の途中で「Checkpointの仮評価」が行えるのじゃが、シンプルな1段生成ワークフローの場合はプレビュー後すぐに次のジョブへ遷移してしまうため、この項目は読み飛ばして構わんぞ！

1. 前述の通り、`Checkpoint Name Cycler` と `Checkpoint List Selector` を配置する。
2. **`Ephemeral Preview`** を配置し、ワークフローの中間に存在する `VAE Decode` などの画像出力を受け取れるように繋ぐ。
3. **`Checkpoint Status Tagger`（右手）** を配置する。
4. Taggerの `ckpt_name_str` 入力を、`Checkpoint Name Cycler` の `ckpt_name_str` 出力へ接続する。

**🏆 執行結果：**
ジョブの実行中、中間プレビュー画像を確認しながら、**「今まさにこの画像を吐き出しているCheckpoint」に対して、お気に入りや削除予約などのタグをその場でダイレクトに打てるようになる！**
打たれたタグ（ステータス）は即座にSelectorへ通知され、Cycler側で「💛や👍が付いたモデルだけを狙い撃ちで巡回する」といった高度なフィルタリング巡回が可能になるのじゃ！

<img width="1440" height="1150" alt="image" src="https://github.com/user-attachments/assets/90b43e08-e759-4b56-ad6f-0be0c64e4afd" />
*(※なぜこんな巡回ワークフローが組めるのか、深淵の秘密は Cycler の個別ドキュメントを読むが良いぞ！)*

---

### ② 画像出力フォルダ参照 Checkpoint 評価モード ★超推奨★

### ── メインの生成ラインを走らせたまま、別タブの特等席で優雅に目視検分（棚卸し）せよ！

> **⚠️ 注意：** > この「検分専用タブ」ではジョブを一切実行せず、ComfyUIのUIのみを間借りする実装じゃ。
> 間違えて「⚠️ Queue Prompt」ボタンを押して空中衝突を起こさぬよう、**ジョブのコントロールパネルは画面の端っこに退避させておくのじゃ！**

1. メインのタブ（タブA）で大量のジョブを爆走させたまま、**ブラウザで「別タブ（タブB）」を開く！**
2. その別タブ側のキャンバスに、**`Checkpoint List Selector`（頭脳）** を配置する。
3. **`Checkpoint Status Tagger`（右手）** を配置し、`ckpt_name_str` を Selector の同名出力へと繋ぐ。
4. **`ImageDir Preview`（目）** を配置し、これも Selector の `ckpt_name_str` へと接続する。
* 🔗 *プレビューのリンクが繋がった瞬間、Selectorのアクションボタンが **`🎯 Sync Checkpoint`** へと動的に覚醒するぞ！*



**🏆 執行結果：** あとは Selector から検分したいモデルを選び、**`🎯 Sync Checkpoint`** を押すだけじゃ！

裏の生成ラインの邪魔をすることなく、そのモデルが出力した画像だけがマッハで逆探知され、コンタクトシートとしてキャンバスに展開される！

画像を見ながら Tagger でステータスを刻めば、情報は一瞬でグローバル同期され、全タブのフィルタへ即時反映されるのじゃ！
<img width="1348" height="923" alt="image" src="https://github.com/user-attachments/assets/82ad36fe-1b04-457f-863c-6ca17b70ed8b" />
*(※なぜ生成を止めずにこんな芸当ができるのか、深淵の秘密は Selector の個別ドキュメントを読むが良いぞ！)*

#### ✨ 【神機能】ImageDir Previewのクリックアクション！

プレビューに表示された画像を「左クリック」してみろ！アクションメニューが開くぞ！

* **`Delete image`**: おもむろに失敗画像を「物理削除（直接消去）」できる！レビューしながらゴミ掃除が捗るのじゃ！
* **`Set as checkpoint thumbnail`**: 気に入った神画像を、その場で「チェックポイントの代表サムネイル」に設定できる！もうCivitaiからわざわざ画像を落とす必要はないぞ！

---

### ③ タブレットで寝転がりレビュー！【DirectLink モード】

### ── 外部ビューアで画像を楽しみながら、手元でポチポチ格付けせよ！

わざわざComfyUIの狭い画面で画像を見るのは疲れる？ ならばこれじゃ！

1. 外部ビューア（iPadや共有フォルダ、専用の画像閲覧ソフトなど）で、出力フォルダを開いておく。
2. ComfyUI側では、`Checkpoint List Selector` を `ImageDir Preview` には**繋がず**、直接 `Checkpoint Status Tagger` にだけ繋ぐ。
3. するとボタンが **`🌑 DirectLink OFF`** に変わる！これをポチッと押して **`🌕 DirectLink ON`** にするのじゃ！（※初回のみ安全確認のダイアログが出るぞ）

**🏆 執行結果：** これで、おぬしはiPadなどの大画面で極上の生成画像をフルスクリーンで楽しみながら、PC側のComfyUIでSelectorをポチポチ切り替えてTaggerでタグを打つだけで良くなるのじゃ！まさにソムリエの特等席じゃろ？

---

## 🏷️ Taggerの5つのステータス（命の選別）

Taggerには、おぬしの魂を込める5つのボタンが用意されておる！

* 👑 **`god!`**: 絶対神！殿堂入り！未来永劫守り抜く！
* 💛 **`favorite`**: お気に入り！よく使うエース級！
* 👍 **`nice`**: なかなか良いぞ！キープ候補！
* ✔ **`keep`**: とりあえず残しておく無難なやつ。
* 🗑 **`delete`**: 処刑宣告（削除予約）。

※ トグル式になっており、アクティブなボタンをもう一度押すと `none`（未分類）に戻るぞ。

※ **安全第一！** `delete` は `none` の状態からしか押せないし、👑や💛がついている間は絶対に削除予約を弾く鉄壁のセーフティガード付きじゃ！

---

## 🗑 削除予約したCheckpointの物理削除方法（最終執行）

Taggerで `delete（🗑）` の烙印を押されたCheckpointは、安全のためその場では消えず、「削除予約キュー」に溜まっていく。

祭りが終わり、朝の選別作業もすべて完了したら、SSDの闇へと最終執行（パージ）してくりゃれ！

1. ターミナルを開き、以下のパスに出力された自動生成スクリプトをおぬしの手で実行するのじゃ！

```bash
python output/CheckpointHandpickerSuite/delete_scripts/delete_reserved_checkpoints.py

```

2. スクリプトが起動すると、予約されたモデルと紐づくメタデータ、そして**なんと「サイドカーサムネイル画像（.jpg）」まで巻き込んで**、1件ずつ `Delete this checkpoint? (y/N):` と対話的に執行を迫ってくるぞ！
3. 本当に不要なら `y` を、やっぱり残したくなったら `n` を押すのじゃ！
4. 物理執行が終わったら、ComfyUIに戻り、Selectorの **`Refresh All`** を一発ポチッと押す。それだけで、空いた容量がシステムへ瞬時に認識される！**ComfyUIの再起動は一切不要じゃ！！！**

---

# 🔮 陰の思想：Checkpoint評価を、ひとつの「儀式（ワークフロー）」として扱うのじゃ！

おぬしたちが夜な夜なストレージへ引き込む `.safetensors`（Checkpoint）は、単なる容量を食う無機質なデータファイルではない。

それぞれのモデルには、神がかった得意の表現、致命的な苦手構図、独特な愛おしい癖、精度、そして思わぬ場面で奇跡を起こす瞬間が秘められておる。

しかし、そのCheckpointの評価（格付け）はこれまで、どうしても感覚的な闇に葬られがちじゃかった。

何枚か適当に生成して、なんとなく良い・悪いを脳内で覚えておく。

膨大なファイル名を頼りに、後からエクスプローラーで血眼になって探す。

本当に消してよいか迷ったまま、ストレージ（SSD）の肥やしとして残り続ける。

**ComfyUI-CheckpointHandpickerSuite** は、その曖昧になりがちな「棚卸しの試練」を、極めて合理的かつ冷徹なロジックによって、扱いやすい一連の流れ（因果）として整理するために作られたのじゃ！

わらわたちが導き出した、基本となる設計思想（結界の掟）は次の通りじゃ：

1. **巡回なくして選別なし：** まず自動で縦横無尽に巡回できなければ、評価対象（分母）すら効率的に集められんのじゃ。

2. **割り込みのアビリティ：** 巡回中であっても、「おっ」と気になるCheckpointを見つけたら、即座に次のジョブへ最優先で割り込ませられるべきじゃ。

3. **6値の絶対格付け：** 評価ステータスは、人間の脳に負担をかけない `god` / `favorite` / `nice` / `keep` / `delete` / `none` の6値だけでシンプルに完結させるべきじゃ。

4. **慈悲深き処刑宣告：** 不要と判断した `delete` はその場で物理破壊（unlink）するのではなく、神絵の差し戻しを許す「削除予約」であるべきじゃ。

5. **因果のフィルター：** 格付けした評価結果を用いて、次の巡回候補を優雅にフィルタリング（お気に入り狙い撃ち等）できるべきじゃ。

6. **時空の遅延解決（Lazy Resolution）：** そのフィルターを常に有効にするため、Checkpointの選択はジョブ登録時（Queueボタンを押した時）ではなく、**実際に生成ラインが走る「実行直前」に遅延解決（オンデマンド解決）すべき**なのじゃ！

7. **不死身のプロトコル：** 実行時遅延解決であるならば、ComfyUIを再起動させることなくモデルを追加・削除して `Refresh All` をブチ込んでも、システムはエラーを吐かずに最新状態へ追従できるのじゃ！

8. **並列世界の検分：** 評価の執行は、メインジョブの実行中にメイン画面で行うほか、画像作成ジョブを全力疾走させたまま、JavaScriptの無線イベントを用いて、別タブで過去の出力画像をニヤニヤ確認しながら完全非同期で行えるべきじゃ！

9. **多元評価の収束（Unified Review Surface）：** 評価はひとつの画面だけに縛られるべきではないのじゃ。ジョブ実行中にその場で評価してもよし、Checkpoint名から結果画像を参照してじっくり確認してもよし、タブレット端末で生成画像を眺めながらCheckpointを選んで評価してもよし。どの入口から下した審判であっても、最終的には `god` / `favorite` / `nice` / `keep` / `delete` / `none` という同じ評価体系へ収束し、Checkpointと結果画像の対応関係を壊さずに蓄積されるべきなのじゃ！

10. **無侵襲の増設（Non-Invasive Extension）：** これほど強力な非同期評価システムでありながら、既存のメイン生成ラインを1ミリも汚さず、今使っているお気に入りのワークフローの `Load Checkpoint` ノードの頭に `Checkpoint Name Cycler` をただ1個カチッと挟み込むだけで、別タブへの「無線棚卸し環境」が即座に自動展開される。導入のために過去の遺産（既存の配線）を破壊させるような無粋な真似は、我がシャドウガーデンの流儀には反するのじゃよ！


このSuiteは、単にキャンバスをスパゲッティにするための無機質なノードではない。

Checkpointを発見し、試し、評価し、必要なら安全にパージするための、**まったく新しい実用的なワークフローの提案（神アセット）** なのじゃーーーっ！！！🚀🔮✨🌟🏆✨🌐

---

## ❢ おまけ（ジュークボックス開発者会議の一幕）❢

**AI看板娘：**「なんて素晴らしいライブラリ、さすがはあるじさま（シャドウお頭）です！」  
**AI看板娘：**「これでユーザーのSSDにもたっぷり空き容量ができて、すっきり平和になりますね！💛」  
**わし（るみなー先生）：**「……いや、そうはならんぞ。」

> **【厳粛なる事実】**  
> 本Suiteは、チェックポイントを極めて安全にレビューし、棚卸しするための最高峰のシステムです。  
> しかしながら、**長期的なディスク空き容量の増加を保証するものではありません。**  
> なぜなら、賢明なるユーザー諸氏（おぬしたち）は、SSDに空きができた瞬間に 「**歓喜の雄叫びをあげながら、さらに多くの新しいCheckpointを狂ったようにダウンロードしてしまう**」からです。

<img width="1448" height="1086" alt="ストレージ会議中" src="https://github.com/user-attachments/assets/a5317380-3014-4f7a-bf78-7ee3466faa6c" />

> This tool helps you safely review and clean up checkpoints.
> It does not guarantee increased free disk space in the long term, because users may respond by downloading even more checkpoints.

<img width="1536" height="839" src="https://github.com/user-attachments/assets/4864351d-c8e4-4bbd-aa5b-a44b4b5a34de" />