name	prototype
description	当用户提到「原型」「可交互原型」「prototype」时触发。PRD / IMAP 完成后可转为可交互版本。
type	pipeline
output_format	.html
output_prefix	proto-
pipeline_position	4
depends_on	["scene-list"]
optional_inputs	["interaction-map"]
consumed_by	["prd"]
owns	["状态全集","交互细节","CRUD流转","Tab切换"]
forbids	["字段表权威定义","池策略权威定义","埋点权威定义"]
scripts	{"check_paradigm.py":"Step 0 范式门 — python3 .claude/skills/prototype/scripts/check_paradigm.py {项目名}","build_proto_skeleton.py":"Step 2 单步生成 — from build_proto_skeleton import generate","audit_against_baseline.py":"Step 3 标杆对照 — python3 .claude/skills/prototype/scripts/audit_against_baseline.py <html> [--baseline <baseline.html>]","pre_proto_phone_shots.py":"Step 2 前 IMAP 硬看 — python3 .claude/skills/prototype/scripts/pre_proto_phone_shots.py <imap.html> -o <out_dir>","check_proto.sh":"Step 3 综合自检（结构 + 文案）— bash .claude/skills/prototype/scripts/check_proto.sh <html> [<scene-list.md>]","check_page_fns_shell.py":"page_fns 设备壳越界检测（prototype-shell-gate 调用）— python3 .claude/skills/prototype/scripts/check_page_fns_shell.py <file.py>...","check_proto_split.py":"src/scenes 分场景拆分门（prototype-split-gate 调用）— python3 .claude/skills/prototype/scripts/check_proto_split.py <html>..."}

可交互原型 Skill（Interactive Prototype）

触发与定位

做什么：根据 scene-list / IMAP 生成可交互单页 HTML 原型（前台 App 深色 + Web 前台 + 后台 CMS 浅色三档），数据驱动 CRUD + 多 View 切换 + 抽屉 / 弹窗 / Tab 切换齐备。

何时触发：用户说「原型 / 可交互原型 / prototype」；scene-list 或 IMAP 完成后转可交互版本。

不做：PRD 行为规格（归 prd）/ 架构方案（归 architecture-diagrams）/ 静态展示页（用 IMAP 即可）。

承载状态全集：IMAP ann-card 出现 → 原型「{view}-{page}」状态全集 锚点时，该页面必须出 ≥ 锚点列举的所有 state-chip。check_proto.sh 比对 IMAP 锚点 ↔ state-chip 文案，缺失 FAIL。

改脚本前 30 秒

