@@ -1,16 +1,19 @@
---
---
name: req-prototype
name: req-prototype
description: Stitch 原型生成与迭代。 基于 PRD 文档 自动生成 UI 原型，支持编辑和变体生成 。当执行 /req prototype 或需要生成界面原型时使用。
description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 PRD 自动生成 UI 原型截图；(2) AI 编写 HTML 原型并上传关联到需求详情页 iframe 。当执行 /req prototype 或需要生成/上传 界面原型时使用。
arguments: [REQ-ID] [--device desktop|mobile|tablet] [--model pro|flash] [--prompt "..."]
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 <id> ` | 报错：需求不存在 |
| 需求存在 | `mcp__ ai-proj__get_requirement ` | 报错：需求不存在 |
| PRD 文档存在 | `ai-proj req tasks --id <id>` 找 linkRole=prd 任务 + 检查文档 | 报错：请先执行 req-prd 编写 PRD |
| 后端运行中（ `curl http://localhost:8080/api/v1/health` | 报错：后端未启动 |
| PRD 包含 UI 描述 | 检查 PRD 中「功能需求」「交互设计」「界面原型」章节 | 警告： |
| PRD 文档存在（ |
## 子命令
## 子命令
### 1 . `/req prototype [REQ-ID]` — 生成原型
### 0 . `/req prototype upload [REQ-ID] [--note "版本说明"]` — 上传 HTML 原型（**推荐**）
**适用场景 ** ：快速为需求关联一个带样式的 HTML 原型，直接在需求详情页以 iframe 展示，供评审人预览交互流程。
**执行流程 ** ：
```
（ ）
2. 读取 PRD 或需求描述，提炼 UI 关键信息
3. AI 编写带完整样式的 HTML 原型文件（见设计规范）
4. 保存到 /tmp/proto_<req_id>_<timestamp>.html
5. 获取本地 JWT token（ ）
6. 上传到后端（ ）
7. 确认上传成功，输出预览 URL
```
**Step 5-6 执行方式 ** ：
``` bash
# 5. 获取 token（ ）
TOKEN = $( curl -s http://localhost:8080/api/v1/auth/login \
'Content-Type: application/json' \
'{"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/<REQ_DB_ID>/prototype" \
" Authorization: Bearer $TOKEN " \
"file=@/tmp/proto_<req_id>_<timestamp>.html;type=text/html" \
"version_note=<--note 的值或空>"
```
**成功响应 ** ：
``` json
{
"success" : true ,
"data" : {
"url" : "/api/v1/uploads/prototypes/proto_xxx.html" ,
"version_note" : "..." ,
"uploaded_at" : "..."
}
}
```
**效果 ** ：需求详情页（`/requirements/<id>` 或 `/platform/requirements/<id>` ） ，
**参数 ** ：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--note` | 空 | 版本说明，如"初稿 v1"、"评审修改版" |
---
#### HTML 原型设计规范
AI 生成的 HTML 原型必须满足以下要求：
**结构要求 ** ：
- 完整独立的 HTML 文件（含 `<!DOCTYPE html>` + `<head>` + `<body>` ）
- 所有样式内联在 `<style>` 标签中，不依赖外部 CDN
- 不使用 JavaScript 框架（纯 HTML+CSS， ）
- 适合在 600px 高度的 iframe 中展示
**视觉要求 ** ：
- 与需求功能高度对应，体现核心交互流程
- 包含真实感数据（非"xxx"占位符）
- 顶部导航栏 / 侧边栏与项目风格一致（深色 header，
- 底部加注释标注条（固定定位，说明版本和需求号）
**内容要求 ** ：
- 覆盖需求描述中的核心功能点
- 展示关键数据状态（列表、表单、卡片等）
- 按钮/操作有视觉反馈样式（
**模板参考 ** （顶部 topbar + 侧边栏 + 主内容区）：
``` html
<!DOCTYPE html>
< html lang = "zh-CN" >
< head >
< meta charset = "UTF-8" / >
< title > [需求标题] - 原型< / title >
< style >
/* reset + layout */
* , * :: before , * :: after { box-sizing : border-box ; margin : 0 ; padding : 0 ; }
body { font-family : - apple-system , BlinkMacSystemFont , 'Segoe UI' , sans-serif ;
background : #f0f2f5 ; color : #1a1a2e ; min-height : 100 vh ; }
. topbar { background : #1e3a5f ; color : #fff ; padding : 0 24 px ; height : 52 px ;
display : flex ; align-items : center ; justify-content : space-between ; }
. layout { display : flex ; height : calc ( 100 vh - 52 px ) ; }
. sidebar { width : 220 px ; background : #fff ; border-right : 1 px solid #e5e7eb ;
padding : 16 px 0 ; overflow-y : auto ; }
. main { flex : 1 ; overflow-y : auto ; padding : 24 px ; padding-bottom : 48 px ; }
/* 底部原型标注条 */
. annotation { position : fixed ; bottom : 0 ; left : 0 ; right : 0 ;
background : rgba ( 30 , 58 , 95 , .92 ) ; color : #fff ;
padding : 6 px 24 px ; font-size : 12 px ;
display : flex ; justify-content : space-between ; }
. annotation strong { color : #93c5fd ; }
< / style >
< / head >
< body >
< div class = "topbar" > <!-- 导航 --> < / div >
< div class = "layout" >
< aside class = "sidebar" > <!-- 侧边栏 --> < / aside >
< main class = "main" > <!-- 主内容 --> < / main >
< / div >
< div class = "annotation" >
< span > 🎨 < strong > 原型预览< / strong > · [REQ-ID] — [需求标题]< / span >
< span style = "color:#93c5fd;" > v1.0 · [日期] · 仅供评审参考< / span >
< / div >
< / body >
< / html >
```
---
### 1. `/req prototype [REQ-ID]` — Stitch AI 生成原型
**流程 ** ： **流程 ** ：
@@ -154,6 +276,18 @@ generated_at: "<timestamp>"
## 异常处理
## 异常处理
### Upload 模式
| 异常 | 处理 |
|------|------|
| 后端 500 / `column prototype_urls does not exist` | 需执行数据库迁移：`psql -U <owner> -d <db> -c "ALTER TABLE requirements ADD COLUMN IF NOT EXISTS prototype_urls JSONB DEFAULT '[]';"` |
| token 获取失败（ ）
| 需求 ID 不存在（ ） ， （ ）
| HTML 文件超过 5MB | 精简样式或拆分多版本上传 |
| iframe 不显示 | 检查 `prototype_urls` 字段是否非空：`mcp__ai-proj__get_requirement` 确认 |
### Stitch 模式
| 异常 | 处理 |
| 异常 | 处理 |
|------|------|
|------|------|
| 需求无 PRD 文档 | 报错：`请先使用 req-prd 技能编写 PRD 文档` |
| 需求无 PRD 文档 | 报错：`请先使用 req-prd 技能编写 PRD 文档` |
@@ -162,3 +296,15 @@ generated_at: "<timestamp>"
| Stitch API 返回错误 | 展示错误信息，建议调整 prompt 或更换模型 |
| Stitch API 返回错误 | 展示错误信息，建议调整 prompt 或更换模型 |
| PRD 无「4.2 界面原型」章节 | 在「## 4. 交互设计」末尾自动追加该章节 |
| PRD 无「4.2 界面原型」章节 | 在「## 4. 交互设计」末尾自动追加该章节 |
| 已有原型元数据 | 询问：`已存在原型，是否覆盖？` |
| 已有原型元数据 | 询问：`已存在原型，是否覆盖？` |
## 版本管理
每次 `/req prototype upload` 都会追加一个新版本（自增 `version` 字段），需求详情页支持版本切换下拉框。多个版本并存时，最新版本默认展示。
可多次上传来迭代原型：
```
v1 → 初稿（评审前）
v2 → 评审修改版
v3 → 开发对齐版
```