@yuhan1124/draw-prompt 0.4.6 → 0.4.8

package/README.md

@@ -35,6 +35,7 @@ Prompt 的默认结构是三段：`User visual brief` 原始视觉需求、`Styl
 
 ```bash
 npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest status
+npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest doctor
 npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest convert "茶饮新品海报，写冷泡系列"
 npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest install-skill --target codex
 ```
@@ -68,7 +69,8 @@ npx --yes --registry=https://registry.npmjs.org/ @yuhan1124/draw-prompt@latest i
 
 `install-skill` 默认复制 npm 包内的运行文件，避免软链到 npx 缓存导致后续路径失效。它只复制
 `SKILL.md`、CLI、references 和必要元数据；开发仓库里的 `tests/`、`tmp/`、`golden-cases.jsonl`、
-`visual-cases.jsonl` 不会进入 npm 包或安装目录。
+`visual-cases.jsonl` 不会进入 npm 包或安装目录。安装后可直接跑 `doctor`，它会检查
+包文件、版本一致性、核心单图转化和一条真实长输入 `compose` 链路。
 
 开发者本地调试也可以软链 repo：
 
@@ -116,6 +118,7 @@ Harness，作为下一次转化的辅助信号。
 
 ```
 convert "自然语言画图需求" [--style-preset premium] [--strict-text] [--out p]  # 默认 single-pass：需求 → Prompt / handoff
+doctor                                                       # 安装后运行时自检：包文件、版本、核心场景转化
 compose "长输入/文档内容" --max-images 6                     # 长输入 → 多图视觉计划
 variants "自然语言画图需求" --style-presets all              # 同一输入 → 多风格 Prompt 组
 styles --json                                                # 查看内置风格预设

package/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   画图的指令"、"优化我的出图 prompt"、"按我的风格生成 prompt"，或在用 GPT Image 2 /
   gpt-image-2 出图前需要一段精准提示词时，使用本 skill。
 metadata:
-  version: 0.4.6
+  version: 0.4.8
   openclaw:
     anyBins: ["uv", "python3"]
 ---
@@ -61,6 +61,7 @@ prompt」「给 Codex 出图的指令」「优化这条出图 prompt」等意图
 
 2. **优先自动转化，并选对入口**。能直接交付时，按场景运行对应命令：
    - 安装到 agent skill 目录：`prompt_cli.py install-skill --target codex|claude [--force]`
