PRD / 需求描述 → 可交互原型

输入：一份 PRD（Markdown/文档/粘贴文本）或一句话需求描述
输出：一个 <feature>.html —— 单文件零依赖多页原型，双击就开，页间真跳转

不产出 PRD。PRD 是你的输入，本 skill 只做「需求 → 原型」这一段。
不依赖任何模型 API：生成由宿主 Agent 完成，本 skill 只提供结构契约 + 设计系统 + 校验器。
装上来就能用，不需要配 key。

0. 宿主能力映射（开工前先读，决定怎么干）

本文件不写死任何工具名。先把手上的能力映射成下表左列，再按右列决定执行方式：

任何一项缺失都不是阻塞项——降级执行，并在交付说明里一句话写清降级了什么。

1. 输入分流（Step 1，先判断手里是什么）

PRD 里有但明显做不了的（要真实后端、要第三方服务、要 100 页），不要静默跳过——列进交付说明的「未实现」。

2. 需求澄清（最多 3 个问题）

能从 PRD / 上下文推断就绝对不要问。 只有类型 C/D 或 PRD 关键信息缺失时才问，且只问这 3 个：

1. 谁用：主角色是谁（决定首屏放什么）
2. 核心动作：用户进来要完成的那一件最主要的事（决定默认路由）
3. 边界：这次明确「不做什么」（防发散）

推断不出来的项按行业惯例补默认值，记进交付说明的「假设」，不要为了问而问，也不要静默替用户拍板。

3. 功能清单快照（内部产物，不交付成文件）

动手前先在对话里列一张紧凑的表，作为原型的追溯基线：

F-01 工单列表       P0  #/orders        ← PRD §3.1
F-02 新建工单       P0  #/orders/new    ← PRD §3.2
F-03 工单详情       P0  #/orders/:id    ← PRD §3.3
F-04 批量关闭       P2  #/orders        ← 推断，PRD 未提

• F-xx 是原型的锚点，会被 HTML 里的 data-req 直接引用
• 最后一列标来源：PRD §x.x / 推断 / 描述
• P0 必做，P1 尽量做，P2 可只做禁用态——但都要在表里出现
• 这张表最终会内嵌进 HTML（见 html-contract.md 的 #req-map），所以追溯是自包含的，不需要额外文件

用户给了 PRD 但没编号时，你编的号要能反查回原文位置，别让评审时找不到出处。

4. 生成原型（Step 4）

硬约束（违反任何一条 = 不合格）：

结构契约、路由规则、6 种交互原语、data-req / #req-map 细节见 references/html-contract.md。

现成的三块料，直接用，别从零写：

assets/components.html 是组件速查页——不确定某个组件长什么样、有哪些状态，浏览器打开看，可实时切 8 主题和暗色。

两套视觉语言，选一套用，不要混：

antd 那份用的是自己的 token（--a-*，主色 #1677ff / 圆角 6px / 14px 基准），不复用 theme.css——两套体系硬混会互相覆盖。用它的时候，组件样式从 components-antd.html 的 CSS 里挑对应片段，不要另造。

缺组件时：两份参考页合起来覆盖 40+ 种控件。真遇到都没有的（如甘特图、看板拖拽），先判断是不是能用已有的组合出来（表格 + 进度条 ≈ 甘特），不行才手写，且必须用 CSS 变量而非硬编码 hex。

完整可跑的参考实现：examples/ticket-system.html（工单系统，3 页 + 空/错/骨架态，11 条需求全覆盖，validate 0 error）。拿不准结构就照着它的骨架改。

复杂原型：分文件写，用脚本拼

单文件 HTML 手写超过 5 页就会失控（几百行字符串拼接，改一处要重写全篇）。
页数多或要反复迭代时，拆成源码目录，用 scripts/build-prototype.mjs 拼：

node scripts/build-prototype.mjs out/<feature>/src -o out/<feature>/<feature>.html

src/ 下放这些（除前两个外都可省）：

脚本会做 4 件事：剥掉 const DB = 之类的冗余前缀并语法检查、断言 11 个占位符全部命中、
把生成物里的内联脚本再查一遍、最后自动跑 validate.mjs。任何一步失败直接退出，不会产出坏文件。

可以直接抄的样例：examples/ticket-system.html 是完整可跑的单页参考实现
（工单系统，3 页 + 空/错/骨架态，11 条需求全覆盖，validate 0 error）。拿不准结构照着它的骨架改。

页数多到需要拆文件时，再按上面 src/ 的约定组织源码目录。

用模板拼装时的两个坑

> 用上面的脚本就自动规避了；手写拼接时才会遇到。

{{REQ_MAP}} 是 <script type="application/json"> 的内容，不是 JS 变量，别写成 const REQ_MAP = ...。

5. 硬校验（Step 5，这一步是分水岭）

node <SKILL>/scripts/validate.mjs out/<feature>/<feature>.html            # 人读
node <SKILL>/scripts/validate.mjs out/<feature>/<feature>.html --json     # 机读
node <SKILL>/scripts/validate.mjs out/<feature>/<feature>.html --strict   # warn 也算失败

