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

2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
@@ -0,0 +1,335 @@
+# 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`