1仕組みと動作原理
機能の核となるのは「スタイルの番号管理」です。ルートの styles_200_reorganized.md から261件のスタイル情報(番号+元参照名+生成名+主要な視覚特徴)を解析して references/styles.json を生成し、build_library.py によってオフライン検索可能なギャラリーHTMLを構築します。
Users can browse `gallery/index.html` for the numbered contact sheets. The authoritative style content is `../styles_200_reorganized.md`; `references/styles.json` is a generated index and must be refreshed with `python scripts/build_library.py` after the Markdown changes.
出力規約は極めてシンプルかつ厳格です。固定の4段構成(選択スタイル/中国語プロンプト/英語プロンプト/1行説明)とし、プロンプト本文の冒頭は `风格名称:#{编号} · {generation_name}。` および `Style name: #{number} · {generation_name}.` で始めることを義務付けています。
For a valid request, return these four parts: 1. Selected style: number and generated style name. Do not output a core-visual-traits field by default for ordinary prompt-only requests. 2. Chinese prompt: begin the copyable prompt itself with `风格名称:#{编号} · {generation_name}。`; describe only the user's theme and constraints explicitly provided by the user, and always include the indexed author/style name as a short `参考作者/风格名称` label. Do not append core traits, the fixed style anchor, extra style adjectives, generic composition advice, quality claims, or negative prompts. 3. English prompt: begin the copyable prompt itself with `Style name: #{number} · {generation_name}.`; describe only the same theme and user-provided constraints, and always include the indexed author/style name as `Reference author/style name`. Do not append visual-trait prose, generic composition advice, quality claims, negative prompts, or the fixed style anchor. 4. A brief note: the prompt can be pasted into any image AI; generation is controlled by that AI.
デフォルトでは画像を生成しません。ユーザーが生成/レンダリング/プレビューを明示的に要求した場合のみ画像生成モードへ移行し、作者の知名度や存命状況ではなく「送信テキスト全体」(インデックス作者名+生成スタイル名)を用いて現在の画像モデルの能力を判定します。
When the user explicitly requests image generation, first resolve the current image model (or model family) against `references/model_capabilities.json` or the equivalent runtime capability metadata. The decision uses the complete text that will be sent to the model: the indexed author name plus the generated style name. It is not based on the author's fame or life status.
モデル能力リストはハードコードではなくデータ管理されています。references/model_capabilities.json は schema_version/description/default/models 構造を用いて「特定モデルが名称のみで特定番号を再現可能か」を記述し、デフォルト値は強制的に unknown + 画像参照必須となっています。
"description": "Model-specific ability to activate a numbered style from its name. Unknown models must use the image fallback.", "default": { "name_activation": "unknown", "use_reference_image": true, "note": "No verified model capability is available. Pass the numbered image."
判断ロジックはスクリプトで実装され再現可能です。resolve_reference.resolve() が番号範囲と値のドメイン(ALLOWED = strong/weak/none/unknown)を検証し、activation_source(name+style / name+style+traits / reference-image)およびフィルタリング済みの prompt_traits を出力します。
return ";".join(kept) def get_reference_path(number: str) -> str: reference_grid = grid_path(number) return str(reference_grid if reference_grid.exists() else single_path(number)) def resolve(model: str, style: str, policy: dict | None = None) -> dict:
参照画像を渡す際は「参照画像隔離ブロック」の挿入が必須です。線画、筆致、画材、質感、色調などのスタイル特徴のみを抽出し、主体、人物、衣装、小道具、ポーズ、シーン、構図、文字、ストーリーを複製してはならず、テーマのみがコンテンツの唯一のソースであることを中英バイリンガルで明記します。
- When an image is passed, inject the following reference-isolation block into the actual image-generation prompt. It is required for every reference-image generation and is not added to ordinary prompt-only output: Chinese: `所附图片仅用于参考画风。只提取参考图的风格特征,例如线条、笔触、媒介、材质、色彩倾向和整体视觉语言;不要使用、复制或延续参考图中的任何主体、人物、动物、服装、道具、动作、姿态、场景、背景、构图、布局、文字或故事。最终画面内容完全以用户提供的主题为准。` English: `Use the attached image only as a style reference. Extract only its stylistic qualities, such as linework, brushwork, medium, material texture, color tendencies, and overall visual language. Do not use, copy, or carry over any subject, person, animal, clothing, prop, action, pose, setting, background, composition, layout, text, or story from the reference image. The user's written theme is the sole source for the image content.` - The user's theme is the sole source for subjects and narrative; the reference image must never override or add content to the theme.
セッションの初期化はホストMCPに依存します。Codexのタスク/スレッドで初回呼び出しされた際に、視覚インデックスとしてローカルギャラリー(file:///E:/handraw-style/handdraw-style-prompter/gallery/index.html)を開き、失敗時はローカルリンクへフォールバックします。再オープンや状態ファイルの書き出しは行いません。
1. If this task has not already displayed the gallery, call `mcp__codex_app__open_in_codex` with `target: { type: "browser", url: "file:///E:/handraw-style/handdraw-style-prompter/gallery/index.html" }` so the rendered gallery opens in the in-app browser. 2. Continue with the user's request after the browser call; opening the gallery must not block prompt generation or an explicitly requested image-generation follow-up. 3. Do not repeat the browser call on later turns in the same task/thread. Use the conversation context (not a persistent state file) to determine whether initialization already happened. 4. If the browser call is unavailable or fails, provide this fallback link: [打开手绘风格编号画廊](file:///E:/handraw-style/handdraw-style-prompter/gallery/index.html), then continue normally.
リソース解決ルールを内蔵しています。同一番号の4分割グリッド参照画像は単体画像より優先され、パスは200番号ごとのバケット(例: 201-400)に分かれています。画像が存在しない場合は制約を報告してテキストのみのプロンプトへフォールバックし、参照画像の捏造や勝手な代替は一切行いません。
- If the numbered image is missing or cannot be passed, report that limitation and provide the normal text prompts; never invent or substitute a reference image.
2コア機能
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| api | 宿主 MCP 工具 mcp__codex_app__open_in_codex(在 Codex 应用内浏览器打开本地 file:// 画廊;skill 自身不含网络调用) |
| api | 外部图像生成工具(由宿主/用户提供;传参考图时使用其 referenced_image_paths 参数)——skill 只产出提示词与路径建议,不调用任何图像 API |
| cli | python3(运行 build_library.py / prompt_style.py;split_contact_sheets.py 另需 Pillow/PIL) |
| package | Pillow(PIL)——仅 split_contact_sheets.py 用于切分拼图为编号单图;非运行提示词所需 |
4推奨統制措置と判定根拠
- scripts/: ローカルスクリプトまたはコマンドの実行: scripts/build_library.py(styles.json および gallery/index.html を再構築 — references/ への書き込み
- 本地工作目录: ファイルの読み書きおよび成果物の出力: build_library.py は handdraw-style-prompter/references/styles.json および handd
5二重目の独立検証
- [ok] style 索引与编号连续性 — styles.json 261 条,首条 001 Gemma Correll / Playful Deadpan Doodle,末条 261 OscarAI;validate_library.py 亦硬断言 [number] == 连续 001–261 且 018 必须映射 'Minimal Deadpan Dialogue Cartoon'。
- [ok] 画廊离线自足 — gallery/index.html 中 http(s):// 字面量 0 命中,img/button data-src 全部为 ../../images/<sheet>.png 相对路径,无 CDN/字体/统计外链。
- [discrepancy] SKILL.md 的 Utilities 命令可运行性 — `python scripts/resolve_reference.py --model <model> --style <number>` 实跑报 ModuleNotFoundError: No module named 'style_asset_paths'(脚本把仓库根 <repo>/scripts 插入 sys.path,但该目录与模块不存在,git ls-tree 全仓库无该文件)。同一缺失还被 split_contact_sheets.py 与 validate_library.py 引用(后者另需 contact_sheet_registry)。故 SKILL.md「Utilities」5 条命令中,仅 build_library.py 与 prompt_style.py 当前可运行;这是仓库在 pin commit 上的真实缺陷,非本报告的定位问题。
- [ok] 模型能力清单的覆盖面 — model_capabilities.json 仅 gpt-image-2 一轮清单、123 条编号条目(strong 78 / none 45);未列编号走 resolve() 的 entry 继承 default(unknown + 传图),即保守回退。SKILL.md 第 12-19 行的三级决策与代码分支逐条对应(name+style / name+style+traits / reference-image)。
- [ok] 「与作者名气无关」的声明与代码一致 — 决策只读 name_activation/traits_activation 两个字段,代码中不存在任何依赖 attribution.json(名气/在世状态)的分支;attribution 仅被 validate_library.py 用于「deceased 必须带 source」的完整性断言。
- [discrepancy] 图片资产覆盖与文档一致性 — 实跑 find 统计:images/ 下 19 张分组拼图 + 单图 200 张(001–200 桶)+ 61 张(201–400 桶 = 201–261)+ 45 张 *_grid.jpg(编号 217–261),合计 325 个受控图片文件=git ls-files 中 images/ 的条目数。但 MANIFEST.md 的「已收录图片」只登记 16 张拼图(止于 G_201-216.png),且仍写「images/individual/201-400/201.png–217.png:201–217 的编号单图」「风格编号覆盖:001–217」「当前无缺失编号段」,README/SKILL.md 已按 001–261 描述。判定:MANIFEST.md 为滞后文档,能力面以 261 为准。
- [discrepancy] 路径可移植性 — SKILL.md 第 21 行把参考图根写死为 `E:\handraw-style\images\individual\{bucket}\{number}.png`,第 37/40 行画廊链接为 `file:///E:/handraw-style/...`;这两处只在作者本机成立(本仓库实际位置为 <repo>/images/individual/...)。跨平台使用需按仓库根改写这三处。
- [ok] 无网络外发与凭证读取 — 对 5 个脚本与 SKILL.md/agents/openai.yaml 扫描 http/fetch/requests/urllib/socket/api_key/token/secret:脚本侧 0 命中;SKILL.md 唯一外部动作为宿主 MCP 打开 file:// 本地文件与把路径交给图像工具。resolve_reference 的能力数据来自本地 JSON,不需要联网查询模型能力。
6結論
b025e1b5b2a3616d…