零依赖（无需 npm install），退出码：0 通过 / 1 有 error / 2 参数或文件错误。

只要有一条 error 就必须修完再交付，不许"大致符合"。它会查的 9 类 error：
外部请求、无 hash 路由、单路由、缺 data-req、缺/坏 #req-map、孤儿 req、P0 零命中、阻塞式弹窗。

纯 UI 操作（关闭图标、logo 这类不对应需求的）加 data-no-req 豁免，不要为凑数硬编 req。

warn 可以选择性忽略，但要在交付说明里写出来。

规则表见 references/html-contract.md 第六节。

维护本 skill 自己时：跑全量检查

改 assets/ scripts/ references/ 之后，单跑 validate 不够——它只看原型，看不出构建脚本能否跑通、组件页 DOM 有没有坏、文档链接是否失效。

node scripts/check-all.mjs              # 全量：构建 + 校验 + DOM + token + 对比度 + 文档链接
node scripts/check-all.mjs --no-build   # 跳过构建，只体检现有产物
node scripts/check-all.mjs --json       # 供 CI 消费

它跑 7 组检查，有一项 error 就不该 commit：

out/ 是用户自己的产出（.gitignore 里），不参与仓库体检。

6. 交付（Step 6）

交付说明固定四段，一段不超过三行：

## 产出
- 原型：<路径>（<k> 个页面，双击打开）
- 入口：默认落在 <路由>，建议按 <A → B → C> 走一遍

## 覆盖
已实现 <x> 条功能（P0 全做 / P1 做了 m 条）；未实现：<列表 + 原因>
状态：正常态 x 页 / 空态 x / 错误态 x —— 按 Shift+? 可开评审模式，看需求逐条命中情况

## 校验
validate.mjs：0 error / <n> warn（warn 说明：…）

## 假设
<没问就替用户决定的，1-3 条；没有就写"无">

7. 输出目录约定

out/<feature>/
└── <feature>.html        # 单文件多页原型（唯一交付物）

• <feature> 小写 kebab-case，如 ticket-system、asset-inventory
• 用户已有目录约定时优先服从用户的，不要另起一套
• 覆盖前先确认文件是否存在；存在就问「覆盖 / 另存 v2」

8. 渐进披露（别一次性全读进来）

首屏只读本文件就够了。 上面这些按需取，不占上下文。

9. 可选增强：批量生成（唯一需要 BYOK 的地方）

单次生成永远不需要 key——宿主 Agent 本身就是模型。

只有一种场景需要配 key：脱离对话批量跑（一次生成 20 个页面，或接进 CI）。
走 OpenAI 兼容协议，火山 Agent-Plan / DeepSeek / Ollama / vLLM 都通吃：

export OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
export OPENAI_API_KEY=<你的 key>
node scripts/batch.mjs --input prds/ --out out/

明确写死这条判断：宿主能直接生成时不要用脚本，脚本只服务批量和 CI。
这样 Claude Code 的用户装完零配置，想批量跑的人才去配 key。

9.5. 发版到 SkillHub（只维护者用）

前置：skillhub login --key skh_xxx（凭据写 ~/.skillhub/credentials.json，沙箱下需放开该路径）。

四步，顺序别乱

# 1. 改 SKILL.md frontmatter 的 version（SemVer，必须比线上大）
# 2. 全量检查，绿了才发
node scripts/check-all.mjs
# 3. 预检（纯本地，不联网、不占版本号）——这是唯一的探测手段
skillhub publish . --dry-run
# 4. 从干净目录发（见下方「必须排除的文件」）
skillhub publish /tmp/req2proto-pkg --changelog "…"

四条硬规则（都是踩过的坑）

除干净目录的例子（保留真正要发布的内容）：

rsync -a --exclude='.git' --exclude='.github' --exclude='out' \
  --exclude='*.png' --exclude='.gitignore' --exclude='.DS_Store' \
  ./ /tmp/req2proto-pkg/
# 发前自检：不该有无扩展名文件
find /tmp/req2proto-pkg -type f ! -name '*.*'   # 有输出就是会 400
skillhub publish /tmp/req2proto-pkg --dry-run   # 先预检

发完必做的验证

# 1. 确认过审且成为 latest
curl -s "https://api.skillhub.cn/api/v1/skills/req2proto" \
  | python3 -c "import json,sys; d=json.load(sys.stdin); print(d['latestVersion'])"

# 2. 下载用户真正拿到的包，确认文件没缺
curl -sL -o /tmp/v.zip \
  "https://api.skillhub.cn/api/v1/download?slug=req2proto&namespace=<你的handle>"
unzip -l /tmp/v.zip

# 3. 从包里跑一次，确认发出去的是能用的
cd /tmp && unzip -q v.zip -d vtest && cd vtest && node scripts/check-all.mjs

审核耗时参考：1.0.0 用了 14 小时（跨夜），1.0.2 约 5 分钟。波动极大，别当 SLA 用。

10. 反面清单（这些是踩过的坑）

11. 安装（给其他 Agent 用）

纯文件型，无构建、无依赖、无 key：

放进去就生效。项目级优先于用户级。