# Prototype > 当用户提到「原型」「可交互原型」「prototype」时触发。PRD / IMAP 完成后可转为可交互版本。 - Skill: `caufieldz/prototype` (Agent Skill, multi-file: 59 files) - Install (CLI): `npx skillmds@latest add caufieldz/prototype` - Raw SKILL.md: https://api.skillmd.com/api/skills/caufieldz/prototype/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: caufieldz (https://skillmd.com/u/caufieldz) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/caufieldz/prototype --- # 可交互原型 Skill（Interactive Prototype） ## 触发与定位 **做什么**：根据 scene-list / IMAP 生成可交互 HTML 原型（前台 App 深色 + Web 前台 + 后台 CMS 浅色三档），数据驱动 CRUD + 抽屉 / 弹窗 / Tab 切换齐备。 **一端一文件**：涉及多端（App / Web 前台 / 后台任意 ≥ 2）时，**每端产一个独立 HTML**（`-app` / `-web` / `-mgt` 后缀），由同一个 orchestrator 循环调 `generate_single` 出多个文件。禁止把多端合并进一个 HTML 用顶栏 view 切换——单端单文件后导航天然全局 scope，page id 不跨端、不撞车。 **何时触发**：用户说「原型 / 可交互原型 / 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_single` — `generate_single(project, view, page_fns, crud_js, output_path)`：单端单文件（**新项目多端默认走这个**，每端一文件，无顶栏）。**web-front 端注意**：骨架 `.p-nav` sticky `top:52px`（多端 gnav 高度）会压正文，需项目 CSS 覆盖 `.web-front > .p-nav{top:0}` - `from build_proto_skeleton import generate` — `generate(project, views, page_fns, crud_js, output_path)`：多 view gnav 合并单文件（**仅存量 archive rebuild**，新项目勿用） - `python3 check_paradigm.py {项目名}` — Step 0 范式门 - `python3 pre_proto_phone_shots.py -o ` — Step 2 前 IMAP 硬看截图 - `python3 audit_against_baseline.py --baseline ` — Step 3 标杆对照 - `bash check_proto.sh []` — Step 3 综合自检 - `python3 check_page_fns_shell.py ...` — page_fns 设备壳越界检测（hook 调用） - `build_proto_v{N}.py --end X`（项目 orchestrator）：`--end` 只决定迭代端，但全量重建所有端 HTML；改单端后需同步重拍全端截图，否则其他端 freshness stale - `screenshot_proto.py`（项目侧，读 `registry.shot_setup` + `extra_shots`）— web 端原型截图走它，**禁用通用 `screenshot_for_prd.py --proto`**（含多场景切换的页面会停在默认态） **会拦你的 hook**： - `script-syntax-gate` / `cjk-punct` - `plain-language-gate` — proto-*.html 文案讲人话（禁裸编号 / 决策号） - `ui-annotation-gate` — 渲染壳内禁开发注解（`（此处占位）`/`注：`/`TODO` 会被开发误读为真实文案）；build 后 Bash 路径拦截 - `prototype-shell-gate` — page_fns 不生成设备壳 - `prototype-split-gate` — proto-*.html 产出时校验 src/scenes 已拆分（找不到即 FAIL） - `prototype-audit` — 产出后自动跑 audit_against_baseline 摘要 - `skill-load-gate` — 改 `proto-*.html` 必先 Read 本 SKILL.md - `deliverable-source-gate` — 禁直接 Edit/Write proto HTML，必须走 build **改完跑啥**： ```bash 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 即拦） ### 反凭印象三红线 1. **凭印象画 = 红线**：任何 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`）。三源任一缺失 → 必须先补再画。Figma frame 名不可信，下图肉眼核对再映射场景编号 2. **IMAP 硬看强制**：上游有 IMAP 时，Step 2 前必须用 `pre_proto_phone_shots.py` 单独截每张 phone（每张独立文件），Read 多模态确认元素细节后再骨架。详见 `references/prototype-source-discipline.md § B` 3. **标杆对照强制**：Step 3 必须跑 `audit_against_baseline.py` 对照范式标杆 HTML，关键组件计数 + Fill 视觉铁律 + 反 AI slop 六禁全过才允许声明完成 ### 数据驱动 CRUD 4. **数据驱动**：JS 数组存数据 → render 函数渲染列表 → 弹窗按索引读 → 保存 = 写回 + 重渲染 + 关弹窗 5. **禁止**列表写死 HTML 而弹窗用另一套数据 6. 新增弹出空表单 + 默认值；编辑弹出对应数据；两者共用同一弹窗组件 7. 增删改全联动，统计实时更新，删除二次确认 ### 设备壳边界 8. **page_fns 不生成设备壳**：禁在 page_fns 函数里生成 `.app-mock` / `.layout` / `.p-nav` / sidebar 等设备壳元素——这些由 build 骨架统一管理。`prototype-shell-gate` hook 拦截 9. **build 模式唯一**：改 HTML = 改 page_fns 函数体 + 重跑 build，禁 Edit/Write 直改 HTML（hook 阻断） - **单端单文件 = 导航天然全局**：`generate_single` 每端只产一个 view，无 gnav 顶栏，`goPage` / `openDrawer` 在整份文档全局查找（JS `|| document` fallback），page id 不跨端、不撞 `getElementById`。无需任何 scope 技巧 - **app 端 .p-nav 隐藏**：`.p-nav` 硬编码在 `build_proto_skeleton.py`（skill 文件不可改），app 端在 `crud.py` 补 `.app-mock > .p-nav{display:none}`，由各 scene 自行接管顶导 ### 每页都得点得到 10. **每个 page 必须有入口**：`view.pages` 里声明的页面，必须能从入口页顺着 `goPage` 点到（顶栏 logo / Tab 栏 / 列表卡片 / 按钮任一）。声明了页面却没入口 = 评审只能改代码才能看到 = 等于没做。多端拆分尤其易漏：某页只在另一端有入口，本端就成孤儿。`goPage` 目标也必须是**本端真实存在**的 `data-page`，指向别端的 page id 点了直接黑屏。build 时 `_warn_unreachable` 提示，`check_proto.sh` §页面可达性 FAIL 拦截 ### src/scenes 分场景拆分（强制） 11. **必须拆 src/scenes**：每个原型一律拆 `projects/{项目}/scripts/src/scenes/{end}_{page}.py` 一文件一页面（≤ 300 行），由 `build_proto_v{N}.py` orchestrator import 收口成 `page_fns`。**禁止把 page_fns 内联在 orchestrator 单文件里**（不分简单 / 大产物，无条件）。`prototype-split-gate` hook 在 proto-*.html 产出时校验，找不到任何 `src/scenes/*.py` 即 FAIL。结构见 `.claude/runbooks/html-build-split.md §二` ### 文案讲人话 12. **正文禁 PM 内部代号**：原型 HTML 文案给用户看，禁正文出现决策 N / 场景编号 A-1 / context 内部条目。规则源头 `.claude/runbooks/human-voice-rules.md`，`plain-language-gate` hook 拦截 13. **屏内只放真实文案**：原型整份就是 UI，禁在渲染壳（`.app-mock` / `.web-front` / `.layout`）内写开发注解——`（此处占位）` / `（灰条占位）` / `（动态加载）` / `注：` / `TODO` 这类括注会被开发误读为真实产品文案。注解一律删掉。`ui-annotation-gate` hook 在 build 后拦截。留删判据：使用者在本页做决定需要知道的才留，系统内部机制 / 版本语言 / 算法口径归 PRD ### 共享场景库的装配纪律（建了 src/registry.py 就必吃） > 总纲：**共享层只放与版本无关的东西。任何与本轮 scope 有关的（装配清单 / 导航映射 / 校验范围 / 页序）必须由 orchestrator 注入，不写死在共享层。** > 这是 `html-build-split.md §二`「素材工厂须信息中性」从素材层到装配层的延伸。 14. **按 scope 装配，禁无条件全拼**：`build()` 拼 CSS / JS 时必须按本端、本轮入选页选包，禁 `js = A + B + C + D` 一把梭。判据：产物里不得出现本轮 scope 之外的端 / 页的代码。**违反后果是跨版本污染** —— 前台改一处 OBS 选币逻辑，会串进只含 CMS 页的另一个版本产物。 15. **registry 自洽性校验随 scope 收敛**：`check_links()` 只校验本轮入选集合内的场景与两端都在集合内的边，禁全局校验。全局校验会让「改了 A 端跳转忘同步 registry」阻断**所有**版本的 build，且报错指着与本轮毫不相干的场景 —— 这是最难定位的一类假故障。 16. **跨版本共享清单禁位置索引**：侧栏 / 导航这类共享清单，场景侧一律存**名字**（`sidebar_name`）由 build 查位置，禁存整数下标。下标在清单中间插一项时整体错位且不报错；按名查找插项自动跟随，名字对不上直接抛错。 17. **停放区（暂不启用的代码）必须保持语法合法**：注释掉的功能段落若丢了 `//` 前缀，恢复时会一次性炸掉整个 `