+   - 安装后自检：`prompt_cli.py doctor`
    - 单图：`prompt_cli.py convert "<自然语言画图需求>" [--style-preset premium] [--strict-text] [--out <path>] [--record-pending]`
    - 长输入整理成多张图：`prompt_cli.py compose "<长输入>" --max-images 6 [--style-preset corporate] [--strict-text]`
    - 同一输入多风格探索：`prompt_cli.py variants "<自然语言画图需求>" --style-presets all`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuhan1124/draw-prompt",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Convert natural-language image requests into high-quality gpt-image-2 prompts and Codex handoff blocks.",
   "type": "commonjs",
   "bin": {

package/scripts/prompt_cli.py

@@ -136,7 +136,7 @@ def ensure_home() -> None:
 
 
 SCHEMA_VERSION = 1
-COMPILER_VERSION = "0.4.6"
+COMPILER_VERSION = "0.4.8"
 
 
 PACKAGED_SKILL_FILES = [
@@ -154,6 +154,86 @@ PACKAGED_SKILL_FILES = [
     "references/harness.md",
 ]
 
+DOCTOR_CASES = [
+    {
+        "id": "social-plain-label",
+        "request": "小红书封面，主题 30分钟搭好AI知识库，副标题 从资料整理到智能问答，不要真人，1:1",
+        "asset_type": "poster",
+        "style_preset": "creator-economy",
+        "expect_asset_type": "poster",
+        "expect_template_id": "poster_social_cover",
+        "expect_aspect": "1:1",
+        "expect_required_text": ["30分钟搭好AI知识库", "从资料整理到智能问答"],
+        "forbid_prompt": ["price/offer block"],
+    },
+    {
+        "id": "saas-dashboard",
+        "request": "SaaS 看板，需要包含通过率、失败数、平均评分、待修复，16:9",
+        "asset_type": "ui",
+        "style_preset": "clean-ui",
+        "expect_asset_type": "ui",
+        "expect_template_id": "ui_dashboard",
+        "expect_aspect": "16:9",
+        "expect_required_text": ["通过率", "失败数", "平均评分", "待修复"],
+        "forbid_prompt": ["chart panel", "data table"],
+    },
+    {
+        "id": "event-poster",
+        "request": "设计一张 AI 产品发布会海报，4:5，标题 Prompt Craft 2026，副标题是 Build visual ideas faster，时间 2026.08.18，地点 Shanghai。",
+        "asset_type": "poster",
+        "style_preset": "event-poster",
+        "expect_asset_type": "poster",
+        "expect_template_id": "poster_event",
+        "expect_aspect": "4:5",
+        "expect_required_text": ["Prompt Craft 2026", "Build visual ideas faster", "2026.08.18", "Shanghai"],
+        "forbid_prompt": ["price/offer block"],
+    },
+    {
+        "id": "architecture-diagram",
+        "request": "draw-prompt 产品架构图，16:9。需要展示用户输入、场景识别、风格预设、Prompt 编译器、意图保持检查、质量门、Image 2 出图、样本反馈学习。",
+        "asset_type": "diagram",
+        "style_preset": "systems-map",
+        "expect_asset_type": "diagram",
+        "expect_template_id": "diagram_system",
+        "expect_aspect": "16:9",
+        "expect_required_text": ["用户输入", "场景识别", "Prompt 编译器", "质量门", "Image 2 出图", "样本反馈学习"],
+        "forbid_prompt": ["academic system-architecture figure"],
+    },
+    {
+        "id": "architecture-with-app-web",
+        "request": "画一张 16:9 中文技术架构图：AI 客服工单自动化系统。结构从左到右：用户入口（App、Web、企业微信）进入消息网关；再到意图识别、知识库检索、工单创建、人工坐席协同；底部有监控与质检层，包含响应时长、解决率、满意度、风险拦截；右侧输出自动回复、工单流转、运营报表。要求企业级、清晰、不要像宣传海报，中文标签要尽量清楚。",
+        "style_preset": "technical-blueprint",
+        "expect_asset_type": "diagram",
+        "expect_template_id": "diagram_system",
+        "expect_aspect": "16:9",
+        "expect_required_text": ["用户入口", "App", "Web", "企业微信", "消息网关", "意图识别", "知识库检索", "工单创建", "人工坐席协同", "响应时长", "解决率", "满意度", "风险拦截", "自动回复", "工单流转", "运营报表"],
+        "forbid_prompt": ["UI mockup", "dashboard workspace"],
+    },
+]
+
+DOCTOR_COMPOSE_CASES = [
+    {
+        "id": "long-input-product-plan",
+        "request": (
+            "请把下面这段产品方案整理成 4 张图用于路演：我们要做一个 AI 生图 Prompt 转化 skill。"
+            "目标用户是经常把长文档、产品需求、运营数据、架构说明变成图片的研发和运营同学。"
+            "当前痛点是直接把长输入丢给模型容易跑偏，常见问题包括风格不稳定、中文标签遗漏、架构图被画成 UI、产品图漏卖点、活动战报颜色跑偏。"
+            "方案包括：场景识别、风格预设、意图保持检查、质量门、真实 Image 2 验证、样本反馈学习。"
+            "上线标准是安装后 doctor 通过、常见场景开箱高质量、NPM 公网安装可用。"
+        ),
+        "max_images": 4,
+        "style_preset": "corporate",
+        "expect_count": 4,
+        "expect_no_asset_type": "illustration",
+        "expect_required_text_by_index": {
+            0: ["目标用户"],
+            1: ["当前痛点"],
+            2: ["方案", "场景识别", "风格预设", "质量门"],
+            3: ["上线标准", "NPM 公网安装可用"],
+        },
+    }
+]
+
 
 def package_root() -> Path:
     return Path(__file__).resolve().parent.parent
@@ -2378,9 +2458,9 @@ def route_asset_type(request: str, override: str | None = None) -> str:
     lower = request.lower()
     explicit_routes = [
         ("slide", ["powerpoint", "slide", "presentation", "ppt", "幻灯片", "演示文稿", "汇报单页"]),
-        ("ui", ["ui", "界面", "app", "dashboard", "仪表盘", "看板", "saas", "后台", "控制台", "网页", "mockup"]),
         ("diagram", ["架构图", "系统图", "流程架构", "architecture diagram", "system diagram"]),
         ("infographic", ["信息图", "infographic", "图解", "流程图", "时间线"]),
+        ("ui", ["ui", "界面", "app", "dashboard", "仪表盘", "看板", "saas", "后台", "控制台", "网页", "mockup"]),
         ("poster", ["海报", "poster", "banner", "主视觉", "kv", "封面"]),
         ("logo", ["logo", "品牌标识", "字标", "visual identity"]),
     ]
@@ -2452,7 +2532,7 @@ def extract_required_texts(request: str, explicit_texts: list[str]) -> list[str]
         text = re.sub(r"(?:要)?(?:渲染)?(?:清晰|清楚|可读|明显)$", "", text)
         text = re.sub(r"(?:这些)?元素$", "", text)
         text = re.sub(r"(?:[一二三四五六七八九十\d]+个)?步骤$", "", text)
-        if re.search(r"箭头.*关系|关系.*箭头|展示输入输出关系", text):
+        if re.search(r"箭头.*(?:关系|展示|输入|输出)|(?:关系|展示|输入|输出).*箭头|展示输入输出关系", text):
             return ""
         if re.fullmatch(r"[A-Za-z]{1,2}", text) and text.upper() not in {"AI", "UI"}:
             return ""
@@ -2558,7 +2638,7 @@ def merge_texts(primary: list[str], extra: list[str]) -> list[str]:
         text = re.sub(r"(?:这些)?元素$", "", text)
         text = re.sub(r"(?:[一二三四五六七八九十\d]+个)?步骤$", "", text)
         text = text.strip(" \t\n\r，,、。；;：:.!?！？")
-        if re.search(r"箭头.*关系|关系.*箭头|展示输入输出关系", text):
+        if re.search(r"箭头.*(?:关系|展示|输入|输出)|(?:关系|展示|输入|输出).*箭头|展示输入输出关系", text):
             continue
         if re.fullmatch(r"[A-Za-z]{1,2}", text) and text.upper() not in {"AI", "UI"}:
             continue
@@ -2572,29 +2652,39 @@ def merge_texts(primary: list[str], extra: list[str]) -> list[str]:
 
 
 def extract_structural_labels(request: str, asset_type: str) -> list[str]:
-    if asset_type not in {"diagram", "infographic", "slide", "ui", "poster"}:
+    if asset_type not in {"diagram", "infographic", "slide", "ui", "poster", "product"}:
         return []
     candidates: list[tuple[int, str]] = []
-    list_intro = r"(?:需要)?(?:展示|呈现|列出|包含|包括|含有|分为|覆盖)"
+    list_intro = r"(?:需要)?(?:展示|呈现|列出|包含|包括|含有|分为|覆盖|输出)"
     stop_words = r"(?:\b16\s*:\s*9\b|\b9\s*:\s*16\b|\b3\s*:\s*4\b|\b1\s*:\s*1\b|适合|用于|画幅|aspect|高质量|高清|clean|corporate)"
     patterns = [
-        rf"{list_intro}\s*(?:这些|以下|对应的)?(?:模块|部分|层|栏目|节点|入口|能力|场景|列表|指标卡|卡片|步骤|分支)?[：:\s]*([^。；;\n]{{2,180}})",
-        rf"(?:模块|节点|栏目|部分|层|入口|能力|场景|列表|指标卡|卡片|步骤|分支)\s*(?:包括|包含|有|为)[：:\s]*([^。；;\n]{{2,180}})",
-        rf"(?:模块|节点|栏目|部分|层|入口|能力|场景|列表|指标卡|卡片|步骤|分支)[^。；;\n：:]{{0,16}}[：:]([^。；;\n]{{2,180}})",
+        rf"(?:结构(?:从左到右|从右到左|从上到下|从下到上)?|链路|流程)\s*[：:]\s*([^。\n]{{2,240}})",
+        rf"(?:数据|指标|核心数据|关键指标|卖点|亮点|功能点|特性|活动路径|路径)\s*(?:包括|包含|有|为)?[：:\s]*([^。；;\n]{{2,180}})",
+        rf"{list_intro}\s*(?:这些|以下|对应的)?(?:模块|部分|层|栏目|节点|入口|能力|场景|列表|指标卡|卡片|步骤|分支|数据|指标|卖点|亮点|功能点|特性|路径)?[：:\s]*([^。；;\n]{{2,180}})",
+        rf"(?:模块|节点|栏目|部分|层|入口|能力|场景|列表|指标卡|卡片|步骤|分支|数据|指标|卖点|亮点|功能点|特性|路径)\s*(?:包括|包含|有|为)[：:\s]*([^。；;\n]{{2,180}})",
+        rf"(?:模块|节点|栏目|部分|层|入口|能力|场景|列表|指标卡|卡片|步骤|分支|数据|指标|卖点|亮点|功能点|特性|路径)[^。；;\n：:]{{0,16}}[：:]([^。；;\n]{{2,180}})",
     ]
     for pattern in patterns:
         for match in re.finditer(pattern, request, flags=re.IGNORECASE):
             value = re.split(stop_words, match.group(1), maxsplit=1, flags=re.IGNORECASE)[0]
+            value = re.sub(r"[()（）]", "、", value)
+            value = re.sub(r"(?:进入|再到|到|输出|->|→)", "、", value)
             for part_match in re.finditer(r"[^、,，;；/|]+", value):
                 part = part_match.group(0).strip(" \t\n\r，,、：:")
                 part = re.sub(r"^(?:[^：:]{0,12}(?:指标卡|卡片|列表|标题|模块|节点|步骤|栏目|分支))[：:]", "", part)
-                part = re.sub(r"^(?:和|与|及|以及|and)\s*", "", part, flags=re.IGNORECASE).strip()
+                part = re.sub(r"^(?:和|与|及|以及|and|再|则)\s*", "", part, flags=re.IGNORECASE).strip()
+                part = re.sub(r"^(?:底部有|顶部有|左侧有|右侧有|上方有|下方有)\s*", "", part)
+                part = re.sub(r"^(?:包含|包括|含有)\s*", "", part)
                 part = re.sub(r"\s*(?:和|与|及|以及|and)$", "", part, flags=re.IGNORECASE).strip()
                 part = re.sub(r"(?:这些)?元素$", "", part)
                 part = re.sub(r"(?:[一二三四五六七八九十\d]+个)?步骤$", "", part)
                 part = part.strip(" \t\n\r，,、：:")
                 if not part:
                     continue
+                if re.search(r"箭头.*(?:关系|展示|输入|输出)|(?:关系|展示|输入|输出).*箭头|展示输入输出关系", part):
+                    continue
+                if part in {"顶部", "底部", "左侧", "右侧", "上方", "下方", "中间", "顶部导航", "底部导航", "左侧导航", "右侧导航", "导航栏", "顶部栏", "状态栏", "箭头关系", "箭头", "关系"}:
+                    continue
                 if re.fullmatch(r"\d+(?:\s*:\s*\d+)?", part):
                     continue
                 if len(part) > 36:
@@ -2630,6 +2720,43 @@ def infer_style_anchors(request: str, override: str | None, profile: dict, prese
     return anchors[:4]
 
 
+def infer_palette_constraints(request: str) -> list[str]:
+    color_terms = [
+        "红", "橙", "黄", "绿", "青", "蓝", "紫", "粉", "黑", "白", "灰", "金", "银", "棕",
+        "深色", "浅色", "渐变", "配色", "主色", "点缀", "背景",
+        "red", "orange", "yellow", "green", "cyan", "blue", "purple", "pink", "black", "white",
+        "gray", "grey", "gold", "silver", "brown", "gradient", "palette", "color", "colour",
+    ]
+    constraints: list[str] = []
+    seen: set[str] = set()
+    for sentence in re.split(r"[。；;\n]", request):
+        for fragment in re.split(r"[，,]", sentence):
+            fragment = fragment.strip(" \t\r\n。.；;，,")
+            if not fragment:
+                continue
+            lower = fragment.lower()
+            if not any(term in lower for term in color_terms):
+                continue
+            if len(fragment) > 72:
+                fragment = fragment[:72].rstrip()
+            if "红" in fragment and any(marker in fragment for marker in ["不要太俗", "别太俗", "不能太俗", "不俗", "高级"]):
+                normalized = "use a restrained, mature red campaign accent palette; keep red visibly present without garish saturated red"
+                if normalized not in seen:
+                    seen.add(normalized)
+                    constraints.append(normalized)
+                    if len(constraints) >= 3:
+                        return constraints
+                continue
+            key = re.sub(r"\s+", "", fragment)
+            if key in seen:
+                continue
+            seen.add(key)
+            constraints.append(f"preserve requested color direction: {fragment}")
+            if len(constraints) >= 3:
+                return constraints
+    return constraints
+
+
 def infer_negative(asset_type: str, texts: list[str], profile: dict, request: str = "", template_id: str = "") -> list[str]:
     negative = ["avoid vague generic AI gloss", "avoid clutter", "avoid adding content not requested by the user"]
     if texts:
@@ -3023,7 +3150,7 @@ def build_spec(args: argparse.Namespace) -> dict:
         "style_anchors": infer_style_anchors(safe_request, getattr(args, "style", None), profile, style_preset),
         "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"],
+        "palette": split_csv(getattr(args, "palette", None)) or infer_palette_constraints(visual_request) or ["restrained palette matched to the asset type"],
         "negative": negative,
         "must_include": infer_must_include(asset_type, template_id, texts, bool(getattr(args, "strict_text", False))),
         "must_avoid": negative,
@@ -3157,7 +3284,7 @@ def render_prompt(spec: dict) -> str:
     if asset_type == "infographic":
         return "\n".join(
             [
-                f"Create a {aspect} educational infographic from the user visual brief below.",
+                f"Create a {aspect} information graphic from the user visual brief below.",
                 brief_block,
                 style_quality_block(spec, label="infographic", extra=["Build a clear information hierarchy from the user's brief and preserve any named regions, section counts, and reading order."]),
                 f"Composition support: {spec.get('template_label', 'infographic')}; layout guidance: {layout}.",
@@ -4783,6 +4910,30 @@ def split_document_sections(text: str, max_images: int) -> list[str]:
     if buf:
         chunks.append(" ".join(buf).strip())
 
+    if len(chunks) <= 1:
+        semantic_patterns = [
+            r"(目标用户(?:是|：|:)[^。；;\n]+)",
+            r"(用户场景(?:是|：|:)[^。；;\n]+)",
+            r"(当前痛点(?:是|：|:)[^。；;\n]+)",
+            r"(主要问题(?:是|：|:)[^。；;\n]+)",
+            r"(方案(?:包括|是|：|:)[^。；;\n]+)",
+            r"(核心能力(?:包括|是|：|:)[^。；;\n]+)",
+            r"(上线标准(?:是|：|:)[^。；;\n]+)",
+            r"(验收标准(?:是|：|:)[^。；;\n]+)",
+        ]
+        semantic_matches: list[tuple[int, str]] = []
+        seen_spans: set[tuple[int, int]] = set()
+        for pattern in semantic_patterns:
+            for match in re.finditer(pattern, text):
+                span = match.span(1)
+                if span in seen_spans:
+                    continue
+                seen_spans.add(span)
+                semantic_matches.append((span[0], match.group(1).strip()))
+        semantic_chunks = [chunk for _, chunk in sorted(semantic_matches, key=lambda item: item[0])]
+        if len(semantic_chunks) >= 2:
+            chunks = semantic_chunks
+
     if len(chunks) <= 1:
         sentences = [s.strip() for s in re.split(r"(?<=[。！？!?；;])\s*", text) if s.strip()]
         chunks = []
@@ -4804,6 +4955,8 @@ def split_document_sections(text: str, max_images: int) -> list[str]:
 
 def choose_compose_asset(chunk: str, index: int) -> str:
     lower = chunk.lower()
+    if re.search(r"^(?:目标用户|用户场景|当前痛点|主要问题|上线标准|验收标准)", chunk):
+        return "infographic"
     if any(k in lower for k in ["架构", "系统", "模块", "链路", "rag", "llm", "retriever", "pipeline"]):
         return "diagram"
     if any(k in lower for k in ["数据", "指标", "报表", "趋势", "占比", "转化率", "漏斗", "图表"]):
@@ -4818,7 +4971,9 @@ def choose_compose_asset(chunk: str, index: int) -> str:
         return "character"
     if index == 0 and any(k in lower for k in ["标题", "主题", "发布", "活动", "封面", "总结"]):
         return "poster"
-    return "illustration"
+    if any(k in lower for k in ["插画", "场景插图", "故事", "氛围图", "场景图", "scene illustration"]):
+        return "illustration"
+    return "infographic"
 
 
 def infer_compose_style(text: str) -> str:
@@ -4842,6 +4997,13 @@ def extract_visual_labels(chunk: str, asset_type: str, limit: int = 5) -> list[s
 
     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.finditer(r"(目标用户|用户场景|当前痛点|主要问题|方案|核心能力|上线标准|验收标准)\s*(?:是|包括|包含|：|:)\s*([^。；;\n]{2,140})", chunk):
+        add(match.group(1))
+        value = match.group(2)
+        for part in re.split(r"[、,，/|]", value):
+            part = re.sub(r"^(?:和|与|及|以及|and)\s*", "", part.strip(), flags=re.IGNORECASE)
+            if 1 < len(part) <= 18:
+                add(part)
     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):
@@ -4860,7 +5022,7 @@ def compose_purpose(asset_type: str, index: int) -> str:
         "ui": "界面概念图",
         "product": "产品视觉图",
         "character": "角色设定图",
-        "illustration": "场景说明图",
+        "illustration": "场景插画",
     }
     return f"{index}. {purpose_map.get(asset_type, '配图')}"
 
@@ -5607,6 +5769,180 @@ def npm_registry_status() -> str:
     return f"{registry}（建议 npx 加 --registry=https://registry.npmjs.org/）"
 
 
+def read_skill_version(path: Path) -> str:
+    if not path.exists():
+        return ""
+    for line in path.read_text(encoding="utf-8").splitlines():
+        match = re.match(r"\s*version:\s*([^\s]+)", line)
+        if match:
+            return match.group(1)
+    return ""
+
+
+def doctor_add(findings: list[dict], severity: str, rule: str, message: str) -> None:
+    findings.append({"severity": severity, "rule": rule, "message": message})
+
+
+def doctor_check_package(root: Path) -> dict:
+    findings: list[dict] = []
+    package_path = root / "package.json"
+    package_version = ""
+    if package_path.exists():
+        try:
+            package_version = str(json.loads(package_path.read_text(encoding="utf-8")).get("version") or "")
+        except Exception as exc:
+            doctor_add(findings, "error", "package.invalid_json", f"package.json 读取失败：{exc}")
+    else:
+        doctor_add(findings, "error", "package.missing", "缺少 package.json")
+    skill_version = read_skill_version(root / "SKILL.md")
+    if not skill_version:
+        doctor_add(findings, "error", "skill.version_missing", "SKILL.md 缺少 metadata.version")
+    if package_version and skill_version and package_version != skill_version:
+        doctor_add(findings, "error", "version.package_skill_mismatch", f"package.json={package_version} SKILL.md={skill_version}")
+    if package_version and package_version != COMPILER_VERSION:
+        doctor_add(findings, "error", "version.compiler_mismatch", f"package.json={package_version} compiler={COMPILER_VERSION}")
+    missing = [rel for rel in PACKAGED_SKILL_FILES if not (root / rel).exists()]
+    for rel in missing:
+        doctor_add(findings, "error", "package.file_missing", f"缺少运行文件：{rel}")
+    style_count = len(available_style_presets(include_auto=False))
+    if style_count < 400:
+        doctor_add(findings, "error", "styles.too_few", f"内置风格数量过少：{style_count}")
+    return {
+        "name": "package",
+        "pass": not has_lint_error(findings),
+        "version": package_version or COMPILER_VERSION,
+        "style_count": style_count,
+        "missing_files": missing,
+        "findings": findings,
+    }
+
+
+def doctor_check_case(case: dict) -> dict:
+    findings: list[dict] = []
+    result = convert_for_benchmark(case)
+    spec = result["spec"]
+    prompt = result["prompt"]
+    for item in result["lint"]:
+        findings.append({"severity": item["severity"], "rule": f"lint.{item['rule']}", "message": item["message"]})
+    for item in result["intent_check"]:
+        findings.append({"severity": item["severity"], "rule": f"intent.{item['rule']}", "message": item["message"]})
+    if case.get("expect_asset_type") and spec.get("asset_type") != case["expect_asset_type"]:
+        doctor_add(findings, "error", "case.asset_type", f"期望 asset_type={case['expect_asset_type']}，实际={spec.get('asset_type')}")
+    if case.get("expect_template_id") and spec.get("template_id") != case["expect_template_id"]:
+        doctor_add(findings, "error", "case.template_id", f"期望 template_id={case['expect_template_id']}，实际={spec.get('template_id')}")
+    if case.get("expect_aspect") and spec.get("aspect") != case["expect_aspect"]:
+        doctor_add(findings, "error", "case.aspect", f"期望 aspect={case['expect_aspect']}，实际={spec.get('aspect')}")
+    labels = set(spec.get("required_text") or [])
+    for text in case.get("expect_required_text") or []:
+        if text not in labels:
+            doctor_add(findings, "error", "case.required_text_missing", f"缺少必显文字：{text}")
+        elif f'"{text}"' not in prompt:
+            doctor_add(findings, "error", "case.required_text_not_quoted", f"Prompt 未逐字引用：{text}")
+    prompt_lower = prompt.lower()
+    for phrase in case.get("forbid_prompt") or []:
+        if phrase.lower() in prompt_lower:
+            doctor_add(findings, "error", "case.forbidden_prompt", f"Prompt 出现不应出现的片段：{phrase}")
+    return {
+        "name": case["id"],
+        "pass": not has_lint_error(findings),
+        "asset_type": spec.get("asset_type"),
+        "template_id": spec.get("template_id"),
+        "aspect": spec.get("aspect"),
+        "prompt_digest": result["prompt_digest"],
+        "required_text": spec.get("required_text") or [],
+        "findings": findings,
+    }
+
+
+def doctor_check_compose_case(case: dict) -> dict:
+    findings: list[dict] = []
+    text = str(case.get("request") or "")
+    max_images = int(case.get("max_images") or 4)
+    chunks = split_document_sections(text, max_images)
+    shared_style = infer_compose_style(text)
+    visual_plan: list[dict] = []
+    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)
+        compiled = compile_visual_case(
+            {
+                "id": f"compose-{idx:02d}",
+                "request": f"{purpose}。根据这段内容生成对应画面：{chunk}",
+                "asset_type": asset_type,
+                "style": shared_style,
+                "style_preset": case.get("style_preset"),
+                "text": labels if asset_type in {"diagram", "infographic", "ui"} else [],
+                "target": "raw",
+                "tags": "compose,long-input",
+            },
+            target="raw",
+            include_handoff=False,
+        )
+        visual_plan.append({"chunk": chunk, "compiled": compiled})
+        for item in compiled["lint"]:
+            findings.append({"severity": item["severity"], "rule": f"compose.{idx}.lint.{item['rule']}", "message": item["message"]})
+        for item in compiled["intent_check"]:
+            findings.append({"severity": item["severity"], "rule": f"compose.{idx}.intent.{item['rule']}", "message": item["message"]})
+
+    if case.get("expect_count") and len(visual_plan) != int(case["expect_count"]):
+        doctor_add(findings, "error", "compose.count", f"期望 {case['expect_count']} 张图，实际 {len(visual_plan)}")
+    forbidden_asset = case.get("expect_no_asset_type")
+    if forbidden_asset:
+        for idx, item in enumerate(visual_plan, start=1):
+            asset_type = item["compiled"]["spec"].get("asset_type")
+            if asset_type == forbidden_asset:
+                doctor_add(findings, "error", "compose.asset_type", f"第 {idx} 张图不应路由为 {forbidden_asset}")
+    for raw_index, expected_texts in (case.get("expect_required_text_by_index") or {}).items():
+        index = int(raw_index)
+        if index >= len(visual_plan):
+            doctor_add(findings, "error", "compose.index_missing", f"缺少第 {index + 1} 张图")
+            continue
+        labels = set(visual_plan[index]["compiled"]["spec"].get("required_text") or [])
+        prompt = visual_plan[index]["compiled"]["prompt"]
+        for text_item in expected_texts:
+            if text_item not in labels:
+                doctor_add(findings, "error", "compose.required_text_missing", f"第 {index + 1} 张图缺少必显文字：{text_item}")
+            elif f'"{text_item}"' not in prompt:
+                doctor_add(findings, "error", "compose.required_text_not_quoted", f"第 {index + 1} 张图 Prompt 未逐字引用：{text_item}")
+    return {
+        "name": f"compose-{case['id']}",
+        "pass": not has_lint_error(findings),
+        "count": len(visual_plan),
+        "asset_types": [item["compiled"]["spec"].get("asset_type") for item in visual_plan],
+        "prompt_digests": [item["compiled"]["prompt_digest"] for item in visual_plan],
+        "required_text": [item["compiled"]["spec"].get("required_text") or [] for item in visual_plan],
+        "findings": findings,
+    }
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    root = package_root()
+    checks = [doctor_check_package(root)]
+    for case in DOCTOR_CASES:
+        try:
+            checks.append(doctor_check_case(case))
+        except Exception as exc:
+            checks.append({"name": case.get("id", "case"), "pass": False, "findings": [{"severity": "error", "rule": "case.exception", "message": str(exc)}]})
+    for case in DOCTOR_COMPOSE_CASES:
+        try:
+            checks.append(doctor_check_compose_case(case))
+        except Exception as exc:
+            checks.append({"name": f"compose-{case.get('id', 'case')}", "pass": False, "findings": [{"severity": "error", "rule": "compose.exception", "message": str(exc)}]})
+    passed = all(item["pass"] for item in checks)
+    summary = {"pass": passed, "version": COMPILER_VERSION, "checks": len(checks), "failed": len([item for item in checks if not item["pass"]])}
+    if args.json:
+        print(json.dumps({"summary": summary, "checks": checks}, ensure_ascii=False, indent=2))
+    else:
+        print(f"doctor: version={COMPILER_VERSION} checks={summary['checks']} pass={passed}")
+        for item in checks:
+            status = "PASS" if item["pass"] else "FAIL"
+            print(f"- {item['name']}: {status}")
+            for finding in item.get("findings", []):
+                print(f"  [{finding['severity']}] {finding['rule']}: {finding['message']}")
+    return 0 if passed else 1
+
+
 def cmd_status(args: argparse.Namespace) -> int:
     print("draw-prompt 环境检查")
     print(f"  数据目录   : {data_home()}  ({'存在' if data_home().exists() else '未创建'})")
@@ -5628,7 +5964,7 @@ def cmd_status(args: argparse.Namespace) -> int:
     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 / variants / series / edit / brand / character / data-viz / rewrite / adapt")
+    print("  核心转化命令: doctor / convert / compose / variants / series / edit / brand / character / data-viz / rewrite / adapt")
     print("  稳定性命令  : overlay / visual-check / edit-check / visual-regress / lint / intent-check / benchmark / revise / styles")
     return 0
 
@@ -5674,6 +6010,10 @@ def build_parser() -> argparse.ArgumentParser:
     pis.add_argument("--json", action="store_true")
     pis.set_defaults(func=cmd_install_skill)
 
+    pdoc = sub.add_parser("doctor", help="安装后运行时自检：包文件、版本和核心场景转化")
+    pdoc.add_argument("--json", action="store_true")
+    pdoc.set_defaults(func=cmd_doctor)
+
     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="覆盖自动识别的资产类型")