OA/zentao-flow
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 根目录文档、脚本、gitignore

Browse Source
This commit is contained in:
guoqibing
2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/pmassist/design/prototype-integration.md
+460
View File
@@ -0,0 +1,460 @@
# 原型设计环节集成方案
## 1. 设计目标
在 pmassist 的 PDCA 流程中增加"原型设计"环节，使 PRD/FRD 不仅有文字描述，还能产出可视化、可交互的原型效果，强化需求可理解性和可验证性。
## 2. 触发时机
### 2.1 自动触发（推荐）
- 当文档类型为 **PRD** 且进入 Round 2+ 时，在 Plan 阶段询问是否需要原型
- 当文档类型为 **FRD** 且包含界面/交互需求时，强制要求原型
### 2.2 用户显式触发
- 用户在任意阶段说"需要原型"、"出个效果图"、"做个 demo"等关键词
- 在问题列表中回答"需要可视化原型"
## 3. 原型输入方式（多轮问答模式）
### Round Proto-1: 收集原型需求
**问题清单**（保存至 `questions/proto_requirements.yaml`）:
```yaml
proto_round: 1
questions:
- id: PROTO-1-1
priority: P0
question: "原型范围是什么？"
options:
- "整体流程 PoC（所有关键页面）"
- "核心页面（单个页面完整交互）"
- "局部组件（如表单、列表、弹窗）"
- "特定效果演示（如动画、数据可视化）"
- "其他（请描述）"
answer: ""
- id: PROTO-1-2
priority: P0
question: "参考来源是什么？"
options:
- "提供 URL（线上产品/竞品）"
- "提供截图（设计稿/现有页面）"
- "提供文字描述（详细交互说明）"
- "无参考，从零设计"
answer: ""
- id: PROTO-1-3
priority: P1
question: "原型保真度要求？"
options:
- "低保真（线框图，黑白灰，主结构）"
- "中保真（基础样式，品牌色，可交互）"
- "高保真（视觉设计，动画，接近真实）"
answer: ""
- id: PROTO-1-4
priority: P1
question: "技术实现偏好？"
options:
- "Pencil (.pen 文件) - 适合设计稿、静态展示"
- "Web Artifact (HTML/React) - 适合交互原型、PoC"
- "两者都要"
answer: ""
```
### Round Proto-2: 原型实现
根据 Proto-1 的回答，选择技术路径：
#### 路径 A: Pencil 设计稿
1. **获取设计指南**:
- `mcp__pencil__get_style_guide_tags()` 获取可用风格标签
- `mcp__pencil__get_style_guide(tags=[...])` 获取设计风格
- `mcp__pencil__get_guidelines(topic="design-system")` 获取设计规范
2. **创建设计**:
- `mcp__pencil__open_document(filePathOrTemplate="new")` 创建新画布
- `mcp__pencil__batch_design(operations=...)` 批量设计操作
- 保存至 `{workdir}/prototypes/design.pen`
3. **验证输出**:
- `mcp__pencil__get_screenshot(nodeId=...)` 获取设计截图
- 保存至 `{workdir}/prototypes/screenshots/`
#### 路径 B: Web Artifact 交互原型
1. **使用 frontend-design skill**:
- 调用 `Skill(skill="document-skills:frontend-design", args="...")`
- 根据需求描述生成 React/HTML 代码
- 保存至 `{workdir}/prototypes/webapp/`
2. **可选：本地测试**:
- 使用 `document-skills:webapp-testing` 验证交互
- 截图保存至 `{workdir}/prototypes/screenshots/`
#### 路径 C: URL/截图范本
1. **URL 范本处理**:
- 使用 Chrome DevTools MCP:
- `mcp__chrome-devtools__navigate_page(url=...)`
- `mcp__chrome-devtools__take_screenshot(filePath=...)`
- `mcp__chrome-devtools__take_snapshot(filePath=...)` 获取结构
- 保存截图和结构分析到 `materials/prototypes/`
2. **截图范本处理**:
- 用户上传截图到 `materials/prototypes/reference/`
- 使用 Read 工具读取（支持图片）
- 分析并提取设计元素（色彩、布局、组件）
3. **基于范本生成**:
- 根据分析结果，选择路径 A 或 B 实现
- 在 `prototypes/design_analysis.md` 记录对标情况
### Round Proto-3: 验证与迭代
**检查清单**:
```yaml
proto_checklist:
- 原型覆盖 PRD/FRD 中所有关键场景
- 关键交互路径可演示
- 视觉风格符合品牌/行业规范
- 技术栈与实际开发可对齐
- 截图已归档到文档中
```
**迭代流程**:
1. 用户反馈调整点
2. 更新 `questions/proto_feedback_N.yaml`
3. 修改设计/代码
4. 重新截图验证
## 4. 目录结构扩展
```
{workdir}/
desc.md
session.yaml
summary.md
decision_log.md
materials/
prototypes/ # 新增：原型参考资料
reference/ # 用户提供的截图/URL 快照
analysis/ # 竞品分析、设计对标
materials_index.md
rounds/
questions/
proto_requirements.yaml # 新增：原型需求问答
proto_feedback_N.yaml # 新增：原型反馈轮次
outputs/
prd.md / frd.md / dar.md
prototypes/ # 新增：原型产出目录
design.pen # Pencil 设计文件
screenshots/ # 原型截图
v1-homepage.png
v1-form.png
webapp/ # Web 原型代码
index.html
app.jsx
design_analysis.md # 设计决策记录
prototype_coverage.md # 原型覆盖度对照表
```
## 5. 证据映射增强
在 PRD/FRD 的"证据映射表"中新增原型证据类型：
| 章节 | 关键结论 | 证据 |
|---|---|---|
| 6.2 商户端订单详情页 | 新增双轨里程展示 | `[PROTO:prototypes/screenshots/v1-order-detail.png]` |
| 6.3 司机端结算页 | 使用最短里程 | `[PROTO:prototypes/webapp/index.html#settlement]` |
## 6. session.yaml 扩展
```yaml
project_alias: "dual-billing"
doc_type: "prd"
title: "取送车双轨计费机制 PRD"
created_at: "2026-02-08 14:43:05"
updated_at: "2026-02-09 12:00:00"
round: 2
status: "prd_draft_complete"
unresolved_questions:
- "Q2-1"
- "Q2-2"
# 新增：原型状态
prototype:
enabled: true
status: "proto_in_progress" # proto_pending | proto_in_progress | proto_complete
proto_round: 2
tech_stack:
- "pencil"
- "web-artifact"
outputs:
- "prototypes/design.pen"
- "prototypes/screenshots/v1-merchant-view.png"
- "prototypes/webapp/index.html"
unresolved_proto_questions:
- "PROTO-2-1"
```
## 7. 集成到 PDCA 流程
### 在现有 Round N 中插入原型环节
```
Round N (PDCA)
├── Plan
│ ├── 本轮文档目标
│ ├── [新增] 是否需要原型？→ 启动 Proto Round
│ └── 需要提出的问题
├── Do
│ ├── 读取证据
│ ├── 分析并更新文档
│ └── [新增] 若启用原型 → 执行 Proto Round
├── Check
│ ├── 证据充足性
│ ├── [新增] 原型覆盖度检查
│ └── 逻辑一致性
└── Act
├── 更新 summary.md
├── [新增] 更新 prototype 状态
└── 规划下一轮
```
### Proto Round 独立子流程
```
Proto Round 1: 需求收集
├── 询问 PROTO-1-1 到 PROTO-1-4
├── 记录答案到 questions/proto_requirements.yaml
└── 根据答案选择技术路径
Proto Round 2: 实现
├── 路径 A: Pencil 设计
├── 路径 B: Web Artifact
├── 路径 C: 基于范本生成
└── 输出到 prototypes/ 目录
Proto Round 3: 验证
├── 截图归档
├── 覆盖度对照
├── 用户反馈
└── 状态更新（proto_complete / 继续迭代）
```
## 8. SKILL.md 更新要点
在现有 SKILL.md 中插入以下章节：
**新增 2.6) 原型设计环节（可选但推荐）**
```markdown
## 2.6) 原型设计环节（可选但推荐）
### 触发条件
- PRD 进入 Round 2+ 时，询问是否需要原型
- FRD 包含界面/交互需求时，强制原型
- 用户显式要求"需要原型"、"出效果"
### 执行流程
1. **Proto Round 1**: 收集需求（范围/来源/保真度/技术栈）
2. **Proto Round 2**: 实现原型（Pencil / Web Artifact / 基于范本）
3. **Proto Round 3**: 验证迭代（覆盖度/反馈/归档）
### 技术选择
- **Pencil (.pen)**: 适合设计稿、视觉展示、无需交互
- **Web Artifact**: 适合交互原型、PoC、可点击演示
- **两者结合**: Pencil 出视觉稿 → Web Artifact 实现交互
### 证据标注
- 原型引用格式: `[PROTO:prototypes/screenshots/xxx.png]`
- 在证据映射表中关联章节与原型文件
```
## 9. init_session.py 脚本更新
在脚本中新增 `prototypes/` 目录创建：
```python
# line 47, 增加原型目录
for d in ["materials", "materials/prototypes", "materials/prototypes/reference",
"rounds", "questions", "outputs", "prototypes", "prototypes/screenshots", "prototypes/webapp"]:
(workdir / d).mkdir(parents=True, exist_ok=True)
```
新增可选参数：
```python
parser.add_argument("--enable-prototype", action="store_true", help="Enable prototype design phase")
```
## 10. 使用示例
### 场景 1: 从零设计 PRD + 原型
```bash
# 初始化
python3 skills/pmassist/scripts/init_session.py \
--path ./dual-billing-proto-20260209-1200 \
--doc prd \
--alias dual-billing-proto \
--title "取送车双轨计费机制 PRD（含原型）" \
--desc "需要商户端和司机端的完整交互原型" \
--enable-prototype
# 进入对话
Claude: "检测到启用原型，请回答以下问题..."
User: "整体流程 PoC，无参考从零设计，中保真，Web Artifact"
Claude: [生成 React 原型] → 保存到 prototypes/webapp/
```
### 场景 2: 基于 URL 范本生成
```bash
# 用户提供竞品 URL
User: "参考 https://example.com/order 的设计，做类似的订单页"
# pmassist 执行
1. Chrome DevTools 抓取 URL → screenshots + DOM 分析
2. 提炼设计元素（布局/色彩/组件）→ materials/prototypes/analysis/competitor.md
3. Pencil 生成视觉稿 → prototypes/design.pen
4. Web Artifact 实现交互 → prototypes/webapp/
```
### 场景 3: 基于截图范本生成
```bash
# 用户上传截图
User: [上传 design-draft.png 到 materials/prototypes/reference/]
# pmassist 执行
1. Read 读取截图（Claude 可视觉理解）
2. 分析布局/元素 → design_analysis.md
3. 询问: "基于此截图，需要高保真实现还是仅结构参考？"
4. 根据回答选择 Pencil 或 Web Artifact
```
## 11. 实施优先级
### P0 (立即实施)
- [ ] 更新 SKILL.md 增加 2.6 原型设计章节
- [ ] 更新 init_session.py 创建 prototypes/ 目录
- [ ] 创建 proto_requirements.yaml 问题模板
- [ ] 更新 session.yaml 增加 prototype 状态字段
### P1 (近期实施)
- [ ] 创建 Pencil 原型生成流程文档
- [ ] 创建 Web Artifact 原型生成流程文档
- [ ] 创建原型覆盖度检查清单模板
- [ ] 更新 PRD/FRD 模板增加原型证据示例
### P2 (优化迭代)
- [ ] 支持原型版本管理（v1/v2/v3）
- [ ] 自动生成原型对比报告
- [ ] 集成设计 token 系统（颜色/字体/间距）
- [ ] 支持原型导出为开发切图
## 12. 风险与应对
| 风险 | 影响 | 应对 |
|---|---|---|
| 原型制作耗时过长 | PDCA 节奏被打乱 | 限制原型范围，优先核心页面 |
| 技术栈与开发脱节 | 原型无法复用 | Proto-1-4 问答时明确开发技术栈 |
| 设计质量不符预期 | 需多轮返工 | 提供保真度选项，降低预期或引入设计师 |
| Pencil 学习曲线陡峭 | 无法快速产出 | 优先使用 Web Artifact，Pencil 仅用于视觉稿 |
## 13. 成功指标
- ✅ PRD/FRD 中 80% 的界面需求有对应原型截图
- ✅ 原型从启动到首版完成 < 2 个 PDCA 轮次
- ✅ 开发阶段可直接参考原型代码，复用率 > 30%
- ✅ 评审时因原型演示减少理解偏差 > 50%
---
## 附录：问题模板文件
### prototypes/proto_requirements_template.yaml
```yaml
# 原型需求问答模板（Proto Round 1）
proto_round: 1
status: "pending" # pending | answered | implemented
questions:
- id: PROTO-1-1
priority: P0
question: "原型范围是什么？"
options:
- "整体流程 PoC（所有关键页面）"
- "核心页面（单个页面完整交互）"
- "局部组件（如表单、列表、弹窗）"
- "特定效果演示（如动画、数据可视化）"
- "其他（请描述）"
answer: ""
- id: PROTO-1-2
priority: P0
question: "参考来源是什么？"
options:
- "提供 URL（线上产品/竞品）"
- "提供截图（设计稿/现有页面）"
- "提供文字描述（详细交互说明）"
- "无参考，从零设计"
answer: ""
answer_detail: "" # 如果选 URL，填写具体 URL；如果选截图，填写文件路径
- id: PROTO-1-3
priority: P1
question: "原型保真度要求？"
options:
- "低保真（线框图，黑白灰，主结构）"
- "中保真（基础样式，品牌色，可交互）"
- "高保真（视觉设计，动画，接近真实）"
answer: ""
- id: PROTO-1-4
priority: P1
question: "技术实现偏好？"
options:
- "Pencil (.pen 文件) - 适合设计稿、静态展示"
- "Web Artifact (HTML/React) - 适合交互原型、PoC"
- "两者都要（先 Pencil 视觉稿，再 Web 实现）"
answer: ""
- id: PROTO-1-5
priority: P2
question: "是否需要真实数据模拟？"
options:
- "是，需要真实业务数据结构（如订单、用户信息）"
- "否，使用 Lorem Ipsum / 假数据即可"
answer: ""
```
### prototypes/prototype_coverage_template.md
```markdown
# 原型覆盖度对照表
## 文档章节 vs 原型文件
| PRD/FRD 章节 | 关键场景 | 原型文件 | 覆盖度 | 备注 |
|---|---|---|---|---|
| 6.1 商户端计费展示 | 双轨里程对比 | `screenshots/v1-merchant-billing.png` | ✅ 完整 | - |
| 6.2 司机端结算 | 最短路线支付 | `webapp/index.html#driver-settlement` | ✅ 完整 | 可点击交互 |
| 6.3 差异告警 | 超限 fallback | `screenshots/v1-alert-dialog.png` | ⚠️ 部分 | 仅静态截图，未实现交互 |
| 6.4 配置开关 | 商户启用双轨 | - | ❌ 缺失 | 待补充 |
## 原型文件清单
| 文件路径 | 类型 | 用途 | 状态 |
|---|---|---|---|
| `prototypes/design.pen` | Pencil | 整体视觉稿 | ✅ 完成 |
| `prototypes/screenshots/v1-merchant-billing.png` | 截图 | 商户端计费页 | ✅ 完成 |
| `prototypes/screenshots/v1-alert-dialog.png` | 截图 | 差异告警弹窗 | ✅ 完成 |
| `prototypes/webapp/index.html` | HTML | 交互原型（司机端） | ✅ 完成 |
| `prototypes/webapp/merchant.html` | HTML | 交互原型（商户端） | 🔄 进行中 |
## 待补充原型
- [ ] 6.4 配置开关（商户后台页面）
- [ ] 7.2 埋点示意（数据看板截图）
```