原型图转 PRD

概述

本技能解决「原型已经改了很多轮，PRD 落后于原型」的问题：以已完成的交互原型为唯一事实来源，反向生成一份可开发、可测试的功能需求文档。

与「思维导图转 PRD」的区别：思维导图转 PRD 是从抽象到具体（补全规则）；本技能是从具体到文档（复述并固化原型里已经成立的一切）——原型是标准答案，PRD 的职责是把原型里"看得见但读不出"的规则写成文字。

核心纪律：不发明功能。原型里没有的，不写进正文（只能进「待确认事项」）；原型里有的，一条都不能漏。

触发条件

• 用户提供原型（HTML 文件、Figma 链接/截图、线上页面）并要求生成 PRD / 需求文档
• 用户说"按现有的原型图重新梳理需求文档"、"把原型生成PRD"、"原型转需求文档"
• 原型已迭代多轮，旧 PRD 与原型不一致，需要重新对齐
• 需要给研发/测试交付一份与原型逐条对得上的开发基线文档
• 用户要求把 PRD 的需求点标注到原型图对应的功能位置（反向标注，见第八步）

输入要求

若原型页面超过 30 页：先输出模块分组与页面清单，暂停等待用户确认分组，再逐模块展开，不要一次性硬写。

工作流程

第一步：抽取原型事实清单（禁止跳过）

运行技能自带脚本，把原型的客观事实先落到纸面。脚本位于技能根目录（本机为 C:\Users\李舟\.workbuddy\skills\原型图转PRD\scripts\，实际调用时用绝对路径，不要假设当前工作目录）：

python <技能根>/scripts/extract_prototype.py <原型.html> --out 原型清单.md

产出：页面清单（定义顺序）、弹层清单、交互动作与按钮文案、数值上限与校验片段、演示与占位统计、常量与枚举表。
这份清单是后续 PRD 的写作依据，也是最终对账的基准。

第二步：读懂原型架构

重点读四类信息，它们决定 PRD 的写法：

1. 页面容器：SCREENS / 路由表 / .screen 节 → PRD 第四章的页面编排顺序
2. 状态对象：S / state → PRD「数据字典 - 状态树」
3. 动作表：A / handlers + data-act → PRD 每个页面的「交互与规则」
4. 常量表：PRESET_* / *_SEED / 枚举 → PRD「数据字典 - 枚举值总表」

同时记录：每个页面的进入路径（从哪个 Tab / 哪个按钮进来）、上限与门槛（会员锁定、试用上限、数量上限）、提示文案原文。

第三步：输出 PRD 结构方案（暂停确认）

在写正文前，先给用户一份 3 分钟可读完的方案：

• 页面总数 → 模块分组结果（例：47 页 → 5 大模块：启动与登录 3 / 首页 1 / 训练 17 / 饮食与身体目标 9 / 我的与档案 17）
• 章节骨架（01 文档信息 → 09 附录）
• 页面编号方案（P01…P47，编号顺序 = 原型定义顺序）
• 全局规范要抽哪几类（信息架构、会员门槛、通用组件、占位与演示规范、全局限制汇总）

用户确认后再进入正文写作。若用户已明确"直接写"，可跳过暂停。

第四步：写正文片段

正文写成独立的 content.html 片段（只含 <section> 与 <div class="fp-head">，不含 html/head/body），随后由脚本套骨架。不要手写侧边栏——目录由脚本从正文自动推导，避免断链。

第五步：组装

python <技能根>/scripts/build_prd.py --content content.html --out <产品名>-功能清单-PRD.html \
  --title "力刻App 用户端" --version "V2.0" \
  --vertags "V2.0,按原型全量重组,2026-09-18"

脚本自动注入 assets/prd-style.css、套 assets/prd-shell.html 骨架、生成侧边栏三级目录与滚动高亮。

第六步：自检与对账

python <技能根>/scripts/build_prd.py --check --out <同一文件>

必须 0 错误（重复 id、侧边栏断链、标签不配平、章节/页码不连续、占位符残留均会报出）。

再做一次覆盖对账，逐条确认原型事实都在 PRD 里落了位置：

第七步：交付

