@siyuan0215/promax-to-prototype-v0

把已有前端项目在无后端 / 无数据库时，改造成可演示、可迭代的交互原型。通过 dev-server middleware 拦截 API、在 mock/ 目录维护假数据，让核心演示路径可走通，其余页面静默成功、不弹 Error toast。

本包 = Agent Skills（v0 · in-app mock）+ 安装 CLI。装好后，在 Cursor / Codex 等 Agent 里可直接触发相关能力。

与 @siyuan0215/promax-to-prototype（独立 .prototype/ HTML 原型）不同：本包走 业务仓库内 mock/ + dev:mock 路线。

适用场景

| 场景 | 用哪个 Skill | |------|----------------| | 客户演示、售前 Demo，后端还没就绪 | promax-to-prototype-v0 | | 第一次搭 dev:mock、mock middleware、fixtures/store/routes | promax-to-prototype-v0 | | 需要锁定演示路径（含登录、项目/租户门禁）再写 mock | promax-to-prototype-v0 | | mock 基础设施已有，某一页报错、白屏、数据空、[mock:miss] | promax-to-prototype-page-v0 | | 单页补数据、或把该页做成可增删改的可演示页 | promax-to-prototype-page-v0 |

不适合： 真 SSO、完整权限仿真、把 mock 打进生产构建、用一套新 UI 皮肤替代产品界面、纯静态 .prototype/ HTML 交付（请用 @siyuan0215/promax-to-prototype）。

包含的 Skills

promax-to-prototype-v0（主 Skill）

端到端搭建原型 mock 体系，典型产出：

• npm run dev:mock（或等价脚本）
• mock/ 目录（fixtures → store → routes → catch-all）
• docs/mock/DESIGN-NOTE.md（领域上下文 + P0 路径 + UX 约定）
• docs/mock/HOW-TO-ADD-MOCK.md（BA / 后续扩展手册）

工作流概要：Phase A 范围与契约确认 → Phase B 实现 mock → Phase C 扩展时一致性检查 → Phase D 交付前对抗审查。

硬约束包括：P0 必须含登录；Propose → Confirm → Lock → Code；默认不改 src/views；catch-all 不返回 4xx；session 内 CRUD 可变更、重启 mock server 恢复 seed。

promax-to-prototype-page-v0（子 Skill · 单页救援）

仅在 mock/ 已存在 时使用。只改 mock/** 与 docs/mock/**，不修业务源码。

• 路径 A（默认）：止错、补字段、让列表有数据
• 路径 B：用户要求可演示增删改时，升级为 session-mutable store

若 mock/ 不存在 → 交回 promax-to-prototype-v0。

安装

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

npx @siyuan0215/promax-to-prototype-v0 install

交互询问：

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

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

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

npx @siyuan0215/promax-to-prototype-v0 install --global --ide agents,cursor
npx @siyuan0215/promax-to-prototype-v0 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 |

安装元数据：

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

装好后怎么用

第一次：整项目原型化

用 promax-to-prototype-v0，把这个 Vite 前端做成客户演示原型，核心路径：登录 → 选项目 → 工作台 → Agent 对话。

Agent 会按 Skill 走预飞确认、锁定 P0、再搭 mock。你只需在 Phase A 批准 DESIGN-NOTE 后再让它写代码。

已有 mock：单页救援

这页 /settings/skills 白屏了，mock 已经开着，用 promax-to-prototype-page-v0 修一下。

或：

补一下这页的 mock 数据，要能新建后列表立刻看到。

CLI 命令详解

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

install — 安装 Skills

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

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

sync — 同 install

从当前 npm 包再覆盖一遍 skill 文件，行为与 install 相同。

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

update — 升级已安装的 Skills

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

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

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

list — 列出包内 Skills

npx @siyuan0215/promax-to-prototype-v0 list

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

doctor — 检查安装是否完整

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

npx @siyuan0215/promax-to-prototype-v0 doctor --global
npx @siyuan0215/promax-to-prototype-v0 doctor --project
npx @siyuan0215/promax-to-prototype-v0 doctor --global --no-strict

常用 flags

| Flag | 说明 | |------|------| | --global | 装到用户目录（~/.agents/skills 等） | | --project | 装到当前项目（.agents/skills 等） | | --ide <列表> | 逗号分隔：cursor,agents,qoder,qoder-cn,codex | | --yes | 非交互；默认 global + 扫描到的 IDE（或 agents,cursor） | | --no-strict | doctor 有 warning 时不退出非 0 |

与 npx skills（skills.sh）的关系

本仓库目录布局也兼容 skills.sh CLI：

npx skills add <owner>/promax-skills-v0 --list
npx skills add <owner>/promax-skills-v0 --skill promax-to-prototype-v0 -a cursor -y

| 方式 | 特点 | |------|------| | @siyuan0215/promax-to-prototype-v0 | 团队固定路径、doctor / update、多 IDE 一键复制 | | npx skills add | 生态 symlink 安装、skills.sh 索引与发现 |

常见问题

装完 Agent 没反应？

1. 确认目录下有 promax-to-prototype-v0/SKILL.md（doctor --global）
2. Cursor 重启或新开 Agent 会话
3. 对话里点名 skill 名或描述场景

doctor 报 version-mismatch？

npx @siyuan0215/promax-to-prototype-v0 update --global

和 @siyuan0215/promax-to-prototype 会冲突吗？

不会。本包 skill 目录带 -v0 后缀（promax-to-prototype-v0 / promax-to-prototype-page-v0），可与正式版并存；按场景选用对应包即可。

和项目里已有的 mock/ 冲突吗？

不会自动改业务仓库；install 只写入 Agent skill 目录。真正改业务代码的是你在 Agent 里执行任务时按 Skill 规范操作。

许可

MIT