character-refs

character-refs

キャラクターの説明を入力すると、キャラクターのリファレンス画像一式を出力します——キャラクターの出どころは問いません：小説の翻案、自作の物語、ふと思いついた人物など。正面全身のアンカー画像を1枚作り、残りの画像はすべてこのアンカーだけを参照します。 動画モデル（H3 / Wan / Seedance）のリファレンス画像としても、人が見る用途としても使えます。

{baseDir} = このファイルがあるディレクトリです。スクリプトは {baseDir}/scripts/character-refs.mjs にあり、依存関係はなく、node で直接実行できます。

**リポジトリ内で実際に画像を生成する唯一の skill です。**ほかの skill はプロンプトだけを出力します。画像を生成するその時になって初めて、モデルと画風を決められるからです。 この skill はまさにその「時」です——モデルは Step 0 でユーザーが選び、画風はキャラクターの作成時に選択します（デフォルトはアニメで、写実的なプリセットもあり、カスタム画風も設定できます）。

コアのルール（よく読んでから作業してください）

• **画像一式の根となるのは1つだけです：正面全身のアンカー画像です。**テキストから画像を生成するのはこの画像だけで、残りはすべて「アンカー + 画像編集指示の一文」です。 髪、顔、襟元の3種類のディテール画像には、確認済みの正面バストアップ画像を追加で使います。画像同士を相互に参照することはありません—— そのため、どれか1枚の出来が悪くても、その画像だけを再生成すればよく、連鎖しません。

• 段階に分け、デフォルトでは第2段階まで生成します：

  段階	内容	生成するタイミング
  1	正面全身（アンカー）	常に、最初の1枚
  2（デフォルト）	正面バストアップ、90°側面（画面の右向き）、背面	デフォルトで全て生成
  3	ディテール画像（最大8枚）：ユーザーが指定した、キャラクターを最も見分けやすくする箇所。指定がなければ、髪／髪飾り、襟元、袖口、靴をデフォルトで使います	アクセサリーや服の一部をクローズアップする場合
  4（デフォルトでは生成しない）	45°バストアップ（画面の左向き）	ユーザーが明確に希望した場合

  H3 での実測：正面全身だけを渡すと、服装と後ろ姿は合っていても、顔が崩れます。バストアップを1枚追加すると、顔が最も近くなります。そのためデフォルトでは第2段階まで全て生成します。 アンカーだけが必要な場合（たとえば、まず見た目を確認したい場合）：gen <asset.json> --tier 1。

• モデルは固定しません：メイン画像と派生画像で異なるモデルを使ってもよく、1枚だけ再生成する際にモデルを変えることもできます。一貫性を保つのは「同じアンカー画像」であり、 「同じモデル」ではありません（実測では、Qwen のアンカー + GPT の派生画像、GPT のアンカー + Qwen の派生画像、同じ画像一式でのモデル混在はいずれも自然につながります）。 各画像にはそれぞれのモデルが記録され、同じ画像一式でモデルを混在させた場合はレポートで通知します。

• 固定されるのは3つだけです：アンカーファイル（sha256）、画風のスナップショット、テキスト説明のフィンガープリントです。いずれかが変わると、 それに依存する画像は「期限切れ」としてマークされます——マークするだけで、削除はしません。旧バージョンはすべて残します。

---

Step 0 — 初回設定（マシンごとに1回）

node {baseDir}/scripts/character-refs.mjs config --show

出力の末尾に「不足：……」とあれば、次の3点をユーザーに確認してください。一度にまとめて質問します：

1. メイン画像（アンカー）に使うモデル：
   • qwen —— Qwen Image 2.1。独自の ComfyUI サーバーを使用します。高速（1枚あたり25〜45秒）で、サイズが正確、サブスクリプションの利用枠を消費しません。 COMFY_URL が必要です（COMFY_USER / COMFY_PASS は任意）。環境変数または .env ファイルに設定します
   • codex —— codex 内蔵の画像生成（GPT）。API key は不要ですが、ChatGPT のサブスクリプション利用枠を消費します（Plus は約25枚で上限に達し、数時間後に回復します）。1枚あたり80〜160秒です
   • openai —— OpenAI Images API。デフォルトは gpt-image-2 です。従量課金で、OPENAI_API_KEY が必要です。互換性のあるインターフェースを指定することもできます（--openai-base-url）
   • custom:<名前> —— ユーザー独自の画像生成コマンド。references/models.md を参照してください
2. 派生画像に使うモデル：デフォルトではメイン画像と同じです。分けることもできます（たとえば、アンカーに GPT、派生画像に Qwen）
3. アンカー生成後、人による確認のために一時停止するか：yes を推奨します——アンカーは画像一式の根なので、問題があるまま後続を生成しても無駄になります。 no を選ぶと自動的に続行し、レポートに「人による確認なし」と記載します。チェックゲートに合格していないアンカーは自動で続行できません。人が確認してから confirm するか、再生成する必要があります