用 present_files 打开 PRD 文件，附一段（不超过 6 行）说明：页面数、模块分组、本版相对上一版的变化。

第八步（可选）：把 PRD 需求点标注到原型对应位置

用户说"把需求标注到原型上"、"给原型加需求标注"时进入本步。产出一份追加了标注系统的原型副本（不改原文件），实现"编号锚点定位到功能位置 → 点击查看需求详情 → 侧边面板浏览全部需求"。

① 生成映射草稿（脚本自动做，防漏页防错位）：

python <技能根>/scripts/annotate_prototype.py --proto <原型.html> --prd <PRD.html> \
  --draft annotations.json --product "<产品名>" --version "<PRD版本>"

脚本自动完成四件事：
1. PRD 页面节 ↔ 原型 SCREENS 页面匹配（全局贪心名称匹配 + 驼峰 key 中英反译 + 邻近锚定推断）
2. 锚点多候选（targets 数组）：独有 data-act > 页内静态标题 > 页内独有静态文本 > __PAGE__ 兜底，运行时依次尝试取第一个可见的——独有动作写在弹窗/条件分支里时自动降级，不会整页标注失效
3. 页面探针（probes，降级路径用）：独有 data-act + 页内静态标题 + 页内独有静态文本（去 ${} 表达式后仍在的"无条件渲染"文本，跨页统计唯一性）
4. 编号重排：按「原型页面出现顺序 + 页内锚点位置」重排为 1..N——编号从原型第一个页面（注册/登录）的 1 号开始逐页递增，同一界面上编号连续且与页面内上下位置一致。原 PRD 编号保留在 prd 字段不受影响

输出一张对账表，标出哪些是精确匹配、哪些需要核对。

② 修正映射（模型职责，脚本无法判断的部分）：

• 核对"邻近推断/待指定"条目：弹窗、浮层不是独立页面，把 page 指向承载它的页面，targets 首选指向触发按钮或弹窗容器
• 想把锚点钉到更精确的功能位置（某个按钮、某张卡片），把该条 targets[0] 改为具体选择器（其余候选保留作兜底）
• 精修 detail：从 PRD 页面节中挑最关键的规则（脚本已预填规则要点，通常够用）

③ 注入标注系统：

python <技能根>/scripts/annotate_prototype.py --proto <原型.html> --map annotations.json \
  --out <原型名>-已标注.html

脚本要求自检 0 错误 再交付。重复运行会先移除旧注入块（幂等）；注入时同样会重排编号（--no-renumber 可关闭），并自动兼容旧格式映射（单字符串 target/probes 会升级为多候选）。

④ 真机验证（必须）：用 Chrome 无头截图或 CDP 驱动，至少验证：锚点显示、切页后锚点跟随当前页面、面板打开、点击卡片高亮目标；重点检查面板定位标签——除当前页外应全部显示灰色「其他界面」，绝不允许出现批量「未定位」（出现即说明面板渲染早于定位计算，或标签逻辑把"其他界面"误判为"未定位"）。

锚点定位与页面判定规则

锚点 targets 是候选数组（运行时按序取第一个可见的），生成时的优先级：

防跨页误显靠双层机制：

1. 首选：宿主渲染状态直读（零误判）。脚本会自动探测原型的当前页面变量（render() 里给 CURRENT 赋值 / STACK 栈顶 / S.page），生成 pageExprs 候选表达式；运行时直接读"当前页面 key"与标注的 page 精确比对。单文件原型把状态声明在顶层 const/let 时跨 <script> 可见，此路径最可靠。
2. 降级：页面探针（probes）。探测不到宿主状态时，检查该页探针（独有 data-act / 页内静态文本，多候选任一命中）在当前 DOM 是否可见，不可见则锚点自动隐藏、卡片标记「未定位」。探针文本必须严格匹配叶子元素文本（去空白后相等），避免"用户协议""训练日志"这类跨页复用文案造成的误显。

自检会对"未探测到宿主状态"和"页面无探针"给出警告——出现时优先排查，不要带病交付。

标注系统交互规格

