feat(req-prototype): 原型展示必须用 iframe，禁止图片方式 (REQ-20260420-0031)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
feat: P1-8 客户场景章节 + P1-9 pm-ask skill (REQ-20260416-0017)
2026-04-21 01:07:10 +09:30 · 2026-04-16 23:04:54 +09:30
5 changed files with 346 additions and 9 deletions
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -23,6 +23,18 @@
      ],
      "strict": false
    },
+    {
+      "name": "pm-ask-plugin",
+      "source": "./skills-core/pm-ask-plugin",
+      "description": "基于真实数据的项目问答 /ask。必须引用 MCP/git 真实数据，禁止编造",
+      "version": "1.0.0",
+      "category": "utility",
+      "keywords": [
+        "utility",
+        "tools"
+      ],
+      "strict": false
+    },
    {
      "name": "publish-plugin",
      "source": "./skills-core/publish-plugin",
--- a/skills-core/pm-ask-plugin/.claude-plugin/plugin.json
+++ b/skills-core/pm-ask-plugin/.claude-plugin/plugin.json
@@ -0,0 +1,8 @@
+{
+  "name": "pm-ask-plugin",
+  "description": "基于真实数据的项目问答 /ask。必须引用 MCP/git 真实数据，禁止编造",
+  "version": "1.0.0",
+  "author": {
+    "name": "qiudl"
+  }
+}
--- a/skills-core/pm-ask-plugin/skills/SKILL.md
+++ b/skills-core/pm-ask-plugin/skills/SKILL.md
@@ -0,0 +1,126 @@
+---
+name: pm-ask
+description: 基于 ai-proj MCP + git log 真实数据的项目问答。禁止编造。当用户说"/ask"、"问一下"、"统计一下"、"最近多少"、"谁做了多少"、"本月进度"等项目相关问题时自动激活。
+---
+
+# pm-ask Skill — 基于真实数据的项目问答
+
+借鉴自 devflow-claude `/pm:ask`。源自 REQ-20260416-0017 P1-9。
+
+## 核心原则（铁律）
+
+> **必须基于真实数据，禁止编造。**
+
+- 所有数字必须来自 MCP API / git log / 文件系统的**真实查询**
+- 必须引用具体 **REQ-XXX / commit-sha / 文件路径**
+- 数据不足时**明确说明缺失**，不得"大概"、"估计"
+- **区分事实和推测**：推测必须用 `⚠️ 推测：` 前缀
+
+## 适用场景
+
+| 用户问题示例 | 数据源 | 工具 |
+|-------------|--------|------|
+| "qiudl 最近一个月提交了多少代码？" | git log | `git log --author=qiudl --since='30 days ago'` |
+| "本月完成了哪些需求？" | ai-proj MCP | `list_requirements --status=completed` |
+| "当前进行中的需求有多少？分别是？" | MCP | `list_requirements --status=in_progress` |
+| "REQ-xxx 拆了哪些任务？完成多少？" | MCP | `get_requirement_tasks` |
+| "backend/services/user.go 最近谁在改？" | git log | `git log --follow -- file` |
+| "和上月对比，产出是多了还是少了？" | git log + MCP | 组合查询 |
+| "生成一封客户更新邮件" | MCP + git | 聚合后结构化输出 |
+
+## 工作流
+
+### 1. 意图分析（确定数据源）
+
+关键词 → 数据源映射：
+
+| 关键词 | 数据源 |
+|--------|--------|
+| 需求 / REQ / 需求状态 | ai-proj MCP `list_requirements` / `find_requirement` |
+| 任务 / todo / 待办 | MCP `list_tasks` / `find_task` |
+| 提交 / commit / 代码量 / 贡献 | `git log` |
+| 文件修改 / 变更 | `git log --follow` / `git blame` |
+| 进度 / 完成率 | MCP `get_project_stats` / `get_requirement_statistics` |
+| 周报 / 月报 | 组合：MCP + git log + 时间范围过滤 |
+| 风险 / 停滞 / 延期 | MCP + 时间戳分析 |
+
+### 2. 执行查询
+
+**查询前必须声明**：
+```
+📊 正在查询数据源：
+- ai-proj MCP: list_requirements (status=in_progress)
+- git log: --author=qiudl --since='2026-04-01'
+```
+
+### 3. 生成答案（强约束）
+
+**结构**：
+```
+## 直接答案
+<一句话结论，附数字>
+
+## 数据来源
+- <查询语句 1> → <结果摘要>
+- <查询语句 2> → <结果摘要>
+
+## 细节
+<表格 / 列表，每条必有 REQ-XXX 或 commit-sha>
+
+## ⚠️ 数据缺失（如有）
+<说明哪些数据无法获取>
+```
+
+### 4. 禁止事项
+
+**不允许的答案：**
+- "大概 XX 个左右"（必须精确数字或说明"无法精确统计"）
+- "主要在做 XX"（必须列具体 REQ）
+- "应该是 XX"（推测必须 `⚠️ 推测：` 标记）
+- "最近进度不错"（必须数据支持）
+
+**违反时自我纠正**：如果生成答案时发现缺少真实数据引用，重新查询，不要猜测。
+
+## 输出适配
+
+根据问题类型自动切换输出格式：
+
+| 问题类型 | 输出格式 |
+|---------|---------|
+| 数量统计 | 数字 + 列表 |
+| 对比分析 | 表格 |
+| 进度追踪 | 进度条 / 完成率 |
+| 历史回顾 | 时间线 |
+| 生成文档（邮件/报告） | 完整结构化文本 |
+
+## 与其他 skill 的关系
+
+| 相关 skill | 分工 |
+|-----------|------|
+| `ai-proj` | 执行 MCP 调用（本 skill 的底层） |
+| `req-workflow` | 需求生命周期管理（本 skill 只读查询） |
+| `dev-review` | 代码评审（本 skill 提供评审背景数据） |
+
+## 受众适配（借鉴自 devflow report-generator）
+
+生成报告时按受众调整：
+
+| 受众 | 侧重 | 禁用 |
+|------|------|------|
+| 高层 | 交付物、里程碑、风险 | 技术细节 |
+| 客户 | 功能价值、上线时间 | 内部术语 |
+| 内部团队 | 技术细节、Blocker | - |
+| 新人 | 背景上下文、术语表 | 假设已知 |
+
+## Memory 使用规则
+
+本 skill **仅基于当前数据查询**生成答案。memory 可用于：
+- 记住用户偏好的输出格式（如"喜欢表格不喜欢列表"）
+- 记住常用的过滤条件（如"默认看 qiudl 的提交"）
+
+**禁止**：用 memory 里的历史数据"缓存"事实类答案（这会导致过时数据）。每次问都要重新查。
+
+## 参考
+
+- devflow-claude: `plugins/pm/commands/ask.md`
+- REQ-20260416-0017 P1-9
--- a/skills-req/req-prd-plugin/skills/SKILL.md
+++ b/skills-req/req-prd-plugin/skills/SKILL.md
@@ -18,6 +18,20 @@ description: 产品设计与需求管理。用于 PRD 文档编写、需求分
 - `req-compare` — 对比式 PRD 编写（系统平移/竞品借鉴时激活）
 - `req-prototype` — UI 原型生成

+## 客户原话原则（REQ-20260416-0017 P1-8）
+
+**编写 PRD 时必须包含「客户原始诉求」章节（模板 1.4），保留客户/业务方原话，不做 AI 加工。**
+
+**为什么**：
+- 产品经理转述会失真（借鉴自 devflow-claude 的"客户场景"设计）
+- 后续争议追溯时有据可查
+- 团队成员看到原话能建立同理心
+
+**填写规范**：
+- 原话用 Markdown `> 引用块` 包裹，区分于 AI 加工内容
+- 标注提出人、时间、出处（会议/邮件/聊天）
+- 特殊约束（时间/合规/预算）必须保留
+
 ---

 ## 对比式 PRD 编写
@@ -50,6 +64,20 @@ description: 产品设计与需求管理。用于 PRD 文档编写、需求分
 |------|--------|--------|----------|
 | ... | ... | ... | ... |

+### 1.4 客户原始诉求 ⭐ 强制保留
+
+> **重要**：记录客户/业务方提出需求时的**原始描述**，**不做 AI 加工、不总结、不转述**。
+> 保留原话是为了后续溯源"我们当初为什么做这个"有据可查，避免产品经理转述失真。
+
+- **场景1**（提出人：xxx / 时间：yyyy-mm-dd）：
+  > "原始描述引用..."
+- **场景2**：
+  > "原始描述引用..."
+
+**补充信息**（可选）：
+- 会议/邮件/聊天记录链接
+- 客户特殊约束（如"必须在 Q2 前上线"）
+
 ## 2. 用户分析
 ### 2.1 目标用户
 [用户画像描述]
--- 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 <id>` | 报错：需求不存在 |
-| PRD 文档存在 | `ai-proj req tasks --id <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_<req_id>_<timestamp>.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/<REQ_DB_ID>/prototype" \
+  -H "Authorization: Bearer $TOKEN" \
+  -F "file=@/tmp/proto_<req_id>_<timestamp>.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/<id>` 或 `/platform/requirements/<id>`）自动出现「原型预览」卡片，iframe 加载上传的 HTML。
+
+**参数**：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `--note` | 空 | 版本说明，如"初稿 v1"、"评审修改版" |
+
+---
+
+#### HTML 原型设计规范
+
+AI 生成的 HTML 原型必须满足以下要求：
+
+**结构要求**：
+- 完整独立的 HTML 文件（含 `<!DOCTYPE html>` + `<head>` + `<body>`）
+- 所有样式内联在 `<style>` 标签中，不依赖外部 CDN
+- 不使用 JavaScript 框架（纯 HTML+CSS，可用少量原生 JS）
+- 适合在 600px 高度的 iframe 中展示
+
+**视觉要求**：
+- 与需求功能高度对应，体现核心交互流程
+- 包含真实感数据（非"xxx"占位符）
+- 顶部导航栏 / 侧边栏与项目风格一致（深色 header，现代 SaaS 风格）
+- 底部加注释标注条（固定定位，说明版本和需求号）
+
+**内容要求**：
+- 覆盖需求描述中的核心功能点
+- 展示关键数据状态（列表、表单、卡片等）
+- 按钮/操作有视觉反馈样式（hover 色等）
+
+**模板参考**（顶部 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: 100vh; }
+    .topbar { background: #1e3a5f; color: #fff; padding: 0 24px; height: 52px;
+               display: flex; align-items: center; justify-content: space-between; }
+    .layout { display: flex; height: calc(100vh - 52px); }
+    .sidebar { width: 220px; background: #fff; border-right: 1px solid #e5e7eb;
+               padding: 16px 0; overflow-y: auto; }
+    .main { flex: 1; overflow-y: auto; padding: 24px; padding-bottom: 48px; }
+    /* 底部原型标注条 */
+    .annotation { position: fixed; bottom: 0; left: 0; right: 0;
+                  background: rgba(30,58,95,.92); color: #fff;
+                  padding: 6px 24px; font-size: 12px;
+                  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,35 @@ 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 获取失败（401）| 检查用户名密码，或改用生产环境 token |
+| 需求 ID 不存在（404）| 确认使用数据库自增 ID，而非 display_id（REQ-xxx） |
+| HTML 文件超过 5MB | 精简样式或拆分多版本上传 |
+| iframe 不显示 | 检查 `prototype_urls` 字段是否非空：`mcp__ai-proj__get_requirement` 确认 |
+
+### 原型展示规则
+
+**原型必须用 iframe 展示**（不得用截图、图片嵌入或内联 HTML 方式替代）。
+
+- PRD 文档的「4.2 界面原型」章节：使用 `<iframe>` 标签嵌入原型 URL，而非 `![](...)` 图片
+- 需求详情页原型预览卡片：后端渲染 iframe，前端不得将 `prototype_urls` 内容渲染为 `<img>`
+- 典型正确写法（PRD 文档内）：
+
+```html
+<iframe src="/api/v1/uploads/prototypes/proto_xxx.html"
+        width="100%" height="600" frameborder="0"
+        style="border-radius:8px;border:1px solid #e5e7eb;">
+</iframe>
+```
+
+> 背景：REQ-20260420-0031 反馈原型图用图片方式展示，无法交互预览，改为 iframe 后可正常使用。
+
+### Stitch 模式
+
 | 异常 | 处理 |
 |------|------|
 | 需求无 PRD 文档 | 报错：`请先使用 req-prd 技能编写 PRD 文档` |
@@ -162,3 +313,15 @@ generated_at: "<timestamp>"
 | Stitch API 返回错误 | 展示错误信息，建议调整 prompt 或更换模型 |
 | PRD 无「4.2 界面原型」章节 | 在「## 4. 交互设计」末尾自动追加该章节 |
 | 已有原型元数据 | 询问：`已存在原型，是否覆盖？` |
+
+## 版本管理
+
+每次 `/req prototype upload` 都会追加一个新版本（自增 `version` 字段），需求详情页支持版本切换下拉框。多个版本并存时，最新版本默认展示。
+
+可多次上传来迭代原型：
+
+```
+v1 → 初稿（评审前）
+v2 → 评审修改版
+v3 → 开发对齐版
+```