@siyuan0215/promax-to-prototype

把已有前端做成可提交、可快速打开的 .prototype/ 独立原型（无框架 HTML/CSS/JS + Style System）。

本包 = Agent Skills（教 Agent 怎么做）+ CLI（把 Skills 装到本机 / 同步 partials）。

缩写： PTP 首交付 · PTPP 新增页 · PTPP-R 修已有页

Skills 详解

安装 CLI 后，在 Cursor / Agents 等对话里用自然语言触发。三个 skill 不要混用：

| 缩写 | Skill 目录名 | 一句话 | |------|--------------|--------| | PTP | promax-to-prototype | 第一次从业务前端抽出 .prototype/ | | PTPP | promax-to-prototype-page | 已有 .prototype/ 后，新建业务页（三 Demo 选型） | | PTPP-R | promax-to-prototype-page-rescue | 修好已有 pages/*.html（不走三 Demo） |

自动交接： PTP 听到「创建页面」→ handoff PTPP；听到「白屏 / 补数据」→ handoff PTPP-R。

PTP — 首交付

何时用

• 仓库还没有 .prototype/
• 要做整仓 / Core Path 演示原型（登录 → 门禁 → 主业务页）
• 后端不可用，需要静态可打开的页面

做什么

1. Clarify：锁定 Core Path、Realism Budget（Full 或 Lite）
2. Extract：Structure Scan + Style System + CONFLICTS
3. Generate：assets/ + pages/ + 可选 reference 截图
4. Review：验收 + D1（Full / Lite）→ Ready

对话示例

用 PTP / promax-to-prototype 做独立原型。
Core Path：登录 → 选项目 → 工作台 → Agent 对话。
Realism：列表页用 Fixture Module，不要 fetch JSON。

整仓原型化，先按 Lite clarify：路径我已经定好了，确认一下表就行。

产出（业务仓库内）

.prototype/
  docs/          # DELIVERY、Style System、clarification…
  assets/        # tokens.css、vendor、fixtures/*.js、partials/…
  pages/         # 01-login.html、02-…、index.html
  README.md

PTPP — 创建页面

何时用

• .prototype/ 和 Style System 已经存在（PTP 做过）
• 要加新业务页、新菜单页，并希望先看 3 个 Demo 再定稿

不要用 PTPP： 修白屏 / 补一条数据 → 用 PTPP-R。

做什么

1. Grill：写清 Page Brief（目的、入口、数据源、Markup strategy…）
2. 生成 demos/<id>/01|02|03.html
3. 你选一个 → 落到 pages/NN-<slug>.html，更新 path.md

对话示例

用 PTPP 做一个「技能市场」新页面。
要先给三个 Demo（列表 / 卡片 / 紧凑密度）我选。
数据用 fixture-js，markup 以 transplant 为主。

PTPP：从工作台进「审批中心」，加到 Extended pages，不进 Core Path 演示脚本。

PTPP-R — 修已有页

何时用

• 已有 pages/NN-*.html 坏了：白屏、空列表、导航错、间距塌、壳层没撑满、DOM 和源不符

不要用 PTPP-R： 「重新设计一个新页面 / 要三个方案」→ PTPP。

分类（Agent 会按症状改）

nav · css · layout · spacing · markup · data · interaction · trace · assets · conflict

对话示例

03-workbench.html 列表是空的，用 PTPP-R 修一下，数据写进 fixtures/*.js。

侧栏和 content 高度对不齐，下面一大块空白，按 classic-shell 用 PTPP-R 修 layout。

header 改完了 partial，页面里还是旧的，帮我核对 include 标记。

CLI 安装 Skills

需要 Node.js ≥ 18。建议在业务前端仓库根目录执行：

npx @siyuan0215/promax-to-prototype install

交互询问：

1. 范围 — Global（本机用户目录）或 Project（当前仓库）
2. IDE — 可多选；若该 scope 下已装过 PTP，会默认勾选扫描到的 IDE

装完后新开一轮 Agent 对话再试 skill。

显式指定（跳过交互里的范围/IDE 选择）

npx @siyuan0215/promax-to-prototype install --global --ide agents,cursor
npx @siyuan0215/promax-to-prototype install --project --ide cursor

装到哪里

| --ide | --project | --global | |---------|-------------|------------| | agents | .agents/skills | ~/.agents/skills | | cursor | .cursor/skills + .agents/skills | ~/.cursor/skills + ~/.agents/skills | | qoder | .qoder/skills | ~/.qoder/skills | | qoder-cn | .qoder-cn/skills | ~/.qoder-cn/skills | | codex | .agents/skills | ~/.codex/skills |

安装元数据：

• 全局：~/.siyuan/promax-to-prototype/.install.json
• 项目：./promax-to-prototype/.install.json

CLI 命令详解

统一前缀：npx @siyuan0215/promax-to-prototype <command>。每个子命令可用 --help。

install — 安装 Skills

把包内 3 个 skill 复制到所选 Agent 目录。

npx @siyuan0215/promax-to-prototype install
npx @siyuan0215/promax-to-prototype install --global --ide cursor
npx @siyuan0215/promax-to-prototype install --project --ide agents,cursor --yes

--yes：非交互；未指定时 scope 默认 global，IDE 默认扫描结果或 agents,cursor。

sync — 同 install

从当前 npm 包再覆盖一遍 skill 文件，行为与 install 相同（适合本地联调包内容时强制刷新）。

npx @siyuan0215/promax-to-prototype sync --global --ide cursor

update — 升级已安装的 Skills

拉取新版包里的 skill 文档/规则，不修改业务仓库里的 .prototype/ 页面。

npx @siyuan0215/promax-to-prototype update
npx @siyuan0215/promax-to-prototype update --global
npx @siyuan0215/promax-to-prototype update --project --ide cursor

选 IDE 时会扫描已安装目录并默认勾选；换 IDE 可显式传 --ide。

list — 列出包内 Skills

看当前 npx 包里带了哪些 skill（与是否已 install 无关）。

npx @siyuan0215/promax-to-prototype list

期望看到：promax-to-prototype、promax-to-prototype-page、promax-to-prototype-page-rescue。

doctor — 检查安装是否完整

对照 install 元数据与磁盘上的 SKILL.md，并提示版本是否落后。

npx @siyuan0215/promax-to-prototype doctor --global
npx @siyuan0215/promax-to-prototype doctor --project
npx @siyuan0215/promax-to-prototype doctor --global --no-strict   # warning 不令退出码非 0

缺文件或未 install 会报错；版本落后会提示再跑 update。

sync-partials — 同步 HTML 片段到页面

解决什么问题

经典壳层的 header / sidebar、多个页面共用的列表块等，会放在：

.prototype/assets/partials/shell-header.html
.prototype/assets/partials/….html

页面里用注释标记嵌入一份副本（保证 file:// 也能打开，不会在运行时 fetch HTML）：

<!-- include:partials/shell-header.html -->
<header class="app-shell__header">…当前副本…</header>
<!-- /include:partials/shell-header.html -->

改 partial 源文件后，各页副本会过期。sync-partials 负责把标记之间的内容替换成 partial 最新内容。

何时用

| 场景 | 要不要跑 | |------|----------| | Agent / 你改了 assets/partials/*.html | 要 — 在业务仓库根目录跑一次 | | 只改了某个 pages/03-*.html 里独有区块（无 include 标记） | 不用 | | 刚 install / update 了 skills | 不用（那是装 skill，不是改原型页） | | CI 里改完 partial 要提交前保证一致 | 建议跑 |

在何地执行

必须在包含 .prototype/ 的业务前端仓库里执行（cwd = 仓库根），不是 skill 包仓库本身。

cd /path/to/your-frontend-app

# 默认读取 ./prototype
npx @siyuan0215/promax-to-prototype sync-partials

# .prototype 不在根目录时
npx @siyuan0215/promax-to-prototype sync-partials --dir apps/web/.prototype

示例流程

# 1. 编辑共享顶栏
$EDITOR .prototype/assets/partials/shell-header.html

# 2. 同步到所有带 include 标记的页面
npx @siyuan0215/promax-to-prototype sync-partials

# 3. 打开任意页确认（可用浏览器直接打开 pages/*.html）
open .prototype/pages/03-workbench.html

终端会报告扫描了多少 page、替换了多少 include 块。若标记指向的 partial 文件不存在，命令会失败并提示路径。

和 Skills 的关系

• PTP / PTPP 生成共享块时应写入 partials/ + 页面 include 标记。
• PTPP-R 修壳层时改 partial 后，应再跑 sync-partials（或让 Agent 跑）。
• 详细约定见 skill 内 html-partials.md（install 后在本地 skills 目录可读）。

Flags 速查

| Flag | 用于 | 说明 | |------|------|------| | --global | install / sync / update / doctor | 用户级目录 | | --project | 同上 | 当前仓库 | | --ide <列表> | install / sync / update | cursor,agents,qoder,qoder-cn,codex | | --yes | install / sync / update | 非交互默认 | | --dir <path> | sync-partials | .prototype 路径，默认 .prototype | | --no-strict | doctor | warning 不导致非 0 退出 |

npx @siyuan0215/promax-to-prototype install --help
npx @siyuan0215/promax-to-prototype sync-partials --help

推荐日常流程

# 第一次（任意机器）
npx @siyuan0215/promax-to-prototype install --global --ide cursor

# 包升级后刷新 skill 文档
npx @siyuan0215/promax-to-prototype update --global

# 在业务仓库：Agent 用 PTP/PTPP 生成 .prototype 后…
# 改了 partial → 同步页面
cd your-app && npx @siyuan0215/promax-to-prototype sync-partials

对话侧：

1. 「用 PTP 做首交付…」
2. 「用 PTPP 加新页，三个 Demo…」
3. 「用 PTPP-R 修 03-workbench…」

与 skills.sh

npx skills add <owner>/promax-skills --list

本 CLI 负责多 IDE 复制、doctor / update / sync-partials；npx skills 面向 skills.sh 生态。可并存。

许可

MIT