• 编号规则：全局 1..N，按原型页面顺序编排（从注册/登录页的 1 号开始），同一界面的编号连续成段、与页面内上下位置一致；PRD 引用（Pnn）单独显示不受影响
• 顶部工具栏（44px，深色）：产品名 + PRD 版本 + 「标注 N 条 · 本页 M 条」+ 标注列表 + 显示开关（快捷键 Alt+A）
• 锚点：24px 圆形编号，默认钉在目标元素右上角；四边界防出界 + 防重叠偏移（最多 8 次）
• 侧边面板（380px 右滑）：按页面分组的卡片列表（分组头 = 起始编号 + 页面名 + 原型 key；当前界面的分组高亮并带「当前」标记），卡片含编号、标题、优先级（P0 红/P1 橙/P2 蓝）、PRD 章节引用（可点击跳转到 PRD 对应锚点）、所属模块、需求详情；筛选：全部 / P0 / P1 / P2 / 当前界面
• 定位状态标签三态（切页自动刷新）：本页且找到元素 → 绿色「本页」；本页但找不到元素 → 橙色「未定位」（真异常，需检查锚点候选）；不属于本页 → 灰色「其他界面」（正常，卡片淡化）。绝不能把"其他界面"显示成"未定位"——那会让用户误以为标注全坏了
• 点击「其他界面」的卡片自动跳页：脚本探测宿主切页函数（go/navTo 等，写入 goExprs），点卡片先切到那一页再高亮锚点；探测不到切页函数则不跳
• 点击锚点 ⇄ 点击卡片双向联动，高亮目标元素（橙色描边）；Esc 关闭面板
• 动态适配：MutationObserver 监听换页重绘 + scroll/resize + 800ms 兜底轮询，切页后锚点与面板标签自动重排

PRD 结构契约

一级章节固定九章（编号与侧边栏徽标对应）：

页面节写法（核心模板）

每个页面节由 头部 + 目标 + 元素表 + 规则列表（+ 提示块） 组成，顺序固定：

<div class="fp-head" id="pg-home"><span class="num">P04</span><h3>首页</h3>
  <span class="tag t-p0">P0</span><span class="tag t-p2">Tab 首页</span></div>
<p><strong>目标：</strong>一屏回答「今天练什么 / 本周练了多少 / 还差什么没记」。</p>

<h4 class="sub">页面元素（自上而下）</h4>
<table>
  <thead><tr><th style="width:170px">区块</th><th>内容与规则</th></tr></thead>
  <tbody>
    <tr><td class="hl">会员提醒条</td><td>试用期展示「试用剩余 N 天 …」；点击跳会员中心。买断用户不展示</td></tr>
  </tbody>
</table>

<h4 class="sub">交互与规则</h4>
<ul class="check">
  <li>数据来自「日历」中<strong>挂载到今天</strong>的模板，未挂载显示空态。</li>
</ul>
<div class="callout info">需要强调的口径写在这里。</div>

写作要求：

1. 页面元素表按自上而下顺序列区块，每行说清"展示什么 + 什么条件下不展示 + 点击去哪一页（写 Pnn）"。
2. 交互与规则用列表，每条一个判断，覆盖：数据来源、上限与门槛、状态切换、跳转去向、文案原文。
3. 文案用「」原文引用，不要转述。
4. 跨页跳转一律写目标页编号（如"→ P22"），保证可点击对账。
5. 优先级标签：P0 核心主流程 / P1 重要体验 / P2 次要或后续迭代。
6. 页面节头部必须带 id="pg-关键英文名"，编号 Pnn 与侧边栏索引一致，且全局连续。

增量修订规范（原型改了之后再更新 PRD）

原型迭代是本流程的常态，按以下纪律避免改坏：

1. 版本步进：每次修订升版本号，并在「01 文档信息」的"上一版本"里写明变更摘要；附录 9.5 修订记录追加一行。
2. 编号只增不改：页面编号 Pnn 一旦发布不再重排，新增页面接在末尾或插入后顺延并同步更新侧边栏与所有"N 页"计数；历史修订记录中的旧编号不动。
3. 批量替换用脚本 + 断言：用 Python 脚本做正文替换，每个替换 assert 命中数 == 1，全部断言通过后再一次性写盘（写盘放在脚本末尾）。中途失败时文件保持原样，可安全重跑。
4. 锚点选取要唯一：避免用会被其它替换提前消耗的短子串（例如"我的 → 设置、协议与政策"这类跨字段串），改用更完整的上下文锚点，或按依赖顺序排列替换。
5. 删整块用行级删除：跨多行的模板字符串不要用行内正则删，按行范围整块移除。
6. 改完必跑 build_prd.py --check，再做一次变更点的定点验证。
7. 同步清理：删除的交互动作，要连带清理旧版 PRD 中引用它的条目（否则文档自相矛盾）。

