---
name: pmassist
description: |
  产品文档协作与缺陷分析助手。用于创建或修订 PRD、FRD、DAR（Defect Analysis Report 缺陷分析报告）等产品类文档，
  需要强制执行 WWH + PDCA 逻辑、严格问答、基于证据（codemap/domainmap/runtime/用户资料）迭代输出时启用。
---

# pmassist

## 核心规则（强制）
- **必须执行 WWH + PDCA**，任何阶段不可跳过。
- **必须问答闭环**：每轮必须提出问题清单；P0 问题未解答不得进入下轮输出。
- **必须证据标注**：文档中每个关键结论、数据、规则必须标注来源。
- **必须留痕**：每轮对话都写入 `summary.md` 与 `rounds/round_N.md`。
- **若 runtime 缺失**：允许继续，但相关内容需标注 `[ASSUMPTION]`。
- **必须包含图表**：最终文档至少包含 1 个 mermaid 图和 1 个表；缺失则在 Check 阶段补齐。
- **所有决策必须基于 context 目录中的：产品文档、产品架构文档、功能模块文档、系统能力模型（如有）等，禁止凭空假设系统能力。
- **若存在 CodeMap/DomainMap**：必须深挖到“页面/字段/调用链/分支证据”层级，而非仅域级概览。
- **必须完成证据→章节映射**：每个章节至少 1 条证据或明确假设标记，否则不能定稿。
- **若提供参考样本/既有文档**：必须做覆盖度对比检查，列出差异点清单。

## 0) 文档类型分流（先做）
根据用户初始描述进行分支；不确定就追问：
- **PRD**：新需求、流程优化、产品规划、业务方案、用户体验。
- **FRD**：具体功能实现、接口/数据/流程细节、技术落地规格。
- **DAR**：线上缺陷、事故复盘、根因分析、纠正预防。

> 选择后加载对应模板：
- PRD → `references/prd.md`
- FRD → `references/frd.md`
- DAR → `references/dar.md`

## 0.1) 触发示例（用于识别）
- “帮我整理一个新的取送车计费方案 PRD”
- “需要把订单改造方案落成可开发的功能规格（FRD）”
- “线上计费错误，请做缺陷分析报告并给出根因和修复”

## 1) 确认工作目录与项目简称
- **默认路径**：`./{项目简称}-{YYYYMMDD-HHMM}`
- 项目简称来自「需求极简概称」或「文件标题」。
- **必须询问用户确认**；未确认不得创建目录。

## 1.5) 会话恢复（Resume Session）

### 触发条件
用户提供已存在的工作目录路径，或明确表达以下意图时立即执行会话恢复：
- "继续之前的工作"
- "修改 XXX 的 PRD/FRD/DAR"
- "重新编辑 {workdir} 的文档"
- "在 {workdir} 基础上调整"
- 用户直接提供形如 `./项目名-20260209-1500` 的路径

### 验证会话有效性
1. 检查目录是否存在
2. 验证必备文件：`session.yaml`、`desc.md`、`summary.md`
3. 若任一缺失 → 提示损坏，建议创建新会话

### 状态回顾（自动生成报告）
读取以下文件：
- `session.yaml` → 获取文档类型、当前 Round、状态
- `summary.md` → 回顾已完成内容
- `questions/round_*.yaml` → 统计遗留问题（P0/P1/P2）
- `outputs/{doc_type}.md` → 检查章节完成度
- `session.yaml` 的 `prototype` 块 → 原型状态（如果启用）

