From 84d4e35a42e0096b7980ae1a1087e8b2916b26a2 Mon Sep 17 00:00:00 2001 From: John Qiu Date: Mon, 20 Apr 2026 18:06:32 +0930 Subject: [PATCH] =?UTF-8?q?feat(req-prototype):=20=E6=96=B0=E5=A2=9E=20HTM?= =?UTF-8?q?L=20=E4=B8=8A=E4=BC=A0=E6=A8=A1=E5=BC=8F=EF=BC=8C=E7=89=88?= =?UTF-8?q?=E6=9C=AC=E5=8D=87=E8=87=B3=20v2.0.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 添加 /req prototype upload 子命令（推荐模式） - 含完整 curl 上传流程、HTML 设计规范及模板 - 更新错误处理与版本管理说明 - marketplace 更新（49 个插件） Co-Authored-By: Claude Sonnet 4.6 --- .claude-plugin/marketplace.json | 4 +- .../.claude-plugin/plugin.json | 4 +- .../req-prototype-plugin/skills/SKILL.md | 164 +++++++++++++++++- 3 files changed, 159 insertions(+), 13 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 456a72a..5dc38c8 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -358,8 +358,8 @@ { "name": "req-prototype-plugin", "source": "./skills-req/req-prototype-plugin", - "description": "Stitch 原型生成与迭代。基于 PRD 文档自动生成 UI 原型。", - "version": "1.0.0", + "description": "原型生成与关联。支持 HTML 上传（/req prototype upload，iframe 嵌入详情页）和 Stitch AI 生成两种模式。", + "version": "2.0.0", "category": "productivity", "keywords": [ "project-management", diff --git a/skills-req/req-prototype-plugin/.claude-plugin/plugin.json b/skills-req/req-prototype-plugin/.claude-plugin/plugin.json index 03a6ced..911d606 100644 --- a/skills-req/req-prototype-plugin/.claude-plugin/plugin.json +++ b/skills-req/req-prototype-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "req-prototype-plugin", - "description": "Stitch 原型生成与迭代。基于 PRD 文档自动生成 UI 原型。", - "version": "1.0.0", + "description": "原型生成与关联。支持 HTML 上传（/req prototype upload，iframe 嵌入详情页）和 Stitch AI 生成两种模式。", + "version": "2.0.0", "author": { "name": "qiudl" } diff --git a/skills-req/req-prototype-plugin/skills/SKILL.md b/skills-req/req-prototype-plugin/skills/SKILL.md index 68295d1..1265144 100644 --- a/skills-req/req-prototype-plugin/skills/SKILL.md +++ b/skills-req/req-prototype-plugin/skills/SKILL.md @@ -1,16 +1,19 @@ --- name: req-prototype -description: Stitch 原型生成与迭代。基于 PRD 文档自动生成 UI 原型，支持编辑和变体生成。当执行 /req prototype 或需要生成界面原型时使用。 -arguments: [REQ-ID] [--device desktop|mobile|tablet] [--model pro|flash] [--prompt "..."] +description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 PRD 自动生成 UI 原型截图；(2) AI 编写 HTML 原型并上传关联到需求详情页 iframe。当执行 /req prototype 或需要生成/上传界面原型时使用。 +arguments: [REQ-ID] [upload|edit|variant] [--device desktop|mobile|tablet] [--model pro|flash] [--note "..."] [--prompt "..."] --- -# Stitch 原型设计 Skill (req-prototype) +# 原型设计 Skill (req-prototype) ## 概述 -基于 PRD 文档自动生成 Stitch UI 原型，插入在 PRD 编写完成后、submit 评审前。 +支持两种原型工作流： -**核心流程**：读取 PRD → 提取 UI 描述 → 转英文 prompt → 调用 Stitch API → 截图回填 PRD +| 模式 | 命令 | 适用场景 | 输出 | +|------|------|----------|------| +| **HTML 上传** | `/req prototype upload` | 快速展示、评审用静态原型 | iframe 嵌入需求详情页 | +| **Stitch AI** | `/req prototype` | 精细 UI 设计、多屏交互 | 截图回填 PRD 文档 | ## 前置条件 @@ -18,13 +21,132 @@ arguments: [REQ-ID] [--device desktop|mobile|tablet] [--model pro|flash] [--prom | 检查项 | 方式 | 失败处理 | |--------|------|----------| -| 需求存在 | `ai-proj req get --id ` | 报错：需求不存在 | -| PRD 文档存在 | `ai-proj req tasks --id ` 找 linkRole=prd 任务 + 检查文档 | 报错：请先执行 req-prd 编写 PRD | -| PRD 包含 UI 描述 | 检查 PRD 中「功能需求」「交互设计」「界面原型」章节 | 警告：PRD 未包含 UI 相关描述，建议先补充 | +| 需求存在 | `mcp__ai-proj__get_requirement` | 报错：需求不存在 | +| 后端运行中（upload 模式）| `curl http://localhost:8080/api/v1/health` | 报错：后端未启动 | +| PRD 文档存在（Stitch 模式）| 找 linkRole=prd 任务 + 检查文档 | 报错：请先执行 req-prd | ## 子命令 -### 1. `/req prototype [REQ-ID]` — 生成原型 +### 0. `/req prototype upload [REQ-ID] [--note "版本说明"]` — 上传 HTML 原型（**推荐**） + +**适用场景**：快速为需求关联一个带样式的 HTML 原型，直接在需求详情页以 iframe 展示，供评审人预览交互流程。 + +**执行流程**： + +``` +1. 获取需求信息（mcp__ai-proj__get_requirement） +2. 读取 PRD 或需求描述，提炼 UI 关键信息 +3. AI 编写带完整样式的 HTML 原型文件（见设计规范） +4. 保存到 /tmp/proto__.html +5. 获取本地 JWT token（登录 API） +6. 上传到后端（multipart POST） +7. 确认上传成功，输出预览 URL +``` + +**Step 5-6 执行方式**： + +```bash +# 5. 获取 token（本地开发环境） +TOKEN=$(curl -s http://localhost:8080/api/v1/auth/login \ + -H 'Content-Type: application/json' \ + -d '{"username":"qiudl","password":"Admin@2026~"}' \ + | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["access_token"])') + +# 6. 上传 HTML 原型并关联到需求 +curl -s -X POST "http://localhost:8080/api/v1/requirements//prototype" \ + -H "Authorization: Bearer $TOKEN" \ + -F "file=@/tmp/proto__.html;type=text/html" \ + -F "version_note=<--note 的值或空>" +``` + +**成功响应**： + +```json +{ + "success": true, + "data": { + "url": "/api/v1/uploads/prototypes/proto_xxx.html", + "version_note": "...", + "uploaded_at": "..." + } +} +``` + +**效果**：需求详情页（`/requirements/` 或 `/platform/requirements/`）自动出现「原型预览」卡片，iframe 加载上传的 HTML。 + +**参数**： + +| 参数 | 默认值 | 说明 | +|------|--------|------| +| `--note` | 空 | 版本说明，如"初稿 v1"、"评审修改版" | + +--- + +#### HTML 原型设计规范 + +AI 生成的 HTML 原型必须满足以下要求： + +**结构要求**： +- 完整独立的 HTML 文件（含 `` + `` + ``） +- 所有样式内联在 ` + + +
+
+ +
+
+
+ 🎨 原型预览 · [REQ-ID] — [需求标题] + v1.0 · [日期] · 仅供评审参考 +
+ + +``` + +--- + +### 1. `/req prototype [REQ-ID]` — Stitch AI 生成原型 **流程**： @@ -154,6 +276,18 @@ generated_at: "" ## 异常处理 +### Upload 模式 + +| 异常 | 处理 | +|------|------| +| 后端 500 / `column prototype_urls does not exist` | 需执行数据库迁移：`psql -U -d -c "ALTER TABLE requirements ADD COLUMN IF NOT EXISTS prototype_urls JSONB DEFAULT '[]';"` | +| token 获取失败（401）| 检查用户名密码，或改用生产环境 token | +| 需求 ID 不存在（404）| 确认使用数据库自增 ID，而非 display_id（REQ-xxx） | +| HTML 文件超过 5MB | 精简样式或拆分多版本上传 | +| iframe 不显示 | 检查 `prototype_urls` 字段是否非空：`mcp__ai-proj__get_requirement` 确认 | + +### Stitch 模式 + | 异常 | 处理 | |------|------| | 需求无 PRD 文档 | 报错：`请先使用 req-prd 技能编写 PRD 文档` | @@ -162,3 +296,15 @@ generated_at: "" | Stitch API 返回错误 | 展示错误信息，建议调整 prompt 或更换模型 | | PRD 无「4.2 界面原型」章节 | 在「## 4. 交互设计」末尾自动追加该章节 | | 已有原型元数据 | 询问：`已存在原型，是否覆盖？` | + +## 版本管理 + +每次 `/req prototype upload` 都会追加一个新版本（自增 `version` 字段），需求详情页支持版本切换下拉框。多个版本并存时，最新版本默认展示。 + +可多次上传来迭代原型： + +``` +v1 → 初稿（评审前） +v2 → 评审修改版 +v3 → 开发对齐版 +```