可视化 PRD

概述

可视化产品需求设计

作者：公众号“AI 翻车现场”的智障研究员

本增强版以用户提供的 visual-prd-aifanche-4.0.2.zip 为原版基底，保留其完整能力；2.2.1 仅作为新增能力的来源。新增功能不删除或替换原版三种工作模式、产品模型、界面规范、需求交接、指标定义或评审模式。原包正文标注 4.1.4 属于其已有元数据差异，不能据此更换基底。

以三栏评审容器、标注协议、离线装配和自检为稳定核心。PRD、原型及其视觉规范都是可替换输入；不要强迫已有项目使用默认产品模型或组件模板。

先选择最小工作模式

读取 [工作模式与交接契约](references/operating-modes.md)，按用户已有材料选择一种模式：

用户给出的是目录时，先查找现有 visual-prd.project.json 和已适配的原型工作副本；Axure 导出的 index.html／start.html 只是载入其他页面的入口壳，不能直接当成单文件原型装配。

• 装配模式：已有 PRD、带标注占位的原型和标注数据；只校验并装配。
• 增强模式：已有普通 HTML 原型；若尚无标注，先按 [现有原型从零建立标注](references/bootstrap-existing.md) 在工作副本中建立 annotations.json 和一一对应的 data-anno 锚点，再注入运行时和装配，不改原文件及其交互。
• 生成模式：只有需求或产品想法；从 product-model.json 派生 PRD、原型与标注。

使用 visual-prd.project.json 固化模式和输入路径，再运行：

python3 scripts/build-review.py visual-prd.project.json

不能把空数组 [] 当作“已有标注”；构建器会拒绝零标注的增强或装配结果。若用户只有原型，没有 PRD 或规则材料，可先写明“原型观察记录，业务规则待确认”，只标注能从页面或代码直接核对的交互，不编造权限、状态和验收规则。

旧项目仍可直接运行 build-container.py 或 build-project.py。

资源路由

• 装配、增强模式先读取 [工作模式与交接契约](references/operating-modes.md)；只有现成 HTML 尚无标注数据或锚点时，再读取 [现有原型从零建立标注](references/bootstrap-existing.md)。随后按需读取 [标注指南](references/annotation-guide.md) 和 [自检清单](references/interaction-checklist.md)。
• 生成模式再读取 [单一产品模型与低冗余工作流](references/token-efficient-workflow.md)，从 [产品模型模板](assets/product-model-template.json) 创建模型。
• 生成模式需要贴近现有产品时，读取 [界面规范配置](references/ui-profile.md)，从 [界面规范模板](assets/ui-profile-template.json) 创建可复用配置；已有 HTML 默认保留自身样式。
• 声明式组件不能表达关键交互时才读取 [原型骨架](assets/prototype-template.html)；仍须沿用 data-action 和标注协议。
• Markdown、故障、指标、交接和安全问题分别按需读取对应 reference，不得为普通任务加载全部资料。
• 需要评审编辑、磁盘保存、流程图或开发页面下载时，读取 [编辑与导出指南](references/editing-and-export.md)。这些能力使用标准容器，不另造一套页面。

共同约束

• 不覆盖用户提供的 PRD、原型或产品模型；所有增强和构建结果写入输出目录。
• 标注内容必须来自需求、业务规则或验收条件；未知内容标为“待确认”。
• 产品说明直接呈现需求内容，不添加“说明来源”“来自某文件/截图”等生成过程文案；核对依据保留在产品模型或交接材料中，不删业务必需的数据来源说明。
• annotation.order 是编号唯一来源，原型圆点和右侧面板禁止使用数组下标计算编号。
• 标注 ID 与 data-anno 必须一一对应；缺数据、缺锚点、重复锚点或可见作用域断号均构建失败。
• 增强模式必须交付至少一条真实可见、可点击定位的标注；仅有三栏容器而没有标注圆点和对应说明，不得报告构建成功。
• 最终容器只保存一份标注数据；内嵌原型由父容器运行时注入。
• 已有原型默认不注入 prototype-runtime.js，避免覆盖自身路由和事件；生成模式统一使用该运行时。
• 界面规范只控制生成器输出或用户明确授权的适配副本，不能用全局 CSS 强行重写任意现有原型。
• 传入 ui-profile.json 时，最终评审页必须显示“界面规范”入口；评审者可实时调整全局默认或当前页面覆盖，并导出可重建的配置。
• 配置器必须拒绝越界数值与低于 4.5:1 的关键文字配色；显式 appearance 锁定和页面覆盖必须可见提示，不得让不可生效的配置看似已生效。
• 特殊业务组件使用 custom 或用户自己的 HTML；不得承诺任意系统自动一比一复刻。