生成**会话状态报告**并展示给用户：
```markdown
📊 会话状态报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 工作目录：{workdir}
📄 文档类型：{PRD/FRD/DAR}
📌 项目简称：{alias}
🔢 当前 Round：{current_round}
📝 已完成内容：
   - 章节 1-{N}（共 {total} 章）
   - 证据映射：{evidence_count} 条
   - Mermaid 图：{mermaid_count} 个
   - 表格：{table_count} 个

❓ 遗留问题：
   - P0（阻塞）：{p0_count} 个
   - P1（关键）：{p1_count} 个
   - P2（细节）：{p2_count} 个

🎨 原型状态：{proto_status}
   - 技术路径：{tech_stack}
   - 产出文件：{proto_outputs}

⏰ 上次更新：{last_update_time}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 询问工作模式
展示报告后，**必须询问**用户选择工作模式：

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

**B. 修改模式**（Revise）
- 开启新 Round（Round N+1），基于新需求/反馈修订
- 用户需说明修改诉求（新增章节 / 重写内容 / 调整结构）
- 重新走一轮 Plan → Do → Check → Act

**C. 局部模式**（Patch）
- 只修改特定章节/段落，不开启新 Round
- 用户明确指定修改范围（如"重写第3章"）
- 仅修改指定内容并更新证据映射，不触发完整 PDCA

**D. 原型模式**（Prototype）
- 更新/重新生成原型（独立于文档迭代）
- 执行 Proto Round 1-3 流程（见 2.6 节）
- 用户需说明原型诉求（新增页面 / 修改样式 / 重构交互）

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

### 工作模式执行

#### A. 继续模式流程
1. 读取 `rounds/round_{N}.md` 获取上次工作内容
2. 读取 `questions/round_{N}.yaml` 获取未答问题
3. 若存在 P0 问题 → 先解决 P0 再继续
4. 继续执行 PDCA：
   - Plan：检查本轮目标是否完成
   - Do：补充缺失章节/证据
   - Check：验证完整性
   - Act：更新 summary 并判断是否进入下轮

#### B. 修改模式流程
1. 创建 `rounds/round_{N+1}.md`
2. 在 `round_{N+1}.md` 头部记录修改诉求
3. 更新 `session.yaml` 中的 `current_round` 为 N+1
4. 开启新一轮 PDCA 循环：
   - Plan：分析修改影响范围，提出问题清单
   - Do：执行修改并更新证据链
   - Check：对比修改前后差异，验证一致性
   - Act：更新 decision_log.md 记录变更原因

#### C. 局部模式流程
1. **不创建新 Round**，在当前 Round 的 `round_{N}.md` 追加修改记录
2. 读取目标章节当前内容
3. 执行修改（覆盖/插入/删除）
4. 更新 `outputs/{doc_type}.md` 中的对应章节
5. 检查证据映射是否需要更新
6. 在 `decision_log.md` 追加局部修改记录
7. **不触发 Check-Act**，完成后直接返回

#### D. 原型模式流程
参见 **2.6 节 原型设计环节**，执行 Proto Round 1-3

#### E. 定稿模式流程
1. **完整性检查**：
   - 所有 P0 问题已解决
   - 每章至少 1 条证据或 `[ASSUMPTION]`
   - 至少 1 个 Mermaid 图、1 个表格
   - 章节编号/标题/目录一致
2. **证据覆盖度检查**：
   - 生成章节 vs 证据映射表
   - 标注未覆盖章节（需补充或标注假设）
3. **定稿操作**：
   - 复制 `outputs/{doc_type}.md` → `outputs/{doc_type}_final.md`
   - 在末尾追加"定稿信息"：时间、版本、审核人
   - 更新 `session.yaml` 状态为 `finalized`
   - 更新 `summary.md` 标注定稿时间
4. **交付物清单**：
   - 最终文档：`outputs/{doc_type}_final.md`
   - 原型文件（如有）：`prototypes/*`
   - 决策日志：`decision_log.md`
   - 证据索引：`materials_index.md`

### 特殊处理

#### 会话版本升级
若检测到 `session.yaml` 格式过旧（缺少 `prototype` 块），提示：
```
⚠️ 检测到旧版会话格式（v1.x），是否升级到 v2.0？
- [Y] 自动增加 prototype 配置块并创建 prototypes/ 目录
- [N] 保持原样继续（不支持原型功能）
```

#### 损坏会话恢复
若必备文件损坏或缺失：
1. 尝试从备份恢复（检查 `.backup/` 目录）
2. 若无备份，询问用户：
   - [A] 基于现有文件重建 session.yaml
   - [B] 放弃恢复，创建新会话

## 2) 初始化工作区（确认后执行）
目录结构：
```
{workdir}/
  desc.md
  session.yaml
  summary.md
  decision_log.md
  materials/
  materials_index.md
  rounds/
  questions/
  outputs/
```

必备文件：
- `desc.md`：原始需求 + WWH（What/Why/How）
- `session.yaml`：文档类型、当前轮次、状态、未决问题
- `summary.md`：每轮摘要（<=20 行）
- `decision_log.md`：关键决策与变更
- `materials_index.md`：资料索引与引用 ID

## 2.5) 资产深挖检查（强制）
- context: `context/`
- CodeMap: `assets/codemap/`
- DomainMap: `assets/domainmap/`
- RuntimeScan: `assets/runtime-scan/`

处理规则：
- 若存在：**本轮 Do 必须至少读取并引用以下层级中的每一类至少 1 个文件**：
  - 前端结构：`codemap/frontend/**/routes.yaml` / `views.yaml` / `dialog_branches.yaml`
  - 后端字段：`codemap/serve/dataobjects/java/*.yaml`
  - 后端调用链：`codemap/serve/callchains/java/domains/*.yaml`
  - 领域证据：`domainmap/*.yaml`（优先 `branch_evidence.yaml`）
- 若缺失：提示影响并询问是否补全；用户拒绝则记录 `[ASSUMPTION]` 并继续。

## 2.6) 原型设计环节（可选但推荐）

### 触发条件
- **PRD** 进入 Round 2+ 时，在 Plan 阶段询问是否需要原型
- **FRD** 包含界面/交互需求时，强制要求原型
- 用户显式要求"需要原型"、"出效果"、"做个 demo"

### 执行流程（Proto Round 1-3）

#### Proto Round 1: 收集需求
向用户提问并记录答案到 `questions/proto_requirements.yaml`：
- **PROTO-1-1 (P0)**: 原型范围？（整体流程 PoC / 核心页面 / 局部组件 / 特定效果）
- **PROTO-1-2 (P0)**: 参考来源？（URL / 截图 / 文字描述 / 从零设计）
- **PROTO-1-3 (P1)**: 保真度？（低保真 / 中保真 / 高保真）
- **PROTO-1-4 (P1)**: 技术实现？（Pencil / Web Artifact / 两者都要）

#### Proto Round 2: 实现原型
根据 Proto Round 1 的答案选择技术路径：

**路径 A: Pencil 设计稿**（适合静态视觉展示）
1. 使用 `mcp__pencil__get_style_guide_tags()` 获取设计风格标签
2. 使用 `mcp__pencil__get_style_guide(tags=[...])` 获取设计指南
3. 使用 `mcp__pencil__open_document("new")` 创建画布
4. 使用 `mcp__pencil__batch_design(operations=...)` 批量设计
5. 使用 `mcp__pencil__get_screenshot(nodeId=...)` 生成截图
6. 保存至 `prototypes/design.pen` 与 `prototypes/screenshots/`

**路径 B: Web Artifact 交互原型**（适合可点击演示）
1. 使用 `Skill(skill="document-skills:frontend-design", args="...")` 生成 React/HTML
2. 保存至 `prototypes/webapp/`
3. 可选：使用 `document-skills:webapp-testing` 验证交互

**路径 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/reference/`
2. **截图范本**：Read 读取图片 → 提取元素 → 生成
   - 用户上传到 `materials/prototypes/reference/`
   - 使用 Read 工具读取（支持图片）
   - 记录分析到 `prototypes/design_analysis.md`
3. 根据分析结果选择路径 A 或 B 实现

#### Proto Round 3: 验证迭代
- 检查原型覆盖度（所有关键场景是否有原型）
- 截图归档到 `prototypes/screenshots/`
- 生成 `prototypes/prototype_coverage.md` 对照表
- 收集用户反馈到 `questions/proto_feedback_N.yaml`
- 若需调整则返回 Proto Round 2，否则标记 `prototype.status: proto_complete`

### 证据标注规则
原型文件作为证据类型：
- 格式：`[PROTO:prototypes/screenshots/xxx.png]` 或 `[PROTO:prototypes/webapp/index.html#section]`
- 在证据映射表中关联章节与原型文件

### 目录结构扩展
```
{workdir}/
  materials/
    prototypes/           # 原型参考资料
      reference/          # 用户提供的截图/URL 快照
      analysis/           # 竞品分析、设计对标
  questions/
    proto_requirements.yaml   # 原型需求问答
    proto_feedback_N.yaml     # 原型反馈轮次
  prototypes/               # 原型产出目录
    design.pen              # Pencil 设计文件
    screenshots/            # 原型截图
    webapp/                 # Web 原型代码
    design_analysis.md      # 设计决策记录
    prototype_coverage.md   # 原型覆盖度对照表
```

## 3) 资料与证据采集（强制）
向用户索取并整理资料：
- **文件/链接/原型/截图/数据/接口文档**
- **可访问的 runtime URL**（用于 Chrome DevTools MCP）

处理规则：
1. **读取并摘要**：对每个资料做 5-10 行摘要。
2. **存档**：保存到 `materials/`，更新 `materials_index.md`。
3. **引用 ID**：为每份资料分配 `SRC-001` 形式的 ID。
4. **使用时引用**：在文档内容中标注 `[SRC-001]`。
5. **公开模板/行业规范**若被引用，也需登记为来源。

本地资产引用规则：
- context：`[CONTEXT:context/...]`
- CodeMap：`[CODEMAP:assets/codemap/...]`
- DomainMap：`[DOMAINMAP:assets/domainmap/...]`
- Runtime：`[RUNTIME:{artifact}]`
- 无证据：`[ASSUMPTION]`

## 3.5) 证据→章节映射（强制）
- 在 PRD/FRD/DAR 中维护“证据映射表”，把**章节 → 关键结论 → 证据**对应起来。
- 若章节无法绑定证据，必须显式标记 `[ASSUMPTION]`，并在 Check 阶段列入“证据缺口清单”。

## 4) PDCA 回合流程（每轮）
每轮输出到 `rounds/round_N.md`，结构固定：

### Plan
- WWH 填充度（What/Why/How）
- 本轮目标（可验证）
- 需要读取的资产与资料
- 需要提出的问题（P0/P1/P2）

### Do
- **读取**：完成“资产深挖检查”清单所需文件
- **分析**：合并证据，形成结论草稿
- **产出**：更新 `outputs/{doc}.md` 的相关章节 + 证据映射表 + 差异点清单
- **提问**：生成 `questions/round_N.yaml`

### Check
- 目标覆盖性
- 证据充足性（证据缺口清单）
- 逻辑一致性/冲突
- 样本覆盖度对比（若提供参考样本/既有文档）

### Act
- 更新 `desc.md`、`summary.md`、`decision_log.md`
- 更新 `session.yaml`
- 规划下一轮

## 5) 问题清单规则（强制）
每轮问题必须包含：
- **P0 阻塞问题**（必须回答）
- **P1 关键决策问题**
- **P2 细节确认问题**

未解决 P0 时，禁止生成下一轮完整输出，只能继续追问。

问题格式模板（questions/round_N.yaml）：
```yaml
round: 1
questions:
  - id: Q1-1
    priority: P0
    question: "..."
    options: ["...", "...", "其他"]
    status: pending
```

## 6) Runtime 证据流程（可选但优先）
- 若用户提供 URL：使用 Chrome DevTools MCP 获取截图/DOM/网络请求。
- 若用户跳过：继续，但相关结论标记 `[ASSUMPTION]`。

## 7) 输出与收敛
- 目标文档在 `outputs/` 中持续更新：`prd.md` / `frd.md` / `dar.md`。
- 收敛条件：
  - P0/P1 全部关闭
  - 证据映射表完成且无关键缺口
  - 用户确认内容可定稿

## 8) 引用与对账
文档中所有非显然事实、数据、规则、策略必须带引用。
在文档末尾追加“来源与索引”，指向 `materials_index.md` 与本地资产。
同时必须包含：
- **证据映射表**（章节 → 关键结论 → 证据）
- **系统资产引用表**（CodeMap/DomainMap/Runtime 路径与用途）

## 资源

### 脚本
- **初始化脚本**：`scripts/init_session.py`
  - 作用：创建新会话工作目录与基础文件
  - 用法：`python3 skills/pmassist/scripts/init_session.py --path <workdir> --doc prd|frd|dar --alias <简称> --title <标题> --desc <原始需求> [--enable-prototype]`
  - 原型支持：添加 `--enable-prototype` 参数自动创建原型目录结构

### 文档模板
- **PRD 模板**：`references/prd.md`
- **FRD 模板**：`references/frd.md`
- **DAR 模板**：`references/dar.md`

### 原型相关模板
- **原型需求模板**：`references/proto_requirements_template.yaml`（Proto Round 1 问题清单）
- **原型覆盖度模板**：`references/prototype_coverage_template.md`（Proto Round 3 对照表）

### 会话恢复模板
- **状态报告模板**：`references/session_status_template.md`（用于生成会话状态报告）