质量检查清单

• [ ] 原型页面数 = PRD 页面节数（脚本已校验编号连续）
• [ ] 每个 Tab / 入口在 3.1.3 都能查到进入路径
• [ ] 每个按钮点击后的行为都在该页面「交互与规则」里有交代，且跨页跳转写了目标编号
• [ ] 所有数量上限、数值区间、字符长度集中在 3.5，且与该页面节描述一致
• [ ] 所有提示文案是原型原文，不是改写
• [ ] 弹窗（含二次确认、成功提示）都有条目，并写明"是否阻断""点遮罩是否关闭"
• [ ] 会员/试用门槛在 3.2 与各页面节双重交代，且口径一致
• [ ] 跨页同步链路（如"目标 → 菜谱 → 记录"）在第五章闭环
• [ ] build_prd.py --check 输出 0 错误
• [ ] 无"优化/提升/适当/合理"等模糊词
• [ ] 推断内容全部进入 9.4 待确认事项

反向标注（若执行了第八步）追加检查：

• [ ] annotate_prototype.py 注入自检 0 错误
• [ ] 真机验证：登录页/任一功能页/弹窗三类界面锚点数量正确，无跨页误显
• [ ] 切页后锚点跟随（换 2–3 个页面抽查）
• [ ] 面板打开、卡片与锚点双向高亮、「未定位」标记正确
• [ ] 原型原有功能不受影响（点几个按钮抽查）、无 JS 控制台报错

输出规范

1. 交付为单文件 HTML：内联全部 CSS 与 JS，零外部请求、零 CDN、离线可打开。
2. 样式与骨架只用技能自带资产（assets/prd-style.css、assets/prd-shell.html），保证多份 PRD 视觉一致；需要微调时改资产文件，不在产物里另起一套样式。
3. 左侧固定侧边栏：一级章节（带 01–09 编号徽标）+ 第四章模块子目录（可折叠）+ 页面索引（P01…Pnn），滚动自动高亮，移动端可收起。
4. 正文不设封面大标题，章节直接以卡片区块呈现。
5. 善用表格（元素、规则、字段、上限）与列表（交互规则），少用长段落；需要强调的口径用 callout。
6. 所有内容用简体中文；技术术语可保留英文并在名词解释中给出对照。
7. 生成后必须用 present_files 打开给用户。

禁止项

• 禁止添加原型中不存在的功能（需要补的只能写进「待确认事项」并标注"原型未实现，待确认"）
• 禁止凭记忆写页面清单——必须来自脚本抽取结果
• 禁止手写侧边栏目录（由脚本生成）
• 禁止在 PRD 中描述原型的内部实现（变量名、函数名、CSS 类名只作为附录索引线索，不作为需求正文）
• 禁止使用模糊词："优化""提升""适当""合理""一定程度""尽快""等"

与其他技能的衔接

思维导图  →[思维导图转PRD]→  PRD  →[PRD转HTML交互原型]→  原型
                                  ↑                        │
                                  └──[原型图转PRD]─────────┘   ← 本技能（原型定稿后回写文档）
                                        │ 第八步
                                        └──→ 需求点反向标注到原型（内建能力）

当原型已经定稿、需要"文档与原型逐条对得上"时，用本技能；当只有需求描述、还没有原型时，用「思维导图转 PRD」。

本技能第八步与独立技能「PRD需求标注到原型图」能力同源：本技能的标注面向按页面组织的 PRD（Pnn ↔ SCREENS 页面映射，脚本可自动生成映射草稿）；「PRD需求标注到原型图」面向按 6 维度功能点组织的 PRD（人工建立功能点 → CSS 选择器映射）。已用本技能生成 PRD 的，优先用第八步。