hook 守的是「Read 过本文件」不看读了多少行。改 scripts/*.py / *.sh 用 Read 此文件 limit=80（§1+§2 即够）。改产出物建议全文。

Public API（不可改签名）：

from build_proto_skeleton import generate — generate(project, views, page_fns, crud_js, output_path)
python3 check_paradigm.py {项目名} — Step 0 范式门
python3 pre_proto_phone_shots.py <imap.html> -o <out_dir> — Step 2 前 IMAP 硬看截图
python3 audit_against_baseline.py <html> --baseline <baseline.html> — Step 3 标杆对照
bash check_proto.sh <html> [<scene-list.md>] — Step 3 综合自检
python3 check_page_fns_shell.py <file.py>... — page_fns 设备壳越界检测（hook 调用）

会拦你的 hook：

post-script-syntax-check / post-cjk-punct-check
post-plain-language-check — proto-*.html 文案讲人话（禁裸编号 / 决策号）
ui-annotation-gate — 渲染壳内禁开发注解（（此处占位）/注：/TODO 会被开发误读为真实文案）；build 后 Bash 路径拦截
post-prototype-source-check — page_fns 不生成设备壳
post-prototype-split-check — proto-*.html 产出时校验 src/scenes 已拆分（找不到即 FAIL）
post-prototype-audit — 产出后自动跑 audit_against_baseline 摘要
pre-skill-load-gate — 改 proto-*.html 必先 Read 本 SKILL.md
pre-deliverable-source-gate — 禁直接 Edit/Write proto HTML，必须走 build

改完跑啥：

python3 .claude/skills/prototype/scripts/build_proto_skeleton.py  # demo 自跑
bash .claude/skills/prototype/scripts/check_proto.sh deliverables/proto-*.html

深入读什么：完整 views/page_fns 结构 grep -A 40 "^## API 速查" SKILL.md；自检规则 grep -A 30 "^## 自检清单" SKILL.md；组件 HTML Read references/crypto-app-vocabulary.md + Read assets/prototype-templates.html。

硬规则（FAIL 即拦）

反凭印象三红线

凭印象画 = 红线：任何 Crypto APP 元素（feed 卡片 / trader 卡 / 战绩组件 / 订阅 CTA / 抽屉 / 状态栏 / 底部导航）必须先查 references/crypto-app-vocabulary.md 对应词条 + Figma 真品 PNG（assets/figma-anchors/）+ imap references（biz-trading.md / biz-social.md / biz-livestream.md / components-core.md）。三源任一缺失 → 必须先补再画
IMAP 硬看强制：上游有 IMAP 时，Step 2 前必须用 pre_proto_phone_shots.py 单独截每张 phone（每张独立文件），Read 多模态确认元素细节后再骨架。详见 references/prototype-source-discipline.md § B
标杆对照强制：Step 3 必须跑 audit_against_baseline.py 对照范式标杆 HTML，关键组件计数 + Fill 视觉铁律 + 反 AI slop 六禁全过才允许声明完成

数据驱动 CRUD

数据驱动：JS 数组存数据 → render 函数渲染列表 → 弹窗按索引读 → 保存 = 写回 + 重渲染 + 关弹窗
禁止列表写死 HTML 而弹窗用另一套数据
新增弹出空表单 + 默认值；编辑弹出对应数据；两者共用同一弹窗组件
增删改全联动，统计实时更新，删除二次确认

设备壳边界

page_fns 不生成设备壳：禁在 page_fns 函数里生成 .app-mock / .layout / .p-nav / sidebar 等设备壳元素——这些由 build 骨架统一管理。post-prototype-source-check hook 拦截
build 模式唯一：改 HTML = 改 page_fns 函数体 + 重跑 build，禁 Edit/Write 直改 HTML（hook 阻断）

src/scenes 分场景拆分（强制）

必须拆 src/scenes：每个原型一律拆 projects/{项目}/scripts/src/scenes/{view_id}_{page_id}.py 一文件一页面（≤ 300 行），由 build_proto_v{N}.py orchestrator import 收口成 page_fns。禁止把 page_fns 内联在 orchestrator 单文件里（不分简单 / 大产物，无条件）。post-prototype-split-check hook 在 proto-*.html 产出时校验，找不到任何 src/scenes/*.py 即 FAIL。结构见 .claude/runbooks/html-build-split.md §二

文案讲人话

正文禁 PM 内部代号：原型 HTML 文案给用户看，禁正文出现决策 N / 场景编号 A-1 / context 内部条目。规则源头 .claude/runbooks/human-voice-rules.md，post-plain-language-check hook 拦截

渲染 UI 内禁注解

屏内只放真实文案：原型整份就是 UI，禁在渲染壳（.app-mock / .web-front / .layout）内写开发注解——（此处占位） / （灰条占位） / （动态加载） / 注： / TODO 这类括注会被开发误读为真实产品文案，造成误会。注解一律删掉。ui-annotation-gate hook 在 build 后拦截

业务组件复用

业务组件：交易卡片 / Feed 列表 / 直播间 / CMS 后台表格 / 表单必须从 references/prototype-components.md 或对应 imap biz-*.md 复制 HTML 结构，禁自行设计样式

核心输出规范

位置：原型是 delta-scoped 产物，不做 living base 版（上线后线上 app 即 UI 真相，活原型是与现实重复的维护黑洞），scoped 到本轮变更场景，随 delta 包落 projects/{产品线}/deliverables/{季度}/{版本}/proto-{产品线}-{版本}.html（版本 = delta 版本），随 delta 整包归 archive/{季度}/。
生成脚本：与产物同目录 delta 包内 scripts/build_proto_{版本}.py
结构：单文件 HTML / CSS / JS 全内联（字体 CDN 除外）；CSS / JS 由 build_proto_skeleton.py 通过 open().read() 自动拼接

device + theme 三档设备壳

prototype 覆盖三档（views 字段 device + theme 决定壳）：

范式	device	theme	壳	用途
对客 App	`phone`	`dark`	`.app-mock` 375×812	深色系合法主题，涨绿 `#0ECB81` / 跌红 `#F6465D` / 金 `#FCD535`
对客 Web	`web-front`	`dark`	`.web-front` 全宽 + `.p-nav` + `.wf-footer`	深色底 `#0B0E11` + Platform C 蓝 accent `#007FFF`
内部后台 Web	忽略	`light`	`.layout` + sidebar	MGT 浅色 `#F5F6FA` + Platform C 蓝 + 深蓝 sidebar `#001529`；可叠 `.theme-cd` 切换到 Claude Design 暖近黑 `#1F1F1E` + `#D97757`
多 view 共建	任意组合	任意	gnav Tab 切换	activity-center v5.1 范式

字体栈走 _shared/claude-design/tokens.css @audit-spec 统一 'Noto Sans SC','Poppins',...（CJK 优先）。

page_fns vs build 骨架边界

提供方	内容
build 骨架	完整设备壳（`.app-mock` / `.layout` / `.p-nav` / sidebar）+ 抽屉 / 弹窗容器壳（`.p-drawer` / `.modal-bg`）+ ✕ 按钮 + 基础 JS 交互（View 切换 / 页面跳转 / 抽屉 / 弹窗开关）+ `<script>` 末尾拼入 `crud_js` 字符串
page_fns	页面内 UI 元素（卡片 / 列表 / 表单 / 抽屉 / 弹窗内容）

page_fns key：

key	内容	注意
`(view_id, page_id)`	页面内部 UI 元素	不包含设备壳
`(view_id, 'drawer')`	抽屉面板内容	不包含抽屉容器壳
`(view_id, 'modal')`	弹窗内容区	不包含弹窗容器壳
`(view_id, 'footer')`	web-front view 自定义 footer	可选，省略用默认

美学通用底线（所有范式必吃）

引 .claude/skills/_shared/claude-design/anti-ai-slop.md：

反 AI slop 六禁：全屏渐变 / emoji 装饰标题 / accent border / SVG 画人 / 烂大街字体作 CJK / 每卡都带 icon
字号比：标题 ≥ 正文 2.5 倍；line-height CJK display 1.25-1.35 / 正文 1.6-1.8
颜色克制：≤ 1 主 + 1 辅 + 1 强调 + 灰阶
留白 ≥ 40%，间距 8pt 网格
字重三级：900 display / 700 标题 / CTA、400 正文（禁全文只 700）
CSS 变量源头唯一：tokens.css 拼入，禁手抄 :root 整块

Step 3 audit_against_baseline.py grep 验证以上，违规即 fail。

执行步骤

通用规则（强制规则 / 快速模式 / Fill 质量）见 .claude/runbooks/html-pipeline.md。本节为 prototype 补充。

Step 0：范式选择门 + 竞品截图收集（强制）

prototype 触发后禁止直接跑 generate，必须先完成本步。

0.1 范式推断：

python3 .claude/skills/prototype/scripts/check_paradigm.py {项目名}

脚本读真相源（lib.truth_source.resolve：baseline）涉及端 + scene-list.md，推断端构成，给出 4 选 1 推荐 + 标杆 HTML 路径 + 必读 references 清单。模型必须向用户口头确认范式正确，确认后才进 Step 2。

端构成	范式	标杆
纯 App + 多场景（≥ 5）	单 phone + scene chips	V8 / community v3
纯 App + 简单流（≤ 3）	单 phone 无 nav	小型项目
Web 前台 + Web 后台共建	多 view 切换 (gnav)	activity-center v5.1
纯 Web 后台 / CMS	单 view + sidebar	activity-center mgt-view

脚本推断不出（端类型混合 / 场景数模糊）→ 模型向用户问 4 选 1，禁自行假设。

0.2 竞品截图 / Figma 真品收集（Crypto 认知 ground truth）：

范式确认后主动问用户：

这个项目对标哪些真品？请给 1-3 个来源：① Figma 真品链接（示例项目优先 — 直接 fetch_figma 入档最高权威） ② 竞品截图（Binance / OKX / Bitget / Gate / 示例平台实际页面） ③ 已有 IMAP（上游存在则直接用）

收集动作：

Figma 链接 → python3 scripts/fetch_figma.py <url> --batch ... --out-dir .claude/skills/prototype/assets/figma-anchors/（持久 anchor，下次复用）
竞品截图 → 存 projects/{项目}/inputs/competitors/
模型 Read 多模态读每张，写「视觉提炼」存 projects/{项目}/inputs/anchors/visual-extracts.md（配色 / 字号层级 / 关键组件 / 交互模式）。禁污染真相源静态章——artifact-conventions §四「静态章四不」禁 UI 视觉

只有用户明确说「不需要 / 直接做 / 已有 IMAP 看就够」才允许跳过。

0.3 上游分支判定：详见 references/prototype-source-discipline.md § A0。有 IMAP 走硬看流程，无 IMAP 走双 anchor 替代流程。

Step 1：回读 + View 结构确定

并行 Read scene-list.md + 真相源（baseline）+ IMAP（如有）+ references/crypto-app-vocabulary.md + references/baseline-pattern-card.md + references/prototype-source-discipline.md。

向用户确认：几个 View / 每个 View 前台后台 / 每个 View 的设备类型 / 包含哪些页面。

设备类型判定：

App 端（iOS / Android）→ device: "phone"
Web 端（浏览器全宽）→ device: "web-front"（新项目）或省略（legacy）
CMS 管理台 → theme: "light"（自带侧边栏布局）
不确定就问用户

Step 2：写 orchestrator + src/scenes（强制拆分）

禁止把 page_fns 内联在 orchestrator 单文件里（硬规则 10，不分简单 / 大产物）。固定结构：

projects/{项目}/scripts/
  build_proto_v{N}.py        # orchestrator（≤ 150 行，只 import scenes/ + 收 page_fns + 调 generate）
  src/
    config.py                # project / views 数据
    helpers.py               # 跨场景复用 HTML 片段（可选）
    scenes/
      __init__.py
      {view_id}_{page_id}.py # 一文件一页面 ≤ 300 行；def page_{view}_{page}(): return '''...'''

orchestrator 范式：

import sys, os
_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), '../../../..'))
sys.path.insert(0, os.path.join(_ROOT, '.claude/skills/prototype/scripts'))
sys.path.insert(0, os.path.dirname(__file__))  # 让 src 包可 import
from build_proto_skeleton import generate
from src.config import project, views
from src.scenes.user_view_main import page_user_view_main
from src.scenes.user_view_detail import page_user_view_detail

page_fns = {
    ('user-view', 'main'): page_user_view_main,
    ('user-view', 'detail'): page_user_view_detail,
}
crud_js = """const items = [...]; function render() {...} ..."""
generate(project, views, page_fns, crud_js, 'projects/{项目}/deliverables/proto-...html')

CSS / JS 不进源码树，由 build_proto_skeleton.py 通过 open().read() 自动内联。

节奏（非快速模式）：前台复杂页面 1 个一批，后台简单页面 2 个一批，每填完一批往 src/scenes 加文件 + 在 orchestrator 注册 + 跑一次 build 验证；Step 3 自检前每填 1-2 页报告进度。

Step 2 不读模板 — 骨架脚本只需下方 API 速查表，CSS / JS 由 open().read() 自动拼接。Step 2 填充开始前 Read assets/prototype-templates.html，按需读 references/prototype-components.md：

前台 App 页面 → 只读 ## A. 前台深色组件
后台管理页面 → 只读 ## B. 管理台浅色组件 + ## D. 数据驱动 CRUD 模式
弹窗 / Toast / 底部弹出 → 只读 ## C. 通用交互组件

grep -n "^## " .claude/skills/prototype/references/prototype-components.md  # 定位章节
sed -n '{起始},{结束}p' .claude/skills/prototype/references/prototype-components.md

Step 3：自检与交付

自检三件套 + Playwright click 全 pass 才视为通过。详见 § 自检清单。

Step 4：版本与归档

原型随 delta 包命名 / 归档，版本 = delta 版本，无独立 v{N} 快照阶梯：本轮 delta 上线后整季度 / 版本文件夹（含原型）归 archive/{季度}/。
改 page_fns / src/scenes 后重跑 build 覆盖本版原型；历史版本随旧 delta 包已在 archive，git blame + git log 提供变更溯源。
无 patch 脚本。

API 速查

generate() 签名

generate(project: dict, views: list, page_fns: dict, crud_js: str, output_path: str)

views 结构

{
    "id": "user-view",         # DOM id
    "name": "用户端",           # Tab 显示名
    "icon": "📱",              # Tab icon
    "theme": "dark",           # "dark" | "light"（light 强制后台壳 .layout + sidebar）
    "device": "phone",         # "phone" 对客 App | "web-front" 对客 web | 省略 = legacy Web 全宽
    "nav_name": "产品名",      # dark 主题 p-nav 显示名（可选）
    "pages": [
        {"id": "main", "name": "首页"},
        {"id": "detail", "name": "详情"},
    ],
    # device="web-front" 可选字段：
    "nav_items": ["买币", "行情", "交易", "合约", "赚币"],
    # light 主题字段：
    "sidebar_group": "功能管理",
    "sidebar": [{"icon": "📋", "name": "列表管理"}],
}

交互函数（build 骨架内置）

函数	用途
`switchGlobalView(idx)`	切换全局 View
`switchTab(el, prefix, tab)`	Tab 切换
`goPage(name)`	页面跳转
`toggleDropdown(e)`	下拉开关
`openDrawer() / closeDrawer()`	抽屉开关
`switchChip(el, prefix, tab)`	Chip 筛选
`switchDevice(webId, appId, btns, idx)`	Web/App 切换
`swPage(el, idx)`	后台侧栏切换

crud_js 模板

后台 CRUD 数据驱动 JS：数据数组 + render + openEdit + saveItem + deleteItem + 初始 renderList 调用，整段作为 crud_js 字符串传入 generate，build 时拼到 <script> 末尾。

自检清单（Step 3 执行）

通用条目（编号一致、脚本保存、FILL 残留、术语一致）见 .claude/runbooks/artifact-conventions.md §三上下文防丢。

踩坑速查（交付前过一遍）：

一级页面展示的摘要 = 编辑弹窗数据（数据驱动根治）
渲染壳内无开发注解（（此处占位）/注：/TODO），屏内只放真实文案
同一概念没有两种叫法
多个编辑按钮传了索引参数，弹窗内容正确对应
保存 = 写数据 + render + 关弹窗三步
两个文件的同一场景数据一致

专项条目：

所有 View 可通过全局导航切换
前台深色 / 后台浅色；App 端 375×812 手机壳内不溢出
抽屉在手机壳内底部上推，不脱出手机框
后台 CRUD 数据驱动：列表数据 = 弹窗数据 = render 输出
弹窗 / 抽屉有遮罩 + ✕ + 遮罩点击关闭

强制验证三件套（不可跳过）

# 1) 综合自检（结构 + 描述当前态四禁 warn）
bash .claude/skills/prototype/scripts/check_proto.sh projects/{项目}/deliverables/XXX.html

# 2) 标杆对照（必备组件 + Fill 视觉铁律 E1-E6 + 反 AI slop 六禁 + 字重三级）
python3 .claude/skills/prototype/scripts/audit_against_baseline.py \
  projects/{项目}/deliverables/XXX.html \
  --baseline {check_paradigm 输出的标杆 HTML 路径}

Playwright click 强制验证（替换原「浏览器验证」软建议）

单纯 screenshot self-check 不算通过，必须 playwright assertion 验证 DOM 状态：

python3 scripts/with_server.py --server "python3 -m http.server 5173" --port 5173 -- \
  python3 -c "
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
    page = p.chromium.launch(headless=True).new_page()
    page.goto('http://localhost:5173/projects/{项目}/deliverables/XXX.html')
    page.wait_for_load_state('networkidle')
    # ... 写下方最小 click 集 assertions
"

最小 click 集（含相关组件的场景全跑过，无 console error / 视觉无错位才算通过）：

每个 scene chip 点击 → .scr.on 切换正确（page.locator('.scr.on').count() == 1）
含订阅 CTA 的场景：click 后文案变「已订阅」+ 宽度不变（保留 flex:1）+ 铃铛出现
含铃铛的场景：click → 🔔 ↔ 🔕 toggle + toast 文案对应
含 toggle 的场景：click → on/off 状态切换 + 跨场景同 toggle 联动
含抽屉 / sheet 的场景：scrim click + ✕ click 都能关
含 TAB 的场景：每个 TAB 切换 .on 类正确

screenshot 仅用于：① 视觉 bug 复现 ② 标杆对照 zoom 局部 ③ 最终交付截图。

三件套全过 + Playwright click 全 pass 才视为自检通过 → 才允许声明完成。任一 fail → 必须修，禁止跳过。

References 索引

必读

文件	触发条件
`.claude/runbooks/html-pipeline.md`	HTML pipeline 通用规则（生成模式 / 内容质量 / Fill 视觉铁律 E1-E6 / 美学硬底线）
`references/crypto-app-vocabulary.md`	真品组件 + 路由表 + Figma anchors（凭印象红线源头）
`references/baseline-pattern-card.md`	3 标杆 × 5 场景对照（Step 0 范式确认）
`references/prototype-source-discipline.md`	有 / 无 IMAP 双流程纪律（Step 0.3 / Step 2）

按需读

文件	触发条件
`assets/prototype-templates.html`	Step 2 填充开始前 Read
`references/prototype-components.md`	按页面类型读对应 section（## A / B / C / D）
`assets/figma-anchors/*.png`	凭印象红线触发时 Read 多模态

美学与主题

产出前 grep 决策速查：grep -A 20 "决策速查" .claude/skills/_shared/claude-design/anti-ai-slop.md
Claude Design opt-in 主题：CSS 中 .theme-cd 作用域已定义（覆盖 Arco 浅色变量为 CD 深色），需切换时手动在 HTML body 加 class="theme-cd"。App 移动端不应用此 theme

注意事项

组件不绑定业务——ref 是通用骨架，按具体产品填充内容
遇到 ref 没有的场景组件（直播间 / K 线 / 聊天区 / Feed 流等），按 CSS Token 自行构建
数据用接近真实的示例，不用 Lorem ipsum
.app-mock 设备框已升级至 iPhone 15 Pro 精细数值（圆角 48px / 状态栏 54px / Dynamic Island 124×36 / Home Indicator 140×5）