Install
openclaw skills install @barry0-0/pm-proto-prd-pinA zero-dependency, plug-and-play interactive PRD annotation and multi-version specification framework for any HTML prototype
openclaw skills install @barry0-0/pm-proto-prd-pinpm-proto-prd-pin 是一套高保真、即插即用、生产就绪、跨框架兼容的原型交互规约标注引擎(纯原生 Vanilla JS + CSS + Vditor IR 引擎 + Serverless 云端 KV / GitHub REST API / Node.js 本地微服务)。
它不仅支持传统的静态 HTML 原型(后台管理系统、电商前台、移动端 H5、PC 门户等),还原生兼容现代 Vue (2/3/Vite/Nuxt) 与 React (17/18/Next.js) SPA 单页应用,瞬间赋予专业的产品经理(PM)交互式打点标注、多版本管理、集成 Vditor 即时渲染与 Tab 多级缩进工作台、纯白 Mermaid 流程图动态防截断渲染、全景文档大屏展示以及三模态持久化与权限强鉴权能力。
zh-CN / zh_CN)en / en_US)ja / ja_JP)ko / ko_KR)localStorage('prd_ui_lang');🌟 核心铁律 (Strict Zero-HTML Generation In Modern Frameworks):
当识别到项目为 React (Vite / Next.js / CRA) 或 Vue (Vue 2/3 / Nuxt) 等现代前端 SPA 工程时,严禁生成任何独立的.html原型文件!
现代工程已有完整的组件与路由体系,打点工具仅作为全局外挂图层(通过main.tsx/main.js导入),实现零新增 HTML、零模板污染、零业务侵入。
🌟 核心规范 (Core Protocol):
本引擎具备跨技术栈自适应能力。在执行打点工具集成前,Agent 必须执行两步感知与确认流程:
package.json 中的 dependencies.vue、vue.config.js、vite.config.*(含 @vitejs/plugin-vue)、或 nuxt.config.*;package.json 中的 dependencies.react、next.config.*、vite.config.*(含 @vitejs/plugin-react)、或 App.tsx/index.jsx;.html 原型文件(如 admin.html、index.html)且无前端构建依赖;package.json 或无法明确推断框架体系,Agent 必须向用户发起明确提问:
💬 “请问当前项目采用的是什么前端框架?(HTML 静态原型 / Vue 2/3 / React / Next.js / Nuxt)以及 PRD 打点标注工具需要应用在哪些页面或模块?(全局所有路由页面 / 仅特定业务端页面)”
.html 页面文件;prd-pin-tool.js 与 vendor/vditor 置于 public/assets/js/ 和 public/assets/vendor/;src/main.tsx 或 src/App.tsx 中写入:
import '../public/assets/js/prd-pin-tool.js';
index.html,零侵入原有业务组件。.html 页面文件;src/main.js 或 src/main.ts 中写入:
import '../public/assets/js/prd-pin-tool.js';
</body> 闭合前引入 <script src="./assets/js/prd-pin-tool.js"></script>。🌟 云端强确认后置缓存核心原则 (Post-Cloud Confirmation Cache Principle):
- 严禁前置假保存:严禁在云端请求返回前静默写入
localStorage假装保存成功;- 真实 HTTP 200 强校验:必须在收到云端 Serverless KV 返回的
HTTP 200 OK且携带合法record/metadata实体后,才允许将数据镜像写入localStorage作为客户端离线/秒开缓存;- 失败原子回滚:若云端网络超时或鉴权失败,系统立即阻断并自动回滚内存状态,弹出红色错误 Toast,杜绝本地与云端数据不一致;
- 跨浏览器/多端免密直读:代码中通过
DEFAULT_JSONBIN_MAPPING固化绑定公开只读 Bin ID,任何同事、评审方在新电脑/新浏览器(含无痕模式)中打开,启动时自动从该 Bin ID 秒级拉取最新规约,实现真正的「全员零配置直读、创立人权限写入」。
🌟 跨浏览器/多端免密实时同步核心架构原理 (Cross-Browser Zero-Config Protocol):
- 创立人写入流程 (Creator Write Flow):创立人通过专属 Master Key 向指定的云端 Bin 发送
PUT请求,成功后数据即时在 JSONBin 全球 CDN 上更新;- 团队/访客免密直读流程 (Visitor Zero-Config Read Flow):代码中通过
DEFAULT_JSONBIN_MAPPING内置该项目或各页面的公开只读 Bin ID。任何团队成员、评审方、或在任意新电脑、新浏览器(包括无痕模式)打开时,无需输入任何 Key 或进行任何配置,系统在页面启动时自动秒级拉取最新规约并热重绘,实现真正的「一次配置、全员秒读、权限隔离、云端协同」!
🌟 核心战略价值 (Strategic Significance):
彻底解决传统 HTML 原型与 SPA 页面在静态托管平台(GitHub Pages / 纯前端静态服务器 / 预览链接)上**「有展示、无后端、无法在线编辑、无法团队跨端协同」的致命痛点。
同时提供了「一键跨模式数据无缝迁移引擎」**:当产品经理在某一模式(如本地 Node 磁盘开发)制作完成打点后,切换至另一模式(如云端 JSONBin 或 GitHub Pages)时,系统自动弹出迁移决策弹窗,支持一键将当前全量打点与多版本规约整体同步写入至新目标数据源,实现零断点无缝过渡!
| 方案 | 核心技术实现 | 读写延迟与快捷性 | 适用场景与权衡 (Trade-offs) |
|---|---|---|---|
| ⚡ 方案 0:Supabase Serverless 数据库打点 (PostgREST API) —— 【强烈推荐 / 大容量首选】 | 基于 Supabase RESTful PostgREST 架构: • 读: GET /rest/v1/{table}?id=eq.{docId} 带 apikey• 写: POST /rest/v1/{table} 带 Prefer: resolution=merge-duplicates | 极速 (100~200ms) 企业级直连,500MB 大容量与高并发,无单条记录容量限制 | 企业与高频首选:大型复杂原型、多页面多版本规约、海量流程图。突破 JSONBin 100KB 单条限制与请求上限,支持显式 Doc ID 映射与自动建档。 |
| 🔑 方案 1:Serverless 云端 KV 存储打点 (JSONBin.io) —— 【免建表即用】 | 基于 RESTful JSONBin API 架构: • 读: GET /v3/b/{binId}/latest?_t=timestamp• 写: PUT /v3/b/{binId} 带 X-Master-Key | 极速 (200~300ms) 秒级实时直读直写,零构建等待,抗浏览器缓存 | 轻量备用:无需建表、开箱即用。适合轻量级原型(免费版限制 100KB/记录及月度调用限制)。 |
| ☁️ 方案 2:GitHub Contents API 推送打点 (Git Commit 模式) | 基于 GitHub REST API: 调用 PUT /repos/{owner}/{repo}/contents/{filePath},将打点 Base64 编码后生成正式 Git Commit 提交入库 | 较慢 (1~3 秒) 需经历 GitHub API 网络调用、生成 Commit 节点与分支推进 | 代码库一体化归档:需要完整 Git Commit 审计记录与提交历史的场景。 |
| 💻 方案 3:本地 Node.js 磁盘直写打点 (Local Node 模式) | 本地启动 node server.js 微服务,前端通过 POST /api/save-prd 调用 fs 模块直接修改磁盘上的物理 prd-data-*.js 文件 | 极快 (10~50ms) 本机 localhost 内部直接落盘 | 纯脱机独立开发:无外网网络、企业保密内网、纯本地研发环境。 |
showModeSwitchConfirmModal):
PUT 或向 GitHub 提交 Commit),实现零断点无缝过渡;💾 下载本地备份 (.json),确保跨模式切换 100% 零数据丢失。为防止外部人员、评审方或访客恶意篡改线上 PRD 原型规约,系统实现了严格的读写权限物理隔离:
🔒 创立人身份鉴权 模态框:
setPRDMode('pick'))openEditorForPin(id))deletePin(id))handlePRDImportFile())createPRDVersion(ver))deletePRDVersion(ver))toggleDrawerManageMode())sessionStorage,当前会话即刻解锁全量编辑工作台;jsonbin 模式时,哪怕在 localhost 打开也绝对禁止调用本地 /api/save-prd 写入磁盘,100% 仅向云端 JSONBin 同步;bindPickListeners):
crosshair,底层元素高亮深琥珀色虚线框;✕ 📍 点击组件打标 (点击或ESC退出),彻底杜绝侧边栏遮挡底层页面组件;getElementSelector):
#id、语义化类名、结构层级路径(div:nth-of-type(n))与表单属性,保证动态重绘后打点依然 100% 准确对齐;requestAnimationFrame 在平滑滚动的 50 帧(约 800ms)全周期内实时调用 getBoundingClientRect() 动态重绘红色发光脉冲框(position: fixed),彻底解决页面平滑滚动导致的坐标漂移;click / Tab 切换),确保目标元素完全可见后再平滑聚焦。#prd-global-toast-container):
z-index: 10000099),不依赖任何第三方 UI 库或 window.UI;ensureVditorLoaded):
#prd-vditor-container 实施严格样式沙箱隔离,重置并锁定工具栏 SVG 图标为标准的 14px × 14px,彻底杜绝 Tailwind CSS 全局 svg { display:block; width:100% } 造成的工具栏图标撕裂与字母巨大化(H/B/T 字母变形)问题;- 列表 或 ### 标题 即刻呈现高保真排版;Tab 即可瞬间向右缩进生成下一层级(如 1 -> 1.1 -> 1.1.1 或 • -> ◦ -> ▪);Shift + Tab 或行首 Backspace 即可瞬间回退层级;| col |),表格直接渲染为可视 HTML 矩阵;Enter/Tab 顺畅换行换格;graph TB 状态机流转矢量图;.prd-editor-mini-dock):
✕,彻底去除重复按钮;✏️ 编辑中: 需求名称 · 草稿已暂存),点击 「恢复编辑」 即可无损还原全部内容。#0f172a)+ 朝内向右箭头 ›,点击完全收起抽屉;#8C4A28)+ 朝内紧凑标号条图标 ⇥,点击收窄为 56px 纯数字标号竖条;📌 需求打点 (n) 胶囊把手;全展开 400px ⇄ 半收起标号条 56px ⇄ 完全收起 0px):
[①][②][③][④]...,完全释放底层 95% 页面画布;
Inspect Popover),无缝查看需求;📌 需求打点 (n);text-overflow: ellipsis);订单 履约)、以及字符流顺序模糊检索,配有一键清空按钮 ✕。⚙️ 排序管理 开启,需创立人鉴权):
✓ 完成退出 按钮;🔝 置顶:直接将目标项瞬移至第 1 项,后续所有项目自动依次向下顺延 (1 -> 2 -> 3...);🔢 移至:输入目标序号,目标项精准插入,其余项目依次顺延;▲ / ▼:单步上移/下移;⠿:鼠标按住拖拽排序;versionRegistry 全局维护:
window.PRD_VERSION_REGISTRY = {
"activeVersion": "v1.0.0",
"versions": {
"v1.0.0": [ /* pins */ ],
"v1.1.0": [ /* pins */ ]
}
};
.js / .json 文件时弹出冲突模态框:
[版本]_imported。📑 查看完整PRD 按钮;↗️ 在新网页打开):
Ctrl+P / Cmd+P 一键导出交付级 PDF;📥 导出 Markdown、💾 导出 JS 数据、🖨️ 打印 / 导出 PDF。针对现代前端 SPA 单页应用与组件化工程,引擎内建了框架自适应技术:
pushState / popstate):
history.pushState 与 history.replaceState,并监听 popstate 与 Hash 变更;/mall/detail -> mall_detail),自动热重绘对应路由的打点列表与大头针。MutationObserver 监听 DOM 树的动态增删;v-if 或 React 的条件渲染组件(如弹窗、抽屉、异步表格)动态插入页面时,引擎在 50~100ms 内自动重新计算坐标并贴附大头针。data-v-xxxx 以及 React CSS-in-JS (Emotion / styled-components) 生成的动态随机哈希类名(如 .css-178fa9);nth-of-type)、组件 ID、表单名称、或业务自定义属性(data-prd="key"),保证打包重构后打点永不漂移。/预警信息/押品预警信息)进行 encodeURIComponent 清洗,杜绝浏览器原生 fetch 因中文字符导致的 non ISO-8859-1 code point 校验阻断,确保云端 KV 瞬时秒级同步。my-prototype/
├── admin.html # 原型页面 A (或 Vue / React 路由页面)
├── mall.html # 原型页面 B
├── merchant.html # 原型页面 C
├── h5.html # 原型页面 D
├── merchant-h5.html # 原型页面 E
├── server.js # 本地持久化后端服务 (Node.js 原生零依赖,提供 /api/save-prd)
├── start.sh # 一键启动脚本 (自动拉起静态服务与持久化接口)
└── assets/
├── vendor/ # 第三方独立组件库
│ └── vditor/
│ ├── index.min.js # Vditor 核心引擎 (本地离线支持)
│ └── index.css # Vditor 核心样式
└── js/
├── prd-pin-tool.js # 核心引擎 (跨框架通用: HTML / Vue / React)
├── prd-data-admin.js# admin.html 专属数据底包
├── prd-data-mall.js # mall.html 专属数据底包
├── prd-data-merchant.js
├── prd-data-h5.js
└── prd-data-merchant-h5.js