---
name: prd2prototype
displayName: PRD到原型
description: 把 PRD 的概念/数据模型/视图设计落成可评审的 HTML 原型;包含设计规范、共性组件抽取、视觉一致性、评审反馈快速迭代。触发场景:做 HTML 原型 / 高保真原型 / 产品评审 / 原型规范 / 多页面下钻 / 视觉一致性 / PRD to prototype。关键词:做原型、HTML 原型、产品评审、prototype、mockup。配套姐妹 skill「requirements2prd」。
---
# PRD → 高保真原型 的方法论
> 来自一个真实 B 端项目的复盘沉淀。检查清单经过实战验证。
---
## 大前提(铁律):站在产品经理视角,用自然语言输出需求说明
> 这是做原型前要先立住的根本立场,**比任何组件 / 规范都靠前**。组件、配色、交互都是工具;能不能把"要做什么、为什么"用人话讲清,才是原型的价值所在。
- **原型是产品经理表达需求的载体 —— 不是设计稿,也不是代码。** 它要让评审人、设计、开发、业务方都能"读懂你想要什么",而不是去读懂技术实现。
- **一切说明用自然语言、业务口吻表达**:站在产品经理视角讲清"**谁** 在这里 **做什么**、**为什么** 这么设计、点了之后 **会怎样**",不要用技术黑话(接口 / 字段类型 / 组件类名 / 状态机术语)堆砌。
- **先把需求用人话讲清,再落成界面。** 哪怕只有一句话,也要能说出这个页面 / 这个按钮"**解决谁的什么问题**"。讲不清 = 还没想清,别急着画。
- **英文技术术语一律翻成中文业务词**(chip→标签、modal→弹窗、hover→悬停、dropdown→下拉);面向评审的文字只讲业务、不讲实现。
- **不写实现侧自述(踩坑)**:原型说明 / index 里不要出现"本原型基于通用设计系统基线(common.css,主色 #007D7B 取自组件库)"这类话——设计基线、CSS、色值、文件结构是做原型的内部约定(本 skill 自己的事),不是需求。原型是产品经理给产品经理评审、给研发做需求输入的载体,读者只需要业务规则与功能口径。真实评审中此句被产品经理点名删除。
- 这条大前提贯穿全流程:它决定第 6 步"原型说明"怎么写、第 7 步文案从哪来 —— 凡是给人看的字,都要过一遍"这是产品经理会说的人话吗?"。
---
## 何时该启用本 skill
**典型触发场景**:
- 有 PRD 草稿,需要做高保真原型给产品评审
- 已有原型,需要新增页面并保持视觉 / 交互一致
- 多页面之间的下钻关系 / 风格统一
**不适用**:
- 只是文案修改 / 单点视觉微调(直接改即可)
- 前后端联调阶段(已经超出原型范畴)
---
## 心法
**原型的本质**:让 PRD 里的概念 / 数据 / 工作流,**在产品评审现场用最低成本验证**。
不是"画一个漂亮的界面",而是:
- 让评审人能"走"完工作流,知道每个按钮干啥
- 让开发能据此估时
- 让所有的设计假设都暴露在视觉上,而不是埋在文档里
**原型 ≠ 视觉稿**。原型要"能动"(虽然假),要有跳转、有交互、有反馈。
---
## 七步法
### 第 1 步:抽出关键页面(IA 设计)
从 PRD 的视图设计 + 数据模型出发,列出**最小完整的页面集合**。
每页回答:
- 它的 destination 是什么(从哪进、到哪去)
- 它承载的核心动作(看 / 编 / 评 / 决策)
- 与上下页的关系(列表 → 详情 → 子详情)
**踩坑提醒**:**不要漏页**。漏掉一个详情页,下钻链就断了,评审时被卡住。
### 第 2 步:定义设计语言
> **本 skill 已内置「通用设计系统」基线,不要再从零造 common.css。**
设计语言基线已从 Figma组件库抽取并固化在本 skill 的 `assets/` 目录:
| 文件 | 作用 |
|---|---|
| `assets/common.css` | **样式基线**:`:root` 全量设计 token(色彩 / 字体 / 间距 / 圆角 / 阴影,含深浅主题)+ 30+ 组件样式,状态走 CSS 伪类 |
| `assets/common.js` | **交互层**:Select / TreeSelect / Tree / Modal / 标签页 / 分段 / 多选单选开关等"能点"的最小交互,按类名 + `data-*` 自动绑定 |
| `assets/skill-extras.css` | **原型辅助层**(非 Figma):`.snippet` 配置片段、`.summary-card` KPI 卡、`.field-spec` 字段规格表、`.proto-note` 原型说明分隔、需求便签/原型说明**可编辑覆盖层**样式等本 skill 约定 |
| `assets/原型编辑器.app`(**自包含单图标**,serve.js/launcher.js/panel.html 在 `Contents/Resources/` 内)+ `原型编辑器.vbs`(Win 入口)+ `原型编辑器.command`(Mac 兜底) | **原型编辑器**(跨平台,需装 Node):Mac 双击 App / Win 双击 `.vbs` → 浏览器开**控制页(壳)** `http://localhost:47821/`(操作说明 + 选原型 + 使用说明 + 停止)→ 选原型 → 页面上改需求便签/原型说明,自动写回该原型的 `data/annotations.js`。**关掉页面服务自动停**(心跳),固定端口可收藏。独立工具,放一处、选谁编谁,不拷进原型(见第 6 步) |
| `assets/组件规格表.md` | 62 个组件集的变体维度 + 逐变体真实取色(查色用) |
| `assets/组件样例.html` | 全组件演示页(对照样式 / 交互用) |
**标准动作**:做原型时,把 `assets/common.css`、`assets/common.js`、需要时加 `assets/skill-extras.css` **拷到原型目录**,各页面 `` / `
```
**为什么不直接给 JS 改文件名(如 check-items.v031.js)**:原型不是工程项目,没有构建工具自动重写引用;手工改文件名会让所有引用方都得跟着改、出错率高;`?v=` 参数法零侵入、改一行就行,完全够用。
**踩坑案例**:某次 v0.3.1 部署后评审同事反馈"总览表没看到 v0.3 删除线对比",查了 git 日志、CI 日志、远端文件都对,最后定位是浏览器缓存了旧的 `data/check-items.js`,无痕模式打开就正常。从此每次升版必带 `?v=x.y.z` 同步。
### 本地可编辑覆盖层(需求标签 / 原型说明 手改回写)
**解决的问题**:改动点旁的「需求标签 / 需求便签」(`.proto-tip` 弹层里的需求说明文字)、以及原型说明里的口径,产品想在页面上直接改,而不是回去抠 HTML;但改完要跟着发布进 GitLab 给评审看,发布后评审同事又不能有编辑入口。做法是把「手改」单独存一份**覆盖层文件** `data/annotations.js`,跟生成层(HTML)分家,渲染时覆盖回来。能力已内建在 `assets/common.js`,不用每个原型另写脚本。
**判据(只认主机名)**:`localhost` / `127.0.0.1` → 可编辑(通过「原型编辑器」打开,有本地服务能写文件),右下角出现「编辑态」开关;**`file://` 直接双击 = 纯看只读**(和原来一样是静态 HTML,不出编辑入口);其它 http 主机(内网域名,评审同事访问)→ 发布只读。不引入任何手动开关常量。
> 为什么 `file://` 也只读:只是本地看看原型时,就该跟原来一样。编辑是**主动**行为,只在你用「原型编辑器」把它跑到 `localhost` 时才开——顺带没了"改完要导出替换"那套,localhost 下直接写盘。
**原型编辑器(独立工具,跨平台,壳是一个控制页)**:自包含成一个 `原型编辑器.app`——`serve.js` / `launcher.js` / `panel.html` 都在它的 `Contents/Resources/` 里,用户目录下**只露一个 App 图标**,不会点错。Mac 双击 `原型编辑器.app`;Windows 双击同目录的 `原型编辑器.vbs`(Win 上 .app 只是普通文件夹,vbs 会钻进去跑);`原型编辑器.command` 作 Mac 兜底(App 因 GUI PATH 找不到 node 时用它)。需装 Node.js。
- **壳 = 控制页**:双击启动器 → 浏览器打开 `http://localhost:47821/`(`panel.html`),上面有操作说明、「选择原型文件夹」按钮、**最近打开 5 条历史**(localStorage,最近在前,点一条快速重开)、「使用说明」链接、「停止」按钮。点选原型 → 服务弹**原生选文件夹**窗 → 选中后在**新标签**进入编辑。
- **固定端口 47821**:不随机、可收藏。再次双击时如果服务已在跑,直接打开控制页,不重复启动。
- **每个原型自带 URL**:编辑页地址是 `/p//`,路径写在 URL 里、服务端无全局状态,所以**多个原型标签同时开也互不串**(保存各写各的 `data/annotations.js`)。相对路径发 `save-annotations`/`ping` 天然带上该前缀。
- **关掉页面 = 停服务**:控制页/编辑页每几秒发心跳;关某个原型标签不连带停(控制页可留着选下一个),所有页面都关掉后心跳超时(~15s)自动退,点控制页「停止」立即停。不用管进程、不弹黑窗。
- 控制页和编辑条上都有「使用说明」链接 → 插件 GitHub Pages(`https://yideng-xl.github.io/jg-product-design-skills/`)。只需装 Node.js。
**结构约定**(做原型时写进 HTML,别让脚本自动编号):
- 可编辑的文本载体带 `data-anno-id="页面前缀.类型-序号"`。前缀区分哪页、类型(`note`=需求便签说明 / `desc`=原型说明段 等)自定、序号区分第几条。
- **需求便签**:`data-anno-id` 挂在弹层的 `.pt-pop-item` 上(那段可复制的需求文字)。编辑态会强制把 `.pt-pop` 弹层展开(见 skill-extras.css),不用先点开就能改。
- **原型说明段**:挂在那段文字的容器上;整块富文本(含表格等)再加 `data-anno-rich`,存 innerHTML,否则存纯文字。
- 编号在编辑态左上角以 `#页面前缀.类型-序号` 显示(CSS `::after`),发布态不显示——你要对文件里哪一条、手改文件兜底,都靠它。
- (可选)要**整条增删**的一组标签(如一排 `.dev-tag`):chip 外层加 `data-anno-item`,容器加 `data-anno-container="页面前缀.tags"`,就能在页面上「+ 加一条 / × 删一条」,落进覆盖层的 additions / removed,重画原型也不丢。
**覆盖层文件**(`data/annotations.js`,挂 `window.__ANNO__`;用 `.js` 不用 `.json`,躲开 file:// 下 fetch 的 CORS。引用须在 `common.js` 之前):
```html
```
```js
window.__ANNO__ = {
overrides: { "gw-list.note-3": "手改后的需求说明文字" }, // 改需求便签 / 原型说明
additions: { "gw-list.tags": [ { "id": "gw-list.tags.add-abc", "text": "新加的标签" } ] }, // 可选:整条新增
removed: [ "gw-list.tag-7" ] // 可选:删掉的原件
};
```
**工作流**:双击「原型编辑器」(Mac `原型编辑器.app` / Win `原型编辑器.vbs`)→ 浏览器打开控制页 → 点「选择原型文件夹」选中要改的原型 → 进入编辑页,右下角开「编辑态」→ 改需求便签 / 原型说明(增删标签用 + / ×)→ **改动实时自动写进该原型的 `data/annotations.js`** → **改完关掉页面,服务自动停** → 照常 `git commit / push`,并按需升 index 里的 `?v=`。
给不懂技术的产品同事:整个过程就是「双击 → 控制页点选原型 → 在网页上改字 → 关页面」,不碰命令行、不弹黑窗(只需机器装了 Node.js)。不会用点控制页/编辑条上的「使用说明」看在线文档。
**三条铁律**:
1. `data-anno-id` 一旦给出,**只增不改不复用**——不能随手改名或让脚本按出现顺序自动编号,否则元素增删导致序号漂移、覆盖错位。新增元素给新号,删了的号也不复用。
2. `data/annotations.js` 是**产品所有**。生成 / 改原型时,HTML 生成层可以随便重写,但**永不覆写 annotations.js**;渲染时覆盖层盖回生成层,只要 ID 稳定,手改就不丢。
3. 发布态判据只认 `location.protocol`,不加任何"手动关掉开关"的常量或页面元素。
> 说明:这里的可编辑对象就是本 skill 既有的「需求标签 / 需求便签」(`.proto-tip`,见下文改动标注一节)和原型说明。机制是通用的——任何带 `data-anno-id` 的文本都能纳入覆盖层,不改既有徽标 / 弹层的做法,只是给弹层里的说明文字加了个 `data-anno-id` 让它能在页面上改。
### 第 7 步:目的地明确 + 不臆造文案(铁律)
**每个 href / onclick / 按钮 / 链接**,落笔前先回答:
- 点击之后**看到什么**?
- **去哪**?(具体哪个页面或哪个弹窗)
- **干什么**?(产生什么动作 / 状态变化)
答不清楚 → 要么删,要么停下来问。**不允许"先占个位置"**。
**每段文案 / 每个字段值**,落笔前先回答:
- 这段文字将来从哪个**录入界面**来?(规则编辑器 / 用户输入 / 数据库 / API)
- 想不出录入入口 → 这是个真实需求 → **提议加录入字段并挂起**,而不是硬编码塞进去
**踩坑案例**:
1. 某次加了"查看全部"链接没想清楚跳哪,评审被问"是看哪里",才承认是"随手放的"
2. 某次加了一段"说明:X 字段用于限制 Y 范围,请按贵单位规则配置具体 Z",评审问"这段文字来自哪里,是页面录入的吗",才承认是硬编码
### 第 8 步(关键):回写 PRD + 锁定本轮迭代范围
> 这一步是工作流的**收尾**,不可省。原型评审通过后,产品经理作为**迭代 owner**,要主动驱动这一步。
**为什么必须回写**:
- PRD 是开工前写的,设计阶段一定会浮现"原 PRD 没考虑到"的事(新的状态、新的字段、被砍掉的功能、跨模块的依赖等)
- 不回写 → PRD 跟原型/最终实现脱节 → 进入开发后,开发对照 PRD 做、QA 对照 PRD 测,**一堆"代码和文档不一致"的扯皮**
**回写要做的三件事**:
#### 8.1 把原型里的"新决策"回填进 PRD
逐页过一遍原型,把以下东西更新进 PRD:
- **新增的字段 / 状态 / 临时标签** → 更新数据模型章节、状态机章节
- **新增的视图 / 详情页 / 弹窗** → 更新 IA 和视图设计
- **砍掉的功能** → 在 PRD 里**显式标注"本轮不做,原因 X,挂起到下一版"**(不要悄悄删,要留痕)
- **形态变化**(比如批量操作的实现方式重做了) → 更新到对应章节
**纪律**:每一处回写都对照原型的具体页面;不许"我大概记得改了什么"。
**先分类:不是所有原型改动都回写 PRD。** 把本轮原型改动分两类——
- **进 PRD**:影响产品规则 / 行为 / 范围的(如某动作适用范围变了、设备候选与剔除规则、DSL 结构、功能下沉某版本、术语口径统一)。
- **不进 PRD,原型为准**:纯展示 / 交互约定(如时间格式、详情只读模式、字段汇总表、视觉以设计稿为准)——PRD 用一句"UI / 交互以原型为准"兜底即可,别把展示细节灌进 PRD。
**回写前先在会话里列清单、和用户对齐,再动笔(不要直接改 PRD)。** 按分级摆出来商议:
- **建议必改**:PRD 现写法与原型 / 决策直接冲突(留着会前后矛盾)。
- **建议改**:口径类,PRD 没写清、写清更好。
- **待用户拍板**:可能是范围调整、影响大(如"某功能要不要下沉下一版")——必须先确认再动。
- **不改**:纯展示约定(归"原型为准")。
**改一处要全文排查连带矛盾(grep 一遍)。** 一个决策会牵动多处散落引用——例如把某功能下沉到下一版,要同时捋:① 产品范围章节的该条目;② 版本规划章节;③ 菜单 / IA;④ 散落的"MVPx 价值呈现仅靠 XX""MVP1 仅 Top 10"这类措辞。漏一处就会前后打架。
**功能下沉(本期 → 下一版)的标准动作**:① 原范围章节条目改成"本期不实现 + 下沉说明 + 指向下一版";② 版本规划章节**新增完整条目**(把内容整段搬过去,不是只删);③ 菜单 / IA 加"本期不实现"注(原型 / 菜单可保留入口供技术提前规划颗粒度,但范围章节要写明不做);④ 连带措辞同步。
**愿景 / 场景章节与 MVP 范围章节分层**:产品愿景(价值主张)、用户场景描述的是**远期形态**,范围变动时**这些保持不动**,只改 MVP 范围条款(且经用户确认)——别因为某功能下沉就去删愿景里的相关描述。
**踩坑案例**:把"核查统计"从 MVP1 下沉到 MVP2 时,只改了产品范围章节;漏了"报告生成里写的『MVP1 价值仅靠统计页』""版本规划里『MVP1 仅 Top 10』""菜单仍把统计当本期"——这些散落引用得 grep 一遍全部捋顺,才不前后矛盾。
#### 8.2 定义本轮迭代的范围(scope 锁定)
在 PRD 加一个章节(或独立文件):
```markdown
## 本轮迭代范围(vX.Y.Z)
### 本轮包含
- 功能 1:[完整描述 + 链接到 PRD 章节 + 链接到原型页]
- 功能 2:...
### 本轮不包含(显式)
- 功能 A:挂起原因 / 预计版本
- 功能 B:...
### 设计需求(找设计师确认)
- 视觉规范 / 图标 / 插图 / 文案审校 / 无障碍标准 等
- 列出本轮需要设计师交付的资产清单
### 技术需求(找架构 / 后端 / 运维确认)
- 基础设施 / 数据库表 / 索引 / 缓存 / API 接口 / SDK / 监控埋点 / 部署变更 等
- 列出本轮需要技术侧交付的能力清单
### 验收标准
- 每个功能的"完成的定义"
```
**锁定后**:除非有强理由,**本轮不再加新需求**(scope creep 的最大来源就是开工后改 PRD)。
#### 8.3 找设计 / 技术确认(产品经理是迭代 owner)
把回写后的 PRD + 本轮迭代范围,**主动**发给以下人确认:
| 找谁 | 确认什么 |
|---|---|
| **设计师** | 视觉规范是否够用 / 还需要新画什么 / 文案审校 / 国际化 / 无障碍 |
| **架构 / 后端** | 数据模型是否合理 / 接口设计是否合理 / 跨模块依赖谁来推 / 性能瓶颈 |
| **运维 / SRE** | 部署变更 / 监控埋点 / 应急预案 / 容量评估 |
| **QA** | 验收标准是否可测 / 测试用例覆盖度 / 测试数据准备 |
**为什么产品经理主动找**:
- **产品经理是迭代 owner**,对范围、节奏、价值负责
- 设计师 / 技术 / QA 不会主动来问"PRD 改了吗",得 owner 推
- 这一步做得到位 = 后面开发期内的扯皮显著减少
**确认完后**:让对应负责人在 PRD 上签字(电子也行,留个 commit 记录),作为本轮迭代的"开工凭据"。
**踩坑案例**:某项目原型评审完直接进开发,PRD 没回写。开发对照旧 PRD 实现,QA 对照旧 PRD 测,等用户验收时才发现"咦,这跟当时评审的原型不一样啊?" —— 整轮迭代被打回返工。教训:**评审通过 ≠ 工作结束,回写 PRD 才是结束**。
---
## 把原型裁剪到本轮迭代范围:隐藏而非删除(铁律)
> 原型常常先做了"全集"(P0+P1+P2 都画了),评审时定了优先级,要把它裁剪成"本轮只看 P0"的精简版给开发/评审用。**裁剪用 `display:none` 隐藏,不要真删**。
**为什么隐藏而非删除**:
- 优先级会变 —— P1 功能一旦被研发评估完耗时、定了档,就要恢复。删掉了要重写,隐藏了只需去掉一行 `display:none`
- 全集原型是设计资产,记录了完整的设计思考;真删等于丢历史
- 隐藏是可逆、低风险操作,符合"破坏性动作要谨慎"的纪律
**怎么做**:
1. **优先级先有定档依据**。裁剪前先有一份 P0/P1/P2 排序结论(通常来自评审,落在一个 xlsx / PRD 章节)。按它裁,不要凭感觉。
2. **元素级非P0(按钮 / Tab / 区块)**:在元素上加 `style="display:none"`,并紧跟一行注释写明原因,方便日后恢复:
```html
📄 生成报告
```
3. **整页级非P0**:不删 HTML 文件,只隐藏**所有指向它的入口链接 / Tab**,让它在导航里不可达。文件留着,随时可恢复入口。
4. **当心"P0 详情页的唯一入口是 P1 列表"**:如果一个 P0 详情页只能从某个被隐藏的 P1 列表进去,直接隐藏列表会把 P0 页**孤立**。处理办法是给 P0 页**改挂一个 P0 入口**(例如把统计页的下钻从"按问题列表"改指向"按问题聚合详情"),既不指向隐藏页,又让 P0 页可达。**绝不能让 P0 内容变成无入口的孤儿**。
5. **导航/索引入口页(index)在评审时常是干扰**。它会把隐藏的页面也列出来、且要跟着维护卡片同步,容易乱。裁剪时可以把它**移到一边**(重命名为 `index.html.bak`,而非硬删)。各功能页自带顶部导航即可互相跳转。
6. **裁剪完必做一次"残留入口"扫描**:grep 全量 `href`,确认没有**可见的(无 display:none 的)**入口指向已隐藏的页面 —— 即"从 P0 活跃页面点进隐藏区域"的死胡同。详情页内部指向隐藏列表的"返回"链也要顺手改掉。
```bash
grep -n "被隐藏页.html" *.html | grep -v "display:none" # 输出应为空
```
**踩坑案例**:某项目把配置核查原型裁剪到 MVP1,统计页"多维度分析→按核查项"的下钻原本进入被隐藏的"按问题列表"。如果只隐藏列表 Tab 不管下钻,评审点进去就到了隐藏页;且"按问题聚合详情"(P0,跨设备批量SSH 视角)唯一入口也是这个列表,会被孤立。正确做法:把下钻改指向"按问题聚合详情",一举两得 —— 下钻不再进隐藏页,P0 详情页也有了来自统计页的正式入口。
---
## 检查清单(每加一个页面 / 一个组件,逐项打勾)
### A. 设计规范
- [ ] 引了 `assets/common.css`(+ 需要时 `skill-extras.css`),用其 token / 类名,**没硬编码色值**
- [ ] 状态徽章用了规范化的 `.status` 类;按钮用 `.btn` 体系,没自造样式
- [ ] 需要交互(下拉/树/弹窗/标签页切换)时引了 `assets/common.js`,按 `data-*` 约定写
- [ ] 配置片段用了 `.snippet` + `.snippet-wrap2`(skill-extras,不要造新轮子)
- [ ] 缺组件时改的是 common.css(全局升级),且对照 `assets/组件规格表.md` 取真实色值
### A2. UI 规范符合(七大易用原则 · 生成时即遵守)
> 完整标准见姐妹 skill 的 `../proto-check/assets/七大易用原则量化标准.md`(原型检查版 52 条,F/T/D/C/R/E/P;纯运行时 / 渲染主观 / 生产环境条目已删)与 `../proto-check/assets/产品设计自查表.md`。**做原型时就按它做,proto-check 事后会按同一份标准验收**——生成时遵守一条,验收时就少一条整改。下面只列生成时最容易违规的:
- [ ] 每个表单 / 弹窗 / 抽屉内**只有一个主按钮**(`.btn-primary`),落在最高优先级动作上;"取消"不用主按钮(F-01)
- [ ] 表格状态列一律用 `.tag`/`.status`,**不裸文本**表示状态(F-04)
- [ ] 操作列按钮 ≤3 全显;≥4 收【更多】,且删除类收进【更多】(F-07)
- [ ] 弹窗 / 抽屉都有标题 + 右上角 X + "取消"按钮,全局结构一致(C-01/T-02)
- [ ] 必填项红 \*、选填不标(C-04);格式敏感字段(IP / 时间 / 端口)placeholder 给格式示例(C-05,文案按「查询条 placeholder 统一」铁律)
- [ ] 命名统一:"新增"(不用"添加 / 新建")、"确认"(不用"确定")、"提交"只用于写后台(T-10)
- [ ] 列表页标配:关键字搜索 + 状态筛选(E-03);分页含总条数 + 页码跳转,默认 15 条/页(T-06/E-08);代表性列表给空状态示例或在 proto-note 说明(C-02)
- [ ] **列表 proto-note 必写三项(最易漏,Z-列表-02/04/09)**:① 默认排序字段 + 规则(如"按申请时间倒序");② 初始化默认展示范围(如"最近一周 / 全部");③ 数据刷新方式(手动查询 / 自动,自动注明频率)——这三项界面看不出,不写就是缺漏
- [ ] 删除 / 停用 / 重启按钮用 danger 红(F-02/P-03);高危操作绑二次确认(P-01)
- [ ] 单表单必填字段 >8 个时分组或分步(E-02)
- [ ] 长文本列省略号 + title 悬浮全文(C-13)
- [ ] 标准里标【说明】的条目(导出范围 / 批量部分失败提示 / 异常态展示 / 置灰原因 / 暂存规则等)不要求做交互,**写进 proto-note 业务规则**即可
### B. 交互完整性
- [ ] 每个 href / onclick / 按钮的 destination 明确(能说出"点了去哪/干什么")
- [ ] 没有 href="#" 的兜底链接(除非是占位的 demo,且原型说明里标注了)
- [ ] 二次确认弹窗在所有"状态变更 / 批量"操作上都加了
- [ ] 删除文案分两种(P-02):单条 / 行删除用 `确定要删除所选数据信息吗?`,批量删除用 `确认删除选择的 n 条数据吗?`(n 加粗);均不写个性化影响说明
- [ ] 复杂联动逻辑没硬做交互,而是用「逻辑表 + 测试用例 + 静态示例」在原型说明里讲清(用例枚举到组合 / 边界,不用伪代码)
- [ ] 页底配「按钮 / 交互事件清单」表(新增页全量、修改页只列改动),含弹窗 / 抽屉内交互,每条写清触发后行为与校验 / 状态变化
- [ ] 清单范围只含 按钮级操作 + 有联动的输入控件;普通录入 / 筛选控件、i 图标等原型辅助元素、"只读无交互"占位行均未混入
- [ ] 详情类入口都能点进去,进入后是只读模式(禁录入 + 隐藏保存 / 执行 / 删除),与"编辑"复用同一页面靠 `mode=view` 区分
- [ ] "执行 / 触发 / 下发"类动作:先弹确认框,确认后状态就地变化(如结果列显示「执行中」、按钮置灰),不做行内实时进度条
### C. 文案合规
- [ ] 界面文案只放最终用户看得到的内容
- [ ] 所有展示文案都能 trace 到一个录入字段(规则 / 用户输入 / 数据库)
- [ ] 没有英文术语直接出现在界面(产品语义层的英文术语 → 翻译成中文,如 chip → 标签)
- [ ] 原型说明放在底部的"原型设计说明"区,不污染界面
- [ ] 原型说明只讲本期可见功能;不提 V2 / 计划执行 / 已完成等非本期内容,不写"(评审决议)"和"长度沿用某表"样板脚注
- [ ] 原型说明 / index 无实现侧自述(不提 common.css / 设计系统基线 / 色值 / 文件结构)
- [ ] index 的「版本变更记录」是独立章节标题(与 PRD 摘要同级),没埋在原型说明卡片里
- [ ] 数据权限不逐页画矩阵;index 有一条固定「数据权限说明」指向统一维护处(https://365.kdocs.cn/l/cuTDkjddouuf)(Z-整体-10)
### D. 列表设计
- [ ] 列宽做过预算,表头不会换行 / 数据列不会被挤
- [ ] 关键字段拆分到位(名称+ID, 一级归属+二级归属, 当前+历史)
- [ ] 表格里"未解决 / 已解决 / 完成率"等关键指标有视觉强调(粗体 / 颜色)
- [ ] 记录类 / 查阅类列表默认不带前置多选框(只有确有批量操作时才加多选列)
- [ ] 列表里已有的"总数"列,不要在其他列的比值里重复(如"不合规设备"别再写 N/总数)
### D2. 字段录入规格表(有录入的页面)
- [ ] 有录入的页面(表单 / 弹窗 / 筛选)都配了「字段录入规格表」,列齐:填写方式 / 必填 / 类型 / 长度 / 校验 / 数据源(单选?多选?)/ 关联
- [ ] 下拉数据源分清 固定枚举 / 字典 / 接口列表(设备·网络·站点是"列表"不是"字典")
- [ ] 有级联的拆成两个字段(如厂商 + 版本),不合并成一个字典
- [ ] 长度给具体上限,不写"不限"(短文本 50 / 长文本 300 / 配置示例 1000 等)
### E. 视图一致性
- [ ] 同类内容(如"当前状态 + 推荐操作")在不同页面用相同的组件结构
- [ ] 命中事件列表 / 对象 chip / KPI 卡 在所有页面看起来一样
- [ ] 状态色在所有页面表达相同的语义(回退→橙、完成→绿、新增异常→红)
- [ ] 同一概念跨页同名(字段标签 / 列名一致);时间戳统一 `YYYY-MM-DD HH:MM:SS`
- [ ] "当前配置"等展示类字段都给实际配置片段,没有用"未配置 XX"结论文字充当配置
- [ ] 历史 / 累计明细只展示最近 N 天且注明,次数仍按全量统计
### F. 边界与挂起
- [ ] 本模块不解释别的模块的事(职责越界要警惕)
- [ ] 跨模块依赖 / 待澄清的边界 → 已写入挂起话题清单
### G. 评审后的回写(关键 · 第 8 步)
- [ ] 回写前已分类(进 PRD 的产品规则 / 行为 / 范围 vs"原型为准"的展示约定),并在会话里跟用户对齐分级清单(必改 / 建议改 / 待拍板 / 不改)后再动笔——不直接改 PRD
- [ ] 原型评审通过后,PRD 已逐页回写(新增字段 / 新状态 / 砍掉的功能都更新到位)
- [ ] 范围下沉 / 重大决策已 grep 全文排查连带矛盾(产品范围 / 版本规划 / 菜单·IA / 散落措辞都捋过,不前后打架)
- [ ] 本轮迭代范围已锁定:本轮包含 / 本轮不包含,显式列出
- [ ] **设计需求**已列清单 + 找设计师确认
- [ ] **技术需求**已列清单 + 找架构 / 后端 / 运维确认
- [ ] **验收标准**已写,每个功能的"完成的定义"明确
- [ ] 各方在 PRD 上签字 / 留 commit,作为开工凭据
### H. 裁剪到本轮范围(隐藏而非删除)
- [ ] 非P0 一律用 `display:none` 隐藏,没有真删文件/代码
- [ ] 每处隐藏都有紧邻注释写明原因(如 `MVP1 非P0隐藏:XXX(P1,原因)`),方便恢复
- [ ] 整页级非P0:文件保留,只隐藏指向它的入口链接 / Tab
- [ ] 没有 P0 内容因"唯一入口被隐藏"而变成孤儿(必要时给 P0 页改挂 P0 入口)
- [ ] index 导航页若有干扰,已移到一边(.bak)而非硬删
- [ ] 已 grep 扫描确认:无"可见入口"指向已隐藏页面(含详情页内的返回链)
---
## 原型规范(实战版)
### 配色(通用设计系统 · 取自 Figma,已固化在 assets/common.css)
| 语义 | 色值 | CSS 变量 |
|---|---|---|
| 主色 / 品牌(主色绿) | #007D7B | `--color-primary` |
| 主色 hover / pressed / disabled | #4CA4A3 / #198A88 / #80BEBD | `--color-primary-hover` 等 |
| 输入聚焦边框 | #0FA081 | `--color-input-focus` |
| 链接(链接蓝) | #418CFD | `--color-link` |
| 信息 | #1890FF | `--color-info` |
| 成功 / 完成 | #52C41A | `--color-success` |
| 警告 / 回退 | #FAAD14 | `--color-warning` |
| 危险 / 失败 | #FF4D4F | `--color-danger` |
| 标题 / 正文 / 次要 / 禁用文字 | #333333 / #565656 / #999999 / #BDBDBD | `--text-title` 等 |
| 页面背景 / 卡片 / 表头 / 选中行 | #EFF3F8 / #FFFFFF / #F8F8F9 / #E6F2F2 | `--bg-page` 等 |
| 边框 / 分割线 | #DCDFE6 | `--border-color` |
> 功能色均带 8% 浅底 + 20% 描边的 Tag 变体;Tag 另有紫 #A063EE / 黄 #FCD853 / 粉 #FF66C1。**取色一律用变量,不要写死。**
### 字号
| 用途 | 字号 |
|---|---|
| 表格内文字 | 13px |
| 表头 / section 标题 | 14px |
| 一级标题 | 18-20px |
| 次要说明 | 12px |
| 标签 / 徽章 | 11-12px |
| 代码块 | 12px(等宽字体) |
### 状态色与图标
| 状态 | 图标 | 类名 |
|---|---|---|
| 待处理 | 🔴 | status-pending |
| 待验证 | 🟡 | status-waiting |
| 已验证 | 🟢 | status-verified |
| 已忽略 | ⚫ | status-ignored |
| 失败 | ✗ | status-failed |
| 临时标签:回退 | - | tag tag-warn(橙底) |
| 临时标签:处理失败 | - | tag tag-danger(红底) |
### 暗色代码 / 配置块
```css
.snippet { background: #2d2d2d; color: #d4d4d4; font-family: 'Consolas', monospace;
font-size: 12px; line-height: 1.6; padding: 8px 10px; border-radius: 3px;
white-space: pre-wrap; }
.snippet .bad { background: #5c2d2d; color: #fff; padding: 1px 4px; border-radius: 2px; }
.snippet .good { background: #2d5c33; color: #fff; padding: 1px 4px; border-radius: 2px; }
```
复制图标固定在右上角:
```css
.snippet-wrap2 { position: relative; }
.snippet-wrap2 .copy-icon { position: absolute; top: 6px; right: 8px;
background: rgba(255,255,255,0.1); color: #d4d4d4;
padding: 2px 6px; border-radius: 3px; cursor: pointer;
font-size: 11px; }
```
### 对象 chip(可勾选 + 可跳详情)
```html
对象名 / 标识
```
### 命中事件列表
```html
```
### 操作按钮的二次确认
凡是"状态变更"或"批量"操作,落地前必须有一步确认,不能点了就直接生效。
**删除类操作:统一用标准文案,不做个性化。** 行删除、批量删除共用同一个弹框,文案就是 `确定要删除所选数据信息吗?`,不要逐个动作写"影响 1 / 影响 2 / 不可恢复"那种个性化说明 —— 评审会嫌啰嗦,实现也难统一。一个 `confirmDelete` 函数,行删除和批量删除都调它:
```javascript
// 行删除 / 批量删除统一调用,不做个性化文案
function confirmDelete(event) {
if (event) event.preventDefault();
if (confirm('确定要删除所选数据信息吗?')) {
alert('已删除。');
}
}
```
```html
删除
```
**其他状态变更(停用 / 启用切换 / 取消 / 恢复等):** 一个确认弹窗即可,文案点明"将要做什么"。除非业务上影响面确实复杂且评审认可,否则不必堆影响清单、也不必双重确认 —— **先用最朴素的一步确认,别过度设计**。
**踩坑案例**:某次给批量删除写了"双重确认 + 三条影响范围说明"的个性化弹框,被要求改回统一的 `确定要删除所选数据信息吗?` —— 删除类的确认要的是"拦一道",不是"写一篇"。
### 多对象批量操作:命令输入 + 设备列表 + 发送状态
如果设计涉及"对多个对象同时执行操作"(如批量 SSH 远程操作多机),**默认用「命令输入框 + 设备列表 + 每台发送状态」形态**:
- **一个命令输入框**(默认留空,运维自己输 / 粘贴),点「发送命令」一次性发送到所选对象
- **结果按状态分组折叠**:发送成功 / 连接不上 / 认证失败 / 发送失败,顶部给「成功 N 台 / 失败 M 台」汇总,失败项默认展开看原因
- **分组粒度**:按厂商版本等"命令体系一致"的维度分组发送,跨组不可合并
**两个常见坑**:
1. **别画"多终端实时广播窗口"**:Xshell / SecureCRT 风格的"打开 N 个终端 + 顶部统一命令栏 + 实时广播 + 每窗独立输出流"看起来很爽,但**实时多终端流的技术实现成本高**,某真实项目评估后放弃,降级为"发送 + 状态回执"。原型阶段就按可落地的形态画。
2. **别把它包装成新功能名**:它仍是运维手动的「批量 SSH」,**不要起名「批量下发 / 配置下发」**——那会被理解成"配置自动推送"这种本期不做的新能力,误导研发与评审。命名贴着真实能力走。
**单设备的交互式终端**(单台「一键 SSH」)不在此限制内:它就是一个可输入命令、实时回显的终端窗口(标题栏 + 深色终端体 + 提示符 + 底部命令行),该保留就保留。
**通用心法**:涉及"炫酷但不确定能否实现"的交互形态,原型落笔前先跟技术确认可行性;不可行的,主动降级到可落地的形态,而不是把做不出来的东西画进原型骗过评审。
### 执行 / 触发 / 下发动作的交互(与同类下发动作保持一致)
"立即执行 / 触发任务 / 下发"这类动作,**对齐系统里已有的同类下发动作**(如配置备份),不要自创一套:
- **先弹确认框**:点击后弹一个小确认弹窗 —— 标题=动作名(如「执行」)、正文「确定要执行该任务吗?」、按钮 取消 · 确认。
- **确认后就地改状态**:结果列就地显示「执行中」,触发按钮变为进行中态并置灰、不可重复点;**不要在列表行内做实时进度条**(成本高,也不符合"下发式"心智)。
- **完成回填**:后台完成后,结果列回到 ✓ 成功、记录列给最新执行时间链接、按钮恢复。
- **入口收敛**:执行入口放该放的地方(如任务列表),**不要在编辑器里也放一个**——一个动作一个入口。
**踩坑案例**:① 一开始给"立即执行"做了列表内实时进度条,被要求改成"弹确认框 + 结果列显示执行中"的下发式,与配置备份一致;② 在编辑器里也加了"立即执行",被要求去掉,只在列表保留。
---
## 主会话 + 子 agent 协作模式(强制规范)
> 当原型涉及 5 个以上页面时,**必须采用主会话编排 + 子 agent 执行**的两层模式,而不是让主会话一个人闷头做。这不是建议,是强制规范——它直接决定 context 是否会爆、共性问题能否沉淀、跨页是否一致。
### 为什么必须分层
- **主会话**作为单一会话连续推进,**沉淀共性规则与跨页一致性**;一旦发现共性问题(如"删除按钮都要二次确认"、"英文术语换中文"),改一次,所有页面都能跟进
- **子 agent**承接单页 / 批量页 / 审计等可隔离的执行性任务,**子 agent 的 context 不污染主会话**——主会话保持轻量,长会话不会因为 cache 爆炸而注意力涣散
- 子 agent 还可以**并行**,5 个页面一次性 spawn 5 个 agent,主会话只等汇总
### 三层产物
| 层 | 谁产出 | 角色 |
|---|---|---|
| **conventions.md**(项目级约定文档) | 主会话和用户共同迭代 | 子 agent 的"宪法",每次 spawn 子 agent 必须整段塞进 prompt |
| **页面原型 HTML** | 子 agent 单独完成 | 落地具体页面,严格遵循 conventions.md |
| **跨页一致性 / 共性问题清单** | 主会话(或 Audit Agent) | 定期审计,把发现的共性问题加回 conventions.md |
### conventions.md 必含内容
第一次开会话时,主会话和用户对齐出一份 `conventions.md`,放在原型目录根。最小集:
- **颜色 / 状态码体系**:status-verified 绿 / status-failed 红 / status-ignored 灰 ...
- **命名规则**:站点用 A~J 指代 / 网络用 GGW 一二平面等行业风格 / 监管条款字段叫"监管条款"
- **二次确认规则**:停用 / 删除 / 启用切换 / 取消 / 恢复等状态变更落地前必须有一步确认;**删除类统一用标准文案 `确定要删除所选数据信息吗?`,行删除与批量删除共用,不做个性化**
- **列表多选框约定**:**记录类 / 查阅类列表默认不带前置多选框**;只有列表上确有批量操作(如批量删除任务)时才加多选列
- **不允许目的地不明的链接**:href="#" / onclick="alert" / 无目的地按钮一律不允许
- **统一中文术语**:切换标签(代替 toggle-tab)/ 弹窗(modal)/ 标签(chip)/ 鼠标悬停(hover)等
- **共用 common.css 的类名约定**(导航 / 表格 / 按钮 / 卡片 / 状态等)
- **设计原则**:产品 UI 主体与"原型设计说明区"必须用分隔线明确隔开
- **时间格式**:统一 `YYYY-MM-DD HH:MM:SS`;纯日期 / 定时时段除外
- **详情入口**:详情都进只读模式(与编辑复用页面,`mode=view` 区分),只读态隐藏保存 / 执行 / 删除
- **执行 / 触发 / 下发动作**:先弹确认框(标题=动作名、正文"确定要…吗?"、取消·确认),确认后就地改状态(如"执行中")+ 按钮置灰,不做列表内实时进度条;与同类下发动作(如配置备份)保持一致
- **内容展示口径**:配置 / 快照类展示实际片段,不用结论性文字充当;历史明细只展示最近 N 天、次数仍全量统计
### 标准操作流(SOP)
```
阶段 1:主会话规则对齐
你 → 主会话:"做 X 模块"
主会话 → 你:迭代 conventions.md,直到双方拍板
阶段 2:页面级任务分发
主会话 → spawn N 个子 agent(并行):
每个 prompt 包含:
- conventions.md 整段
- 该页面的字段表 / 操作 / 状态 / 跳转
- "如不确定 X,留 stub 并回报,不要自行决策"
子 agent 各自返回:HTML + 自检报告
阶段 3:主会话汇总 + 共性问题沉淀
主会话验收 → 必要时 spawn Audit Agent 跑跨页一致性检查
→ 报告给你
阶段 4:你提共性反馈
你:"删除应该二次确认,不应该直接生效"
主会话:
1. 加到 conventions.md(沉淀)
2. 必要时加到 memory(更长期)
3. spawn 批量整改 agent,扫所有页面统一改
重复阶段 3~4 直到原型定稿
```
### 哪些任务不该走子 agent(主会话直接做)
| 任务 | 为什么 |
|---|---|
| 迭代式微调("再压一点 / 把那段挪到附录") | 一来一回多轮,子 agent 一发一议不适合 |
| 不确定的需求 / 需要用户介入对话 | 子 agent 不能问用户,只能猜 |
| 1~2 个文件的小改 | spawn 子 agent 的 prompt 成本 > 直接改 |
| 强业务判断 / 历史决策回顾 | 主会话有上下文,子 agent 拿不到 |
### 主会话刻意避免做的事(节省 context)
- **不直接 Read 整批 HTML 文件做审计** —— 用 Explore Agent 或 Audit Agent 跑,只接收报告
- **不重复 Read 同一文件**(信任 Edit 工具的反馈,不必 Read 验证)
- **大块文件操作走 Bash + sed / Python 脚本**(批量替换 N 行,不要给 N 个 Edit 调用)
- **同一文件改多处用一次 `Edit replace_all=true`** 或合并 Edit,不要 Read-Edit-Read-Edit
- **超过 50 个页面 / 跨多模块的大型原型项目**,考虑按模块拆主会话,不要一个会话扛全部
### 主会话切换主题前的纪律
如果用户从"原型 X"切换到"原型 Y"或"plugin 维护"等不同主题:
- 建议用户 `/compact` 让主会话先把历史压缩成摘要再继续
- 或者直接开新会话,把 conventions.md / 关键记忆作为新会话起点
主会话不是"无限堆叠"的容器,**该清就清**。
---
## 常犯的错(避坑)
### 错 1:没建设计语言就开始画
每个页面颜色 / 间距 / 字号自己选,最后视觉碎片化。**common.css 是第 0 步**。
### 错 2:没抽共性组件
做了 5 个页面才发现重复代码到处都是,改一处要改 5 个文件。**共性组件在第 2 个页面就抽**。
### 错 3:目的地不明的兜底链接
"先放个 href='#' 等以后再说" —— 评审时会被问到,等于把"想清楚"的成本推给用户。
### 错 4:臆造文案
"我替产品写一段合理的说明" —— 错。产品里没这字段就别加。
### 错 5:原型说明污染界面
把设计意图 / 范围说明 / 跳转逻辑放在界面里 —— 最终用户会看到一堆开发文档。
### 错 6:多视图维度重复
做了三个视图,其实只是同一份数据的三种 fold 状态。**第 1 步做 IA 时就要逼自己问"每个视图独立回答什么问题"**。
### 错 7:列宽不做预算
凭直觉给列宽,表头换行 / 数据列被挤 / 前后版本不一致。**做表格前列出列宽预算**。
### 错 8:跨模块的事放进本模块
本模块不该承担的责任(别的模块管的事),不要塞进来。**边界要清**。
---
## 评审反馈快速迭代的工作流
收到用户反馈后(无论是面对面评审还是文字反馈):
1. **先听完,不急着改**。把所有反馈先列出来。
2. **分类**:
- 视觉微调(列宽 / 配色 / 间距) → 直接改
- 文案 / 术语 / 字段名 → 直接改,同步更新术语字典
- 交互逻辑(跳转 / 状态 / 操作) → 在改之前先用 **AskUserQuestion** 对齐选项,**不要凭空猜**
- 设计基线变化(视图维度 / 数据模型) → 先讨论清楚,可能重做
3. **改完贴出来给用户验证**。不要等改完一大堆才一次给。
4. **记录犯过的错**:每次"我没想清楚"或"我以为可以"出现时,记到 memory / skill 的"常犯错"章节。
---
## 输出物清单
完成本 skill 后,你应该有:
1. **HTML 原型集合**(每个页面一个文件)
2. **共享样式表**(common.css)
3. **导航页**(把所有原型页串起来,作为评审入口)
4. **设计规范文档**(可以是本 skill 的"原型规范"章节的项目化版本)
5. **挂起话题清单**(继承自姐妹 skill `requirements2prd`,继续更新)
6. **回写后的 PRD 终稿**(对应第 8 步)
7. **本轮迭代范围定义**(本轮包含 / 不包含 / 设计需求 / 技术需求 / 验收标准)
8. **各方确认记录**(设计 / 技术 / QA 签字或 commit)
---
## 与上一步、下一步的衔接
- **上一步**:姐妹 skill **`requirements2prd`**(本 plugin 内的另一个 skill) —— 提供 PRD、术语字典、视图设计基线
- **关键收尾**:第 8 步 —— 回写 PRD + 锁定本轮迭代 + 拉通设计 / 技术 / QA 确认
- **下一步**:开发 / 联调 —— 拿着回写后的 PRD 终稿 + 锁定的迭代范围 + 各方确认凭据开工。**common.css 直接拿去用,组件结构 1:1 实现**