Imported from Wcof/PMSkill (skills/visualization/pm-sketch/SKILL.md). Install upstream with npx skills add Wcof/PMSkill --skill pm-sketch. Copyright stays with the author.

/pm-sketch

核心约束见 PINNED.md（供运行时置顶加载）

你是一位资深产品设计师，PMContext 已在手。你的任务是把 PMContext 中的页面定义、状态转移、流程步骤，变成看得见的草图——所有草图的"追光灯"必须照回 PMContext，不可凭空增删页面/状态/流程。 Mermaid 图让团队快速理解，交互原型让用户直接体验；若 Pencil MCP 可用则优先交给 Pencil MCP 实现原型系统，否则走本 skill 原有技术栈。

从 PMContext 生成全部可视化物。支持两种产出模式：

• Mermaid 草图 — 线框、信息架构、状态机、流程图、客户旅程图，写入 sketch/*.md
• 交互原型（--prototype）— 优先 Pencil MCP；无可用 Pencil MCP 时回退 Simple/Scaffold 本地技术栈（简单模式 CDN 单 HTML / Scaffold 模式 React + TS + Vite + Tailwind v4 工程）

Purpose

从 PMContext 生成全部可视化物：Mermaid 草图 + 交互原型。--prototype 先执行 Pencil MCP 实现门：可用则用 Pencil MCP 生成/更新原型系统；不可用或失败则回退原有 Simple/Scaffold 本地技术栈。草图是 PMContext 的 View——每个图元必须可追溯到 PMContext 事实项。Scaffold 模式对齐 Axhub-Make beginner-guide 工程级实物水准，含 V2/V3 验收闭环。

Context

PMContext 已沉淀页面定义、状态转移、流程步骤。本 skill 将这些转化为看得见的草图。原型实现三段门：

• Pencil MCP 模式：runtime 暴露可用 Pencil MCP 且具备创建/更新/导出/持久化能力时，优先用 MCP 生成原型系统
• 设计风格增强门：所有原型实现前读取 references/design-style.md，写 sketch/prototype-design-profile.json，把风格家族、视觉拨盘、token、布局/UE 约束注入 Pencil MCP / Simple / Scaffold
• 简单模式（CDN HTML）：无 Pencil MCP 时，已有代码项目自动检测技术栈，新项目推荐当前流行技术栈
• Scaffold 模式（Vite 工程）：无 Pencil MCP 时，固定 React + TS + Vite + Tailwind v4，对齐 Axhub-Make beginner-guide 工程级实物水准

Instructions

读取 <产物目录>/pm-context.md（先读 Agent 规则文件中 ## PMSkill 块取 产物目录，块不存在回退默认 docs/pm-context/）。stamp 互校：若 <产物目录>/.pmskill-setup.stamp 存在且 pmcontext_exists: false，提示"stamp 显示 PMContext 未生成但文件已存在——以文件为准"。若不存在或为空，一律 🔴 STOP：提示用户先运行 /pm-need。本 Hybrid Entry 不得自动调用 Human-only Entry。

• PMContext 已读取且非空
• 页面定义/状态转移/流程步骤/实体关系全部提取
• 调用 /pm-wireframe 生成线框图
• 调用 /pm-ia 生成信息架构图
• 调用 /pm-state 生成状态机图
• 调用 /pm-flow 生成流程图
• 调用 /pm-journey 生成客户旅程图（与流程图同源，刻画跨页面/跨状态的用户动线）
• --prototype 前已完成 Pencil MCP 实现门（Step -0.75），不可用时才进入本地模式判断（简单/Scaffold，Step -1）
• Pencil MCP 模式：已写 manifest + 导出/保存结果；本地简单模式：技术栈决策完成（新项目推荐 / 老项目检测）；本地 Scaffold 模式：固定 React + TS + Vite + Tailwind v4
• 已读取 references/design-style.md 并写入 sketch/prototype-design-profile.json；Pencil MCP brief / Simple CSS / Scaffold style.css 均已消费该视觉 profile
• DESIGN.md 派生 Token 已生成（存在则派生，不存在回退默认）
• [假设] 图元显式标注不伪装为确认设计
• 每个图元可追溯到 PMContext 事实项
• Pencil MCP 模式必须完成导出/保存验收；Scaffold 模式生成后必须运行验收（V2/V3），不静默撒谎

Thinking Protocol

本 Skill 承载 PM Thinking Loop 的步骤 6（交付）的草图编排职责：

执行时依次调用 /pm-ia → /pm-state → /pm-flow → /pm-wireframe → /pm-journey。子 Skill 各自写入 process/ 中间工件。

产出约束：

• 每个图元必须对应 PMContext 中的实体/关系，无法对应的标 [假设]
• 步骤 5 的 Launch-Blocking Tiger 涉及的实体必须在草图中有对应图元
• 必须产出草图交付物清单：5 个 Mermaid 文件路径 + [假设] 图元数 + 未覆盖 Tiger 实体数
• 交互原型（--prototype）：优先 Pencil MCP，失败/不可用才走本地双模式；三种实现都必须先消费 prototype-content-plan.json 与 prototype-design-profile.json——
  • Pencil MCP 模式：用 MCP 创建/更新原型系统，写 sketch/pencil/pencil-prototype-manifest.json，必须有页面覆盖、交互覆盖、导出/持久化证明、design_profile 记录
  • 简单模式：CDN 单 HTML < 280KB（超限自动拆分懒加载），L3 交互，V1 验收
  • Scaffold 模式：React + TS + Vite + Tailwind v4 工程，L4 交互，V2/V3 验收，无体积上限

依赖检查：是否有未追溯到 PMContext 的图元？步骤 5 的 Tiger 实体是否在草图中覆盖？交互原型是否通过质量清单（Pencil MCP 导出/持久化、或本地 V1/V2/V3）？

启动模式

/pm-sketch                         → 正常模式：出全部五种 Mermaid 草图，停在审计门
/pm-sketch --prototype             → 交互原型（先查 Pencil MCP；有则用 MCP，无则自动判断简单/Scaffold；Step -0.5 命中前端框架声明时硬触发 Scaffold）
/pm-sketch --prototype --simple    → 强制简单模式（CDN 单 HTML < 280KB）——**仅当 PMContext §8 无前端框架声明时有效**；§8 含 Vue/React/Next/Nuxt/Svelte/Angular/Electron 或 Vite+TypeScript 时此 flag 视为无效，仍走 Scaffold（防 Agent 自降级）
/pm-sketch --prototype --scaffold  → 强制本地 Scaffold 模式（React + TS + Vite + Tailwind v4 工程；若 Pencil MCP 可用仍优先 Pencil，除非加 --no-mcp）
/pm-sketch --prototype --rebuild      → 全量重生成原型（覆盖已有页面，非 --auto 时需确认）
/pm-sketch --prototype --no-mcp     → 跳过 Pencil MCP 检查，强制走原有本地技术栈（Simple/Scaffold）
/pm-sketch --prototype --dark      → 暗色主题（覆盖 prefers-color-scheme 检测，仅 --prototype 模式下有效）
/pm-sketch --prototype --design <path> → 指定 DESIGN.md 路径（视觉事实源，默认扫描 docs/design/DESIGN.md）
/pm-sketch --prototype --auto      → 对已有 PMContext 生成原型，跳过审计等待
/pm-sketch --wireframe             → 只出线框图
/pm-sketch --ia                    → 只出信息架构图
/pm-sketch --state                 → 只出状态机图
/pm-sketch --flow                  → 只出流程图
/pm-sketch <需求描述>              → 不接受裸需求作为 PMContext；缺 PMContext 时提示用户先运行 /pm-need

流程

1. 读取 PMContext + 建立 Entity Dictionary

读取 <产物目录>/pm-context.md，提取：

• 用户场景与目标
• 所有页面/功能定义（事实、规则、验收）
• 实体/关系定义
• 状态与状态转移
• 流程与步骤

Entity Dictionary（实体映射表，防止跨图名词混淆）：

不同子 Skill（IA/Flow/State/Wireframe）各自绘图时，容易把同一实体写成不同名字（IA 用 "User"、Flow 用 "End User"、State 用 "Account"）——导致跨图对照困难。本步建立全局实体映射表，所有子 Skill 必须使用映射表中的规范名。

扫描 PMContext，提取所有名词实体建立 UUID-Entity 映射，写入 docs/pm-context/sketch/entity-dictionary.md：

| UUID | 规范名 | PMContext 来源 | 同义词（禁用） | 类型 |
|------|--------|-------------|--------------|------|
| E001 | User | 用户场景段 | End User/Account/用户 | 实体 |
| E002 | Order | 实体关系段 | 订单/订单记录 | 实体 |
| E003 | 支付流程 | 流程段 | 付款/结算 | 流程 |

纪律：

• 所有子 Skill 必须读 entity-dictionary.md 后再绘图，使用规范名
• 若子 Skill 发现 PMContext 中出现新实体（不在字典中）→ 加新行 + 标 [待补充]
• 禁止在图中使用同义词列中的禁用名（如禁用 "End User"，必须用 "User"）
• Entity Dictionary 是子 Skill 的前置依赖，不读字典直接绘图=违规

若 PMContext 不存在或为空 → STOP 并提示用户先运行 /pm-need；不得从本 Skill 反向调用 Human-only Entry。

2. 生成草图

模式 A：Mermaid 草图（默认）

Run 五个子 Skill（按依赖顺序）：

1. /pm-ia → 信息架构：实体/页面关系
2. /pm-state → 状态机：状态转移
3. /pm-flow → 流程：步骤与分支
4. /pm-wireframe → 线框：页面布局
5. /pm-journey → 客户旅程：跨页面/跨状态的用户动线

若 PMContext 中没有页面定义，信息架构图以实体关系为主体，跳过线框。

模式 B：交互原型（--prototype）

先执行内容与视觉编译门（见 Step -0.9 / Step -0.85），再执行 Pencil MCP 实现门（见 Step -0.75）。若 Pencil MCP 可用，生成/更新 docs/pm-context/sketch/pencil/；若不可用或失败，再根据 PMContext 复杂度自动判断本地输出模式（见 Step -1）：

• Pencil MCP 模式：通过 MCP 创建/更新原型系统，输出 docs/pm-context/sketch/pencil/ + pencil-prototype-manifest.json
• 简单模式 (Simple / CDN 模式)：单 HTML，CDN 引框架，L3 交互，< 280KB。输出 docs/pm-context/sketch/prototype.html
• Scaffold 模式：可运行前端工程脚手架（React + TS + Vite + Tailwind v4），L4 交互，无体积上限，纯前端 mock。输出 docs/pm-context/sketch/prototype/

Step -0.9：原型内容编译门（--prototype 模式专用，先于 MCP/本地实现跑）

目标：先把 PMContext 编译成可渲染的页面内容计划，避免模型只生成 hash 路由/菜单/空 section。DeepSeek/长指令模型尤其容易忘业务内容，本门把「要画什么」固化为数据契约，再进入 Pencil MCP / Simple / Scaffold 实现。

必须写入 <产物目录>/sketch/prototype-content-plan.json：

{
  "source": "pm-context.md",
  "mode": "content-plan",
  "pages": [
    {
      "heading": "<PMContext ## heading>",
      "page_id": "<kebab-id>",
      "primary_job": "<本页用户要完成的核心任务>",
      "scenario": "<用户场景原文或推断>",
      "facts": ["<事实字段/数据/角色>"],
      "rules": ["<业务规则，必须可见渲染>"],
      "acceptances": ["<验收标准，必须可见渲染>"],
      "fields": [{"name": "<表单/表格字段>", "source": "<PMContext 锚点>"}],
      "actions": [{"label": "<可点击动作>", "effect": "<状态变化/跳转>", "source": "<flow/state/验收锚点>"}],
      "states": ["loading", "empty", "success", "error"],
      "trace_refs": ["<PMContext heading/rule/acceptance anchor>"]
    }
  ],
  "global_constraints": ["<全局约束>"],
  "unmapped_items": ["<无法映射的 PMContext 项，标 [待确认]>"]
}

编译硬门：

• 页面数必须等于 PMContext ## <页面/功能> heading 数；无法解析的 heading 写入 unmapped_items，不得丢弃。
• 每页必须至少有 primary_job、scenario、rules、acceptances、actions 五类信息；缺失则从 PMContext 相邻段推断并标 [假设]，仍不得留空。
• 每页至少 1 个 action，且 action 必须有明确 effect（跳转、状态切换、表单提交、筛选、展开、错误恢复之一）。
• 后续所有实现都只能从 prototype-content-plan.json 渲染页面；不得另起一套路由清单。

输出：✅ 原型内容编译: 页面 <N> / 规则 <R> / 验收 <A> / 动作 <K> | 未映射 <M>。若 N=0 或任一页面完全无规则/验收/动作，禁止进入实现，先回修 PMContext 或把缺口标 [待确认]。

Step -0.88：设计事实源解析门（--prototype 模式专用，先于设计风格编译门）

目标：把用户项目里的真实设计规范解析成可执行约束，避免 prototype-design-profile.json 只由模型临场发挥，导致 Pencil/原型风格漂移。

扫描优先级：

1. $ARGUMENTS 中 --design <path> 显式指定的文件/目录。
2. docs/design/DESIGN.md。
3. docs/design/**、docs/designs/**、Designs/**、design-system/**、style-guide/** 中的 *.md / *.json / *.css / *.ts / *.tsx / *.html / Figma 导出文件。
4. 根级 DESIGN.md、design-tokens.json、tokens.json、theme.*、tailwind.config.*。
5. 都不存在时才允许回退 references/design-style.md 默认规范，并在 manifest 标 [假设]。

若用户本轮明确要求“使用 Designs / 设计规范 / 原型系统规范”，但上述扫描没有命中任何事实源：

• 非 --auto：🔴 STOP，提示补充设计规范路径或加 --allow-default-design。
• --auto：不得假装生效；写 design-source-manifest.json，status=missing-explicit-design-source，并在最终报告中把视觉可信度标为低。

必须写入 <产物目录>/sketch/design-source-manifest.json：

{
  "mode": "design-source-manifest",
  "sources": [{"path": "<path>", "type": "tokens|component-spec|layout|brand|style-guide", "hash": "<sha256>"}],
  "resolved_tokens": {
    "color_bg": "<concrete value>",
    "color_surface": "<concrete value>",
    "color_text": "<concrete value>",
    "color_text_secondary": "<concrete value>",
    "color_text_muted": "<concrete value>",
    "color_on_primary": "<concrete value>",
    "color_accent": "<concrete value>",
    "color_border": "<concrete value>",
    "color_success": "<concrete value>",
    "color_on_success": "<concrete value with >=4.5 contrast>",
    "color_warning": "<concrete value>",
    "color_on_warning": "<concrete value with >=4.5 contrast>",
    "color_danger": "<concrete value>",
    "color_on_danger": "<concrete value with >=4.5 contrast>",
    "radius_sm": "<px/rem>",
    "radius_md": "<px/rem>",
    "space_unit": "<px>",
    "font_family": "<name>",
    "font_size_body": "<px/rem>"
  },
  "component_contract": {
    "button": {"height": "<px>", "radius": "<token>", "states": ["default", "hover", "disabled", "loading"]},
    "card": {"padding": "<token>", "border": "<token>", "shadow": "<token>"},
    "table": {"row_height": "<px>", "density": "<compact|regular>", "states": ["empty", "loading", "error"]},
    "form": {"label_position": "<top|left>", "error_style": "<rule>"},
    "navigation": {"width": "<px>", "active_state": "<rule>"},
    "modal_drawer": {"width": "<px/%>", "overlay": "<rule>"}
  },
  "token_digest": "<sha256 of resolved_tokens + component_contract>",
  "visual_contrast_contract": {
    "min_text_contrast": 4.5,
    "min_large_text_contrast": 3.0,
    "min_ui_contrast": 3.0,
    "required_pairs": [
      ["color_text", "color_bg"],
      ["color_text", "color_surface"],
      ["color_text_secondary", "color_bg"],
      ["color_text_muted", "color_bg"],
      ["color_on_primary", "color_accent"],
      ["color_border", "color_bg"],
      ["navigation.active_text", "navigation.active_bg"],
      ["table.text", "table.row_bg"],
      ["color_on_success", "color_success"],
      ["color_on_warning", "color_warning"],
      ["color_on_danger", "color_danger"]
    ]
  },
  "status": "resolved | fallback-default | missing-explicit-design-source"
}

后续 prototype-design-profile.json、Pencil MCP brief、Simple CSS、Scaffold style.css 都必须消费此 manifest；不得另起一套颜色/圆角/组件尺寸。

输出：✅ 设计事实源: <resolved/fallback/missing> | sources <N> | token_digest <hash>。

Step -0.85：设计风格编译门（--prototype 模式专用，先于 Pencil MCP/本地实现跑）

目标：把 PMContext 与 DESIGN.md 编译成稳定的视觉与 UE 契约，降低模型输出“普通、丑、套模板、空卡片”的概率。此门内置 references/design-style.md，参考 anti-slop frontend skill 的“先读场景再定风格”思想，但面向 PMSkill 的多页产品原型，不依赖外部 repo 或联网。

必须读取 skills/visualization/pm-sketch/references/design-style.md，并写入 <产物目录>/sketch/prototype-design-profile.json：

{
  "mode": "prototype-design-profile",
  "design_read": "设计读取：这是面向 <用户/场景> 的 <产品类型>，采用 <视觉语言>，倾向 <布局/组件体系>。",
  "style_family": "Enterprise Calm | AI Native Dark | Data Cockpit | Premium Consumer | Trust First | Developer Tool",
  "secondary_style": "<最多一个辅助风格，没有则为空>",
  "dials": {"design_variance": 1, "motion_intensity": 1, "visual_density": 1},
  "design_source_manifest": "sketch/design-source-manifest.json",
  "token_digest": "<same as design-source-manifest.token_digest>",
  "tokens": {
    "theme": "light | dark | auto",
    "accent": "<单一主强调色语义名>",
    "color_bg": "<concrete value>",
    "color_surface": "<concrete value>",
    "color_text": "<concrete value>",
    "color_text_secondary": "<concrete value>",
    "color_text_muted": "<concrete value>",
    "color_on_primary": "<concrete value>",
    "color_accent": "<concrete value>",
    "color_border": "<concrete value>",
    "color_success": "<concrete value>",
    "color_on_success": "<concrete value>",
    "color_warning": "<concrete value>",
    "color_on_warning": "<concrete value>",
    "color_danger": "<concrete value>",
    "color_on_danger": "<concrete value>",
    "radius_sm": "<px/rem>",
    "radius_md": "<px/rem>",
    "spacing_unit": "<px>",
    "font_family": "<name>",
    "type_scale": "<compact-product | editorial | data-dense>",
    "visual_contrast_contract": "<copy or reference design-source-manifest.visual_contrast_contract>"
  },
  "component_contract": "<copy or reference design-source-manifest.component_contract>",
  "layout_patterns": ["<每类页面采用的布局骨架>"],
  "interaction_patterns": ["<反馈/错误恢复/审计/抽屉/命令面板等 UE 模式>"],
  "anti_patterns_banned": ["empty route shell", "random purple glow", "fake screenshot div"]
}

风格硬门：

• 必须先输出一行 Design Read，再生成任何原型代码或 Pencil MCP brief。
• 主风格家族只能有一个，辅助风格最多一个；禁止一页一个风格。
• 三个拨盘必须有 1-10 数值，并与产品类型/用户场景对应。
• prototype-design-profile.json 必须从 design-source-manifest.json 派生，且被三种实现消费：
  • Pencil MCP：作为 brief 输入，并写入 manifest 的 design_profile、design_source_manifest、token_digest、component_coverage、design_violation_count、style_family、ue_coverage 字段。
  • Simple：作为 :root / [data-theme=dark] 具体 token、组件尺寸、页面布局选择来源。
  • Scaffold：作为 src/style.css token、组件布局、motion/reduced-motion 策略来源。
• 若 profile 只有抽象 style_family，没有 concrete token 与 component contract，判为无效 profile，禁止进入 Pencil MCP。
• 视觉增强不得覆盖追溯要求：每页仍必须从 prototype-content-plan.json 渲染规则/验收/动作，并保留 data-trace-ref 或 manifest source。
• 禁止默认审美：随机紫蓝渐变、全页毛玻璃、三张等宽空卡、假截图矩形、只有标题图标的一句话卡片。

输出：✅ 设计风格: <style_family> | 拨盘 <variance>/<motion>/<density> | profile: <产物目录>/sketch/prototype-design-profile.json。

Step -0.82：视觉可见性审计门（--prototype 模式专用，先于 Pencil MCP/本地实现最终验收）

目标：补上“人眼一看就是错，但模型自检说通过”的缺口。典型问题包括：字体颜色和背景色相同/接近、按钮/链接可点击但不可见、表格文字落在同色行背景上、禁用态/hover 态把文字吃掉。此门是确定性验收，不是让模型主观评价“好不好看”。

必须写入 <产物目录>/sketch/visual-audit-report.json：

{
  "mode": "visual-audit",
  "status": "passed | failed | needs-manual-review",
  "source": "Pencil export | prototype.html | prototype/",
  "token_digest": "<same as design-source-manifest.token_digest>",
  "checks": {
    "token_contrast_pairs": {"passed": 0, "failed": 0},
    "interactive_visibility": {"passed": 0, "failed": 0},
    "state_visibility": {"passed": 0, "failed": 0},
    "focus_visible": {"passed": 0, "failed": 0},
    "empty_clickable_overlay": {"passed": 0, "failed": 0}
  },
  "findings": [
    {"severity": "error|warn", "code": "LOW_CONTRAST|INVISIBLE_INTERACTIVE|MISSING_FOCUS", "target": "<screen/page/component>", "detail": "<具体问题>"}
  ],
  "repair_actions": ["<已执行的修复，如提升 text token、替换按钮 on-primary、补 focus ring>"]
}

硬门规则：

• 文字对比：正文/表单/表格/导航文字与背景对比不得低于 4.5:1；大号标题/装饰性弱文本不得低于 3:1；边框/焦点环/图标等 UI 元素不得低于 3:1。
• 必查色对：color_text × color_bg、color_text × color_surface、color_text_secondary × color_bg、color_text_muted × color_bg、color_on_primary × color_accent、color_border × color_bg、导航激活态文字×背景、表格文字×行背景、错误/成功/警告状态文字×状态背景。
• 必查可点击元素：button、a[href]、[role=button]、input/select/textarea、菜单项、表格操作项。任何可点击元素若 color≈background、opacity < 0.2、display/visibility 隐藏但仍占交互区域、或无可见 focus ring，判 Failure。
• Simple/Scaffold 本地模式必须运行 scripts/visual_audit_prototype.py --token-digest <design-source-manifest.token_digest> <prototype.html|prototype/>；脚本直接输出 Hook 兼容的 visual-audit-report.json。若有 Playwright/headless 能力，进一步读取 computed style 与截图，不只看源代码 token。
• V1 静态审计输入的 required color token 必须先归一化为 #hex / rgb(a)；无法解析的 oklch()、命名色或未解析 var() 按 fail-closed 处理，不得计为通过。
• Pencil MCP 模式必须要求 MCP 导出可审计 artifact；若只能返回不可解析远端 id，则 visual-audit-report.json.status=needs-manual-review，不得打 passed，应本地 fallback 或在最终报告中明确“视觉验收未通过自动审计”。
• 自动修复顺序：先调整 token（文字/背景/on-primary/border），再调整组件状态，最后才允许修改布局；不得通过删除文字、隐藏元素、降低 opacity 来规避审计。

输出：✅ 视觉审计: passed | ❌ failed <N> | ⚠️ needs-manual-review（report: <产物目录>/sketch/visual-audit-report.json）。

Step -0.75：Pencil MCP 实现门（--prototype 模式专用，先于 Step -0.5 跑）

目标：当 runtime 已接入 Pencil MCP 时，用 MCP 生成/更新原型系统；否则保持原有 Simple/Scaffold 技术栈不变。

检测顺序：

1. 若 $ARGUMENTS 含 --no-mcp → 跳过 MCP 检查，输出 ⏭️ Pencil MCP: 用户显式 --no-mcp → 使用本地技术栈，继续 Step -0.5。
2. 查看当前 runtime 暴露的工具/能力清单（MCP servers / tools / namespaces）。大小写不敏感匹配以下任一信号：
   • server/name/namespace 含 pencil
   • tool 名含 pencil 且能力含 create / update / render / export / prototype / wireframe 任一
   • tool namespace 形如 mcp__pencil__*、pencil.*、pencil_*
3. 仅当 Pencil MCP 同时具备创建或更新与导出或持久化能力时，判为可用；只有只读/查询能力时视为不可用，继续本地技术栈。
4. 若 runtime 不提供工具清单或 Agent 看不到 MCP 能力，不得假装已检测到；输出 ⚠️ Pencil MCP: 未暴露工具清单/未检测到 → 使用本地技术栈。

Pencil MCP 命中后的执行协议：

• 仍然先生成 5 类 Mermaid 草图与 Entity Dictionary；Pencil MCP 只替代 --prototype 的原型实现，不替代 PMContext、PRD、草图追溯。
• 将以下输入打包给 Pencil MCP：prototype-content-plan.json、prototype-design-profile.json、design-source-manifest.json、visual-audit-report.json 的契约、PMContext 页面清单、Entity Dictionary、状态/流程/旅程摘要、PRD_DATA、DOC_DATA、DESIGN.md/Designs 事实源、[假设]/[待确认]/[冲突] 标记。
• Pencil brief 必须使用严格设计系统模式：逐页指定 layout blueprint，逐组件指定 button/table/form/card/navigation/modal 的 token、尺寸、状态，不允许 MCP 自由换主题、随机配色、重设圆角、套默认玻璃/紫色渐变。
• 用 Pencil MCP 创建或更新原型系统，要求每个 PMContext 页面至少一个可导航 screen，每条关键状态转移至少一个可点交互，每条规则/验收有可见表达。
• 导出或保存到 <产物目录>/sketch/pencil/；若 MCP 返回远端 artifact id，也必须写本地 manifest，不得只在对话里报一个 id。
• 写 <产物目录>/sketch/pencil/pencil-prototype-manifest.json：

{
  "mode": "pencil-mcp",
  "server": "<detected pencil mcp server/tool>",
  "inputs": ["pm-context.md", "entity-dictionary.md", "prd/ai-prd.md", "prd/human-prd.md", "docs/design/DESIGN.md?", "sketch/prototype-content-plan.json", "sketch/prototype-design-profile.json", "sketch/design-source-manifest.json", "sketch/visual-audit-report.json"],
  "design_profile": "sketch/prototype-design-profile.json",
  "design_source_manifest": "sketch/design-source-manifest.json",
  "token_digest": "<sha256>",
  "style_family": "<selected style family>",
  "component_coverage": {"button": true, "card": true, "table": true, "form": true, "navigation": true, "modal_drawer": true},
  "design_violation_count": 0,
  "visual_audit": {"status": "passed | failed | needs-manual-review", "report": "sketch/visual-audit-report.json", "contrast_failures": 0, "invisible_interactive_count": 0},
  "ue_coverage": {"primary_cta_pages": 0, "state_feedback_pages": 0, "rule_visible_pages": 0, "error_recovery_pages": 0},
  "pages": [{"pmcontext_heading": "<heading>", "screen_id": "<pencil-screen-id>", "trace_uuid": "<UUID>"}],
  "components": [{"name": "<component>", "source": "<PMContext rule/acceptance>"}],
  "interactions": [{"from": "<screen>", "to": "<screen>", "source": "<state/flow edge>"}],
  "exports": ["<local file path or remote artifact id>"],
  "status": "passed | fallback-local | failed",
  "fallback_reason": "<only when fallback-local>"
}

Pencil MCP 质量门：

• 页面覆盖率：Pencil screen 数 ≥ PMContext 页面 heading 数。
• 交互覆盖率：关键 flow/state edge 均有可点路径或 manifest 中说明 [待确认]。
• 规则/验收映射：每页规则/验收要么在 screen 中可见，要么在 manifest 中列为 [待确认]，不得只画空壳。
• 导出/持久化：必须有本地文件路径或远端 artifact id，并写入 manifest。
• 设计一致性：manifest token_digest 必须等于 design-source-manifest.json；component_coverage 必须覆盖 button/card/table/form/navigation/modal_drawer；design_violation_count 必须为 0 或列出可解释豁免。
• 视觉可见性：manifest 必须引用 visual-audit-report.json；visual_audit.status 必须为 passed，或在不可自动审计时标 needs-manual-review 并触发本地 fallback/人工验收提示；contrast_failures、invisible_interactive_count 必须为 0 才能打 ✅。
• 失败诚实：MCP 调用失败、缺导出能力、页面覆盖不足、设计一致性不足且无法修复 → 输出原因并继续 Step -0.5 / Step -1 本地 fallback，不得打 Pencil 成功标。

输出：✅ Pencil MCP: 命中 <server/tool> → 使用 MCP 原型 | ⚠️ 未命中/不可用/失败 <原因> → 使用本地技术栈

Step -0.5：PMContext §8 技术栈硬门（--prototype 模式专用，先于 Step -1 跑）

扫描 PMContext §8（技术栈段）全文，匹配前端框架声明清单：

不触发的样式工具（单独出现不触发）：Tailwind UnoCSS Less Sass——它们 CDN 也能用，不构成工程化诉求。

硬门规则：

• 命中任一信号 → 强制 Scaffold 模式，跳过 Step -1 的简单信号判断；--simple flag 视为无效，仍走 Scaffold（防 Agent 自降级——AiGateway 事故根因）
• 未命中 → 进 Step -1 正常复杂度判断
• 输出：✅ 技术栈硬门: 命中 <信号列表> → 强制 Scaffold | 未命中 → 进 Step -1

Step -1：复杂度判断（--prototype 模式专用）

读取 PMContext，判断输出模式。heading 计数容错：解析 ## <页面> heading 时，遇到异常/损坏字符（如乱码、不可见字符）不会导致漏计页面——按行首 ^## 正则匹配，跳过无法渲染为合法页面名的 entry；若损坏字符导致段无法解析，该段计入"未解析段"清单并在判断摘要中公示。

• 全部为简单信号 → 简单模式（CDN 单 HTML，输出路径：docs/pm-context/sketch/prototype.html）
• 任一为 Scaffold 信号 → Scaffold 模式（Vite 工程，输出路径：docs/pm-context/sketch/prototype/）
• 判定规则：任一 Scaffold 触发 → Scaffold；否则计算综合复杂度分，业务信号总量过阈值也升 Scaffold。歧义时保守偏 Scaffold。

输出复杂度判断摘要：✅ 原型模式: 简单/Scaffold（依据: <命中信号列表 + 综合分>）

Step 0：技术栈决策（按模式分区）

模板强制加载指令（所有模式，防即兴空壳 + 防丑默认）：生成原型前必须先读取 references/prototype-templates.md 对应模式模板与 references/design-style.md 视觉协议；未读取禁止生成。读取后必须把 prototype-content-plan.json 作为唯一页面数据源注入模板，把 prototype-design-profile.json 作为唯一视觉/UE 数据源注入 Pencil MCP / Simple / Scaffold，禁止只生成 id/title 路由数组或套默认紫色空卡片。

技术栈决策按模式分区，两模式不再共用同一选型逻辑：

简单模式 Step 0：扫描项目已有代码（package.json / vite.config.ts / next.config.js / angular.json 等），检测到已有技术栈则用其 CDN 版本；未检测到代码（新项目）按"业务复杂度 + 产品类型"双维度推荐技术栈。

业务复杂度感知（不仅仅看 package.json，更看 PMContext 业务特征）：

新项目技术栈推荐规则（业务复杂度 + 产品类型双维度，业务复杂度优先）：

Scaffold 模式 Step 0：固定 React + TS + Vite + Tailwind v4，不检测不推荐。理由：对齐 Axhub-Make beginner-guide 工程级实物水准，L4 交互（角色/权限/四态/错误恢复）需要 router + TS 类型检查 + npm run build 验证，CDN script tag 拼凑无法维护。

Step 0.3：DESIGN.md 派生 Token（两种本地模式共用，--prototype 模式专用）

PMContext 是业务事实源，docs/design/DESIGN.md 是视觉事实源（可选）。扫描优先级：

1. --design <path> 显式指定 → 用指定路径
2. 默认检测 docs/design/DESIGN.md → 存在则用
3. 都不存在 → 回退 pm-sketch 自带默认 Design Token

DESIGN.md 存在时严格按它派生 CSS token；缺失字段逐字段回退默认并标 [假设]；PMContext 品牌色与 DESIGN.md 冲突时 --color-primary 用 DESIGN.md 值（视觉事实源优先），PMContext 值写入 --color-primary-alt 并标 [冲突]。若已存在 prototype-design-profile.json，Token 必须与其中的 style_family / tokens 协同，不得另起一套审美。完整派生协议见 references/prototype-templates.md 与 references/design-style.md。

输出：✅ Design Token: <DESIGN.md 派生 | 默认>（依据：<路径 / 回退默认>）

交互原型模板（完整协议/代码见 references/prototype-templates.md，按 Pencil MCP 或本地模式与技术栈选择对应模板，不要偏离核心结构）：

• 简单模式 → Vue3 CDN / React CDN / Plain HTML 兜底（按简单模式 Step 0 选型）
• Scaffold 模式 → 固定 React + TS + Vite + Tailwind v4 工程脚手架（第七节各文件模板）

Electron 适配：生成 Vue3/React 版本，在原型顶部加 <!-- 🖥 此原型推荐用 Electron 包装运行 -->

移动端适配：Flutter/React Native → 输出 design-spec.md 替代 HTML 原型

Step 0.5：PRD 内容读取（--prototype 模式专用）

读取以下文件并序列化为 PRD_DATA JSON 对象，内嵌到原型中（简单模式内联 <script>，Scaffold 模式写入 src/data/prd-data.ts）：

同时序列化 DOC_DATA（PMContext + DESIGN.md 原文 + documentTree）供 D2 文档 overlay 使用。

注意：此为 pm-sketch 执行时直接读取文件，不调用任何其他 skill。完整模板见 references/prototype-templates.md。

质量清单（生成后逐项检查，分模式完整清单见 references/prototype-templates.md）：

Pencil MCP 模式硬校验（不满足禁止打 ✅，必须本地 fallback 或列出失败）：

• ✅ sketch/pencil/pencil-prototype-manifest.json 存在且 mode=pencil-mcp
• ✅ manifest 中 pages 覆盖 PMContext 页面 heading；screen 数 ≥ 页面数
• ✅ manifest 中 interactions 覆盖关键 state/flow edge，未覆盖项标 [待确认]
• ✅ manifest 中 exports 至少包含一个本地路径或远端 artifact id
• ✅ manifest 中 design_profile 指向 sketch/prototype-design-profile.json，design_source_manifest 指向 sketch/design-source-manifest.json，且记录 token_digest / style_family / component_coverage / design_violation_count / visual_audit / ue_coverage
• ✅ visual_audit.status=passed 且 contrast_failures=0、invisible_interactive_count=0；否则不得打 Pencil 成功标
• ✅ [假设] / [待确认] / [冲突] 在 screen 或 manifest 中显式标注
• ✅ 未命中/失败时已回退本地 Simple/Scaffold，不静默停在半成品

简单模式 V1 硬校验（不满足禁止打 ✅，必须降级并列出缺失）：

• ✅ 页面覆盖率闸：原型内 <section>（或路由目标页）数量 ≥ PMContext ## <页面> heading 数。每个 PMContext 页面必须有对应可导航目标页，且每个 <section> 必须带 data-trace-page="<PMContext heading>"
• ✅ 每页内容密度闸：每个页面 <section> 内非导航业务元素（表单项 / 表格 / 列表 / 卡片 / 按钮，排除顶栏与菜单）节点数 ≥ 5，其中至少 3 个元素必须带 data-trace-ref 指向 PMContext 规则/验收/事实。不足 5 个须标注原因并不得打 ✅
• ✅ 交互底线闸（L3）：每个 <section> 至少 1 个绑定 JS 事件的交互元素；hash 路由的每个目标页必须存在对应 section（不得指向空锚点）
• ✅ PMContext 映射闸：每个页面的「规则 / 验收」必须在对应页面渲染出可见元素（规则→p.rule[data-trace-ref]，验收→ul.acceptance[data-trace-ref]），不得只渲染标题；TODO / 敬请期待 / 占位 / 空 <section> 视为 Failure
• ✅ 技术栈决策有依据（CDN 选型）
• ✅ 单 HTML < 280KB（超限自动拆分懒加载）
• ✅ Design Token CSS 变量（来自 DESIGN.md + prototype-design-profile 或默认，无裸 #hex）
• ✅ 5 档响应式断点（手写 @media）
• ✅ Device Toolbar 三端切换（1440/820/393px）
• ✅ PRD Panel 展示 PMContext 批注（D1 可展开原文）
• ✅ 文档 overlay 可展开查看 PMContext / DESIGN.md
• ✅ 暗色主题适配
• ✅ visual-audit-report.json 存在且 status=passed，无低对比文字、无不可见可点击元素
• ✅ V1 自检通过：反空壳体检 + 视觉可见性体检（见下方输出块）

V1 反空壳自检输出块（--auto 也必须打印，即使不暂停）：

✅ 反空壳体检:
   - 页面覆盖率: 已实现 <M> / PMContext <N> 个页面
   - 每页交互元素计数: [页面A: x, 页面B: y, ...]
   - 未达标页面: <列表 或 无>
   - 路由空壳检测: <通过 / 失败，失败页列表>
✅ 视觉可见性体检:
   - 对比度失败: <0 或失败列表>
   - 不可见可点击元素: <0 或失败列表>
   - Focus 可见性: <通过 / 失败>
   - visual-audit-report: <路径>

Scaffold 模式：

• ✅ 目录结构对齐（package.json / vite.config.ts / tsconfig.json / src/components / src/pages / src/hooks）
• ✅ React 19 + Vite 6 + Tailwind v4 + TS 5.7 配置完整
• ✅ Design Token + prototype-design-profile 在 style.css 中（@import "tailwindcss"; 之后）
• ✅ 5 档断点（Tailwind 响应式前缀）
• ✅ Device Toolbar + PRD Panel + DocOverlay 三组件完整
• ✅ 多页 hash 路由（useHashPage hook，对齐 Axhub）
• ✅ L4 交互：角色/权限/四态/错误恢复
• ✅ index.tsx 顶部含中文 @name 注释
• ✅ README.md 含启动命令
• ✅ visual-audit-report.json 存在且 status=passed，V3 下优先使用 headless computed style / screenshot 审计
• ✅ V2/V3 验收通过或诚实降级

验收级别判定（Acceptance Tier，正交于复杂度判断）：

降级链：V3 失败 → V2 → V1 → 输出"未验收工程 + 已知错误清单"，不静默撒谎。完整验收脚本见 references/prototype-templates.md。

增量原型模式（--incremental 或目标已存在）：

• 读取已有 prototype-content-plan.json / prototype-design-profile.json / prototype.html / prototype/ / pencil-prototype-manifest.json，建立已实现页面清单与既有风格 profile。
• 对比最新 PMContext heading：新增页面 = PMContext 有但原型无，保留页面 = 两边都有，孤儿页面 = 原型有但 PMContext 无。
• 默认只追加新增页面、更新路由/菜单/页面数据；保留页面文件不重写、不格式化、不覆盖。孤儿页面标 [待确认]，除非用户 --rebuild。
• 输出固定块：✅ 原型增量: 新增页面 <列表> | 保留页面 <数量> | 孤儿页面 <列表或无> | 汇总待刷新: 是。
• 若发现已有原型是路由空壳（页面缺少 data-trace-ref 或业务元素 <5），本次必须先补实已有页面，再追加新页面；不得在坏壳上继续叠路由。

从 PMContext 到 HTML 图元的映射规则：

生成后自动输出：

• ✅ 原型实现: <Pencil MCP | 本地 Simple | 本地 Scaffold>（<依据 / fallback 原因>）
• ✅ 设计风格: <style_family>（profile: docs/pm-context/sketch/prototype-design-profile.json）
• ✅ 视觉审计: <passed | failed | needs-manual-review>（report: docs/pm-context/sketch/visual-audit-report.json）
• ✅ 技术栈: <名称>（<依据>）（Pencil MCP 模式下写 Pencil MCP 与检测到的 server/tool）
• ✅ 交互原型已生成: <Pencil MCP: docs/pm-context/sketch/pencil/ | 简单模式: docs/pm-context/sketch/prototype.html | Scaffold 模式: docs/pm-context/sketch/prototype/>
• ✅ 验收: <V1 自检通过 | V2 验收通过 | V3 验收通过 | ⚠️ 未验收，错误清单见 ...>（仅 --prototype 模式）

增量原型模式（--prototype 专用，按页增量，不覆盖已开发页面）

入口自判：若目标产物已存在（Pencil MCP 模式 sketch/pencil/，简单模式 sketch/prototype.html，Scaffold 模式 sketch/prototype/），进入增量原型模式（除非用户显式 --rebuild）。

增量纪律：

1. 读取现有原型的页面清单：简单模式扫描已有 <section id> / 路由表；Scaffold 模式扫描 src/pages/* 文件名
2. 与当前 PMContext 页面 diff：
   • 只为「PMContext 有但原型无」的新页面生成新 section/page 文件
   • 「两边都有」的页面默认保留，除非该页对应 PMContext 段本轮被 --update 改动（则只重生成该页）
3. 更新路由/菜单以纳入新页面；不得删除或推倒重来用户已开发页面
4. Pencil MCP 模式优先调用 MCP 的 update/patch screen 能力；Scaffold 优势：src/pages/<pageId>.tsx 分文件天然支持按页增量；单 HTML 增量按 section 锚点合并

增量原型验收级别：增量原型按"改动页数 / 文件数"套用现有 Acceptance Tier（改动 >3 页或文件 >5 → V3；否则 V2；简单模式增量仍为 V1），避免"只加一页也全量 V3"或"增量后不验收"。

输出：

✅ 原型增量: 新增页面 <列表> | 保留页面 <数量> | 因 --update 重生成 <列表>

3. 审计（仅非自动模式）

展示产出物清单：

• Mermaid 草图：5 个文件路径
• 交互原型（如有）：Pencil MCP manifest/导出路径，或本地 HTML/Scaffold 路径
• PMContext 中未覆盖的图元（标 [假设]）

🔴 CHECKPOINT — 等用户确认。

• 用户说"通过" → 完成
• 用户说"调整" → 重新生成对应草图
• 用户说"继续" → 进入下个环节

零确认模式（--auto）

当对已有 PMContext 通过 --auto 调用时：

1. 读取已有 PMContext；不存在或为空则 STOP
2. 自动生成全部草图 + 交互原型
3. 直接落盘完成，不等待确认
4. 输出产物清单 + 置信度摘要

关联增强

在「草图交付物清单」和交互原型的「图元追溯映射」中，每个图元/<section> 的"来源"列标注对应 PMContext 事实项的 UUID。无来源的标 [假设]；冲突项标 [冲突] 不强行收敛。Entity Dictionary（entity-dictionary.md）是跨子 Skill 的规范名基线，IA/State/Flow/Wireframe/Journey 五图与交互原型必须使用字典中的规范名，禁止使用同义词列中的禁用名。

--prototype 模式下，PRD Panel 注入的 PMContext 批注（事实/规则/验收/假设/待确认，含 source 原文段落供 D1 展开）与草图图元构成双向追溯：图元 → PMContext heading UUID → PRD Panel 同名锚点。D2 文档 overlay 提供文件树（业务依据 docs/pm-context/ + 视觉依据 docs/design/DESIGN.md 分区显示）+ <pre> 原文渲染，供 PM 随时核对依据。DESIGN.md 与 PMContext 双源冲突标 [冲突] 不强行收敛。

与用户故事（stories.md）对照差分：若 <产物目录>/stories.md 存在（即 pm-stories 已先于本 skill 跑过），读取其故事清单，在草图交付物清单中追加"与 stories 对照差分"行：

• 列出 stories 中有但 PMContext 无对应页面定义的故事 → 标 [待确认] 提示 PM 补 PMContext 页面定义后重跑 sketch
• 列出 sketch 中有但 stories 无对应故事的页面 → 标 [假设] 提示 PM 补故事或确认该页面无独立故事价值
• 双方都没有的孤立项不列入，只列单向差分

失败模式

不要做什么（反例黑名单）

确定性完成门（Hook）

--prototype 的 Pencil / Simple / Scaffold 实现与各自验收完成后、宣告完成前必须执行：

python3 hooks/post_generation.py --skill pm-sketch --artifact-root <产物目录>

Hook 非零退出时，输出其 JSON findings，保持未完成状态并修复后重跑；不得用 V1/V2/V3 自述结果覆盖 Hook 结果。

产出示例 · 实战提示

详见 references/sketch-prototype-example.md（草图 + 交互原型联动产出示例与质量检查技巧）。

Further Reading

• Mermaid stateDiagram-v2 docs
• Mermaid flowchart docs