node {baseDir}/scripts/character-refs.mjs config --model qwen --confirm-anchor yes --qwen-env-file <.env 路径>
# 分开设置：--anchor-model codex --derive-model qwen

設定は {baseDir}/config.local.json に保存されます（バージョン管理の対象外で、再インストールしても上書きされません）。以降は常にこれを使います。 ユーザーが「xx に変えて」と言ったら、config を再実行します。.env 内のパスワードや key を表示してはいけません。config --show はすでにマスキングされています。

Step 1 — 一度だけ入力

ユーザーはキャラクターを一段落で説明すれば十分です。一項目ずつ質問する必要はありません。あなた（モデル）が内容を分解します：

node {baseDir}/scripts/character-refs.mjs intake-template

テンプレートに従って説明を各フィールドに分解し、<作業ディレクトリ>/<キャラクター名>-intake.json に書き込みます。ルール（詳しくは references/intake.md を参照）：

• lang にはユーザーが話した言語を設定します（中国語は zh、英語は en、日本語は ja が組み込み済みです）。確認表とレポートはすべてこの言語で表示します。 それ以外の言語は、まず ui-template <lang> を実行し、出力された英語の文言を一つずつ翻訳して、全体を intake の ui フィールドに入れます
• ユーザーが述べた内容には stated、推測した内容には inferred、慣例に従って補った内容には default の印を付けます——実際の区分を正直に付けてください。確認表ではその印を使って、ユーザーが確認すべき項目を示します
• 年齢、性別、時代が推測できない場合はユーザーに質問します。この3つだけは自分で作りません。それ以外はすべて自分で補い、追加質問はしないでください
• プロンプトに入れる en は、常に英語で、キャラクター名も画風の用語も書きません。人が読む text は、lang の言語で書きます（旧形式の入力にある zh もそのまま受け付けます）
• 服装は top / bottom に分けます——バストアップでは上半身の服だけを使います。上下の服を含めると、モデルがカメラを引いてしまいます
• ディテール画像はキャラクターに合わせて選びます：ユーザーが指定したものを優先し、指定がなければキャラクターを最も見分けやすくする箇所を選びます。デフォルトでは4つのスロットを使用します。顔の特徴はディテール画像にしません（バストアップですでによく見えるためです）。詳しくは references/intake.md を参照してください

node {baseDir}/scripts/character-refs.mjs intake-check <intake.json>

問題があれば、エラーに従って修正し、通過するまで続けます。通過すると確認表が出力されるので、そのままユーザーに見せます。推測した項目とデフォルトの項目には印が付いています。 ユーザーが確認する（または修正後に再確認する）までは、先に進みません。

Step 2 — アセットの作成

node {baseDir}/scripts/character-refs.mjs new <intake.json> --out <输出目录> [--look 画风]

<出力ディレクトリ>/<キャラクター名>/asset.json が作成されます。この時点で画風レイヤー全体がアセットにスナップショットとして保存され、後からプリセットを変更しても既存のキャラクターには影響しません。

画風：ユーザーが指定した場合はその指定に従い、指定がなければアニメにします。同じ作品に登場するキャラクターにはすべて同じ画風を使います。

プリセット	--look が認識する名前
アニメ（デフォルト）	动漫 卡通 anime cartoon 二次元 アニメ
写実写真	写实 realistic photo 真人

looks で全プリセットを一覧表示します。ユーザーが別の画風（中国風、アメリカンコミック風など）を希望する場合：look-template <最も近いプリセット> > my-look.json を実行し、style（媒体、線）、 clean（背景と光、白背景は必ず維持すること）、neg（ネガティブ語句——描画する画風に変更する場合は、ネガティブ語句から anime illustration を削除します）を編集します。 描画する画風では medium を drawn に設定し、その後 --look my-look.json を指定します。カスタム画風は実測されていないため、まずアンカーを生成して効果を確認してください。

作成済みのキャラクターの画風を変更する場合：

node {baseDir}/scripts/character-refs.mjs restyle <asset.json> --look 动漫

変更後はアンカーを含む既存の画像がすべて期限切れとしてマークされます。旧画像は残し、アンカーから再生成します。

Step 3 — デフォルトの第2段階まで生成

node {baseDir}/scripts/character-refs.mjs gen <asset.json>

ビューと段階を指定しない場合、第1・第2段階のうち、まだ生成されていない画像と期限切れの画像を補完します。

確認を設定している場合、このコマンドはアンカーだけを生成して停止します。画像をユーザーに見せ（レポートを表示するか、PNG を直接開きます）、ユーザーが問題ないと言ったら、次を実行します

node {baseDir}/scripts/character-refs.mjs confirm <asset.json>
node {baseDir}/scripts/character-refs.mjs gen <asset.json>      # 同一条命令，接着出大头照、侧面、背面

