@yuhan1124/draw-prompt 0.4.0

package/scripts/prompt_cli.py

@@ -0,0 +1,3141 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["pyyaml>=6.0", "pillow>=10.0"]
+# ///
+"""draw-prompt CLI — 生图需求转化 + 偏好持久化 + Codex 交付块生成。
+
+设计边界（重要）：这个 skill 只做两件事——
+  1. 把自然语言画图需求转化成高质量、可执行的 gpt-image-2 prompt / handoff；
+  2. Harness 辅助转化：记录你的口味、采纳/弃用样本、评分，越用越贴合。
+
+它【不主动调用 Codex 出图】。出图交给下游（/codex-image 插件或你手动跑
+codex exec）。本 CLI 的 `handoff` 子命令负责把 prompt 包装成一段可以直接
+粘贴/转交给 Codex 的现成指令，但不会自己去执行它。
+
+CLI 只干确定性的脏活：
+  convert   自然语言画图需求 -> Prompt / handoff
+  compose   长输入/文档 -> 多张配套图的视觉计划 + Prompt
+  series    多张同风格系列图 -> 稳定一致的 Prompt 组
+  edit      参考图/改图需求 -> 保留项、修改项、编辑 Prompt
+  brand     品牌风格档案 -> 可复用品牌 Prompt 块
+  character 角色设定 -> 角色一致性 bible + 场景 Prompt
+  data-viz  数据/报表需求 -> 信息图/图表 Prompt
+  rewrite   低质量 prompt -> 结构化高质量 Prompt
+  adapt     同一需求 -> 多尺寸/多画幅适配 Prompt
+  overlay   按 text_overlay_spec 对成品图做精确文字后处理
+  visual-check / edit-check / visual-regress  成品图质量门与回归验证
+  lint      检查 Prompt 是否满足生图转化硬约束
+  benchmark 批量跑 golden cases，检查转化稳定性
+  revise    按失败分类生成修订版 Prompt
+  profile   读写风格偏好档案 style_profile.md
+  samples   记录 / 检索出图样本（few-shot 来源）
+  feedback  对样本回填采纳 / 弃用
+  judge     存储 agent 给出的评分（CLI 不评分、不看图、不调 Codex）
+  handoff   生成交给 Codex 的现成指令块（仅打印，不执行）
+  status    数据与下游通道健康检查
+
+所有运行时数据写到数据目录（默认 ~/.local/share/draw-prompt/，可用
+DRAW_PROMPT_HOME 覆盖），不进 git repo。
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import hashlib
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from shutil import which
+from tempfile import NamedTemporaryFile
+
+# ---- yaml：有 pyyaml 用它，没有就退化到极简解析，保证裸 python 也能跑 ----
+try:
+    import yaml  # type: ignore
+
+    def _yaml_load(text: str) -> dict:
+        return yaml.safe_load(text) or {}
+
+    def _yaml_dump(data: dict) -> str:
+        return yaml.safe_dump(data, allow_unicode=True, sort_keys=False).strip()
+
+except Exception:  # pragma: no cover - 仅在无 pyyaml 时走到
+
+    def _yaml_load(text: str) -> dict:
+        out: dict = {}
+        for line in text.splitlines():
+            line = line.rstrip()
+            if not line or line.lstrip().startswith("#") or ":" not in line:
+                continue
+            key, _, val = line.partition(":")
+            key, val = key.strip(), val.strip()
+            if val.startswith("[") and val.endswith("]"):
+                inner = val[1:-1].strip()
+                parts = re.findall(r'"[^"]*"|\'[^\']*\'|[^,]+', inner)
+                out[key] = [p.strip().strip("\"'") for p in parts if p.strip()]
+            elif val:
+                out[key] = val.strip("\"'")
+            else:
+                out[key] = ""
+        return out
+
+    def _yaml_dump(data: dict) -> str:
+        lines = []
+        for key, val in data.items():
+            if isinstance(val, list):
+                inner = ", ".join(f'"{v}"' for v in val)
+                lines.append(f"{key}: [{inner}]")
+            else:
+                lines.append(f"{key}: {val}")
+        return "\n".join(lines)
+
+
+# --------------------------------------------------------------------------- #
+# 路径与时间
+# --------------------------------------------------------------------------- #
+def data_home() -> Path:
+    env = os.environ.get("DRAW_PROMPT_HOME")
+    if env:
+        return Path(env).expanduser()
+    xdg = os.environ.get("XDG_DATA_HOME")
+    base = Path(xdg).expanduser() if xdg else Path.home() / ".local" / "share"
+    return base / "draw-prompt"
+
+
+def profile_path() -> Path:
+    return data_home() / "style_profile.md"
+
+
+def samples_path() -> Path:
+    return data_home() / "samples.jsonl"
+
+
+def judgements_path() -> Path:
+    return data_home() / "judgements.jsonl"
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def now_stamp() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+
+
+def ensure_home() -> None:
+    data_home().mkdir(parents=True, exist_ok=True)
+
+
+SCHEMA_VERSION = 1
+COMPILER_VERSION = "0.4.0"
+
+
+# --------------------------------------------------------------------------- #
+# profile：style_profile.md = yaml frontmatter + markdown body
+# --------------------------------------------------------------------------- #
+PROFILE_TEMPLATE_FM = {
+    "default_aspect": "未设置",
+    "default_quality": "high",
+    "favored_styles": [],
+    "avoided_elements": [],
+    "text_language": "zh",
+    "updated_at": "",
+}
+
+PROFILE_TEMPLATE_BODY = """# 风格偏好笔记
+
+（agent 在这里用自然语言累积对你口味的观察：你反复要求的构图、留白、
+配色、镜头语言、排斥的"AI 味"等。每条尽量带一句依据，并标注日期。）
+"""
+
+
+def read_profile() -> tuple[dict, str]:
+    """返回 (frontmatter dict, body str)。文件不存在则返回模板。"""
+    path = profile_path()
+    if not path.exists():
+        return dict(PROFILE_TEMPLATE_FM), PROFILE_TEMPLATE_BODY
+    text = path.read_text(encoding="utf-8")
+    if text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) >= 3:
+            fm = _yaml_load(parts[1])
+            body = parts[2].lstrip("\n")
+            return fm, body
+    return dict(PROFILE_TEMPLATE_FM), text
+
+
+def write_profile(fm: dict, body: str) -> None:
+    ensure_home()
+    fm = dict(fm)
+    fm["updated_at"] = now_iso()
+    text = f"---\n{_yaml_dump(fm)}\n---\n\n{body.rstrip()}\n"
+    profile_path().write_text(text, encoding="utf-8")
+
+
+def cmd_profile(args: argparse.Namespace) -> int:
+    action = args.action
+    if action == "path":
+        print(profile_path())
+        return 0
+    if action == "init":
+        if profile_path().exists() and not args.force:
+            print(f"已存在：{profile_path()}（加 --force 覆盖）", file=sys.stderr)
+            return 0
+        write_profile(dict(PROFILE_TEMPLATE_FM), PROFILE_TEMPLATE_BODY)
+        print(f"已初始化：{profile_path()}")
+        return 0
+    if action == "show":
+        fm, body = read_profile()
+        if not profile_path().exists():
+            print("（档案尚未创建，下面是模板默认值。运行 `profile init` 创建。）\n", file=sys.stderr)
+        print(f"---\n{_yaml_dump(fm)}\n---\n\n{body.rstrip()}")
+        return 0
+    if action == "set":
+        if not args.key:
+            print("用法：profile set KEY VALUE   （列表字段用逗号分隔）", file=sys.stderr)
+            return 2
+        fm, body = read_profile()
+        val = args.value or ""
+        # 只对显式列表字段做逗号拆分，避免标量值（如 "high, low"）被误拆成列表
+        if args.key in ("favored_styles", "avoided_elements"):
+            fm[args.key] = [v.strip() for v in val.split(",") if v.strip()]
+        else:
+            fm[args.key] = val
+        write_profile(fm, body)
+        print(f"已更新 {args.key} = {fm[args.key]}")
+        return 0
+    if action == "note":
+        text = args.value or args.key  # 单参数会落在 key 槽
+        if not text:
+            print("用法：profile note \"一条偏好观察\"", file=sys.stderr)
+            return 2
+        fm, body = read_profile()
+        stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        body = body.rstrip() + f"\n\n- ({stamp}) {text}"
+        write_profile(fm, body)
+        print("已追加一条偏好笔记。")
+        return 0
+    print(f"未知 profile 动作：{action}", file=sys.stderr)
+    return 2
+
+
+# --------------------------------------------------------------------------- #
+# samples：jsonl，每行一条出图记录
+# --------------------------------------------------------------------------- #
+def append_jsonl(path: Path, record: dict) -> None:
+    ensure_home()
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def read_jsonl(path: Path) -> list[dict]:
+    if not path.exists():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if line:
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError:
+                continue
+    return out
+
+
+def rewrite_jsonl(path: Path, records: list[dict]) -> None:
+    ensure_home()
+    # 全量重写前先备份，避免读取时跳过的损坏行被静默永久删除
+    if path.exists():
+        backup = path.with_suffix(path.suffix + ".bak")
+        backup.write_text(path.read_text(encoding="utf-8"), encoding="utf-8")
+    with NamedTemporaryFile("w", encoding="utf-8", delete=False, dir=str(data_home())) as fh:
+        for rec in records:
+            fh.write(json.dumps(rec, ensure_ascii=False) + "\n")
+        tmp_name = fh.name
+    os.replace(tmp_name, path)
+
+
+def new_id() -> str:
+    # 秒级时间戳 + 随机后缀，避免同秒同进程批量写入时 id 碰撞
+    return now_stamp() + "-" + os.urandom(2).hex()
+
+
+# --------------------------------------------------------------------------- #
+# convert / lint：自然语言生图需求 -> Prompt -> 可验证 handoff
+# --------------------------------------------------------------------------- #
+ASSET_ROUTES = {
+    "poster": {
+        "label": "poster",
+        "title": "海报 / 视觉主 KV",
+        "keywords": ["海报", "poster", "banner", "主视觉", "kv", "促销", "活动图", "封面"],
+        "aspect": "3:4",
+        "size": "portrait",
+        "quality": "high",
+        "tags": ["poster"],
+    },
+    "ui": {
+        "label": "ui",
+        "title": "UI / 产品界面",
+        "keywords": ["ui", "界面", "app", "dashboard", "仪表盘", "网页", "web", "小程序", "mockup"],
+        "aspect": "9:16",
+        "size": "portrait",
+        "quality": "high",
+        "tags": ["ui"],
+    },
+    "infographic": {
+        "label": "infographic",
+        "title": "信息图 / 科普图解",
+        "keywords": ["信息图", "infographic", "图解", "科普", "说明图", "流程图", "时间线"],
+        "aspect": "3:4",
+        "size": "portrait",
+        "quality": "high",
+        "tags": ["infographic"],
+    },
+    "diagram": {
+        "label": "diagram",
+        "title": "学术 / 系统架构图",
+        "keywords": ["架构图", "系统图", "论文图", "diagram", "architecture", "模型图", "流程架构"],
+        "aspect": "16:9",
+        "size": "landscape",
+        "quality": "high",
+        "tags": ["diagram"],
+    },
+    "product": {
+        "label": "product",
+        "title": "产品 / 食品商业渲染",
+        "keywords": ["产品", "商品", "渲染", "电商", "食品", "饮料", "包装", "瓶", "杯", "茶饮"],
+        "aspect": "3:4",
+        "size": "portrait",
+        "quality": "high",
+        "tags": ["product"],
+    },
+    "character": {
+        "label": "character",
+        "title": "角色设计",
+        "keywords": ["角色", "人物", "立绘", "character", "人设", "表情", "三视图"],
+        "aspect": "16:9",
+        "size": "landscape",
+        "quality": "high",
+        "tags": ["character"],
+    },
+    "photography": {
+        "label": "photography",
+        "title": "写实摄影",
+        "keywords": ["摄影", "写实", "照片", "photo", "photography", "街拍", "纪实"],
+        "aspect": "16:9",
+        "size": "landscape",
+        "quality": "high",
+        "tags": ["photography"],
+    },
+    "illustration": {
+        "label": "illustration",
+        "title": "插画 / 风格化图像",
+        "keywords": ["插画", "illustration", "绘本", "漫画", "二次元", "扁平", "风格化"],
+        "aspect": "1:1",
+        "size": "square",
+        "quality": "medium",
+        "tags": ["illustration"],
+    },
+    "logo": {
+        "label": "logo",
+        "title": "Logo / 品牌系统板",
+        "keywords": ["logo", "标识", "品牌", "字标", "brand", "vi"],
+        "aspect": "1:1",
+        "size": "square",
+        "quality": "high",
+        "tags": ["logo"],
+    },
+}
+
+STYLE_HINTS = [
+    (["国风", "新中式", "东方", "中式"], "New Chinese visual style, restrained and elegant"),
+    (["极简", "minimal", "简洁"], "minimal editorial design, clean grid, generous negative space"),
+    (["高级", "轻奢", "质感"], "premium commercial visual style, refined and not flashy"),
+    (["赛博", "cyber", "科技感"], "futuristic cyber-tech aesthetic with controlled neon accents"),
+    (["复古", "retro"], "tasteful retro print design with contemporary restraint"),
+    (["瑞士", "swiss"], "Swiss International Typographic style, strict grid discipline"),
+    (["手绘", "水彩"], "hand-drawn illustration with tactile paper texture"),
+    (["写实", "真实"], "realistic, natural, unprocessed visual language"),
+]
+
+ASPECT_SIZE = {
+    "3:4": "portrait",
+    "4:3": "landscape",
+    "16:9": "landscape",
+    "9:16": "portrait",
+    "1:1": "square",
+}
+
+BUZZWORDS = ["stunning", "beautiful", "professional", "high quality", "nice", "modern", "高级感"]
+
+TEMPLATE_DEFS = {
+    "poster_zh_promo": {
+        "asset_type": "poster",
+        "label": "中文促销海报",
+        "layout": "large headline zone, hero product zone, price/offer block, quiet footer",
+        "keywords": ["促销", "新品", "价格", "优惠", "茶饮", "冷泡", "海报"],
+    },
+    "poster_brand_kv": {
+        "asset_type": "poster",
+        "label": "品牌主视觉 KV",
+        "layout": "single hero visual, brand message zone, generous negative space",
+        "keywords": ["品牌", "主视觉", "kv", "发布", "形象"],
+    },
+    "poster_event": {
+        "asset_type": "poster",
+        "label": "活动海报",
+        "layout": "title, date/venue, speaker or theme block, organizer footer",
+        "keywords": ["活动", "会议", "展览", "event", "workshop", "讲座"],
+    },
+    "poster_info_dense": {
+        "asset_type": "poster",
+        "label": "信息密集海报",
+        "layout": "modular grid with clear title, sections, callouts, and footer rules",
+        "keywords": ["日程", "规则", "清单", "信息", "流程", "说明"],
+    },
+    "ui_mobile_home": {
+        "asset_type": "ui",
+        "label": "移动 App 首页",
+        "layout": "phone status bar, app header, content cards, primary action, bottom navigation",
+        "keywords": ["app", "首页", "手机", "移动", "小程序"],
+    },
+    "ui_dashboard": {
+        "asset_type": "ui",
+        "label": "Web / SaaS Dashboard",
+        "layout": "sidebar, top bar, KPI cards, chart panel, data table",
+        "keywords": ["dashboard", "仪表盘", "后台", "saas", "web"],
+    },
+    "diagram_rag": {
+        "asset_type": "diagram",
+        "label": "RAG 架构图",
+        "layout": "left-to-right pipeline: User -> Retriever -> Vector DB -> LLM -> Answer",
+        "keywords": ["rag", "retriever", "vector db", "llm", "answer", "检索"],
+    },
+    "diagram_system": {
+        "asset_type": "diagram",
+        "label": "系统架构图",
+        "layout": "layered system boxes with directional arrows and a small legend",
+        "keywords": ["架构", "系统", "模块", "服务", "流程"],
+    },
+    "product_hero": {
+        "asset_type": "product",
+        "label": "产品英雄图",
+        "layout": "single product hero, controlled props, clear material close-up, editorial finish",
+        "keywords": ["产品", "商品", "渲染", "电商", "新品"],
+    },
+    "illustration_scene": {
+        "asset_type": "illustration",
+        "label": "场景插画",
+        "layout": "main subject, environment details, foreground/midground/background depth",
+        "keywords": ["插画", "场景", "绘本", "风格化"],
+    },
+}
+
+FAILURE_PLAYBOOK = {
+    "text_error": {
+        "label": "文字错误 / 乱码",
+        "add_negative": ["avoid garbled text", "avoid tiny unreadable type"],
+        "revision": "Switch to strict text mode: generate the visual background and layout first, reserve clean text areas, then apply exact text through overlay_spec.",
+    },
+    "layout_error": {
+        "label": "布局错误",
+        "add_negative": ["avoid ambiguous layout", "avoid overlapping sections"],
+        "revision": "Make the layout explicit with named regions, fixed reading order, and stable spacing.",
+    },
+    "missing_subject": {
+        "label": "主体缺失",
+        "add_negative": ["avoid missing the main subject"],
+        "revision": "Restate the main subject as the first visible object and require it to dominate the composition.",
+    },
+    "wrong_style": {
+        "label": "风格不匹配",
+        "add_negative": ["avoid style drift"],
+        "revision": "Replace vague style words with a concrete visual production context and palette.",
+    },
+    "too_cluttered": {
+        "label": "画面过满",
+        "add_negative": ["avoid clutter", "avoid excessive decorative elements"],
+        "revision": "Increase negative space, reduce supporting objects, and prioritize one visual hierarchy.",
+    },
+    "bad_composition": {
+        "label": "构图差",
+        "add_negative": ["avoid weak composition"],
+        "revision": "Add composition anchors such as hero position, foreground/midground/background, and reading path.",
+    },
+    "brand_risk": {
+        "label": "品牌 / 版权风险",
+        "add_negative": ["avoid real brand logos", "avoid stock clip-art", "avoid existing IP resemblance"],
+        "revision": "Use invented branding only and explicitly require original marks.",
+    },
+    "low_readability": {
+        "label": "可读性差",
+        "add_negative": ["avoid low contrast", "avoid unreadable microtext"],
+        "revision": "Increase contrast, enlarge labels, simplify background behind text, and reserve clear reading zones.",
+    },
+}
+
+REFERENCE_REWRITE = {
+    "宫崎骏": "warm hand-painted fantasy animation mood with original characters",
+    "吉卜力": "warm hand-painted fantasy animation mood with original characters",
+    "迪士尼": "family-friendly polished animation mood with original characters",
+    "Disney": "family-friendly polished animation mood with original characters",
+    "皮克斯": "polished 3D animation mood with original characters",
+    "Pixar": "polished 3D animation mood with original characters",
+    "漫威": "cinematic superhero-comic energy with original characters",
+    "Marvel": "cinematic superhero-comic energy with original characters",
+    "Nike": "invented athletic brand language",
+    "耐克": "invented athletic brand language",
+    "Apple": "invented premium consumer electronics brand language",
+    "苹果": "invented premium consumer electronics brand language",
+    "可口可乐": "invented beverage brand language",
+    "Coca-Cola": "invented beverage brand language",
+}
+
+
+def split_csv(value: str | None) -> list[str]:
+    if not value:
+        return []
+    return [v.strip() for v in re.split(r"[,，]", value) if v.strip()]
+
+
+def normalize_ws(text: str) -> str:
+    return " ".join(text.split())
+
+
+def has_cjk(text: str) -> bool:
+    return bool(re.search(r"[\u4e00-\u9fff]", text))
+
+
+def sanitize_reference_risks(text: str) -> tuple[str, list[str]]:
+    """把真实 IP/品牌引用改成可执行的原创视觉描述，避免 prompt 直接要求仿冒。"""
+    safe = text
+    notes: list[str] = []
+    for key, replacement in REFERENCE_REWRITE.items():
+        if key == "苹果" and not any(ctx in safe for ctx in ["品牌", "logo", "手机", "电脑", "发布会", "科技"]):
+            continue
+        if key.isascii():
+            pattern = rf"\b{re.escape(key)}\b"
+            flags = 0 if key == "Apple" else re.IGNORECASE
+        else:
+            pattern = re.escape(key)
+            flags = 0
+        if re.search(pattern, safe, flags=flags):
+            safe = re.sub(pattern, replacement, safe, flags=flags)
+            notes.append(f"Rewrote risky reference '{key}' to original visual language.")
+    return safe, notes
+
+
+def safety_avoid_list(notes: list[str]) -> list[str]:
+    if not notes:
+        return []
+    return [
+        "avoid copying a living artist or studio house style",
+        "avoid real brand logos and trademarks",
+        "avoid resemblance to existing IP characters",
+        "use invented names, marks, and original character shapes",
+    ]
+
+
+def route_asset_type(request: str, override: str | None = None) -> str:
+    if override:
+        return override
+    lower = request.lower()
+    best = ("poster", 0)
+    for asset_type, meta in ASSET_ROUTES.items():
+        score = 0
+        for kw in meta["keywords"]:
+            if kw.lower() in lower:
+                score += 1
+        if score > best[1]:
+            best = (asset_type, score)
+    return best[0]
+
+
+def infer_aspect(request: str, asset_type: str, override: str | None, profile: dict) -> str:
+    if override:
+        return override
+    match = re.search(r"(\d{1,2}\s*[:x×]\s*\d{1,2})", request)
+    if match:
+        return match.group(1).replace(" ", "").replace("x", ":").replace("×", ":")
+    lower = request.lower()
+    if any(k in lower for k in ["横版", "横图", "landscape", "宽屏"]):
+        return "16:9"
+    if any(k in lower for k in ["竖版", "竖图", "portrait"]):
+        return "3:4"
+    if any(k in lower for k in ["方图", "方形", "square"]):
+        return "1:1"
+    prof = str(profile.get("default_aspect") or "").strip()
+    if prof and prof != "未设置":
+        return prof
+    return str(ASSET_ROUTES[asset_type]["aspect"])
+
+
+def infer_size(aspect: str, override: str | None, asset_type: str) -> str:
+    if override:
+        return override
+    return ASPECT_SIZE.get(aspect, str(ASSET_ROUTES[asset_type]["size"]))
+
+
+def infer_quality(request: str, asset_type: str, texts: list[str], override: str | None, profile: dict) -> str:
+    if override:
+        return override
+    lower = request.lower()
+    if any(k in lower for k in ["草稿", "draft", "探索"]):
+        return "medium"
+    if texts or asset_type in {"poster", "ui", "infographic", "diagram", "logo"}:
+        return "high"
+    prof = str(profile.get("default_quality") or "").strip()
+    if prof:
+        return prof
+    return str(ASSET_ROUTES[asset_type]["quality"])
+
+
+def extract_required_texts(request: str, explicit_texts: list[str]) -> list[str]:
+    seen: set[str] = set()
+    out: list[str] = []
+
+    def add(text: str) -> None:
+        text = text.strip(" \t\n\r，,。；;：:")
+        key = re.sub(r"\s+", "", text)
+        if 0 < len(text) <= 40 and key not in seen:
+            seen.add(key)
+            out.append(text)
+
+    for item in explicit_texts:
+        add(item)
+    if explicit_texts:
+        return out
+    patterns = [
+        r'"([^"\n]{1,40})"',
+        r"'([^'\n]{1,40})'",
+        r"“([^”\n]{1,40})”",
+        r"「([^」\n]{1,40})」",
+        r"『([^』\n]{1,40})』",
+    ]
+    for pat in patterns:
+        for match in re.findall(pat, request):
+            add(match)
+    text_hint = r"(?:写上|写|显示|包含|文案|标题|文字)"
+    for match in re.findall(rf"{text_hint}[：:\s]*(?:写上|写|显示|包含)?[：:\s]*([^，。；;,.]{{2,24}})", request):
+        add(match)
+    for match in re.findall(r"\d+(?:\s*/\s*\d+)?\s*元", request):
+        add(match)
+    return out
+
+
+def infer_style_anchors(request: str, override: str | None, profile: dict) -> list[str]:
+    anchors: list[str] = []
+    if override:
+        anchors.extend(split_csv(override))
+    lower = request.lower()
+    for keys, anchor in STYLE_HINTS:
+        if any(k.lower() in lower for k in keys):
+            anchors.append(anchor)
+    favored = profile.get("favored_styles") or []
+    if isinstance(favored, str):
+        favored = split_csv(favored)
+    for item in favored:
+        if item and item not in anchors:
+            anchors.append(str(item))
+    if not anchors:
+        anchors.append("clear, reproducible visual direction with concrete materials and composition")
+    return anchors[:4]
+
+
+def infer_negative(asset_type: str, texts: list[str], profile: dict) -> list[str]:
+    negative = ["avoid vague generic AI gloss", "avoid clutter"]
+    if texts:
+        negative.append("avoid garbled or wrong text")
+    if asset_type in {"poster", "ui", "infographic", "diagram", "logo"}:
+        negative.append("avoid fake logos and unreadable microtext")
+    if asset_type == "photography":
+        negative.extend(["avoid HDR over-processing", "avoid plastic skin"])
+    avoided = profile.get("avoided_elements") or []
+    if isinstance(avoided, str):
+        avoided = split_csv(avoided)
+    for item in avoided:
+        if item and item not in negative:
+            negative.append(str(item))
+    return negative[:8]
+
+
+def infer_tags(asset_type: str, request: str, extra: str | None = None) -> list[str]:
+    tags = list(ASSET_ROUTES[asset_type]["tags"])
+    if has_cjk(request):
+        tags.append("zh")
+    for key, vals in {
+        "tea": ["茶", "茶饮", "冷泡"],
+        "brand": ["品牌", "logo", "标识"],
+        "promo": ["促销", "价格", "优惠", "新品"],
+        "academic": ["论文", "学术", "系统", "模型"],
+    }.items():
+        if any(v.lower() in request.lower() for v in vals) and key not in tags:
+            tags.append(key)
+    for item in split_csv(extra):
+        if item not in tags:
+            tags.append(item)
+    return tags
+
+
+def infer_template_id(request: str, asset_type: str, override: str | None = None) -> str:
+    if override:
+        return override
+    lower = request.lower()
+    if asset_type == "diagram" and "rag" in lower:
+        return "diagram_rag"
+    candidates = {tid: meta for tid, meta in TEMPLATE_DEFS.items() if meta["asset_type"] == asset_type}
+    best_id = ""
+    best_score = -1
+    for tid, meta in candidates.items():
+        score = sum(1 for kw in meta["keywords"] if kw.lower() in lower)
+        if score > best_score:
+            best_id = tid
+            best_score = score
+    if best_score > 0 and best_id:
+        return best_id
+    defaults = {
+        "poster": "poster_zh_promo",
+        "ui": "ui_mobile_home",
+        "diagram": "diagram_system",
+        "product": "product_hero",
+        "illustration": "illustration_scene",
+    }
+    return defaults.get(asset_type, asset_type)
+
+
+def infer_layout(template_id: str, asset_type: str) -> str:
+    if template_id in TEMPLATE_DEFS:
+        return str(TEMPLATE_DEFS[template_id]["layout"])
+    fallback = {
+        "photography": "single realistic capture with foreground, subject, and environmental context",
+        "character": "reference sheet grid with turnaround, expressions, details, and palette",
+        "logo": "brand board grid with mark, wordmark, palette, type sample, and applications",
+        "infographic": "title band, main diagram, summary modules, and legend",
+    }
+    return fallback.get(asset_type, "clear composition with named regions and stable visual hierarchy")
+
+
+def infer_text_hierarchy(asset_type: str, texts: list[str], request: str) -> list[dict]:
+    if not texts:
+        return []
+    roles = []
+    for idx, text in enumerate(texts):
+        role = "label"
+        area = "content area"
+        priority = "medium"
+        if asset_type == "poster":
+            if idx == 0:
+                role, area, priority = "headline", "largest title zone", "high"
+            elif re.search(r"\d", text):
+                role, area, priority = "price_or_offer", "prominent price block", "high"
+            else:
+                role, area, priority = "supporting_copy", "secondary copy zone", "medium"
+        elif asset_type == "ui":
+            role, area, priority = ("app_name" if idx == 0 else "ui_label", "top header or relevant component", "high")
+        elif asset_type == "diagram":
+            role, area, priority = "component_label", "inside its corresponding node box", "high"
+        elif asset_type == "logo":
+            role, area, priority = ("wordmark" if idx == 0 else "brand_label", "brand board", "high")
+        roles.append({"text": text, "role": role, "area": area, "priority": priority})
+    return roles
+
+
+def infer_must_include(asset_type: str, template_id: str, texts: list[str]) -> list[str]:
+    base = {
+        "poster": ["main visual subject", "readable title/offer hierarchy", "clear negative space"],
+        "ui": ["device screen frame", "navigation", "primary action", "realistic content cards"],
+        "infographic": ["title band", "main diagram", "callout labels", "legend"],
+        "diagram": ["labeled components", "directional arrows", "legend or flow semantics"],
+        "product": ["single hero product", "visible material texture", "controlled studio lighting"],
+        "photography": ["realistic subject", "specific scene details", "natural imperfections"],
+        "character": ["consistent character identity", "turnaround views", "expression close-ups"],
+        "illustration": ["main subject", "environment details", "controlled palette"],
+        "logo": ["original mark", "wordmark", "palette swatches", "application mockups"],
+    }.get(asset_type, ["main subject", "clear visual hierarchy"])
+    if template_id == "diagram_rag":
+        base = ["User node", "Retriever node", "Vector DB node", "LLM node", "Answer node", "left-to-right arrows"]
+    if texts:
+        base.append("reserved readable text zones")
+    return base
+
+
+def infer_acceptance_criteria(spec: dict) -> list[str]:
+    criteria = [
+        f"Image uses {spec['aspect']} composition and matches {spec['asset_type']} intent.",
+        "Main subject is visible and matches the request.",
+        "Composition follows the named layout without incoherent overlap.",
+        "No fake logos, garbled filler text, or unrelated decorative clutter.",
+    ]
+    if spec.get("required_text"):
+        criteria.append("Every required text string appears exactly once, unchanged, and readable.")
+    if spec["asset_type"] in {"diagram", "ui", "infographic"}:
+        criteria.append("Labels are large enough to read and aligned to their components.")
+    if spec["asset_type"] == "product":
+        criteria.append("Product material and silhouette are clear, with no CGI-plastic tell.")
+    if spec.get("strict_text"):
+        criteria.append("Generated image reserves clean text areas; final text is applied from text_overlay_spec.")
+    return criteria
+
+
+def overlay_align_hint(item: dict) -> str:
+    role = str(item.get("role") or "")
+    if role in {"price_or_offer", "supporting_copy"}:
+        return "center"
+    if role in {"component_label", "ui_label"}:
+        return "center"
+    return "center"
+
+
+def overlay_box_hint(spec: dict, item: dict, idx: int, total: int) -> list[float]:
+    """返回归一化 box: x, y, w, h。用于 deterministic text overlay。"""
+    asset_type = str(spec.get("asset_type") or "")
+    role = str(item.get("role") or "")
+    area = str(item.get("area") or "")
+
+    if asset_type == "poster":
+        if role == "headline" or "largest title" in area:
+            return [0.08, 0.08, 0.84, 0.16]
+        if role == "price_or_offer" or "price" in area:
+            return [0.58, 0.72, 0.34, 0.12]
+        return [0.08, 0.72, 0.50, 0.10]
+    if asset_type == "ui":
+        return [0.12, 0.08 + idx * 0.10, 0.76, 0.08]
+    if asset_type == "diagram":
+        count = max(1, total)
+        width = min(0.24, 0.82 / count)
+        gap = (0.84 - width * count) / max(1, count - 1) if count > 1 else 0
+        return [0.08 + idx * (width + gap), 0.42, width, 0.11]
+    if asset_type == "infographic":
+        if idx == 0:
+            return [0.08, 0.06, 0.84, 0.12]
+        return [0.10, 0.22 + (idx - 1) * 0.14, 0.32, 0.09]
+    if asset_type == "logo":
+        return [0.12, 0.72, 0.76, 0.12]
+    if asset_type == "character":
+        return [0.06, 0.05, 0.28, 0.08]
+    if asset_type == "product":
+        return [0.10, 0.08, 0.80, 0.12]
+    return [0.10, 0.08 + idx * 0.10, 0.80, 0.10]
+
+
+def build_text_overlay_spec(spec: dict) -> dict:
+    overlays = []
+    items = spec.get("text_hierarchy", [])
+    for idx, item in enumerate(items):
+        overlays.append(
+            {
+                "text": item["text"],
+                "role": item["role"],
+                "target_area": item["area"],
+                "priority": item["priority"],
+                "box": overlay_box_hint(spec, item, idx, len(items)),
+                "align": overlay_align_hint(item),
+                "font_weight": "semibold" if item["priority"] == "high" else "regular",
+                "style": "crisp typography, high contrast, no distortion",
+            }
+        )
+    return {
+        "mode": "postprocess_overlay",
+        "reason": "Strict text mode keeps exact copy out of the generative image pass to improve text reliability.",
+        "overlays": overlays,
+        "rules": [
+            "Render text after image generation with exact string matching.",
+            "Do not translate, rewrite, or stylize text into illegibility.",
+            "Keep text inside reserved clear areas with sufficient contrast.",
+        ],
+    }
+
+
+def build_spec(args: argparse.Namespace) -> dict:
+    request = args.request_text
+    safe_request, safety_notes = sanitize_reference_risks(request)
+    profile, _ = read_profile()
+    asset_type = route_asset_type(safe_request, getattr(args, "asset_type", None))
+    texts = extract_required_texts(request, getattr(args, "text", None) or [])
+    aspect = infer_aspect(request, asset_type, getattr(args, "aspect", None), profile)
+    size = infer_size(aspect, getattr(args, "size", None), asset_type)
+    quality = infer_quality(request, asset_type, texts, getattr(args, "quality", None), profile)
+    subject = getattr(args, "subject", None) or safe_request
+    template_id = infer_template_id(safe_request, asset_type, getattr(args, "template", None))
+    negative = list(dict.fromkeys(infer_negative(asset_type, texts, profile) + safety_avoid_list(safety_notes)))
+    spec = {
+        "schema_version": SCHEMA_VERSION,
+        "compiler_version": COMPILER_VERSION,
+        "request": request,
+        "safe_request": safe_request,
+        "safety_rewrite": safety_notes,
+        "asset_type": asset_type,
+        "asset_title": ASSET_ROUTES[asset_type]["title"],
+        "template_id": template_id,
+        "template_label": TEMPLATE_DEFS.get(template_id, {}).get("label", ASSET_ROUTES[asset_type]["title"]),
+        "aspect": aspect,
+        "size": size,
+        "quality": quality,
+        "subject": subject,
+        "required_text": texts,
+        "strict_text": bool(getattr(args, "strict_text", False)),
+        "layout": getattr(args, "layout", None) or infer_layout(template_id, asset_type),
+        "text_hierarchy": infer_text_hierarchy(asset_type, texts, request),
+        "style_anchors": infer_style_anchors(safe_request, getattr(args, "style", None), profile),
+        "materials": split_csv(getattr(args, "materials", None)) or ["tactile, specific visible materials chosen for the subject"],
+        "lighting": getattr(args, "lighting", None) or "controlled, readable light with clear subject hierarchy",
+        "palette": split_csv(getattr(args, "palette", None)) or ["restrained palette matched to the asset type"],
+        "negative": negative,
+        "must_include": infer_must_include(asset_type, template_id, texts),
+        "must_avoid": negative,
+        "tags": infer_tags(asset_type, request, getattr(args, "tags", None)),
+    }
+    spec["acceptance_criteria"] = infer_acceptance_criteria(spec)
+    if spec["strict_text"]:
+        spec["text_overlay_spec"] = build_text_overlay_spec(spec)
+    return spec
+
+
+def exact_text_block(texts: list[str]) -> str:
+    if not texts:
+        return "No required in-image text unless explicitly useful; avoid decorative fake text."
+    quoted = " / ".join(f'"{t}"' for t in texts)
+    return (
+        "The image must accurately display these exact strings, unchanged and large enough to read: "
+        f"{quoted}. Use crisp, legible typography; keep Chinese text exactly as written."
+    )
+
+
+def reserved_text_block(spec: dict) -> str:
+    if not spec.get("required_text"):
+        return "No required in-image text unless explicitly useful; avoid decorative fake text."
+    roles = ", ".join(f"{item['role']} in {item['area']}" for item in spec.get("text_hierarchy", []))
+    return (
+        "Strict text mode: do not render the exact copy in the generated image. "
+        f"Reserve clean, high-contrast text areas for later overlay ({roles}). "
+        "Use subtle placeholder-free layout guides only; no fake characters."
+    )
+
+
+def render_visual_prompt(spec: dict) -> str:
+    visual_spec = dict(spec)
+    visual_spec["required_text"] = []
+    prompt = render_prompt(visual_spec)
+    return prompt + "\n" + reserved_text_block(spec)
+
+
+def render_prompt(spec: dict) -> str:
+    if spec.get("strict_text") and spec.get("required_text"):
+        return render_visual_prompt(spec)
+    asset_type = spec["asset_type"]
+    style = "; ".join(spec["style_anchors"])
+    materials = ", ".join(spec["materials"])
+    palette = ", ".join(spec["palette"])
+    negative = "; ".join(spec["negative"])
+    must_include = ", ".join(spec.get("must_include", []))
+    text_block = exact_text_block(spec["required_text"])
+    aspect = spec["aspect"]
+    subject = spec["subject"]
+    layout = spec.get("layout", "clear composition with named regions")
+
+    if asset_type == "poster":
+        return "\n".join(
+            [
+                f"Design a {aspect} vertical poster for: {subject}.",
+                f"Visual direction: {style}. Use a strong layout grid, clear hierarchy, and enough negative space for a readable commercial poster.",
+                f"Template: {spec.get('template_label', 'poster')}. Layout: {layout}.",
+                f"Main subject and scene density: make the core subject specific and visible, with 5-8 relevant supporting details from the brief.",
+                f"Must include: {must_include}.",
+                f"Materials: {materials}. Lighting: {spec['lighting']}. Palette: {palette}.",
+                text_block,
+                "Promotional information hierarchy must pass the three-glance test: silhouette first, key message second, texture/details third.",
+                f"Avoid: {negative}.",
+            ]
+        )
+    if asset_type == "ui":
+        return "\n".join(
+            [
+                f"Design a production-quality {aspect} UI mockup for: {subject}.",
+                f"Visual system: {style}. Use a coherent component system, precise spacing, realistic invented data, and crisp typography.",
+                f"Template: {spec.get('template_label', 'UI')}. Layout: {layout}.",
+                "Include clear navigation, primary content cards, relevant charts/lists/actions, and believable interaction states.",
+                f"Must include: {must_include}.",
+                f"Materials: {materials}. Lighting/rendering: {spec['lighting']}. Palette: {palette}.",
+                text_block,
+                f"Avoid: {negative}.",
+            ]
+        )
+    if asset_type == "infographic":
+        return "\n".join(
+            [
+                f"Create a {aspect} educational infographic about: {subject}.",
+                f"Editorial direction: {style}. Fixed regions: title band, primary diagram, 3 concise summary modules, and a bottom legend.",
+                f"Template: {spec.get('template_label', 'infographic')}. Layout: {layout}.",
+                "Use leader lines, numbered callouts, labeled parts, and calm classroom-wall clarity.",
+                f"Must include: {must_include}.",
+                f"Materials/linework: {materials}. Lighting: {spec['lighting']}. Palette: {palette}.",
+                text_block,
+                f"Avoid: {negative}.",
+            ]
+        )
+    if asset_type == "diagram":
+        return "\n".join(
+            [
+                f"Landscape {aspect} academic system-architecture figure for: {subject}.",
+                f"Style: {style}. White background, large readable labels, clean boxes, and precise alignment.",
+                f"Template: {spec.get('template_label', 'diagram')}. Layout: {layout}.",
+                "Show layers/components, directional arrows, data/control semantics, and a small legend if useful.",
+                f"Must include: {must_include}.",
+                f"Rendering: {materials}. Palette: {palette}.",
+                text_block,
+                f"Avoid: {negative}.",
+            ]
+        )
+    if asset_type == "product":
+        return "\n".join(
+            [
+                f"/* PRODUCT_RENDER_CONFIG  VERSION: 1.0  ASPECT: {aspect} */",
+                "{",
+                f'  "SUBJECT": "{subject}",',
+                f'  "AESTHETIC": "{style}",',
+                f'  "MATERIALS": "{materials}",',
+                f'  "LIGHTING": "{spec["lighting"]}",',
+                f'  "PALETTE": "{palette}",',
+                f'  "LAYOUT": "{layout}",',
+                f'  "MUST_INCLUDE": "{must_include}",',
+                '  "COMPOSITION": "single hero product shot, low three-quarter angle, sharp foreground, editorial finish"',
+                "}",
+                text_block,
+                f"Avoid: {negative}.",
+            ]
+        )
+    if asset_type == "photography":
+        return "\n".join(
+            [
+                f"A candid documentary-style {aspect} photograph of: {subject}.",
+                f"Capture language: {style}. Natural full-frame look, unprocessed realism, ordinary imperfect details.",
+                f"Layout: {layout}.",
+                "Scene density: include 8-12 concrete visible nouns from the brief; no staged studio posing.",
+                f"Must include: {must_include}.",
+                f"Light: {spec['lighting']}. Palette: {palette}.",
+                text_block,
+                f"Avoid: {negative}.",
+            ]
+        )
+    if asset_type == "character":
+        return "\n".join(
+            [
+                f"Create a {aspect} original character design reference sheet for: {subject}.",
+                f"Art direction: {style}. Clean model-sheet clarity on a neutral background.",
+                f"Layout: {layout}.",
+                "Panels: front/side/back turnaround, 4 expression close-ups, one prop/detail breakout, and a small color swatch strip.",
+                f"Must include: {must_include}.",
+                f"Materials/linework: {materials}. Lighting: {spec['lighting']}. Palette: {palette}.",
+                text_block,
+                f"Avoid: {negative}; avoid resemblance to existing IP.",
+            ]
+        )
+    if asset_type == "logo":
+        return "\n".join(
+            [
+                f"Create a {aspect} brand identity presentation board for: {subject}.",
+                f"Brand direction: {style}. Show an original geometric mark, wordmark, color palette, typography sample, and two small application mockups.",
+                f"Layout: {layout}. Must include: {must_include}.",
+                f"Materials: {materials}. Palette: {palette}.",
+                text_block,
+                f"Avoid: {negative}; no stock clip-art, no resemblance to real-world brands.",
+            ]
+        )
+    return "\n".join(
+        [
+            f"Create a {aspect} stylized illustration for: {subject}.",
+            f"Art direction: {style}. Use concrete subject details, controlled composition, and a clear visual hierarchy.",
+            f"Template: {spec.get('template_label', 'illustration')}. Layout: {layout}. Must include: {must_include}.",
+            f"Materials/texture: {materials}. Lighting: {spec['lighting']}. Palette: {palette}.",
+            text_block,
+            f"Avoid: {negative}.",
+        ]
+    )
+
+
+def lint_prompt(prompt: str, asset_type: str | None, quality: str | None, required_texts: list[str]) -> list[dict]:
+    findings: list[dict] = []
+
+    def add(severity: str, rule: str, message: str) -> None:
+        findings.append({"severity": severity, "rule": rule, "message": message})
+
+    compact = prompt.strip()
+    lower = compact.lower()
+    if len(compact) < 80:
+        add("error", "prompt.too_short", "Prompt 太短，缺少可执行的视觉约束。")
+    if not re.search(r"\b(3:4|4:3|16:9|9:16|1:1|portrait|landscape|square)\b", lower):
+        add("error", "prompt.missing_aspect", "Prompt 缺少画幅/宽高比/制品类型开场。")
+    if not re.search(r"\b(avoid|no |without|不要|避免)\b", lower):
+        add("warning", "prompt.missing_negative", "Prompt 缺少针对常见失败模式的否定项。")
+    for text in required_texts:
+        quoted_patterns = [
+            f'"{re.escape(text)}"',
+            f"“{re.escape(text)}”",
+            f"「{re.escape(text)}」",
+            f"『{re.escape(text)}』",
+        ]
+        if not any(re.search(pat, compact) for pat in quoted_patterns):
+            add("error", "text.not_quoted", f"必显文字未用引号包住：{text}")
+    if (required_texts or asset_type in {"poster", "ui", "infographic", "diagram", "logo"}) and quality and quality != "high":
+        add("error", "quality.not_high", "文字/海报/UI/图表类转化应使用 high quality。")
+    if has_cjk(compact) and not re.search(r"(garbled|legible|readable|乱码|可读|清晰)", lower):
+        add("warning", "text.no_legibility_guard", "含中文文字时建议加入 legible / no garbled characters 约束。")
+    buzz_hits = [word for word in BUZZWORDS if word in lower]
+    if len(buzz_hits) >= 3:
+        add("warning", "prompt.too_many_buzzwords", "空泛形容词过多，建议换成具体材料、光照、构图。")
+    if "logo" in lower and "no real" not in lower and "fake logo" not in lower and "真实品牌" not in compact:
+        add("warning", "brand.logo_guard", "涉及 logo 时建议明确 no real brand logos / original mark。")
+    return findings
+
+
+def print_lint(findings: list[dict]) -> None:
+    if not findings:
+        print("lint: pass")
+        return
+    for item in findings:
+        print(f"{item['severity']}: {item['rule']} - {item['message']}")
+
+
+def sample_record(
+    *,
+    request: str,
+    prompt: str,
+    verdict: str,
+    reason: str = "",
+    image: str = "",
+    size: str = "",
+    quality: str = "",
+    tags: list[str] | None = None,
+    spec: dict | None = None,
+    source: str = "convert",
+    confidence: str = "medium",
+    scope: str = "",
+) -> dict:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "compiler_version": COMPILER_VERSION,
+        "id": new_id(),
+        "ts": now_iso(),
+        "request": request,
+        "prompt": prompt,
+        "verdict": verdict,
+        "reason": reason,
+        "image": image,
+        "size": size,
+        "quality": quality,
+        "tags": tags or [],
+        "spec": spec or {},
+        "source": source,
+        "confidence": confidence,
+        "scope": scope,
+    }
+
+
+def cmd_samples(args: argparse.Namespace) -> int:
+    action = args.action
+    if action == "add":
+        rec = sample_record(
+            request=args.request or "",
+            prompt=args.prompt or "",
+            verdict=args.verdict or "pending",
+            reason=args.reason or "",
+            image=args.image or "",
+            size=args.size or "",
+            quality=args.quality or "",
+            tags=split_csv(args.tags),
+            source=args.source or "manual",
+            confidence=args.confidence or "medium",
+            scope=args.scope or "",
+        )
+        append_jsonl(samples_path(), rec)
+        print(rec["id"])
+        return 0
+    if action == "search":
+        records = read_jsonl(samples_path())
+        query = (args.query or "").lower()
+        terms = [t for t in re.split(r"[\s,]+", query) if t]
+
+        def term_score(term: str, rec: dict) -> int:
+            s = 0
+            tags = [t.lower() for t in rec.get("tags", [])]
+            if term in tags:
+                s += 10  # tag 精确命中权重最高
+            text = (rec.get("request", "") + " " + rec.get("prompt", "")).lower()
+            if term.isascii() and term.isalpha() and len(term) <= 4:
+                # 短英文词用词边界，避免 ui 误命中 build/gui 这类子串噪声
+                s += 2 * len(re.findall(rf"\b{re.escape(term)}\b", text))
+            else:
+                s += text.count(term)
+            return s
+
+        scored = []
+        for rec in records:
+            if args.verdict and rec.get("verdict") != args.verdict:
+                continue
+            score = sum(term_score(t, rec) for t in terms) if terms else 1
+            if score > 0:
+                # 采纳样本优先，其次按时间倒序
+                bonus = 5 if rec.get("verdict") == "accept" else 0
+                scored.append((score + bonus, rec.get("ts", ""), rec))
+        scored.sort(key=lambda x: (x[0], x[1]), reverse=True)
+        hits = [r for _, _, r in scored][: args.limit]
+        if args.json:
+            print(json.dumps(hits, ensure_ascii=False, indent=2))
+        else:
+            if not hits:
+                print("（无匹配样本）")
+            for rec in hits:
+                print(f"\n● [{rec.get('verdict')}] {rec.get('id')}  tags={rec.get('tags')}")
+                print(f"  需求: {rec.get('request')}")
+                print(f"  prompt: {rec.get('prompt')[:400]}")
+                if rec.get("reason"):
+                    print(f"  反馈: {rec.get('reason')}")
+        return 0
+    if action == "list":
+        records = read_jsonl(samples_path())[-args.limit :]
+        print(json.dumps(records, ensure_ascii=False, indent=2))
+        return 0
+    print(f"未知 samples 动作：{action}", file=sys.stderr)
+    return 2
+
+
+def cmd_feedback(args: argparse.Namespace) -> int:
+    records = read_jsonl(samples_path())
+    if not records:
+        print("没有任何样本记录。", file=sys.stderr)
+        return 1
+    target = args.id
+    if target in (None, "", "last"):
+        idx = len(records) - 1
+    else:
+        idx = next((i for i, r in enumerate(records) if r.get("id") == target), None)
+        if idx is None:
+            print(f"找不到样本 id：{target}", file=sys.stderr)
+            return 1
+    records[idx]["verdict"] = args.verdict
+    if args.reason:
+        records[idx]["reason"] = args.reason
+    if args.category:
+        records[idx]["failure_category"] = args.category
+    if args.image:
+        records[idx]["image"] = args.image
+    records[idx]["feedback_ts"] = now_iso()
+    rewrite_jsonl(samples_path(), records)
+    print(f"已记录反馈：{records[idx]['id']} -> {args.verdict}")
+    print("提示：若这条揭示了稳定口味，记得 `profile note` 或 `profile set` 沉淀到偏好档案。")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# judge：CLI 只存储 agent 给出的评分，自己不看图、不评分、不调 Codex
+# --------------------------------------------------------------------------- #
+JUDGE_RUBRIC = {
+    "text_accuracy": "图中文字是否与 prompt 要求逐字一致、无乱码（无文字给 10）",
+    "composition": "构图/布局/层级是否清晰",
+    "style_match": "是否贴合 prompt 指定的风格锚点",
+    "artifacts": "反向分，10=无瑕疵，0=明显畸变/多指/糊",
+    "verdict": "任一轴 <=5 则 revise，否则 pass",
+    "failure_category": "verdict=revise 时建议填 text_error/layout_error/missing_subject/wrong_style/too_cluttered/bad_composition/brand_risk/low_readability",
+}
+
+
+def cmd_judge(args: argparse.Namespace) -> int:
+    if args.action == "rubric":
+        print(json.dumps(JUDGE_RUBRIC, ensure_ascii=False, indent=2))
+        print(
+            '\n评分由 agent（具备视觉）对照 prompt 给出后，用：\n'
+            '  judge record --image <path> --prompt "<prompt>" '
+            "--score '{\"text_accuracy\":9,\"composition\":8,\"style_match\":9,"
+            '"artifacts":9,"verdict":"pass","notes":"..."}\''
+        )
+        return 0
+    if args.action == "record":
+        if not args.image or not args.prompt or not args.score:
+            print("用法：judge record --image path --prompt \"...\" --score '<json>'", file=sys.stderr)
+            return 2
+        try:
+            score = json.loads(args.score)
+        except json.JSONDecodeError as exc:
+            print(f"--score 不是合法 JSON：{exc}", file=sys.stderr)
+            return 2
+        if not isinstance(score, dict):
+            print("--score 必须是 JSON 对象（含 verdict 等字段）", file=sys.stderr)
+            return 2
+        rec = {
+            "ts": now_iso(),
+            "image": str(Path(args.image).expanduser()),
+            "prompt": args.prompt,
+            "score": score,
+            "sample_id": args.sample_id or "",
+        }
+        append_jsonl(judgements_path(), rec)
+        print(f"已记录评分 verdict={score.get('verdict', '?')}")
+        return 0
+    if args.action == "list":
+        recs = read_jsonl(judgements_path())[-args.limit :]
+        print(json.dumps(recs, ensure_ascii=False, indent=2))
+        return 0
+    print(f"未知 judge 动作：{args.action}", file=sys.stderr)
+    return 2
+
+
+# --------------------------------------------------------------------------- #
+# handoff：把 prompt 包装成可交给 Codex 的现成指令块（只打印，不执行）
+# --------------------------------------------------------------------------- #
+HANDOFF_HEADER = (
+    "Use the imagegen skill with the built-in image_gen tool "
+    "(no CLI fallback, no OPENAI_API_KEY). "
+    "Use the gpt-image-2 model specifically if a model choice is exposed."
+)
+
+
+def handoff_text(prompt: str, out: str | None, size: str | None, quality: str | None, target: str) -> str:
+    save_clause = f"Save to {out}." if out else "Save under ./codex-images/<UTC-timestamp>-<n>.png."
+    spec = []
+    if size:
+        spec.append(f"at size {size}")
+    if quality:
+        spec.append(f"{quality} quality")
+    spec_clause = (" " + " ".join(spec) + ".") if spec else ""
+
+    if target == "raw":
+        return prompt
+
+    if target == "codex-image":
+        # codex-image 插件把整段 $ARGUMENTS 原样透传给 imagegen，所以这里【不加外层
+        # 引号】——prompt 内部用于精确文字的双引号（如 "山川茶事"）才不会引号冲突损坏。
+        line = " ".join(prompt.split())
+        return f"/codex-image:generate {line} {save_clause}{spec_clause} Use the gpt-image-2 model."
+
+    if target == "codex-exec":
+        instruction = (
+            f"{HANDOFF_HEADER}\n{save_clause}{spec_clause}\n"
+            "For each saved image print exactly one line: SAVED: <absolute path>\n\n"
+            f"Image prompt:\n{prompt}"
+        )
+        # 用单引号包裹，转义内部单引号
+        safe = instruction.replace("'", "'\\''")
+        return f"codex exec --full-auto --skip-git-repo-check -- '{safe}'"
+
+    raise ValueError(f"未知 target：{target}")
+
+
+def cmd_handoff(args: argparse.Namespace) -> int:
+    if not args.prompt:
+        print("用法：handoff --request \"<原始需求>\" --prompt \"<prompt>\" [--out path] [--target codex-image|codex-exec|raw]", file=sys.stderr)
+        return 2
+    if args.record_pending and not args.request:
+        print("--record-pending 需要同时提供 --request，避免样本缺少原始需求。", file=sys.stderr)
+        return 2
+
+    if args.record_pending:
+        spec = {}
+        if args.spec:
+            try:
+                spec = json.loads(args.spec)
+            except json.JSONDecodeError as exc:
+                print(f"--spec 不是合法 JSON：{exc}", file=sys.stderr)
+                return 2
+        rec = sample_record(
+            request=args.request or "",
+            prompt=args.prompt,
+            verdict="pending",
+            image=args.out or "",
+            size=args.size or "",
+            quality=args.quality or "",
+            tags=split_csv(args.tags),
+            spec=spec,
+            source="handoff",
+            confidence="medium",
+            scope=spec.get("asset_type", "") if isinstance(spec, dict) else "",
+        )
+        append_jsonl(samples_path(), rec)
+        print(f"# sample_id: {rec['id']}")
+
+    if args.target == "codex-image":
+        print("# 复制到 Claude Code 里执行（已装 codex-image 插件时）：")
+    elif args.target == "codex-exec":
+        print("# 终端直接执行：")
+    print(handoff_text(args.prompt, args.out, args.size, args.quality, args.target))
+    return 0
+
+
+def cmd_lint(args: argparse.Namespace) -> int:
+    prompt = args.prompt or ""
+    findings = lint_prompt(prompt, args.asset_type, args.quality, args.text or [])
+    if args.json:
+        print(json.dumps({"findings": findings}, ensure_ascii=False, indent=2))
+    else:
+        print_lint(findings)
+    return 1 if any(item["severity"] == "error" for item in findings) else 0
+
+
+def cmd_convert(args: argparse.Namespace) -> int:
+    if isinstance(args.request_text, list):
+        args.request_text = " ".join(args.request_text)
+    if not args.request_text:
+        print("用法：convert \"<自然语言画图需求>\"", file=sys.stderr)
+        return 2
+    spec = build_spec(args)
+    prompt = render_prompt(spec)
+    lint_texts = [] if spec.get("strict_text") else spec["required_text"]
+    findings = lint_prompt(prompt, spec["asset_type"], spec["quality"], lint_texts)
+
+    if args.record_pending:
+        rec = sample_record(
+            request=spec["request"],
+            prompt=prompt,
+            verdict="pending",
+            image=args.out or "",
+            size=spec["size"],
+            quality=spec["quality"],
+            tags=spec["tags"],
+            spec=spec,
+            source="convert",
+            confidence="medium",
+            scope=spec["asset_type"],
+        )
+        append_jsonl(samples_path(), rec)
+        spec["sample_id"] = rec["id"]
+
+    handoff = None if args.no_handoff else handoff_text(prompt, args.out, spec["size"], spec["quality"], args.target)
+
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "spec": spec,
+                    "prompt": prompt,
+                    "text_overlay_spec": spec.get("text_overlay_spec"),
+                    "acceptance_criteria": spec.get("acceptance_criteria", []),
+                    "lint": findings,
+                    "handoff": handoff,
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+        return 1 if any(item["severity"] == "error" for item in findings) else 0
+
+    print("## Prompt")
+    print(prompt)
+    print()
+    print(f"推荐：size={spec['size']} quality={spec['quality']} asset_type={spec['asset_type']}")
+    print()
+    print("## Lint")
+    print_lint(findings)
+    if handoff:
+        print()
+        print("## Handoff")
+        print(handoff)
+    if spec.get("text_overlay_spec"):
+        print()
+        print("## Text Overlay Spec")
+        print(json.dumps(spec["text_overlay_spec"], ensure_ascii=False, indent=2))
+    print()
+    print("## Acceptance Criteria")
+    for item in spec.get("acceptance_criteria", []):
+        print(f"- {item}")
+    if "sample_id" in spec:
+        print()
+        print(f"sample_id: {spec['sample_id']}")
+    return 1 if any(item["severity"] == "error" for item in findings) else 0
+
+
+def prompt_digest(prompt: str) -> str:
+    return hashlib.sha256(prompt.encode("utf-8")).hexdigest()[:12]
+
+
+def normalize_text_list(value: object) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    return [str(value)]
+
+
+def namespace_from_case(case: dict) -> argparse.Namespace:
+    request = case.get("request") or case.get("brief") or case.get("prompt_request")
+    if not request:
+        raise ValueError("case 缺少 request 字段")
+    return argparse.Namespace(
+        request_text=str(request),
+        asset_type=case.get("asset_type"),
+        aspect=case.get("aspect"),
+        text=normalize_text_list(case.get("text") or case.get("required_text")),
+        subject=case.get("subject"),
+        style=case.get("style"),
+        materials=case.get("materials"),
+        lighting=case.get("lighting"),
+        palette=case.get("palette"),
+        size=case.get("size"),
+        quality=case.get("quality"),
+        out=case.get("out"),
+        tags=case.get("tags"),
+        target=case.get("target") or "codex-image",
+        template=case.get("template") or case.get("template_id"),
+        layout=case.get("layout"),
+        strict_text=bool(case.get("strict_text", False)),
+        record_pending=False,
+        no_handoff=True,
+        json=True,
+    )
+
+
+def load_benchmark_cases(path: Path) -> list[dict]:
+    text = path.read_text(encoding="utf-8").strip()
+    if not text:
+        return []
+    if text.startswith("["):
+        data = json.loads(text)
+        if not isinstance(data, list):
+            raise ValueError("JSON benchmark 文件必须是数组或 JSONL")
+        return [dict(item) for item in data]
+    if text.startswith("{"):
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError:
+            return [json.loads(line) for line in text.splitlines() if line.strip()]
+        cases = data.get("cases") if isinstance(data, dict) else None
+        if isinstance(cases, list):
+            return [dict(item) for item in cases]
+        return [dict(data)]
+    return [json.loads(line) for line in text.splitlines() if line.strip()]
+
+
+def convert_for_benchmark(case: dict) -> dict:
+    args = namespace_from_case(case)
+    spec = build_spec(args)
+    prompt = render_prompt(spec)
+    lint_texts = [] if spec.get("strict_text") else spec["required_text"]
+    findings = lint_prompt(prompt, spec["asset_type"], spec["quality"], lint_texts)
+    return {
+        "case_id": case.get("id") or case.get("name") or "",
+        "spec": spec,
+        "prompt": prompt,
+        "prompt_digest": prompt_digest(prompt),
+        "lint": findings,
+        "acceptance_criteria": spec.get("acceptance_criteria", []),
+    }
+
+
+def cmd_benchmark(args: argparse.Namespace) -> int:
+    try:
+        cases = load_benchmark_cases(Path(args.cases).expanduser())
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"读取 benchmark cases 失败：{exc}", file=sys.stderr)
+        return 2
+    results = []
+    total_errors = 0
+    unstable = 0
+    for idx, case in enumerate(cases, start=1):
+        runs = []
+        try:
+            for _ in range(args.runs):
+                runs.append(convert_for_benchmark(case))
+        except ValueError as exc:
+            result = {"case_index": idx, "case_id": case.get("id", ""), "error": str(exc), "runs": []}
+            results.append(result)
+            total_errors += 1
+            continue
+        digests = {run["prompt_digest"] for run in runs}
+        lint_errors = [item for run in runs for item in run["lint"] if item["severity"] == "error"]
+        if lint_errors:
+            total_errors += len(lint_errors)
+        if len(digests) > 1:
+            unstable += 1
+        results.append(
+            {
+                "case_index": idx,
+                "case_id": runs[0]["case_id"] or f"case-{idx}",
+                "asset_type": runs[0]["spec"]["asset_type"],
+                "template_id": runs[0]["spec"]["template_id"],
+                "strict_text": runs[0]["spec"].get("strict_text", False),
+                "runs": args.runs,
+                "stable": len(digests) == 1,
+                "prompt_digest": runs[0]["prompt_digest"],
+                "lint_errors": lint_errors,
+                "lint_warnings": [item for run in runs for item in run["lint"] if item["severity"] == "warning"],
+                "acceptance_criteria": runs[0]["acceptance_criteria"],
+            }
+        )
+    summary = {
+        "cases": len(cases),
+        "runs_per_case": args.runs,
+        "lint_error_count": total_errors,
+        "unstable_case_count": unstable,
+        "pass": total_errors == 0 and unstable == 0,
+    }
+    output = {"summary": summary, "results": results}
+    if args.json:
+        print(json.dumps(output, ensure_ascii=False, indent=2))
+    else:
+        print(f"benchmark: cases={summary['cases']} runs={args.runs} pass={summary['pass']}")
+        for result in results:
+            if result.get("error"):
+                print(f"- {result['case_id'] or result['case_index']}: error {result['error']}")
+                continue
+            status = "PASS" if result["stable"] and not result["lint_errors"] else "FAIL"
+            print(
+                f"- {result['case_id']}: {status} asset={result['asset_type']} "
+                f"template={result['template_id']} digest={result['prompt_digest']}"
+            )
+            for item in result["lint_errors"]:
+                print(f"  error: {item['rule']} - {item['message']}")
+    return 0 if summary["pass"] else 1
+
+
+def find_sample(sample_id: str) -> tuple[list[dict], int] | tuple[None, None]:
+    records = read_jsonl(samples_path())
+    if not records:
+        return None, None
+    if sample_id in ("", "last"):
+        return records, len(records) - 1
+    idx = next((i for i, rec in enumerate(records) if rec.get("id") == sample_id), None)
+    if idx is None:
+        return None, None
+    return records, idx
+
+
+def revise_from_spec(spec: dict, category: str) -> tuple[dict, str, list[str]]:
+    playbook = FAILURE_PLAYBOOK[category]
+    revised = dict(spec)
+    revised["compiler_version"] = COMPILER_VERSION
+    revised["revision_reason"] = category
+    revised["revision_label"] = playbook["label"]
+    revised.setdefault("negative", [])
+    for item in playbook["add_negative"]:
+        if item not in revised["negative"]:
+            revised["negative"].append(item)
+    revised["must_avoid"] = list(dict.fromkeys((revised.get("must_avoid") or []) + playbook["add_negative"]))
+    criteria = list(revised.get("acceptance_criteria") or [])
+    criteria.append(f"Revision addresses {category}: {playbook['label']}.")
+    revised["acceptance_criteria"] = criteria
+    if category == "text_error" and revised.get("required_text"):
+        revised["strict_text"] = True
+        revised["text_overlay_spec"] = build_text_overlay_spec(revised)
+    if category in {"layout_error", "bad_composition", "too_cluttered"}:
+        revised["layout"] = (
+            str(revised.get("layout") or "clear layout")
+            + "; stronger region boundaries, fixed reading order, no overlapping elements"
+        )
+    if category == "missing_subject":
+        revised["subject"] = f"{revised.get('subject', '').strip()} — main subject must dominate the frame"
+    prompt = render_prompt(revised)
+    return revised, prompt, [playbook["revision"]]
+
+
+def revise_plain_prompt(prompt: str, category: str) -> tuple[str, list[str]]:
+    playbook = FAILURE_PLAYBOOK[category]
+    additions = [
+        "",
+        f"Revision focus: {playbook['revision']}",
+        "Additional avoid constraints: " + "; ".join(playbook["add_negative"]) + ".",
+    ]
+    return prompt.rstrip() + "\n".join(additions), [playbook["revision"]]
+
+
+def cmd_revise(args: argparse.Namespace) -> int:
+    if args.list_reasons:
+        print(json.dumps(FAILURE_PLAYBOOK, ensure_ascii=False, indent=2))
+        return 0
+    category = args.reason
+    if category not in FAILURE_PLAYBOOK:
+        print(f"未知失败分类：{category}", file=sys.stderr)
+        return 2
+    sample = None
+    if args.sample_id:
+        records, idx = find_sample(args.sample_id)
+        if records is None or idx is None:
+            print(f"找不到样本：{args.sample_id}", file=sys.stderr)
+            return 1
+        sample = records[idx]
+    if sample:
+        spec = sample.get("spec") or {}
+        base_prompt = sample.get("prompt", "")
+        request = sample.get("request", "")
+    else:
+        spec = json.loads(args.spec) if args.spec else {}
+        base_prompt = args.prompt or ""
+        request = args.request or ""
+    if spec:
+        revised_spec, revised_prompt, changes = revise_from_spec(spec, category)
+    else:
+        if not base_prompt:
+            print("没有可修订的 spec 或 prompt。请提供 --sample-id、--spec 或 --prompt。", file=sys.stderr)
+            return 2
+        revised_spec = {}
+        revised_prompt, changes = revise_plain_prompt(base_prompt, category)
+    findings = lint_prompt(
+        revised_prompt,
+        revised_spec.get("asset_type") if revised_spec else None,
+        revised_spec.get("quality") if revised_spec else None,
+        [] if revised_spec.get("strict_text") else revised_spec.get("required_text", []),
+    )
+    new_sample_id = ""
+    if args.record_pending:
+        rec = sample_record(
+            request=request,
+            prompt=revised_prompt,
+            verdict="pending",
+            reason=f"revised from {category}",
+            image=args.out or "",
+            size=revised_spec.get("size", ""),
+            quality=revised_spec.get("quality", ""),
+            tags=revised_spec.get("tags", []),
+            spec=revised_spec,
+            source="revise",
+            confidence="medium",
+            scope=revised_spec.get("asset_type", ""),
+        )
+        append_jsonl(samples_path(), rec)
+        new_sample_id = rec["id"]
+    result = {
+        "reason": category,
+        "reason_label": FAILURE_PLAYBOOK[category]["label"],
+        "changes": changes,
+        "spec": revised_spec,
+        "prompt": revised_prompt,
+        "text_overlay_spec": revised_spec.get("text_overlay_spec") if revised_spec else None,
+        "lint": findings,
+        "sample_id": new_sample_id,
+    }
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"reason: {category} ({FAILURE_PLAYBOOK[category]['label']})")
+        print("## Revised Prompt")
+        print(revised_prompt)
+        if result["text_overlay_spec"]:
+            print("\n## Text Overlay Spec")
+            print(json.dumps(result["text_overlay_spec"], ensure_ascii=False, indent=2))
+        print("\n## Lint")
+        print_lint(findings)
+        if new_sample_id:
+            print(f"\nsample_id: {new_sample_id}")
+    return 1 if any(item["severity"] == "error" for item in findings) else 0
+
+
+# --------------------------------------------------------------------------- #
+# overlay / visual gates：把“高质量”变成可执行后处理与回归门
+# --------------------------------------------------------------------------- #
+def load_json_value(value: str | None) -> dict:
+    if not value:
+        return {}
+    raw = value.strip()
+    if raw.startswith("@"):
+        raw = Path(raw[1:]).expanduser().read_text(encoding="utf-8")
+    elif raw.startswith("{"):
+        pass
+    else:
+        path = Path(raw).expanduser()
+        if path.exists():
+            raw = path.read_text(encoding="utf-8")
+    data = json.loads(raw)
+    if not isinstance(data, dict):
+        raise ValueError("JSON 必须是对象")
+    return data
+
+
+def extract_spec_payload(data: dict) -> dict:
+    if "spec" in data and isinstance(data["spec"], dict):
+        return data["spec"]
+    if "compiled" in data and isinstance(data["compiled"], dict):
+        compiled = data["compiled"]
+        if isinstance(compiled.get("spec"), dict):
+            return compiled["spec"]
+    if "reference_sheet" in data and isinstance(data["reference_sheet"], dict):
+        sheet = data["reference_sheet"]
+        if isinstance(sheet.get("spec"), dict):
+            return sheet["spec"]
+    return data
+
+
+def default_overlay_out(image_path: Path) -> Path:
+    return image_path.with_name(f"{image_path.stem}.final{image_path.suffix or '.png'}")
+
+
+def font_candidates() -> list[str]:
+    return [
+        "/System/Library/Fonts/PingFang.ttc",
+        "/System/Library/Fonts/Hiragino Sans GB.ttc",
+        "/System/Library/Fonts/Supplemental/Songti.ttc",
+        "/System/Library/Fonts/Supplemental/Arial Unicode.ttf",
+        "/Library/Fonts/Arial Unicode.ttf",
+        "/System/Library/Fonts/Helvetica.ttc",
+    ]
+
+
+def choose_font_path(explicit: str | None = None) -> str | None:
+    if explicit:
+        path = Path(explicit).expanduser()
+        return str(path) if path.exists() else explicit
+    for item in font_candidates():
+        if Path(item).exists():
+            return item
+    return None
+
+
+def load_pil_font(size: int, font_path: str | None):
+    from PIL import ImageFont
+
+    if font_path:
+        try:
+            return ImageFont.truetype(font_path, size=size)
+        except OSError:
+            pass
+    try:
+        return ImageFont.truetype("Arial.ttf", size=size)
+    except OSError:
+        return ImageFont.load_default()
+
+
+def text_bbox(draw, text: str, font) -> tuple[int, int]:
+    bbox = draw.multiline_textbbox((0, 0), text, font=font, spacing=max(2, int(getattr(font, "size", 12) * 0.14)))
+    return max(1, bbox[2] - bbox[0]), max(1, bbox[3] - bbox[1])
+
+
+def wrap_text(draw, text: str, font, max_width: int) -> str:
+    if not text:
+        return ""
+    if text_bbox(draw, text, font)[0] <= max_width:
+        return text
+    lines: list[str] = []
+    current = ""
+    tokens = list(text) if has_cjk(text) else re.split(r"(\s+)", text)
+    for token in tokens:
+        candidate = current + token
+        if current and text_bbox(draw, candidate, font)[0] > max_width:
+            lines.append(current.rstrip())
+            current = token.lstrip()
+        else:
+            current = candidate
+    if current.strip():
+        lines.append(current.strip())
+    return "\n".join(lines)
+
+
+def fit_overlay_text(draw, text: str, box: tuple[int, int, int, int], font_path: str | None):
+    max_width = max(8, box[2] - box[0])
+    max_height = max(8, box[3] - box[1])
+    lo, hi = 8, max(12, int(max_height * 0.72))
+    best_font = load_pil_font(lo, font_path)
+    best_text = text
+    while lo <= hi:
+        mid = (lo + hi) // 2
+        font = load_pil_font(mid, font_path)
+        wrapped = wrap_text(draw, text, font, max_width)
+        w, h = text_bbox(draw, wrapped, font)
+        if w <= max_width and h <= max_height:
+            best_font, best_text = font, wrapped
+            lo = mid + 1
+        else:
+            hi = mid - 1
+    return best_font, best_text
+
+
+def normalized_box_to_pixels(box: list[float], width: int, height: int) -> tuple[int, int, int, int]:
+    x, y, w, h = box
+    return (
+        int(max(0, min(1, x)) * width),
+        int(max(0, min(1, y)) * height),
+        int(max(0.01, min(1, x + w)) * width),
+        int(max(0.01, min(1, y + h)) * height),
+    )
+
+
+def overlay_spec_from_texts(texts: list[str], spec: dict | None = None) -> dict:
+    base = spec or {"asset_type": "poster", "aspect": "3:4"}
+    text_hierarchy = []
+    for idx, text in enumerate(texts):
+        role = "headline" if idx == 0 else "supporting_copy"
+        text_hierarchy.append({"text": text, "role": role, "area": "largest title zone", "priority": "high"})
+    enriched = dict(base)
+    enriched["text_hierarchy"] = text_hierarchy
+    return build_text_overlay_spec(enriched)
+
+
+def chart_overlay_to_overlays(spec: dict) -> list[dict]:
+    title = spec.get("title") or spec.get("chart_data_spec", {}).get("title") or ""
+    overlays = []
+    if title:
+        overlays.append(
+            {
+                "text": str(title),
+                "role": "headline",
+                "target_area": "chart title",
+                "box": [0.08, 0.04, 0.84, 0.10],
+                "align": "center",
+                "style": "crisp chart title",
+            }
+        )
+    return overlays
+
+
+def extract_overlay_items(spec: dict, explicit_texts: list[str] | None = None) -> list[dict]:
+    if explicit_texts:
+        return overlay_spec_from_texts(explicit_texts, spec).get("overlays", [])
+    overlay_spec = spec.get("text_overlay_spec") if isinstance(spec, dict) else None
+    if isinstance(overlay_spec, dict):
+        if overlay_spec.get("mode") == "chart_text_overlay":
+            return chart_overlay_to_overlays(overlay_spec)
+        overlays = overlay_spec.get("overlays")
+        if isinstance(overlays, list):
+            return [item for item in overlays if isinstance(item, dict)]
+    if spec.get("mode") == "chart_text_overlay":
+        return chart_overlay_to_overlays(spec)
+    if isinstance(spec.get("overlays"), list):
+        return [item for item in spec["overlays"] if isinstance(item, dict)]
+    texts = normalize_text_list(spec.get("required_text"))
+    if texts:
+        return overlay_spec_from_texts(texts, spec).get("overlays", [])
+    return []
+
+
+def draw_text_overlays(image_path: Path, out_path: Path, spec: dict, texts: list[str] | None, font_path: str | None) -> dict:
+    from PIL import Image, ImageDraw
+
+    image = Image.open(image_path).convert("RGBA")
+    width, height = image.size
+    layer = Image.new("RGBA", image.size, (0, 0, 0, 0))
+    draw = ImageDraw.Draw(layer)
+    overlays = extract_overlay_items(spec, texts)
+    font_file = choose_font_path(font_path)
+    rendered = []
+
+    for idx, item in enumerate(overlays):
+        text = str(item.get("text") or "").strip()
+        if not text:
+            continue
+        role = str(item.get("role") or "")
+        box = item.get("box")
+        if not isinstance(box, list) or len(box) != 4:
+            box = overlay_box_hint(spec, item, idx, len(overlays))
+        px = normalized_box_to_pixels([float(v) for v in box], width, height)
+        pad = max(8, int(min(width, height) * 0.012))
+        inner = (px[0] + pad, px[1] + pad, px[2] - pad, px[3] - pad)
+        font, wrapped = fit_overlay_text(draw, text, inner, font_file)
+        tw, th = text_bbox(draw, wrapped, font)
+        align = str(item.get("align") or "center")
+        if align == "left":
+            tx = inner[0]
+        elif align == "right":
+            tx = inner[2] - tw
+        else:
+            tx = inner[0] + max(0, (inner[2] - inner[0] - tw) // 2)
+        ty = inner[1] + max(0, (inner[3] - inner[1] - th) // 2)
+
+        if role == "price_or_offer":
+            fill = (31, 84, 55, 232)
+            outline = (255, 255, 255, 90)
+            text_fill = (255, 255, 245, 255)
+        else:
+            fill = (255, 255, 255, 218)
+            outline = (31, 84, 55, 65)
+            text_fill = (19, 35, 27, 255)
+        radius = max(6, int(min(px[2] - px[0], px[3] - px[1]) * 0.12))
+        draw.rounded_rectangle(px, radius=radius, fill=fill, outline=outline, width=max(1, int(pad * 0.14)))
+        draw.multiline_text((tx, ty), wrapped, font=font, fill=text_fill, align=align, spacing=max(2, int(getattr(font, "size", 12) * 0.14)))
+        rendered.append({"text": text, "box": box, "font_size": getattr(font, "size", 0), "role": role})
+
+    final = Image.alpha_composite(image, layer).convert("RGB")
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    final.save(out_path)
+    return {"image": str(image_path), "out": str(out_path), "overlay_count": len(rendered), "rendered": rendered}
+
+
+def cmd_overlay(args: argparse.Namespace) -> int:
+    try:
+        data = load_json_value(args.spec) if args.spec else {}
+        spec = extract_spec_payload(data) if data else {}
+        image_path = Path(args.image).expanduser()
+        out_path = Path(args.out).expanduser() if args.out else default_overlay_out(image_path)
+        report = draw_text_overlays(image_path, out_path, spec, args.text, args.font)
+    except Exception as exc:
+        print(f"overlay 失败：{exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print(f"overlay: rendered={report['overlay_count']} out={report['out']}")
+        for item in report["rendered"]:
+            print(f"- {item['text']} font={item['font_size']} box={item['box']}")
+    return 0 if report["overlay_count"] > 0 else 1
+
+
+def parse_aspect_ratio(value: str | None) -> float | None:
+    if not value:
+        return None
+    match = re.match(r"^\s*(\d+(?:\.\d+)?)\s*[:x×]\s*(\d+(?:\.\d+)?)\s*$", value)
+    if not match:
+        return None
+    w, h = float(match.group(1)), float(match.group(2))
+    return w / h if h else None
+
+
+def image_quality_metrics(image_path: Path, expected_aspect: str | None = None) -> dict:
+    from PIL import Image, ImageFilter, ImageStat
+
+    image = Image.open(image_path).convert("RGB")
+    width, height = image.size
+    gray = image.convert("L")
+    stat = ImageStat.Stat(gray)
+    brightness = stat.mean[0] / 255.0
+    contrast = stat.stddev[0] / 255.0
+    edge = gray.filter(ImageFilter.FIND_EDGES)
+    edge_density = ImageStat.Stat(edge).mean[0] / 255.0
+    aspect = width / height if height else 0
+    expected = parse_aspect_ratio(expected_aspect)
+    aspect_error = abs(aspect - expected) / expected if expected else 0.0
+    return {
+        "width": width,
+        "height": height,
+        "aspect": round(aspect, 4),
+        "expected_aspect": expected_aspect or "",
+        "aspect_error": round(aspect_error, 4),
+        "brightness": round(brightness, 4),
+        "contrast": round(contrast, 4),
+        "edge_density": round(edge_density, 4),
+    }
+
+
+def image_quality_findings(metrics: dict, strict: bool = False) -> list[dict]:
+    findings = []
+
+    def add(severity: str, rule: str, message: str) -> None:
+        findings.append({"severity": severity, "rule": rule, "message": message})
+
+    if metrics["width"] < 512 or metrics["height"] < 512:
+        add("error", "image.too_small", "成品图尺寸低于 512px，不适合作为高质量输出。")
+    if metrics["contrast"] < 0.045:
+        add("error", "image.low_contrast", "图像对比度过低，疑似空白、过曝或不可读。")
+    if metrics["brightness"] < 0.04 or metrics["brightness"] > 0.96:
+        add("error" if strict else "warning", "image.bad_brightness", "图像整体亮度异常。")
+    if metrics["edge_density"] < 0.008:
+        add("warning", "image.low_detail", "图像边缘细节偏少，可能过空或糊。")
+    if metrics.get("expected_aspect") and metrics["aspect_error"] > 0.18:
+        add("error", "image.aspect_mismatch", "成品图画幅与 spec 期望偏差过大。")
+    return findings
+
+
+def cmd_visual_check(args: argparse.Namespace) -> int:
+    try:
+        spec = extract_spec_payload(load_json_value(args.spec)) if args.spec else {}
+        expected = args.aspect or spec.get("aspect")
+        metrics = image_quality_metrics(Path(args.image).expanduser(), expected)
+    except Exception as exc:
+        print(f"visual-check 失败：{exc}", file=sys.stderr)
+        return 2
+    findings = image_quality_findings(metrics, args.strict)
+    result = {"image": args.image, "metrics": metrics, "findings": findings, "pass": not any(f["severity"] == "error" for f in findings)}
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result["pass"] else 1
+
+
+def center_crop(image, ratio: float = 0.36):
+    width, height = image.size
+    crop_w, crop_h = int(width * ratio), int(height * ratio)
+    left = (width - crop_w) // 2
+    top = (height - crop_h) // 2
+    return image.crop((left, top, left + crop_w, top + crop_h))
+
+
+def histogram_similarity(a, b) -> float:
+    a_hist = a.convert("RGB").histogram()
+    b_hist = b.convert("RGB").histogram()
+    total = max(1, sum(a_hist))
+    return sum(min(x, y) for x, y in zip(a_hist, b_hist)) / total
+
+
+def mean_image_difference(a, b) -> float:
+    from PIL import ImageChops, ImageStat
+
+    if a.size != b.size:
+        b = b.resize(a.size)
+    diff = ImageChops.difference(a.convert("RGB"), b.convert("RGB"))
+    stat = ImageStat.Stat(diff)
+    return sum(stat.mean) / (3 * 255.0)
+
+
+def edit_validation_report(reference: Path, output: Path, threshold: float, min_change: float) -> dict:
+    from PIL import Image
+
+    ref = Image.open(reference).convert("RGB")
+    out = Image.open(output).convert("RGB")
+    if out.size != ref.size:
+        out = out.resize(ref.size)
+    center_similarity = histogram_similarity(center_crop(ref), center_crop(out))
+    full_change = mean_image_difference(ref, out)
+    findings = []
+    if center_similarity < threshold:
+        findings.append(
+            {
+                "severity": "error",
+                "rule": "edit.subject_drift",
+                "message": "中心主体相似度低，参考图主体可能没有被稳定保留。",
+            }
+        )
+    if full_change < min_change:
+        findings.append(
+            {
+                "severity": "error",
+                "rule": "edit.no_effective_change",
+                "message": "输出图与参考图差异过小，改图目标可能没有生效。",
+            }
+        )
+    return {
+        "reference": str(reference),
+        "output": str(output),
+        "center_subject_similarity": round(center_similarity, 4),
+        "full_image_change": round(full_change, 4),
+        "threshold": threshold,
+        "min_change": min_change,
+        "findings": findings,
+        "pass": not any(item["severity"] == "error" for item in findings),
+    }
+
+
+def cmd_edit_check(args: argparse.Namespace) -> int:
+    try:
+        report = edit_validation_report(
+            Path(args.reference).expanduser(),
+            Path(args.output).expanduser(),
+            args.threshold,
+            args.min_change,
+        )
+    except Exception as exc:
+        print(f"edit-check 失败：{exc}", file=sys.stderr)
+        return 2
+    if args.json:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0 if report["pass"] else 1
+
+
+def visual_case_compile(case: dict) -> dict:
+    tool = str(case.get("tool") or case.get("cmd") or "convert")
+    if tool in {"convert", "rewrite", "adapt", "series", "compose", "brand", "character", "data-viz"}:
+        compiled = compile_visual_case(case, target=case.get("target") or "codex-image")
+        return {**compiled, "tool": tool}
+    raise ValueError(f"visual-regress 暂不支持 tool={tool}")
+
+
+def cmd_visual_regress(args: argparse.Namespace) -> int:
+    try:
+        cases = load_benchmark_cases(Path(args.cases).expanduser())
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"读取 visual cases 失败：{exc}", file=sys.stderr)
+        return 2
+    results = []
+    lint_errors = 0
+    visual_errors = 0
+    missing_images = 0
+    for idx, case in enumerate(cases, start=1):
+        case_id = case.get("id") or f"visual-{idx}"
+        try:
+            if case.get("reference") and case.get("output") and not (case.get("request") or case.get("brief")):
+                edit_report = edit_validation_report(
+                    Path(str(case["reference"])).expanduser(),
+                    Path(str(case["output"])).expanduser(),
+                    args.edit_threshold,
+                    args.edit_min_change,
+                )
+                visual_errors += sum(1 for f in edit_report["findings"] if f.get("severity") == "error")
+                results.append(
+                    {
+                        "id": case_id,
+                        "scenario": case.get("scenario") or "edit-check",
+                        "status": "edit_checked",
+                        "edit_check": edit_report,
+                    }
+                )
+                continue
+            compiled = visual_case_compile(case)
+            lint = compiled["lint"]
+            lint_errors += sum(1 for item in lint if item.get("severity") == "error")
+            item = {
+                "id": case_id,
+                "scenario": case.get("scenario") or case.get("tool") or "convert",
+                "prompt_digest": compiled["prompt_digest"],
+                "asset_type": compiled["spec"]["asset_type"],
+                "aspect": compiled["spec"]["aspect"],
+                "lint": lint,
+                "status": "compiled",
+            }
+            image = case.get("image") or case.get("output")
+            if image:
+                metrics = image_quality_metrics(Path(str(image)).expanduser(), compiled["spec"].get("aspect"))
+                findings = image_quality_findings(metrics, args.strict)
+                visual_errors += sum(1 for f in findings if f.get("severity") == "error")
+                item.update({"status": "checked", "metrics": metrics, "visual_findings": findings})
+            elif args.require_images:
+                missing_images += 1
+                item.update({"status": "missing_image", "visual_findings": [{"severity": "error", "rule": "visual.image_missing", "message": "case 缺少 image/output，无法做真实视觉回归。"}]})
+            if case.get("reference") and case.get("output"):
+                edit_report = edit_validation_report(
+                    Path(str(case["reference"])).expanduser(),
+                    Path(str(case["output"])).expanduser(),
+                    args.edit_threshold,
+                    args.edit_min_change,
+                )
+                visual_errors += sum(1 for f in edit_report["findings"] if f.get("severity") == "error")
+                item["edit_check"] = edit_report
+            results.append(item)
+        except Exception as exc:
+            visual_errors += 1
+            results.append({"id": case_id, "status": "error", "error": str(exc)})
+    summary = {
+        "cases": len(cases),
+        "lint_error_count": lint_errors,
+        "visual_error_count": visual_errors,
+        "missing_image_count": missing_images,
+        "pass": lint_errors == 0 and visual_errors == 0 and missing_images == 0,
+    }
+    output = {"summary": summary, "results": results}
+    if args.json:
+        print(json.dumps(output, ensure_ascii=False, indent=2))
+    else:
+        print(f"visual-regress: cases={summary['cases']} pass={summary['pass']} lint_errors={lint_errors} visual_errors={visual_errors} missing_images={missing_images}")
+        for item in results:
+            print(f"- {item['id']}: {item['status']} asset={item.get('asset_type', '?')} digest={item.get('prompt_digest', '?')}")
+    return 0 if summary["pass"] else 1
+
+
+# --------------------------------------------------------------------------- #
+# 真实场景命令：长输入、多图、改图、品牌/角色一致性、数据图、改写、适配
+# --------------------------------------------------------------------------- #
+def read_text_argument(parts: list[str] | None, file_path: str | None) -> str:
+    chunks: list[str] = []
+    if file_path:
+        chunks.append(Path(file_path).expanduser().read_text(encoding="utf-8"))
+    if parts:
+        chunks.append(" ".join(parts))
+    return "\n".join(chunks).strip()
+
+
+def compact_title(text: str, limit: int = 28) -> str:
+    clean = normalize_ws(re.sub(r"^[#\-\*\d\.\)、\s]+", "", text))
+    if len(clean) <= limit:
+        return clean
+    return clean[:limit].rstrip() + "..."
+
+
+def normalize_case_values(case: dict) -> dict:
+    out = dict(case)
+    for key in ("style", "materials", "palette", "tags"):
+        value = out.get(key)
+        if isinstance(value, list):
+            out[key] = ",".join(str(v) for v in value if str(v).strip())
+    return out
+
+
+def compile_visual_case(
+    case: dict,
+    *,
+    target: str = "codex-image",
+    out: str | None = None,
+    include_handoff: bool = True,
+) -> dict:
+    args = namespace_from_case(normalize_case_values(case))
+    args.target = case.get("target") or target
+    args.out = case.get("out") or out
+    spec = build_spec(args)
+    prompt = render_prompt(spec)
+    lint_texts = [] if spec.get("strict_text") else spec["required_text"]
+    findings = lint_prompt(prompt, spec["asset_type"], spec["quality"], lint_texts)
+    return {
+        "spec": spec,
+        "prompt": prompt,
+        "prompt_digest": prompt_digest(prompt),
+        "text_overlay_spec": spec.get("text_overlay_spec"),
+        "acceptance_criteria": spec.get("acceptance_criteria", []),
+        "lint": findings,
+        "handoff": handoff_text(prompt, args.out, spec["size"], spec["quality"], args.target) if include_handoff else None,
+    }
+
+
+def has_lint_error(items: list[dict]) -> bool:
+    return any(item.get("severity") == "error" for item in items)
+
+
+def split_document_sections(text: str, max_images: int) -> list[str]:
+    lines = [line.strip() for line in text.splitlines() if line.strip()]
+    marker = re.compile(r"^(#{1,6}\s+|[-*]\s+|\d+[.)、]\s+|第[一二三四五六七八九十0-9]+[章节部分步][：:\s]*)")
+    chunks: list[str] = []
+    buf: list[str] = []
+    for line in lines:
+        starts_new = bool(marker.match(line))
+        clean = marker.sub("", line).strip()
+        if starts_new and buf:
+            chunks.append(" ".join(buf).strip())
+            buf = [clean]
+        else:
+            buf.append(clean)
+    if buf:
+        chunks.append(" ".join(buf).strip())
+
+    if len(chunks) <= 1:
+        sentences = [s.strip() for s in re.split(r"(?<=[。！？!?；;])\s*", text) if s.strip()]
+        chunks = []
+        bucket = ""
+        for sentence in sentences:
+            if bucket and len(bucket) + len(sentence) > 220:
+                chunks.append(bucket.strip())
+                bucket = sentence
+            else:
+                bucket = f"{bucket} {sentence}".strip()
+        if bucket:
+            chunks.append(bucket.strip())
+
+    chunks = [c for c in chunks if len(c) >= 8]
+    if not chunks:
+        chunks = [text.strip()]
+    return chunks[: max(1, max_images)]
+
+
+def choose_compose_asset(chunk: str, index: int) -> str:
+    lower = chunk.lower()
+    if any(k in lower for k in ["架构", "系统", "模块", "链路", "rag", "llm", "retriever", "pipeline"]):
+        return "diagram"
+    if any(k in lower for k in ["数据", "指标", "报表", "趋势", "占比", "转化率", "漏斗", "图表"]):
+        return "infographic"
+    if any(k in lower for k in ["步骤", "教程", "操作", "sop", "流程", "指南", "怎么"]):
+        return "infographic"
+    if any(k in lower for k in ["ui", "界面", "app", "dashboard", "页面", "产品后台", "控制台"]):
+        return "ui"
+    if any(k in lower for k in ["产品", "商品", "包装", "电商", "渲染", "饮料", "食品"]):
+        return "product"
+    if any(k in lower for k in ["角色", "人物", "人设", "表情", "立绘"]):
+        return "character"
+    if index == 0 and any(k in lower for k in ["标题", "主题", "发布", "活动", "封面", "总结"]):
+        return "poster"
+    return "illustration"
+
+
+def infer_compose_style(text: str) -> str:
+    lower = text.lower()
+    if any(k in lower for k in ["架构", "系统", "论文", "rag", "llm", "技术"]):
+        return "clean technical editorial style, white background, strict alignment, large readable labels"
+    if any(k in lower for k in ["品牌", "营销", "活动", "海报", "新品"]):
+        return "consistent premium brand campaign style, controlled palette, clear commercial hierarchy"
+    if any(k in lower for k in ["教程", "步骤", "指南", "科普"]):
+        return "calm instructional editorial style, numbered modules, high readability"
+    return "coherent editorial visual system, concrete subject details, restrained palette, stable hierarchy"
+
+
+def extract_visual_labels(chunk: str, asset_type: str, limit: int = 5) -> list[str]:
+    labels: list[str] = []
+
+    def add(value: str) -> None:
+        value = value.strip(" \t\n\r，,。；;：:")
+        if 1 < len(value) <= 28 and value not in labels:
+            labels.append(value)
+
+    for match in re.findall(r'"([^"\n]{1,28})"|“([^”\n]{1,28})”|「([^」\n]{1,28})」', chunk):
+        add(next((m for m in match if m), ""))
+    for match in re.findall(r"\b[A-Z][A-Za-z0-9_-]{1,20}\b", chunk):
+        add(match)
+    for match in re.findall(r"(?:标题|主题|模块|步骤|节点|页面)[：:\s]*([^，。；;\n]{2,24})", chunk):
+        add(match)
+    if not labels and asset_type in {"diagram", "infographic", "ui"}:
+        add(compact_title(chunk, 18))
+    return labels[:limit]
+
+
+def compose_purpose(asset_type: str, index: int) -> str:
+    purpose_map = {
+        "poster": "封面/主视觉",
+        "diagram": "结构关系图",
+        "infographic": "信息整理图",
+        "ui": "界面概念图",
+        "product": "产品视觉图",
+        "character": "角色设定图",
+        "illustration": "场景说明图",
+    }
+    return f"{index}. {purpose_map.get(asset_type, '配图')}"
+
+
+def cmd_compose(args: argparse.Namespace) -> int:
+    text = read_text_argument(args.input_text, args.file)
+    if not text:
+        print("用法：compose \"<长输入>\" 或 compose --file doc.md", file=sys.stderr)
+        return 2
+    shared_style = args.shared_style or infer_compose_style(text)
+    chunks = split_document_sections(text, args.max_images)
+    visual_plan = []
+    for idx, chunk in enumerate(chunks, start=1):
+        asset_type = choose_compose_asset(chunk, idx - 1)
+        labels = extract_visual_labels(chunk, asset_type)
+        purpose = compose_purpose(asset_type, idx)
+        out = None
+        if args.out_dir:
+            out = str(Path(args.out_dir).expanduser() / f"compose-{idx:02d}-{asset_type}.png")
+        case = {
+            "id": f"compose-{idx:02d}",
+            "request": f"{purpose}。根据这段内容生成对应画面：{chunk}",
+            "asset_type": asset_type,
+            "style": shared_style,
+            "palette": args.palette,
+            "text": labels if (args.strict_text or asset_type in {"diagram", "infographic", "ui"}) else [],
+            "strict_text": args.strict_text,
+            "target": args.target,
+            "out": out,
+            "tags": "compose,long-input",
+        }
+        compiled = compile_visual_case(case, target=args.target, out=out)
+        visual_plan.append(
+            {
+                "id": case["id"],
+                "purpose": purpose,
+                "brief": chunk,
+                "asset_type": compiled["spec"]["asset_type"],
+                "template_id": compiled["spec"]["template_id"],
+                "prompt": compiled["prompt"],
+                "handoff": compiled["handoff"],
+                "lint": compiled["lint"],
+                "text_overlay_spec": compiled["text_overlay_spec"],
+                "acceptance_criteria": compiled["acceptance_criteria"],
+                "spec": compiled["spec"],
+            }
+        )
+    result = {
+        "summary": compact_title(text, 80),
+        "shared_style": shared_style,
+        "visual_plan": visual_plan,
+        "bundle_acceptance": [
+            "每张图对应长输入中的一个明确信息单元，不混淆主题。",
+            "整组图使用同一风格、配色和信息层级规则。",
+            "图表/架构/UI 类标签清晰可读；strict_text 时文字走 overlay_spec。",
+            "任一单图 lint 出现 error 时必须先修 prompt 再交给下游出图。",
+        ],
+    }
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"compose: {len(visual_plan)} 张图 shared_style={shared_style}")
+        for item in visual_plan:
+            status = "FAIL" if has_lint_error(item["lint"]) else "PASS"
+            print(f"\n## {item['id']} {item['purpose']} [{status}]")
+            print(item["prompt"])
+            if item["handoff"]:
+                print("\nHandoff:")
+                print(item["handoff"])
+    return 1 if any(has_lint_error(item["lint"]) for item in visual_plan) else 0
+
+
+def load_series_cases(file_path: str | None) -> list[dict | str]:
+    if not file_path:
+        return []
+    text = Path(file_path).expanduser().read_text(encoding="utf-8").strip()
+    if not text:
+        return []
+    if text.startswith("["):
+        data = json.loads(text)
+        if not isinstance(data, list):
+            raise ValueError("series JSON 文件必须是数组")
+        return data
+    if text.startswith("{"):
+        data = json.loads(text)
+        briefs = data.get("briefs") if isinstance(data, dict) else None
+        if isinstance(briefs, list):
+            return briefs
+        return [data]
+    items: list[dict | str] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        if line.startswith("{"):
+            items.append(json.loads(line))
+        else:
+            items.append(line)
+    return items
+
+
+def cmd_series(args: argparse.Namespace) -> int:
+    try:
+        items = load_series_cases(args.file)
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        print(f"读取 series 文件失败：{exc}", file=sys.stderr)
+        return 2
+    items.extend(args.brief or [])
+    if not items:
+        print("用法：series --brief \"图1\" --brief \"图2\" 或 series --file briefs.jsonl", file=sys.stderr)
+        return 2
+    shared_style = args.style or "single coherent series style, same camera language, same palette discipline, same visual density"
+    variants = []
+    for idx, item in enumerate(items, start=1):
+        case = dict(item) if isinstance(item, dict) else {"request": str(item)}
+        brief = str(case.get("request") or case.get("brief") or "")
+        if not brief:
+            print(f"series 第 {idx} 项缺少 request/brief", file=sys.stderr)
+            return 2
+        case["request"] = brief
+        if args.asset_type:
+            case["asset_type"] = args.asset_type
+        case["style"] = "; ".join([shared_style, str(case.get("style") or "").strip()]).strip("; ")
+        if args.palette:
+            case["palette"] = args.palette
+        if args.strict_text:
+            case["strict_text"] = True
+            case.setdefault("text", extract_visual_labels(brief, str(case.get("asset_type") or route_asset_type(brief))))
+        case["target"] = args.target
+        case["tags"] = "series,consistent-set"
+        compiled = compile_visual_case(case, target=args.target)
+        variants.append(
+            {
+                "id": f"series-{idx:02d}",
+                "brief": brief,
+                "asset_type": compiled["spec"]["asset_type"],
+                "prompt": compiled["prompt"],
+                "handoff": compiled["handoff"],
+                "lint": compiled["lint"],
+                "spec": compiled["spec"],
+            }
+        )
+    result = {"shared_style": shared_style, "count": len(variants), "variants": variants}
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(f"series: {len(variants)} 张图")
+        for item in variants:
+            print(f"\n## {item['id']} {item['asset_type']}")
+            print(item["prompt"])
+    return 1 if any(has_lint_error(item["lint"]) for item in variants) else 0
+
+
+def parse_reference(value: str) -> dict:
+    if ":" in value and not value.startswith("/"):
+        role, _, ref = value.partition(":")
+        if role.strip() and ref.strip():
+            return {"role": role.strip(), "ref": ref.strip()}
+    return {"role": "reference", "ref": value.strip()}
+
+
+def cmd_edit(args: argparse.Namespace) -> int:
+    if not args.goal:
+        print("用法：edit --goal \"<改图目标>\" --reference role:path --preserve ... --change ...", file=sys.stderr)
+        return 2
+    references = [parse_reference(v) for v in (args.reference or [])]
+    preserve = args.preserve or ["main subject identity, silhouette, material cues, and composition anchors"]
+    changes = args.change or [args.goal]
+    required_text = args.text or []
+    aspect = args.aspect or "3:4"
+    quality = args.quality or "high"
+    reference_block = "; ".join(f"{item['role']}={item['ref']}" for item in references) or "provided reference image(s)"
+    prompt = "\n".join(
+        [
+            f"Edit the provided reference image(s) into a {aspect} {args.asset_type} result for: {args.goal}.",
+            f"References: {reference_block}.",
+            "Preserve exactly: " + "; ".join(preserve) + ".",
+            "Change only: " + "; ".join(changes) + ".",
+            f"Visual target: {args.style or 'production-quality realistic edit, consistent lighting, no visible seams'}; quality={quality}.",
+            exact_text_block(required_text),
+            "Avoid: identity drift; unwanted background changes; mismatched perspective; fake logos; garbled text; low-resolution artifacts.",
+        ]
+    )
+    findings = lint_prompt(prompt, args.asset_type, quality, required_text)
+    result = {
+        "edit_spec": {
+            "goal": args.goal,
+            "references": references,
+            "preserve": preserve,
+            "change": changes,
+            "required_text": required_text,
+            "aspect": aspect,
+            "asset_type": args.asset_type,
+            "quality": quality,
+        },
+        "prompt": prompt,
+        "lint": findings,
+        "handoff": handoff_text(prompt, args.out, infer_size(aspect, None, args.asset_type), quality, args.target),
+    }
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print("## Edit Prompt")
+        print(prompt)
+        print("\n## Lint")
+        print_lint(findings)
+        print("\n## Handoff")
+        print(result["handoff"])
+    return 1 if has_lint_error(findings) else 0
+
+
+def cmd_brand(args: argparse.Namespace) -> int:
+    if not args.name:
+        print("用法：brand --name <品牌名> [--request <要生成的图>]", file=sys.stderr)
+        return 2
+    palette = split_csv(args.palette)
+    avoid = split_csv(args.avoid)
+    values = split_csv(args.values)
+    brand_profile = {
+        "name": args.name,
+        "industry": args.industry or "unspecified",
+        "values": values,
+        "palette": palette,
+        "style": args.style or "original, consistent, premium but restrained brand system",
+        "avoid": avoid + ["real brand logos", "stock clip-art", "existing trademark resemblance"],
+    }
+    brand_block = "\n".join(
+        [
+            f"Brand system for invented brand \"{args.name}\":",
+            f"- Industry: {brand_profile['industry']}.",
+            f"- Values: {', '.join(values) if values else 'clear, trustworthy, distinctive'}.",
+            f"- Palette: {', '.join(palette) if palette else '2-3 controlled brand colors plus neutral support'}.",
+            f"- Style: {brand_profile['style']}.",
+            "- Rules: keep mark shapes original; use the same spacing, palette, and typography logic across assets; no real brand logos.",
+            f"- Avoid: {', '.join(brand_profile['avoid'])}.",
+        ]
+    )
+    result: dict = {"brand_profile": brand_profile, "brand_prompt_block": brand_block}
+    if args.request:
+        case = {
+            "request": f"{args.request}\n{brand_block}",
+            "asset_type": args.asset_type,
+            "style": brand_profile["style"],
+            "palette": args.palette,
+            "text": args.text or [],
+            "strict_text": args.strict_text,
+            "target": args.target,
+            "tags": "brand,consistency",
+        }
+        result["compiled"] = compile_visual_case(case, target=args.target)
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(brand_block)
+        if "compiled" in result:
+            print("\n## Prompt")
+            print(result["compiled"]["prompt"])
+    compiled = result.get("compiled")
+    return 1 if compiled and has_lint_error(compiled["lint"]) else 0
+
+
+def cmd_character(args: argparse.Namespace) -> int:
+    if not args.name or not args.description:
+        print("用法：character --name <角色名> --description <外观设定> [--scene ...]", file=sys.stderr)
+        return 2
+    palette = split_csv(args.palette)
+    bible = {
+        "name": args.name,
+        "description": args.description,
+        "style": args.style or "original character model-sheet clarity, no existing IP resemblance",
+        "outfit": args.outfit or "stable signature outfit and silhouette",
+        "palette": palette,
+        "consistency_rules": [
+            "same face shape, hair silhouette, outfit anchors, and palette in every image",
+            "do not copy or resemble existing IP characters",
+            "describe identity anchors before scene action in every prompt",
+        ],
+    }
+    identity = (
+        f"Original character \"{args.name}\": {args.description}. "
+        f"Outfit anchors: {bible['outfit']}. Palette: {', '.join(palette) if palette else 'stable limited palette'}. "
+        "Keep the same identity anchors in every image; no existing IP resemblance."
+    )
+    reference_case = {
+        "request": f"角色设定三视图和表情板：{identity}",
+        "asset_type": "character",
+        "style": bible["style"],
+        "palette": args.palette,
+        "text": [args.name],
+        "target": args.target,
+        "tags": "character,consistency",
+    }
+    reference = compile_visual_case(reference_case, target=args.target)
+    scenes = []
+    for idx, scene in enumerate(args.scene or [], start=1):
+        case = {
+            "request": f"{identity} 场景图：{scene}",
+            "asset_type": "illustration",
+            "style": bible["style"],
+            "palette": args.palette,
+            "target": args.target,
+            "tags": "character,scene",
+        }
+        compiled = compile_visual_case(case, target=args.target)
+        scenes.append({"id": f"scene-{idx:02d}", "scene": scene, **compiled})
+    result = {"character_bible": bible, "reference_sheet": reference, "scene_prompts": scenes}
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(json.dumps(bible, ensure_ascii=False, indent=2))
+        print("\n## Reference Sheet Prompt")
+        print(reference["prompt"])
+        for item in scenes:
+            print(f"\n## {item['id']}")
+            print(item["prompt"])
+    return 1 if has_lint_error(reference["lint"]) or any(has_lint_error(item["lint"]) for item in scenes) else 0
+
+
+def read_data_preview(file_path: str | None) -> dict:
+    if not file_path:
+        return {"columns": [], "rows": [], "row_count": 0, "source": ""}
+    path = Path(file_path).expanduser()
+    text = path.read_text(encoding="utf-8")
+    rows: list[dict] = []
+    columns: list[str] = []
+    if path.suffix.lower() == ".json":
+        data = json.loads(text)
+        if isinstance(data, dict):
+            data = data.get("rows") or data.get("data") or data.get("items") or []
+        if isinstance(data, list):
+            rows = [dict(item) for item in data if isinstance(item, dict)]
+            columns = list(rows[0].keys()) if rows else []
+    else:
+        delimiter = "\t" if path.suffix.lower() == ".tsv" else ","
+        reader = csv.DictReader(text.splitlines(), delimiter=delimiter)
+        rows = [dict(row) for row in reader]
+        columns = list(reader.fieldnames or [])
+    return {"columns": columns, "rows": rows[:5], "row_count": len(rows), "source": str(path)}
+
+
+def infer_chart_type(request: str, columns: list[str], override: str | None) -> str:
+    if override:
+        return override
+    lower = request.lower()
+    if any(k in lower for k in ["dashboard", "看板", "仪表盘"]):
+        return "dashboard"
+    if any(k in lower for k in ["趋势", "时间", "date", "day", "month", "week"]):
+        return "line chart"
+    if any(k in lower for k in ["占比", "比例", "份额", "share", "ratio"]):
+        return "donut chart"
+    if len(columns) >= 3:
+        return "bar chart with supporting table"
+    return "bar chart"
+
+
+def cmd_data_viz(args: argparse.Namespace) -> int:
+    request = args.request or "根据数据生成清晰的信息图"
+    try:
+        data_preview = read_data_preview(args.file)
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"读取数据失败：{exc}", file=sys.stderr)
+        return 2
+    title = args.title or compact_title(request, 24)
+    chart_type = infer_chart_type(request, data_preview["columns"], args.chart_type)
+    facts = {
+        "title": title,
+        "request": request,
+        "chart_type": chart_type,
+        "columns": data_preview["columns"],
+        "row_count": data_preview["row_count"],
+        "rows_preview": data_preview["rows"],
+        "source": data_preview["source"],
+    }
+    if args.strict_text:
+        text_rule = (
+            "Strict chart text mode: reserve clean title, axis, legend, and callout zones; "
+            "exact labels and numbers will be applied as deterministic vector/text overlay."
+        )
+        required_text: list[str] = []
+    else:
+        text_rule = f'The title must read exactly "{title}". Keep labels large and readable.'
+        required_text = [title]
+    prompt = "\n".join(
+        [
+            f"Create a 16:9 high-quality data visualization infographic for: {request}.",
+            f"Chart type: {chart_type}.",
+            f"Data schema: columns={', '.join(data_preview['columns']) or 'not provided'}, rows={data_preview['row_count']}.",
+            f"Rows preview for visual truthfulness: {json.dumps(data_preview['rows'], ensure_ascii=False)}.",
+            "Layout: title band, main chart area, short insight callouts, compact legend, and optional source note.",
+            "Use honest scales, aligned axes, restrained colors, and no decorative fake data.",
+            text_rule,
+            "Avoid: misleading charts; unreadable microtext; random numbers not present in the data; fake logos; visual clutter.",
+        ]
+    )
+    overlay_spec = None
+    if args.strict_text:
+        overlay_spec = {
+            "mode": "chart_text_overlay",
+            "title": title,
+            "columns": data_preview["columns"],
+            "rows_preview": data_preview["rows"],
+            "rules": ["Render all labels and numbers as deterministic text/vector overlays.", "Do not invent values."],
+        }
+    findings = lint_prompt(prompt, "infographic", "high", required_text)
+    result = {"chart_data_spec": facts, "prompt": prompt, "text_overlay_spec": overlay_spec, "lint": findings}
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print("## Data Viz Prompt")
+        print(prompt)
+        print("\n## Lint")
+        print_lint(findings)
+    return 1 if has_lint_error(findings) else 0
+
+
+def cmd_rewrite(args: argparse.Namespace) -> int:
+    source = read_text_argument(args.prompt_text, args.file)
+    if not source:
+        print("用法：rewrite \"<低质量 prompt 或画图需求>\"", file=sys.stderr)
+        return 2
+    case = {
+        "request": source,
+        "asset_type": args.asset_type,
+        "style": args.style,
+        "strict_text": args.strict_text,
+        "text": args.text or [],
+        "target": args.target,
+        "tags": "rewrite,prompt-cleanup",
+    }
+    compiled = compile_visual_case(case, target=args.target)
+    result = {
+        "original": source,
+        "rewrite_notes": [
+            "Converted vague adjectives into concrete asset type, layout, material, lighting, palette, and negative constraints.",
+            "Applied safety rewrite for risky brand/IP/style references when detected.",
+            "Ran lint on the rewritten prompt.",
+        ],
+        "spec": compiled["spec"],
+        "prompt": compiled["prompt"],
+        "handoff": compiled["handoff"],
+        "lint": compiled["lint"],
+    }
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print("## Rewritten Prompt")
+        print(compiled["prompt"])
+        print("\n## Lint")
+        print_lint(compiled["lint"])
+    return 1 if has_lint_error(compiled["lint"]) else 0
+
+
+def adapt_layout_for_aspect(aspect: str, asset_type: str) -> str:
+    if aspect == "16:9":
+        return "wide layout with horizontal reading path, hero subject left or center, supporting details to the side"
+    if aspect == "9:16":
+        return "vertical mobile layout with stacked hierarchy, safe top/bottom margins, large central subject"
+    if aspect == "1:1":
+        return "square layout with centered subject, balanced margins, compact supporting details"
+    if aspect == "3:4":
+        return "portrait layout with clear top title zone, central visual, and bottom detail zone"
+    if aspect == "4:3":
+        return "landscape editorial layout with stable side margins and readable detail panels"
+    return infer_layout(infer_template_id("", asset_type), asset_type)
+
+
+def cmd_adapt(args: argparse.Namespace) -> int:
+    request = read_text_argument(args.request_text, None)
+    if not request:
+        print("用法：adapt \"<画图需求>\" --aspects 1:1,3:4,16:9", file=sys.stderr)
+        return 2
+    variants = []
+    for aspect in split_csv(args.aspects):
+        asset_type = args.asset_type or route_asset_type(request)
+        case = {
+            "request": request,
+            "asset_type": asset_type,
+            "aspect": aspect,
+            "layout": adapt_layout_for_aspect(aspect, asset_type),
+            "style": args.style,
+            "text": args.text or [],
+            "strict_text": args.strict_text,
+            "target": args.target,
+            "tags": "adapt,multi-size",
+        }
+        compiled = compile_visual_case(case, target=args.target)
+        variants.append({"aspect": aspect, "size": compiled["spec"]["size"], **compiled})
+    result = {
+        "request": request,
+        "variants": variants,
+        "adaptation_rules": [
+            "同一主体、同一风格、同一关键文案在所有画幅保持一致。",
+            "每个画幅使用专属布局，不做简单裁切。",
+            "移动竖图保留上下安全区，横图保留左右信息区，方图保持中心识别度。",
+        ],
+    }
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        for item in variants:
+            print(f"\n## {item['aspect']} / {item['size']}")
+            print(item["prompt"])
+    return 1 if any(has_lint_error(item["lint"]) for item in variants) else 0
+
+
+# --------------------------------------------------------------------------- #
+# status
+# --------------------------------------------------------------------------- #
+def cmd_status(args: argparse.Namespace) -> int:
+    print("draw-prompt 环境检查")
+    print(f"  数据目录   : {data_home()}  ({'存在' if data_home().exists() else '未创建'})")
+    print(f"  偏好档案   : {profile_path()}  ({'已有' if profile_path().exists() else '未创建'})")
+    samples = read_jsonl(samples_path())
+    accepted = sum(1 for r in samples if r.get("verdict") == "accept")
+    print(f"  样本数     : {len(samples)}（采纳 {accepted}）")
+    print(f"  评分记录   : {len(read_jsonl(judgements_path()))}")
+    own = Path(__file__).resolve().parent.parent / "references" / "gallery.md"
+    print(f"  自带范例库 : {own}  ({'可用' if own.exists() else '缺失！'})")
+    gi = Path.home() / ".claude" / "skills" / "gpt-image" / "references" / "gallery.md"
+    print(f"  可选扩展库 : gpt-image  ({'可用' if gi.exists() else '未装（不影响）'})")
+    print("  ── 下游出图通道（本 skill 不主动调用，仅提示可用性）──")
+    print(f"  codex CLI  : {which('codex') or '未找到'}")
+    plugin = Path.home() / ".claude" / "plugins" / "cache" / "codex-image-in-cc"
+    print(f"  codex-image: {'已安装' if plugin.exists() else '未安装（可 /codex-image:generate 出图）'}")
+    print("  核心转化命令: convert / compose / series / edit / brand / character / data-viz / rewrite / adapt")
+    print("  稳定性命令  : overlay / visual-check / edit-check / visual-regress / lint / benchmark / revise")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# argparse
+# --------------------------------------------------------------------------- #
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="prompt_cli.py", description="draw-prompt：自然语言画图需求 -> 生图 Prompt / handoff（不主动出图）")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pc = sub.add_parser("convert", help="自然语言画图需求 -> 高质量生图 Prompt / handoff")
+    pc.add_argument("request_text", nargs="+", help="自然语言画图需求")
+    pc.add_argument("--asset-type", choices=sorted(ASSET_ROUTES.keys()), help="覆盖自动识别的资产类型")
+    pc.add_argument("--template", choices=sorted(TEMPLATE_DEFS.keys()), help="覆盖细分模板")
+    pc.add_argument("--aspect", help="覆盖画幅，如 3:4 / 16:9 / 1:1")
+    pc.add_argument("--text", action="append", help="必须逐字显示的文字，可重复")
+    pc.add_argument("--subject", help="覆盖主体描述")
+    pc.add_argument("--layout", help="覆盖布局规格")
+    pc.add_argument("--style", help="风格锚点，逗号分隔")
+    pc.add_argument("--materials", help="材料/质感，逗号分隔")
+    pc.add_argument("--lighting", help="光照描述")
+    pc.add_argument("--palette", help="配色，逗号分隔")
+    pc.add_argument("--size", help="size 预设或像素，如 portrait / 1024x1536")
+    pc.add_argument("--quality", choices=["low", "medium", "high"], help="质量档")
+    pc.add_argument("--out", help="期望输出路径")
+    pc.add_argument("--tags", help="额外样本标签，逗号分隔")
+    pc.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    pc.add_argument("--strict-text", action="store_true", help="输出 visual prompt + text_overlay_spec，提升文字稳定性")
+    pc.add_argument("--record-pending", action="store_true", help="把本次转化记录为 pending 样本")
+    pc.add_argument("--no-handoff", action="store_true", help="只输出 Prompt，不输出下游指令")
+    pc.add_argument("--json", action="store_true")
+    pc.set_defaults(func=cmd_convert)
+
+    pco = sub.add_parser("compose", help="长输入/文档 -> 多张配套图视觉计划 + Prompt")
+    pco.add_argument("input_text", nargs="*", help="长输入内容；也可用 --file")
+    pco.add_argument("--file", help="从文件读取长输入")
+    pco.add_argument("--max-images", type=int, default=6, help="最多拆成多少张图")
+    pco.add_argument("--shared-style", help="整组图共享风格锚点")
+    pco.add_argument("--palette", help="整组图共享配色，逗号分隔")
+    pco.add_argument("--strict-text", action="store_true", help="文字/标签走 overlay_spec")
+    pco.add_argument("--out-dir", help="为每张 handoff 生成建议输出路径")
+    pco.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    pco.add_argument("--json", action="store_true")
+    pco.set_defaults(func=cmd_compose)
+
+    psr = sub.add_parser("series", help="多张同风格系列图 -> Prompt 组")
+    psr.add_argument("--brief", action="append", help="单张图 brief，可重复")
+    psr.add_argument("--file", help="JSON/JSONL/纯文本 briefs")
+    psr.add_argument("--asset-type", choices=sorted(ASSET_ROUTES.keys()), help="覆盖所有 brief 的资产类型")
+    psr.add_argument("--style", help="整组图共享风格")
+    psr.add_argument("--palette", help="整组图共享配色")
+    psr.add_argument("--strict-text", action="store_true")
+    psr.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    psr.add_argument("--json", action="store_true")
+    psr.set_defaults(func=cmd_series)
+
+    pe = sub.add_parser("edit", help="参考图/改图需求 -> 编辑 Prompt")
+    pe.add_argument("--goal", required=True, help="改图目标")
+    pe.add_argument("--reference", action="append", help="参考图，格式 role:path 或 path，可重复")
+    pe.add_argument("--preserve", action="append", help="必须保留的元素，可重复")
+    pe.add_argument("--change", action="append", help="必须修改的元素，可重复")
+    pe.add_argument("--text", action="append", help="必须逐字显示的文字，可重复")
+    pe.add_argument("--asset-type", choices=sorted(ASSET_ROUTES.keys()), default="product")
+    pe.add_argument("--aspect", default="3:4")
+    pe.add_argument("--style")
+    pe.add_argument("--quality", choices=["low", "medium", "high"], default="high")
+    pe.add_argument("--out")
+    pe.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    pe.add_argument("--json", action="store_true")
+    pe.set_defaults(func=cmd_edit)
+
+    pbr = sub.add_parser("brand", help="品牌一致性档案 -> 品牌 Prompt 块/可选编译")
+    pbr.add_argument("--name", required=True)
+    pbr.add_argument("--industry")
+    pbr.add_argument("--values", help="品牌价值，逗号分隔")
+    pbr.add_argument("--palette", help="品牌配色，逗号分隔")
+    pbr.add_argument("--style", help="品牌视觉风格")
+    pbr.add_argument("--avoid", help="禁用项，逗号分隔")
+    pbr.add_argument("--request", help="可选：直接用品牌档案编译一张图")
+    pbr.add_argument("--asset-type", choices=sorted(ASSET_ROUTES.keys()), default="poster")
+    pbr.add_argument("--text", action="append", help="编译图时必须显示的文字")
+    pbr.add_argument("--strict-text", action="store_true")
+    pbr.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    pbr.add_argument("--json", action="store_true")
+    pbr.set_defaults(func=cmd_brand)
+
+    pch = sub.add_parser("character", help="角色一致性 bible + 参考表/场景 Prompt")
+    pch.add_argument("--name", required=True)
+    pch.add_argument("--description", required=True)
+    pch.add_argument("--style")
+    pch.add_argument("--outfit")
+    pch.add_argument("--palette")
+    pch.add_argument("--scene", action="append", help="用同一角色生成的场景，可重复")
+    pch.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    pch.add_argument("--json", action="store_true")
+    pch.set_defaults(func=cmd_character)
+
+    pdv = sub.add_parser("data-viz", help="数据/报表需求 -> 信息图/图表 Prompt")
+    pdv.add_argument("--file", help="CSV/TSV/JSON 数据文件")
+    pdv.add_argument("--request", help="图表需求")
+    pdv.add_argument("--chart-type", help="覆盖图表类型")
+    pdv.add_argument("--title", help="图表标题")
+    pdv.add_argument("--strict-text", action="store_true", help="标题/轴/数字走 overlay_spec")
+    pdv.add_argument("--json", action="store_true")
+    pdv.set_defaults(func=cmd_data_viz)
+
+    prw = sub.add_parser("rewrite", help="低质量 prompt/画图需求 -> 结构化高质量 Prompt")
+    prw.add_argument("prompt_text", nargs="*", help="原始 prompt；也可用 --file")
+    prw.add_argument("--file", help="从文件读取原始 prompt")
+    prw.add_argument("--asset-type", choices=sorted(ASSET_ROUTES.keys()))
+    prw.add_argument("--style")
+    prw.add_argument("--text", action="append", help="必须逐字显示的文字，可重复")
+    prw.add_argument("--strict-text", action="store_true")
+    prw.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    prw.add_argument("--json", action="store_true")
+    prw.set_defaults(func=cmd_rewrite)
+
+    pad = sub.add_parser("adapt", help="同一需求 -> 多尺寸/多画幅适配 Prompt")
+    pad.add_argument("request_text", nargs="+", help="画图需求")
+    pad.add_argument("--aspects", default="1:1,3:4,16:9,9:16", help="逗号分隔画幅列表")
+    pad.add_argument("--asset-type", choices=sorted(ASSET_ROUTES.keys()))
+    pad.add_argument("--style")
+    pad.add_argument("--text", action="append", help="必须逐字显示的文字，可重复")
+    pad.add_argument("--strict-text", action="store_true")
+    pad.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    pad.add_argument("--json", action="store_true")
+    pad.set_defaults(func=cmd_adapt)
+
+    pov = sub.add_parser("overlay", help="按 text_overlay_spec 给成品图叠加精确文字")
+    pov.add_argument("--image", required=True, help="下游生成的原始图片路径")
+    pov.add_argument("--spec", help="spec JSON 字符串、JSON 文件路径，或 @path")
+    pov.add_argument("--text", action="append", help="没有 spec 时直接叠加的文字，可重复")
+    pov.add_argument("--out", help="输出路径，默认 <image>.final.png")
+    pov.add_argument("--font", help="字体文件路径；默认优先用系统中文字体")
+    pov.add_argument("--json", action="store_true")
+    pov.set_defaults(func=cmd_overlay)
+
+    pvc = sub.add_parser("visual-check", help="对单张成品图做尺寸/画幅/亮度/对比度质量门")
+    pvc.add_argument("--image", required=True)
+    pvc.add_argument("--spec", help="spec JSON 字符串、JSON 文件路径，或 @path")
+    pvc.add_argument("--aspect", help="覆盖期望画幅，如 3:4 / 16:9")
+    pvc.add_argument("--strict", action="store_true", help="更严格地处理亮度异常")
+    pvc.add_argument("--json", action="store_true")
+    pvc.set_defaults(func=cmd_visual_check)
+
+    pec = sub.add_parser("edit-check", help="验证参考图编辑是否保留中心主体并产生有效变化")
+    pec.add_argument("--reference", required=True)
+    pec.add_argument("--output", required=True)
+    pec.add_argument("--threshold", type=float, default=0.58, help="中心主体直方图相似度阈值")
+    pec.add_argument("--min-change", type=float, default=0.03, help="整图最小变化量")
+    pec.add_argument("--json", action="store_true")
+    pec.set_defaults(func=cmd_edit_check)
+
+    pvr = sub.add_parser("visual-regress", help="批量跑场景 prompt + 可选成品图质量回归")
+    pvr.add_argument("cases", help="JSONL/JSON visual cases 文件")
+    pvr.add_argument("--require-images", action="store_true", help="case 必须带 image/output 才算通过")
+    pvr.add_argument("--strict", action="store_true")
+    pvr.add_argument("--edit-threshold", type=float, default=0.58)
+    pvr.add_argument("--edit-min-change", type=float, default=0.03)
+    pvr.add_argument("--json", action="store_true")
+    pvr.set_defaults(func=cmd_visual_regress)
+
+    pl = sub.add_parser("lint", help="检查 Prompt 是否满足生图转化硬约束")
+    pl.add_argument("--prompt", required=True)
+    pl.add_argument("--asset-type", choices=sorted(ASSET_ROUTES.keys()))
+    pl.add_argument("--quality", choices=["low", "medium", "high"])
+    pl.add_argument("--text", action="append", help="必须逐字显示的文字，可重复")
+    pl.add_argument("--json", action="store_true")
+    pl.set_defaults(func=cmd_lint)
+
+    pb = sub.add_parser("benchmark", help="批量跑 golden cases，检查转化稳定性和 lint")
+    pb.add_argument("cases", help="JSONL 或 JSON cases 文件")
+    pb.add_argument("--runs", type=int, default=3, help="每个 case 重复转化次数，用于检查确定性")
+    pb.add_argument("--json", action="store_true")
+    pb.set_defaults(func=cmd_benchmark)
+
+    pr = sub.add_parser("revise", help="按失败分类生成修订版 Prompt")
+    pr.add_argument("--sample-id", help="样本 id 或 last")
+    pr.add_argument("--prompt", help="没有样本时直接修订这段 prompt")
+    pr.add_argument("--request", help="没有样本时提供原始需求")
+    pr.add_argument("--spec", help="没有样本时提供 Prompt Spec JSON")
+    pr.add_argument("--reason", choices=sorted(FAILURE_PLAYBOOK.keys()), default="text_error")
+    pr.add_argument("--out", help="记录 pending 时补记输出路径")
+    pr.add_argument("--record-pending", action="store_true")
+    pr.add_argument("--list-reasons", action="store_true", help="列出支持的失败分类")
+    pr.add_argument("--json", action="store_true")
+    pr.set_defaults(func=cmd_revise)
+
+    pp = sub.add_parser("profile", help="读写风格偏好档案")
+    pp.add_argument("action", choices=["show", "init", "set", "note", "path"])
+    pp.add_argument("key", nargs="?", help="set 的字段名")
+    pp.add_argument("value", nargs="?", help="set 的值 / note 的文本")
+    pp.add_argument("--force", action="store_true", help="init 时覆盖已有档案")
+    pp.set_defaults(func=cmd_profile)
+
+    ps = sub.add_parser("samples", help="记录/检索出图样本")
+    ps.add_argument("action", choices=["add", "search", "list"])
+    ps.add_argument("query", nargs="?", help="search 的关键词")
+    ps.add_argument("--request")
+    ps.add_argument("--prompt")
+    ps.add_argument("--verdict", choices=["accept", "reject", "pending"])
+    ps.add_argument("--reason")
+    ps.add_argument("--image")
+    ps.add_argument("--size")
+    ps.add_argument("--quality")
+    ps.add_argument("--tags")
+    ps.add_argument("--source")
+    ps.add_argument("--confidence", choices=["low", "medium", "high"])
+    ps.add_argument("--scope")
+    ps.add_argument("--limit", type=int, default=5)
+    ps.add_argument("--json", action="store_true")
+    ps.set_defaults(func=cmd_samples)
+
+    pf = sub.add_parser("feedback", help="对上一次/指定样本记录采纳或弃用")
+    pf.add_argument("id", nargs="?", default="last", help="样本 id 或 'last'")
+    pf.add_argument("--verdict", required=True, choices=["accept", "reject"])
+    pf.add_argument("--reason")
+    pf.add_argument("--category", choices=sorted(FAILURE_PLAYBOOK.keys()), help="reject 时记录结构化失败分类")
+    pf.add_argument("--image", help="补记成品图路径")
+    pf.set_defaults(func=cmd_feedback)
+
+    pj = sub.add_parser("judge", help="存储 agent 给出的评分（CLI 不评分、不调 Codex）")
+    pj.add_argument("action", choices=["rubric", "record", "list"])
+    pj.add_argument("--image")
+    pj.add_argument("--prompt")
+    pj.add_argument("--score", help="agent 算好的评分 JSON 字符串")
+    pj.add_argument("--sample-id", dest="sample_id")
+    pj.add_argument("--limit", type=int, default=10)
+    pj.set_defaults(func=cmd_judge)
+
+    ph = sub.add_parser("handoff", help="生成交给 Codex 的现成指令块（仅打印，不执行）")
+    ph.add_argument("--prompt", required=True)
+    ph.add_argument("--request", help="原始画图需求；--record-pending 时必填")
+    ph.add_argument("--out", help="期望输出路径")
+    ph.add_argument("--size", help="size 预设或像素，如 portrait / 1024x1536")
+    ph.add_argument("--quality", help="质量档：low/medium/high")
+    ph.add_argument("--tags", help="样本标签，逗号分隔")
+    ph.add_argument("--spec", help="关联的 Prompt Spec JSON；--record-pending 时写入样本")
+    ph.add_argument("--record-pending", action="store_true", help="把 handoff 记录为 pending 样本")
+    ph.add_argument("--target", choices=["codex-image", "codex-exec", "raw"], default="codex-image")
+    ph.set_defaults(func=cmd_handoff)
+
+    sub.add_parser("status", help="数据与下游通道健康检查").set_defaults(func=cmd_status)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args) or 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())