From dec25562a40985c50fd1884bccbd668c71b4d8ad Mon Sep 17 00:00:00 2001 From: John Qiu Date: Fri, 21 Aug 2026 23:59:14 +0930 Subject: [PATCH] feat(req-prd): persist docs and prototypes remotely --- .claude-plugin/marketplace.json | 8 ++-- .../req-prd-plugin/.claude-plugin/plugin.json | 4 +- skills-req/req-prd-plugin/skills/SKILL.md | 42 ++++++++++++++++-- .../design-interview-and-defect-loop.md | 21 ++++++--- .../.claude-plugin/plugin.json | 4 +- .../req-prototype-plugin/skills/SKILL.md | 44 ++++++++++++------- 6 files changed, 92 insertions(+), 31 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index aece8c7..b9f9afb 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -482,8 +482,8 @@ { "name": "req-prd-plugin", "source": "./skills-req/req-prd-plugin", - "description": "产品需求设计技能。覆盖问答访谈、PRD、缺陷收敛及 HTML 原型验证闭环。纯产品视角，不含技术实现。", - "version": "2.1.0", + "description": "产品需求设计技能。覆盖问答、PRD、缺陷与 OSS 原型闭环，文档双写本地和 ai-proj。", + "version": "2.2.0", "category": "productivity", "keywords": [ "project-management", @@ -495,8 +495,8 @@ { "name": "req-prototype-plugin", "source": "./skills-req/req-prototype-plugin", - "description": "原型生成与关联。支持 HTML 正式交付、Requirement 关联、iframe 验证闭环及 Stitch AI 视觉探索。", - "version": "2.1.0", + "description": "原型生成与关联。支持 HTML 本地留源、OSS 正式交付、Requirement/iframe 验证及 Stitch AI。", + "version": "2.2.0", "category": "productivity", "keywords": [ "project-management", diff --git a/skills-req/req-prd-plugin/.claude-plugin/plugin.json b/skills-req/req-prd-plugin/.claude-plugin/plugin.json index 9a4c2af..640693c 100644 --- a/skills-req/req-prd-plugin/.claude-plugin/plugin.json +++ b/skills-req/req-prd-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "req-prd-plugin", - "description": "产品需求设计技能。覆盖问答访谈、PRD、缺陷收敛及 HTML 原型验证闭环。纯产品视角，不含技术实现。", - "version": "2.1.0", + "description": "产品需求设计技能。覆盖问答、PRD、缺陷与 OSS 原型闭环，文档双写本地和 ai-proj。", + "version": "2.2.0", "author": { "name": "qiudl" }, diff --git a/skills-req/req-prd-plugin/skills/SKILL.md b/skills-req/req-prd-plugin/skills/SKILL.md index 7cf43f3..7cecf5e 100644 --- a/skills-req/req-prd-plugin/skills/SKILL.md +++ b/skills-req/req-prd-plugin/skills/SKILL.md @@ -1,6 +1,6 @@ --- name: req-prd -description: 产品设计与需求管理。用于 PRD 文档编写、需求分析、用户故事创建、功能设计和原型规划。当用户提到产品设计、PRD、需求文档、功能规划、用户故事相关任务时自动激活。 +description: 产品设计与需求管理。用于 PRD、需求分析、用户故事、功能设计和原型规划，并将正式需求文档双写到本地仓库与 ai-proj Task Document。 --- # 产品需求设计 Skill (req-prd) @@ -19,6 +19,36 @@ description: 产品设计与需求管理。用于 PRD 文档编写、需求分 - `req-prototype` — UI 模块在 PRD/缺陷收敛后生成、上传并关联 HTML 原型 - `defect-analysis` — 设计访谈确认后，对最新版 PRD 反复审计和修订直至收敛 +## 产品需求文档双写门禁 + +本技能创建或修改的所有正式需求文档都必须同时保存到： + +1. 当前产品仓库的本地 Markdown 文件； +2. Requirement 对应角色任务的 ai-proj Task Document。 + +适用文档至少包括原始诉求/讨论记录、PRD、缺陷优化记录、原型版本与评审记录。Requirement description 只保存已确认的讨论摘要，不能替代 Task Document。 + +### 路径与任务映射 + +优先遵循仓库已有文档目录和命名约定；没有约定时使用： + +| 文档 | 本地默认路径 | ai-proj 任务角色 | +|------|--------------|------------------| +| 需求讨论记录 | `docs/product/{REQ-ID}-{slug}-discussion.md` | `documentation` | +| PRD（含缺陷修订和原型回填） | `docs/product/{REQ-ID}-{slug}-prd.md` | `prd` | + +同一 Requirement、同一角色只维护一个当前任务文档。不得把本地文件路径当成 ai-proj 持久化，也不得只把远程 Task Document 导出一次后继续单边修改。 + +### 每次写入协议 + +1. 修改前同时读取本地文件与 ai-proj Task Document；任一不存在则基于另一份初始化，二者都不存在才新建空模板； +2. 若两份内容不一致，比较文档 ID、版本、更新时间和内容摘要，保留双方未知内容并显式合并；无法安全合并时停止并请用户选择，禁止静默覆盖； +3. 先用安全文件编辑方式写入本地 Markdown，再创建或更新对应 Task Document； +4. 写后重新读取两端，计算或比较内容摘要，确认正文一致，并记录本地路径、task_id、document_id、version/updated_at； +5. 任一端写入或复读失败都属于未完成的部分写入：保留已成功一端用于恢复，立即报告并停止后续阶段，不得宣称“已保存”“已收敛”或提交评审。 + +问答每一轮、每次 PRD 修订、每轮 defect 处置和每次原型回填都执行该协议；不能等到流程结束再一次性补传。 + ## 模块设计访谈模式 设计模块、系统、跨域流程，或目标/边界/业务规则尚未确定时，必须先执行问答式设计访谈，不得直接补全假设后生成 PRD。用户明确要求“你问我答”时也进入此模式。范围小、规则已完整确认的需求可以直接编写 PRD。 @@ -41,8 +71,8 @@ description: 产品设计与需求管理。用于 PRD 文档编写、需求分 1. 原型基于最新版、已完成缺陷收敛的 PRD，并记录 PRD 文档标识、版本或内容摘要； 2. 覆盖核心入口、主流程以及 PRD 明确要求的空态、失败态、无权限态和确认/撤销反馈； -3. 上传后重新读取 Requirement，确认原型 URL/版本已关联，并验证 URL 可访问、iframe 可展示、核心交互可操作； -4. 将 iframe、原型版本、版本说明和验证结果回填 PRD `4.2 界面原型`，并把生成、反馈、修订和确认写入同一讨论文档； +3. 将本地 HTML 源文件通过 ai-proj 上传到 OSS；上传后重新读取 Requirement，确认 OSS URL/版本已关联，并验证 URL 可访问、iframe 可展示、核心交互可操作； +4. 将 iframe、原型版本、版本说明和验证结果双写到本地 PRD 与 prd 角色 Task Document，并把生成、反馈、修订和确认双写到本地讨论记录与 documentation 任务文档； 5. 用户明确确认最终 PRD 与原型表达的是同一方案。 纯后端、批处理、基础设施等确实没有用户界面的模块可以跳过，但必须在讨论文档和 PRD `4.2` 中记录“无 UI，原型不适用”的理由及用户确认，不得静默省略。 @@ -401,6 +431,8 @@ mcp__ai-proj__link_tasks_to_requirement ### 文档管理 +以下 MCP 操作只完成 ai-proj 侧写入；每次调用前后都必须按“产品需求文档双写门禁”同步并校验本地 Markdown。 + ```bash # 创建 PRD 文档并关联任务 mcp__ai-proj__create-and-attach @@ -418,6 +450,8 @@ mcp__ai-proj__export_task_document_to_file - taskId: 任务ID ``` +导出命令不能代替双写校验：导出后仍需确认目标路径符合仓库约定、正文与 Task Document 当前版本一致，且没有覆盖本地新增内容。 + --- ## 功能设计流程 @@ -561,6 +595,8 @@ UI 模块还必须核对最终 HTML 原型与最新版 PRD 一致，并取得用 ### PRD 完整性检查 - [ ] 模块/系统设计已完成单轮单问访谈，且全过程已写入 ai-proj 讨论文档 +- [ ] 讨论记录与 PRD 均已保存到仓库本地 Markdown 和对应 ai-proj Task Document +- [ ] 两端复读正文一致，交付说明包含本地路径、task/document 标识和远程版本 - [ ] 讨论结论已由用户明确确认 - [ ] `defect-analysis` 已基于最新版 PRD 收敛到一轮 0 个新缺陷 - [ ] 无未处置的致命/高严重度缺陷 diff --git a/skills-req/req-prd-plugin/skills/references/design-interview-and-defect-loop.md b/skills-req/req-prd-plugin/skills/references/design-interview-and-defect-loop.md index e4e4569..2c5d5ba 100644 --- a/skills-req/req-prd-plugin/skills/references/design-interview-and-defect-loop.md +++ b/skills-req/req-prd-plugin/skills/references/design-interview-and-defect-loop.md @@ -28,6 +28,7 @@ - 任务标题：`【讨论】需求讨论: {需求标题}` - 文档标题：`{REQ-ID} 需求讨论记录` +- 本地文件：优先使用仓库约定；默认 `docs/product/{REQ-ID}-{slug}-discussion.md` - 一个 Requirement 只维护一个当前讨论文档，不因会话中断重复创建。 查找时同时核对 Requirement 关联关系、任务角色和标题，不能只按相似标题猜测。发现多个候选讨论文档时，列出标识和最近更新时间，请用户指定或授权合并；在此之前不得静默选择其中一个继续写入。 @@ -38,7 +39,15 @@ 若尚未指定 Requirement，先请用户提供已有 Requirement，或明确授权创建。取得 Requirement 和讨论文档前不得开始声称“已留痕”的正式访谈；不得仅为执行本技能本身擅自创建 Requirement。用户明确要求“创建需求并设计”才构成创建授权。 -每次恢复会话时，先读取 Requirement、现有 PRD 和讨论文档，从最后一个未决问题继续。讨论文档是跨会话、上下文压缩后的权威记录；模型记忆不能覆盖文档中的用户原话和已确认决策。 +每次恢复会话时，先读取 Requirement、现有 PRD，以及讨论记录/PRD 的本地文件和 ai-proj Task Document，从最后一个未决问题继续。两端持久化内容必须一致；模型记忆不能覆盖文档中的用户原话和已确认决策。 + +### 本地与 ai-proj 双写 + +- 讨论记录和 PRD 的每次新增或修订，都必须同步到仓库本地 Markdown 与对应 ai-proj Task Document；本地文件用于代码库评审和版本控制，Task Document 用于需求关联、跨会话恢复和团队查看。 +- 修改前读取两端。内容不一致时按版本、更新时间和摘要显式合并，保留双方未知内容；不能判断时停止并请用户选择，禁止以任一旧副本覆盖另一端。 +- 每轮问答按顺序完成：更新本地讨论文件 → 更新 documentation 任务文档 → 复读两端并核对正文/摘要 → 再向用户提出下一问。 +- 每次 PRD/defect/原型回填按同样协议更新本地 PRD 文件和 prd 任务文档。默认本地路径为 `docs/product/{REQ-ID}-{slug}-prd.md`，已有项目约定优先。 +- 任一端失败时记录“部分写入”及成功端的路径/标识，停止后续流程。恢复时从成功端与失败前最后版本合并，禁止重复追加同一 Q/Round/Prototype 编号。 ### 写入纪律 @@ -49,7 +58,7 @@ - 用户原话逐字保留在引用块中；AI 的解释、推论和建议必须分栏，不能伪装成用户决定。访问令牌、密码、私钥及依法需要保护的个人敏感信息不得落库，用 `[敏感信息已脱敏]` 替代并注明脱敏原因。 - 文档以追加式记录为主。状态为“待回答”的问题块可以在收到回答后原位补全一次；变为“已确认”后不得静默改写。纠正已确认结论时追加“决策变更”，并引用被替代的编号。 - 更新整篇文档前重新读取最新版并保留未知内容；若读取后文档又发生变化，基于最新版合并后重试，不能用旧副本覆盖其他会话的记录。 -- 写入后读取文档确认本轮编号和正文存在。写入或校验失败时立即报告，停止进入下一轮，且不得声称“已记录”。 +- 写入后读取本地文件和 ai-proj Task Document，确认本轮编号、正文和内容摘要一致。任一写入或校验失败时立即报告，停止进入下一轮，且不得声称“已记录”。 - Requirement 描述只同步用户确认后的“讨论结论”摘要；完整过程保留在讨论文档中。 ## 3. 单轮单问访谈 @@ -155,9 +164,9 @@ PRD 包含页面、表单、列表、可视状态、用户操作或跨页面流 ### 6.3 上传、关联、回填与验证 -1. 通过 `upload_prototype` 上传 HTML，并记录 Requirement 数字 ID、原型 URL、版本说明和上传时间； -2. 重新读取 Requirement，确认返回的原型 URL/版本确实已关联。仅拿到上传成功响应不足以通过； -3. 将 iframe、PRD 基线、原型版本、版本说明和验证结果回填 PRD `4.2 界面原型`； +1. 将 HTML 源文件保存到仓库约定目录（默认 `docs/prototypes/`），再通过 `upload_prototype` 上传到 ai-proj 配置的 OSS，并记录 Requirement 数字 ID、OSS URL、版本说明和上传时间； +2. 重新读取 Requirement，确认返回的 OSS URL/版本确实已关联。仅有本地文件或上传成功响应不足以通过； +3. 将 iframe、PRD 基线、原型版本、版本说明和验证结果同时回填本地 PRD 与 prd 角色 Task Document； 4. 用浏览器或等价方式验证 URL 可访问、iframe 可展示、核心导航和交互可操作、关键状态可识别。使用临时浏览器时按环境规则关闭； 5. 将生成输入、上传结果、验证证据和待确认差异写入讨论文档。任何写入或验证失败都必须停止，不得声称原型已完成。 @@ -236,7 +245,9 @@ PRD 包含页面、表单、列表、可视状态、用户操作或跨页面流 - ai-proj Requirement 标识； - 讨论任务/文档标识； +- 讨论记录本地路径及双写一致性状态； - PRD 任务/文档标识； +- PRD 本地路径及双写一致性状态； - 问答轮数、缺陷审计轮数和收敛轮； - HTML 原型版本、URL、Requirement 关联与验证状态；无 UI 时给出跳过理由和用户确认； - 仍被接受的中/低风险； diff --git a/skills-req/req-prototype-plugin/.claude-plugin/plugin.json b/skills-req/req-prototype-plugin/.claude-plugin/plugin.json index 233fd20..627dc7d 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": "原型生成与关联。支持 HTML 正式交付、Requirement 关联、iframe 验证闭环及 Stitch AI 视觉探索。", - "version": "2.1.0", + "description": "原型生成与关联。支持 HTML 本地留源、OSS 正式交付、Requirement/iframe 验证及 Stitch AI。", + "version": "2.2.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 a526192..308d7a4 100644 --- a/skills-req/req-prototype-plugin/skills/SKILL.md +++ b/skills-req/req-prototype-plugin/skills/SKILL.md @@ -1,6 +1,6 @@ --- name: req-prototype -description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 PRD 自动生成 UI 原型截图；(2) AI 编写 HTML 原型并上传关联到需求详情页 iframe。当执行 /req prototype 或需要生成/上传界面原型时使用。 +description: 原型生成与关联。生成可交互 HTML、上传到 ai-proj OSS 并关联 Requirement/PRD iframe，也支持 Stitch AI 视觉探索。 --- # 原型设计 Skill (req-prototype) @@ -13,7 +13,7 @@ description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 P | 模式 | 命令 | 适用场景 | 输出 | |------|------|----------|------| -| **HTML 上传** | `/req prototype upload` | UI 模块正式产品设计交付、评审与交互验证 | 可交互 HTML + Requirement 关联 + PRD iframe | +| **HTML 上传** | `/req prototype upload` | UI 模块正式产品设计交付、评审与交互验证 | 本地 HTML 源文件 + OSS URL + Requirement 关联 + PRD iframe | | **Stitch AI** | `/req prototype` | 精细 UI 视觉探索、多屏草图 | 截图回填 PRD，后续仍需转为 HTML 正式原型 | ## 前置条件 @@ -27,6 +27,17 @@ description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 P | PRD 已完成 defect 收敛（正式 HTML 模式） | 读取讨论文档的收敛轮和最新版 PRD 标识 | 报错：先完成 req-prd/defect-analysis 收敛 | | UI 原型适用 | PRD 含页面、操作流程或可视状态 | 无 UI 时记录不适用理由与用户确认，不生成空壳原型 | +## HTML 原型持久化门禁 + +正式 HTML 原型必须上传到 ai-proj 配置的 OSS（对象存储），并以 OSS HTTPS URL 关联 Requirement。仅生成本地文件、`file://` URL、临时 HTTP 服务或聊天附件都不算完成。 + +- 本地源文件优先遵循仓库约定；默认保存为 `docs/prototypes/{REQ-ID}-{slug}-v{N}.html`，纳入版本控制。 +- OSS 上传必须通过 `mcp__ai-proj__upload_prototype` 或 ai-proj 提供的等价正式接口完成，禁止绕过 Requirement 关联自行上传后只粘贴 URL。 +- `/tmp` 只能存放编码或校验过程中的临时副本，不能作为原型交付位置。 +- 上传后必须复读 Requirement，确认 `prototype_urls`/版本记录指向本次 OSS URL；再验证 URL 可访问、响应为 `text/html` 且可内联展示。 +- OSS 地址必须由 ai-proj 长期管理，不能把短期预签名 URL 写入 PRD；访问控制与 iframe 策略由 ai-proj 统一提供。 +- 原型元数据和 iframe 回填属于 PRD 修订，必须同时更新本地 PRD Markdown 与 prd 角色 Task Document，并复读校验一致。 + ## 子命令 ### 0. `/req prototype upload [REQ-ID] [--note "版本说明"]` — 上传 HTML 原型（**推荐**） @@ -40,24 +51,24 @@ description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 P 2. 完整读取最新版 PRD，记录任务/文档 ID、版本、更新时间和内容摘要或哈希；正式交付还要核对 defect 收敛轮 3. 从 PRD 提取页面清单、角色入口、主流程、关键状态和验收条件，形成覆盖矩阵 4. AI 编写带完整样式和必要原生交互的独立 HTML 原型文件（见设计规范） -5. 保存到 /tmp/proto__.html，并在本地做结构、大小和敏感信息检查 -6. Base64 编码：base64 < /tmp/proto__.html -7. 调用 mcp__ai-proj__upload_prototype 上传（传入 requirementId + base64 content） -8. 重新读取 Requirement，确认原型 URL/版本已关联；不得只相信上传响应 -9. 将 iframe、PRD 基线、原型版本/说明和验证状态回填 PRD「4.2 界面原型」 +5. 保存到仓库原型目录（默认 docs/prototypes/--v.html），并做结构、大小和敏感信息检查 +6. 从本地源文件 Base64 编码；如工具需要，可在 /tmp 创建临时编码副本 +7. 调用 mcp__ai-proj__upload_prototype 上传到 OSS（传入 requirementId + base64 content） +8. 重新读取 Requirement，确认 OSS URL/版本已关联；不得只相信上传响应 +9. 将 iframe、PRD 基线、原型版本/说明和验证状态双写到本地 PRD 与 prd 角色 Task Document 10. 打开最终 URL 或需求详情页，验证 iframe 展示和核心交互；记录证据后关闭临时浏览器 -11. 将生成、关联、验证、用户反馈和版本状态写入同一讨论文档 +11. 将生成、关联、验证、用户反馈和版本状态双写到本地讨论记录与 documentation 角色 Task Document ``` -**Step 5-6 执行方式**： +**Step 6-7 执行方式**： ```bash -# 5. Base64 编码 HTML 文件 -B64=$(base64 < /tmp/proto__.html) +# 6. Base64 编码本地 HTML 源文件 +B64=$(base64 < docs/prototypes/--v.html) ``` ``` -# 6. 通过 MCP 工具上传（无需本地后端） +# 7. 通过 MCP 工具上传到 OSS（无需本地后端） mcp__ai-proj__upload_prototype( requirementId = <需求数字ID>, content = , @@ -72,7 +83,7 @@ mcp__ai-proj__upload_prototype( "success": true, "message": "原型已上传并关联到需求 （version=N/A）", "data": { - "url": "https://ai-proj-1252326374.cos.ap-beijing.myqcloud.com/prototypes/.html", + "url": "https:///prototypes/.html", "versionNote": "...", "uploadedAt": "...", "requirementId": @@ -80,7 +91,7 @@ mcp__ai-proj__upload_prototype( } ``` -**效果**：需求详情页自动出现「原型预览」卡片，iframe 加载 COS 上的 HTML 文件。**无需本地后端运行**。 +**效果**：需求详情页自动出现「原型预览」卡片，iframe 加载 OSS 上的 HTML 文件。**无需本地后端运行**。OSS 的具体厂商和域名由 ai-proj 服务配置，技能不得硬编码 COS、S3 或其他厂商地址。 **参数**： @@ -183,6 +194,9 @@ AI 生成的 HTML 原型必须满足以下要求： #### HTML 上传后验证清单 - [ ] 上传响应成功且 Requirement 复读能看到同一 URL/版本 +- [ ] URL 为 ai-proj 返回的持久化 OSS HTTPS 地址，不是本地或临时地址 +- [ ] URL 不是短期预签名地址，响应 `Content-Type` 为 `text/html` 且不会强制下载 +- [ ] 仓库中保留与该 OSS 版本对应的 HTML 源文件 - [ ] 原型 URL 返回可展示的 HTML，不是下载错误页、登录页或 404 - [ ] 需求详情页使用 iframe 展示，没有降级为截图或图片 - [ ] 核心入口、主流程和覆盖矩阵中的关键状态可识别/可操作 @@ -327,7 +341,7 @@ generated_at: "" | 异常 | 处理 | |------|------| -| `mcp__ai-proj__upload_prototype` 返回失败 | 检查 requirementId 是否为数字 ID（非 display_id REQ-xxx） | +| `mcp__ai-proj__upload_prototype` 返回失败 | 检查 requirementId 是否为数字 ID（非 display_id REQ-xxx）；不得降级为只留本地文件 | | HTML 文件超过 5MB | 精简样式或拆分多版本上传 | | iframe 不显示 | 检查 `prototype_urls` 字段是否非空：`mcp__ai-proj__get_requirement` 确认 | | base64 命令失败 | macOS 用 `base64 < file`，Linux 用 `base64 -w 0 < file` | -- 2.54.0