不満があれば、もう一度 gen <asset.json> front-full を実行します（v2 を生成します。--seed でシードを変更でき、--model でモデルを変更できます）。 または Step 1 に戻り、説明を修正します。**アンカーが確認されるまで、派生画像は拒否されます。**確認しない設定の場合は、1つのコマンドで4枚すべてを生成します。

Step 4 — 必要に応じて段階を上げる

node {baseDir}/scripts/character-refs.mjs gen <asset.json> --tier 3 --reason "E03 有发饰和领口特写"

--reason には段階を上げる理由を記入し、アセットに記録します。一部の画像だけを生成することもできます：gen <asset.json> detail-hair detail-neck。

Step 5 — 確認と再生成

node {baseDir}/scripts/character-refs.mjs check <asset.json>

各画像はコードチェックゲートを通過します（サイズが300〜5760、アスペクト比が0.4〜2.5、比率が指定どおり、≤20MB、背景が十分に白いこと）。その後、期限切れかどうかを確認します。 **問題があれば exit 1 になります。**ゲートに合格しなかった画像や期限切れの画像は、該当する1枚だけを再生成します：

node {baseDir}/scripts/character-refs.mjs gen <asset.json> detail-neck --model codex

ゲートの「背景が十分に白いか」のチェックでは、全身画像は四辺を確認し、バストアップ画像は上辺と両側の上半分だけを確認します（体はもともと下辺まで写るためです）。ディテール画像はチェックを省略し、その旨を明示します。 ゲートでは顔立ち、角度、構図を確認できません——生成後は必ず画像を見てください。これらは目視で確認する必要があります。

Step 6 — レポート

node {baseDir}/scripts/character-refs.mjs render <asset.json>... --out <输出目录>/character-refs.html

複数のキャラクターをまとめて生成できます。言語はデフォルトでアセットの lang を使い、一時的に変更する場合は --lang en を追加します。組み込み以外の言語で ui が設定されていない場合は、翻訳済みの文言を --ui <ファイル> で渡します。 文言が不足している場合は、英語と別の言語が混在したレポートを出さず、エラーになります。画面上の文言の言語は変更されますが、キャラクターの説明は原文のままです。 第1段階ではカードを1枚だけ表示します。第2段階以降は設定画のレイアウト（左にバストアップ、右上に正面／側面／背面、右下にディテールの帯）になります。 デフォルトではディテール画像を表示しません。ページ上でワンクリックで切り替えられます。期限切れの画像は赤枠で囲まれ、ページ上部には凡例が表示されます。赤枠の画像にマウスを合わせると理由が表示されます。モデルを混在させた場合は通知します。

Step 7 — 汇报

一句话：出了哪几张、使用的哪个模型、报告路径。门没过或过期的点名。没看过图不要说「效果很好」。

---

落地结构

<输出目录>/
├── character-refs.html          ← render 产出
└── <角色名>/
    ├── asset.json               ← 角色描述 + 每张图的全部版本
    └── default/                 ← 造型（v1 只有 default 一套）
        ├── front-full.v1.png    ← 锚点
        ├── face-front.v1.png
        ├── face-front.v2.png    ← 重出不覆盖
        └── detail-hair.v1.png …

每张 PNG 里都写着标识（角色/造型/视图/版本）、模型、参考了哪几张，图被单独拷走也查得到来历。 asset.json 的结构见 references/schema.md。

边界

• 实测过的画风只有写实和动漫两种（都是 Qwen 跑四档）；自定义画风效果取决于写法，先出锚点看
• 细节图只收长在角色身上的（发饰、领口、袖口、鞋）；道具归 novel-art
• 已知短板：小疤痕容易画成新伤、双排扣这类大面积细节取景偏远、Qwen 的领口细节会把粗布画得像丝绒（换 codex 重出这一张）、Qwen 细节图里露出的皮肤会偏老（提示词已加年龄句，16 岁样例上有效，未大量验证）
• openai 适配器只使用本地假服务器验过请求格式，没有用真 key 跑过；第一次使用时先出一张锚点看看
• 同一套提示词在 Qwen 和 GPT 上都实测过；自定义模型的效果取决于那个模型

自测

node {baseDir}/scripts/selftest.mjs

233 项断言，不调模型、不花额度：PNG 标识读写、检查门、输入校验、多语言确认表与报告、画风预设与换画风、提示词、过期传导、出图适配器的请求格式（Qwen 与 GPT Image 使用本地假服务器）、 以及使用自定义命令跑通的完整流程。改完脚本先跑这个。

自带样例

{baseDir}/examples/阿禾-描述.txt 是一段用户式的一句话描述（1920 年代江南采茶姑娘）， 阿禾-intake.json 是拆好的输入，推断和默认的字段都标了。样例图不进版本控制，要看就使用自己的模型跑一遍。