# pmassist Changelog

## [v2.1.0] - 2026-02-09

### 新增功能：会话恢复（Session Resumption）

#### 核心特性
- ✅ **自动状态回顾**：读取 session.yaml、summary.md、questions/* 生成完整的会话状态报告
- ✅ **5 种工作模式**：继续/修改/局部/原型/定稿，精准匹配不同使用场景
- ✅ **触发词识别**：支持"继续之前的工作"、"修改 XXX 的 PRD"等自然语言触发
- ✅ **版本升级检测**：自动识别 v1.x 会话并提示升级到 v2.x

#### 文件变更

**1. SKILL.md**
- 新增 `## 1.5) 会话恢复（Resume Session）`
- 位置：第 1 节（确认工作目录）与第 2 节（初始化工作区）之间
- 内容：
  - 触发条件与验证逻辑
  - 状态回顾报告模板（包含 Round、章节、问题、原型状态）
  - 5 种工作模式（A-E）详细流程
  - 特殊处理：版本升级、损坏会话恢复

#### 5 种工作模式

**A. 继续模式**（Continue）
- 接续当前 Round，补充未完成章节
- 优先解决 P0 遗留问题
- 继续执行 PDCA 循环直到本轮收敛

**B. 修改模式**（Revise）
- 开启新 Round（N+1），基于新需求/反馈修订
- 重新走一轮完整 PDCA
- 记录修改诉求到新 round 文件

**C. 局部模式**（Patch）
- 只修改特定章节/段落，不开启新 Round
- 不触发完整 PDCA，快速修改
- 追加修改记录到 decision_log.md

**D. 原型模式**（Prototype）
- 独立于文档迭代，执行 Proto Round 1-3
- 支持更新/重新生成原型
- 与 2.6 节原型设计环节联动

**E. 定稿模式**（Finalize）
- 最终审核并定稿，不再修改内容
- 完整性检查（证据覆盖、图表齐全、问题清零）
- 生成 `{doc_type}_final.md` 并更新状态

#### 状态报告模板

```markdown
📊 会话状态报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 工作目录：{workdir}
📄 文档类型：{PRD/FRD/DAR}
📌 项目简称：{alias}
🔢 当前 Round：{current_round}
📝 已完成内容：章节数、证据数、图表数
❓ 遗留问题：P0/P1/P2 统计
🎨 原型状态：技术路径、产出文件
⏰ 上次更新：时间戳
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

#### 特殊处理

**会话版本升级**
- 检测旧版 session.yaml（缺少 `prototype` 块）
- 提示用户升级到 v2.0，自动创建 prototypes/ 目录

**损坏会话恢复**
- 尝试从 `.backup/` 恢复
- 若无备份，提供重建或创建新会话选项

#### 使用场景

**场景 1：继续未完成工作**
```
用户："继续 dual-billing-20260209-1500 的 PRD"
Claude：
1. 读取 session.yaml → Round 2
2. 生成状态报告 → 已完成 3 章，遗留 5 个 P1 问题
3. 询问："[A] 继续当前 Round 2"
4. 用户选 A → 解决 P1 问题并补充第 4 章
```

**场景 2：基于新需求修改**
```
用户："修改 dual-billing 的计费逻辑，增加时长计费"
Claude：
1. 读取会话 → 当前 Round 3
2. 生成状态报告
3. 询问："[B] 修改模式 - 开启 Round 4"
4. 用户选 B → 记录修改诉求，重新 PDCA
```

**场景 3：快速修正单章节**
```
用户："把 dual-billing PRD 的第 3 章重写一下"
Claude：
1. 读取会话
2. 生成状态报告
3. 询问："[C] 局部模式 - 只修改第 3 章"
4. 用户选 C → 重写第 3 章，更新证据，不开新 Round
```

**场景 4：更新原型**
```
用户："dual-billing 的原型需要增加一个结算页面"
Claude：
1. 读取会话 → prototype.status = "proto_complete"
2. 生成状态报告 → 已有 Pencil 设计稿
3. 询问："[D] 原型模式 - Proto Round 2（增量）"
4. 用户选 D → 执行 Proto Round 补充结算页面
```

**场景 5：最终定稿**
```
用户："dual-billing PRD 可以定稿了"
Claude：
1. 读取会话 → Round 5
2. 生成状态报告
3. 询问："[E] 定稿模式"
4. 用户选 E → 完整性检查 → 生成 prd_final.md
```

#### 向后兼容

- ✅ v1.x 会话可自动识别并提示升级
- ✅ 不影响现有新建会话流程（第 1-2 节）
- ✅ 所有恢复功能为可选，不破坏原有工作流

#### 文档更新

- [x] SKILL.md - 新增 1.5 节会话恢复
- [x] CHANGELOG.md - 记录 v2.1.0 变更

#### 设计原则

- **手动触发**：无需额外脚本，Claude 读取文件并生成报告
- **明确模式**：5 种模式覆盖所有工作场景，避免混淆
- **状态透明**：报告模板清晰展示会话状态
- **灵活切换**：用户可根据需求自由选择工作模式

---

## [v2.0.0] - 2026-02-09

### 新增功能：原型设计环节

#### 核心特性
- ✅ **多轮问答式原型需求收集** (Proto Round 1-3)
- ✅ **4 种输入方式支持**: URL 范本、截图范本、文字描述、从零设计
- ✅ **2 条技术路径**:
  - Pencil (.pen) - 静态设计稿、视觉展示
  - Web Artifact (React/HTML) - 交互原型、可点击 PoC
- ✅ **证据链增强**: 原型文件作为新型证据类型 `[PROTO:...]`

#### 文件变更

**1. SKILL.md**
- 新增 `## 2.6) 原型设计环节（可选但推荐）`
- 内容：触发条件、执行流程（Proto Round 1-3）、技术选择、目录结构、证据标注规则
- 更新 `## 资源` 章节，增加原型模板引用

**2. scripts/init_session.py**
- 新增参数：`--enable-prototype`
- 新增目录创建逻辑：
  - `materials/prototypes/`（reference / analysis）
  - `prototypes/`（screenshots / webapp）
- session.yaml 模板扩展：增加 `prototype` 配置块

**3. references/proto_requirements_template.yaml** (新增)
- Proto Round 1 的问题清单模板
- 5 个标准问题（PROTO-1-1 到 PROTO-1-5）
- 优先级：2 个 P0、2 个 P1、1 个 P2

**4. references/prototype_coverage_template.md** (新增)
- 原型覆盖度对照表模板
- 章节 vs 原型文件映射表
- 原型文件清单
- 反馈记录与验收标准

**5. design/prototype-integration.md** (新增)
- 完整的原型集成方案设计文档
- 包含：设计目标、触发时机、流程图、风险应对、成功指标

#### 目录结构变化

**启用原型前**:
```
{workdir}/
├── materials/
├── rounds/
├── questions/
└── outputs/
```

**启用原型后** (`--enable-prototype`):
```
{workdir}/
├── materials/
│   └── prototypes/          # 新增
│       ├── reference/       # 截图/URL 快照
│       └── analysis/        # 竞品分析
├── rounds/
├── questions/
│   ├── proto_requirements.yaml    # 新增
│   └── proto_feedback_N.yaml      # 新增
├── outputs/
└── prototypes/              # 新增
    ├── design.pen           # Pencil 设计稿
    ├── screenshots/         # 原型截图
    ├── webapp/              # Web 原型代码
    ├── design_analysis.md   # 设计决策
    └── prototype_coverage.md # 覆盖度对照
```

#### session.yaml 扩展

新增 `prototype` 配置块：
```yaml
prototype:
  enabled: true
  status: "proto_pending"  # proto_pending | proto_in_progress | proto_complete
  proto_round: 0
  tech_stack: []
  outputs: []
  unresolved_proto_questions: []
```

#### 使用示例

**基础用法** (不启用原型):
```bash
python3 skills/pmassist/scripts/init_session.py \
  --path ./myproject-20260209-1500 \
  --doc prd \
  --alias myproject \
  --title "我的产品需求文档" \
  --desc "需求描述..."
```

**启用原型**:
```bash
python3 skills/pmassist/scripts/init_session.py \
  --path ./myproject-20260209-1500 \
  --doc prd \
  --alias myproject \
  --title "我的产品需求文档" \
  --desc "需求描述，需要可视化原型" \
  --enable-prototype  # 新增参数
```

#### 工作流程集成

原型环节融入现有 PDCA 流程：

```
Round N (文档迭代)
├── Plan
│   ├── 本轮文档目标
│   ├── [新增] 是否需要原型？
│   └── 需要提出的问题
├── Do
│   ├── 读取证据
│   ├── 分析并更新文档
│   └── [新增] 若启用原型 → 执行 Proto Round 1-3
├── Check
│   ├── 证据充足性
│   ├── [新增] 原型覆盖度检查
│   └── 逻辑一致性
└── Act
    ├── 更新 summary.md
    ├── [新增] 更新 prototype 状态
    └── 规划下一轮
```

**Proto Round 子流程**:
1. **Round 1**: 需求收集（问答 PROTO-1-1 到 PROTO-1-5）
2. **Round 2**: 实现原型（选择技术路径 A/B/C）
3. **Round 3**: 验证迭代（覆盖度检查/反馈/归档）

#### 技术依赖

**MCP 工具**:
- `pencil` - Pencil 设计稿生成
- `chrome-devtools` - URL 范本抓取
- `document-skills:frontend-design` - Web Artifact 生成
- `document-skills:webapp-testing` - 原型交互测试（可选）

**证据类型扩展**:
- `[PROTO:prototypes/screenshots/xxx.png]` - 原型截图
- `[PROTO:prototypes/webapp/index.html#section]` - 交互原型

#### 向后兼容

- ✅ 未使用 `--enable-prototype` 时，行为与 v1.x 完全一致
- ✅ 现有会话目录不受影响
- ✅ 所有原型功能为可选特性

#### 文档更新

- [x] SKILL.md - 新增 2.6 章节
- [x] init_session.py - 新增参数和目录逻辑
- [x] 新增 proto_requirements_template.yaml
- [x] 新增 prototype_coverage_template.md
- [x] 新增 design/prototype-integration.md

#### 测试验证

- [x] `--help` 显示 `--enable-prototype` 参数
- [x] 创建会话时正确生成原型目录结构
- [x] session.yaml 包含 `prototype` 配置块
- [x] 清理测试环境

#### 下一步计划 (P1)

- [ ] 创建 Pencil 原型生成流程文档
- [ ] 创建 Web Artifact 原型生成流程文档
- [ ] 更新 PRD/FRD 模板增加原型证据示例
- [ ] 在真实项目中测试完整流程

---

## [v1.0.0] - 2026-02-08

### 初始版本
- WWH + PDCA 工作流程
- PRD/FRD/DAR 三类文档支持
- 证据映射机制
- 问题清单管理（P0/P1/P2）
- 初始化脚本 `init_session.py`