生成模式补充

• 业务事实只写入 product-model.json；PRD、标注和通用原型均为派生产物。
• 优先使用声明式组件；组件外观引用 ui-profile.json，不要在页面中重复整段 CSS。
• 未提供界面规范时使用内置中性评审样式，保证 3.0 产品模型继续构建。
• 修改单个板块时只加载相关模型切片，完成后仍校验完整模型。

交付与验证

• 交付 build-report.json 的 primary_artifact 指向的 visual-prd.html；这是唯一主交付，需要独立查看时才同时交付 prototype.html。
• 禁止绕过 build-review.py 另行手写、复制或重命名一份同名评审容器；扩展容器必须修改标准模板后重建。
• 主交付必须同时保留三栏评审与浮动标注两种模式，顶部入口要明确显示即将切换到的模式。保留现有模式切换行为，不把模式按钮改成某个栏位的开关。
• 跨页面说明固定保留产品概述、流程图、功能需求、角色权限、业务规则、待确认与决策、数据与发布七个栏目；材料缺少某栏内容时显示待补充，不删除入口。
• 流程图预览支持点击全屏查看、滚轮缩放和 PNG 图片下载；放大查看状态与渲染图为临时展示，不作为源码写回。
• 保留逐条标注编辑、独立栏位开关、流程图栏目、授权自动写回、单页 HTML 与全部页面 ZIP 下载。流程图在产品概述后，以 Mermaid 围栏源码和配套文字说明编辑，离线预览为 SVG；真实业务流程依据确认材料，未知规则标为待确认。三种模式均可在项目清单 inputs.flows 中指定 flows.md。
• 原型默认随可用画布宽度自适应，关闭两侧栏、调整栏宽或切换评审模式后继续填满画布；固定宽度原型按编辑与导出指南标记外层布局，不改业务组件和模式按钮行为。
• 顶部标题栏高度为 48 px，只保留 Logo 与主标题，不附加版本、页面数或标注数副标题。标题栏下的全宽工具栏左侧为页面翻页与选择，右侧依次为“编辑、下载、重新载入”；不另设重复当前页信息行，不添加画布/缩放控制、“本页需求”或右上角产品背景文字。已有项目的评审场景选择可保留在导航旁；选中项必须与实际场景同步，具体约束见编辑与导出指南。原型画布无外边距、边框、圆角或阴影，填满可用区域；仅调整评审容器，不移除原型内部业务布局。
• 全宽工具栏提供“编辑/完成编辑”，可点击修改 HTML 文案，保留图标、锚点、事件和字段绑定；修改随评审 HTML 保存并进入单页/全部页面导出。编辑模式只针对原型，临时编辑框与开关不写回；具体规则见编辑与导出指南。
• 左侧产品说明标题只显示“跨页面产品说明”，不附加英文眉题或 Markdown 标签。文档输入即提交自动保存，失焦不丢修改，不提供重复的“立即保存”按钮。
• 标注与文档修改立即提交保存；首次授权选择正在编辑的已有 HTML 后自动写回该文件。未授权时通过顶部“授权自动写回”选择文件。只有写入成功才能显示已写回；写回 HTML 不会修改 product-model.json、prd.md、flows.md 或 annotations.json 源文件。需更新正式需求时回写对应源文件并重建。
• 生成模式同时交付 product-model.json；使用自定义界面规范时同时交付 ui-profile.json 与 ui-profile-preview.html。
• 浏览器中的规范修改先保存在本机；需要回写项目时导出 ui-profile.json 并用它重建，不得把运行时状态冒充为已修改源文件。
• 先运行 python3 scripts/validate-review-artifact.py <visual-prd.html> 与其他静态检查，再在真实浏览器检查关键流程、三栏/浮动切换、响应式布局、标注定位、组件状态和控制台断言。已有原型至少抽查首页及切页后各一条圆点；右栏有数据但圆点全无时，检查原型 body[data-anno-page] 与运行时当前页 ID 是否一致，不把 PASS_STATIC 当成视觉通过。
• 失败项修复后重建；最终只汇报关键决策、文件链接、自检结果与实际修复记录，不在对话中粘贴完整派生产物。

迁移与发布

运行 python3 scripts/validate-package.py，再运行 python3 scripts/package-skill.py。不得手工压缩；压缩包必须离线、自包含、无系统垃圾和平台专属元数据，并保留原作者署名。