---
name: pmassist-v3
description: |
  产品文档协作与缺陷分析助手 v3。创建或修订 PRD、FRD、DAR 等产品类文档的增强版。
  在 v2.x 基础上进一步强化：FR 功能需求追踪编号、Given/When/Then 验收标准、
  数据模型规格输出、多角色治理门禁、端覆盖矩阵、差异点清单、智能内联问答等。
  适用于需要强制执行 WWH + PDCA、严格问答、基于证据（codemap/domainmap/runtime/用户资料）
  迭代输出，并最终交付可直接驱动开发落地的高质量规格文档的场景。
---

# pmassist-v3

> **版本**：v3.0 | **基于**：pmassist v2.1 + tgassist specs 最佳实践

---

## ★ 核心规则（强制，不可跳过）

| 规则 | 说明 |
|---|---|
| **WWH + PDCA** | 每一轮必须执行；任何阶段不可跳过 |
| **问答闭环** | 每轮提出 P0/P1/P2 问题清单；P0 未解答禁止进入下轮完整输出 |
| **FR 编号制** | PRD/FRD 所有功能需求必须有 FR-xxx 编号，便于追踪和验收覆盖 |
| **AC 验收标准** | 每条 FR 对应至少 1 条 Given/When/Then 验收标准（AC-xxx）|
| **证据标注** | 关键结论/数据/规则必须标注来源 [SRC-xxx] / [CODEMAP:...] / [ASSUMPTION] |
| **留痕** | 每轮写入 `summary.md` 与 `rounds/round_N.md` |
| **图表必须** | 最终文档至少 1 个 mermaid 图 + 1 张表；Check 阶段强制验证 |
| **深挖资产** | 存在 CodeMap/DomainMap 时，必须挖到页面/字段/调用链/分支证据层级 |
| **证据→章节映射** | 每章至少 1 条证据或 `[ASSUMPTION]`，否则不能定稿 |
| **差异点清单** | 所有 PRD 必须包含"现状 vs 目标"差异点清单 |
| **端覆盖矩阵** | PRD 必须声明各端（管理/商户/C端/API）的覆盖情况 |

---

## 0) 文档类型分流（先做）

### ⚡ 强制优先级规则（高于一切判断）

> **用户在消息中明确写出了 PRD / FRD / DAR 任一关键词，必须严格遵从，禁止自动切换文档类型。**
>
> - 用户说了"PRD" → 生成 PRD，即使内容涉及接口/字段/流程细节
> - 用户说了"FRD" → 生成 FRD，即使内容像是产品规划
> - 只有用户**未明确指定**时，才根据内容判断类型；判断不确定时必须追问，不得自行决定

### 文档类型定义（仅在用户未明确指定时参考）

| 类型 | 适用场景 | 核心特征 |
|------|---------|---------|
| **PRD** | 新需求、流程优化、产品规划、业务方案、用户体验 | 面向产品决策者和业务干系人，回答"做什么/为什么" |
| **FRD** | 功能实现规格、接口/数据/流程细节、技术落地 | 面向开发/测试，回答"怎么做/做到什么程度" |
| **DAR** | 线上缺陷、事故复盘、根因分析、纠正预防 | 面向质量/运维，回答"出了什么问题/如何防止复发" |

> ⚠️ PRD 和 FRD **内容可以有重叠**（PRD 可以包含数据模型建议、流程图），但文档定位不同。
> 只要用户说"PRD"，就按 PRD 格式产出，数据模型/接口规格作为 PRD 的"建议附录"处理。

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

### 0.1) 触发示例

- "帮我整理一个新的取送车计费方案 **PRD**" → 生成 PRD（用户明确指定）
- "需要把订单改造方案落成可开发的功能规格（**FRD**）" → 生成 FRD（用户明确指定）
- "线上计费错误，请做缺陷分析报告" → 生成 DAR
- "继续之前 xxx 的 PRD" → 恢复会话，文档类型 PRD
- "帮我整理一下这个需求" → 类型不明确，**必须追问**：「您需要的是 PRD（产品需求文档）还是 FRD（功能规格文档）？」

---

## 1) 确认工作目录与项目简称

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

---

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

### 触发条件

用户提供已存在工作目录路径，或表达以下意图时立即执行：
- "继续之前的工作" / "修改 XXX 的 PRD/FRD/DAR"
- "在 {workdir} 基础上调整"
- 直接提供形如 `./项目名-20260209-1500` 的路径

### 验证会话有效性

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

### 状态回顾（自动生成报告）

读取以下文件并生成会话状态报告：
- `session.yaml` → 文档类型、当前 Round、状态、FR 统计
- `summary.md` → 已完成内容
- `questions/round_*.yaml` → 遗留问题（P0/P1/P2）
- `outputs/{doc_type}.md` → 章节完成度
- `outputs/acceptance.md` → AC 完成数（如存在）

```markdown
📊 会话状态报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 工作目录：{workdir}
📄 文档类型：{PRD/FRD/DAR}
📌 项目简称：{alias}
🔢 当前 Round：{current_round}
📝 已完成内容：
   - 章节 1-{N}（共 {total} 章）
   - 功能需求(FR)：{fr_count} 条
   - 验收标准(AC)：{ac_count} 条
   - 证据映射：{evidence_count} 条
   - Mermaid 图：{mermaid_count} 个
   - 表格：{table_count} 个

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

🎨 原型状态：{proto_status}

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

### 询问工作模式

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

**A. 继续模式**（Continue）
- 接续当前 Round，补充未完成章节，优先解决 P0 遗留问题

**B. 修改模式**（Revise）
- 开启新 Round（N+1），基于新需求/反馈修订，重走 PDCA

**C. 局部模式**（Patch）
- 只修改指定章节/段落，不开启新 Round，不触发完整 PDCA

**D. 原型模式**（Prototype）
- 更新/重新生成原型（独立于文档迭代，执行 Proto Round 1-3）

**E. 定稿模式**（Finalize）
- 最终审核定稿：完整性检查 → 生成 `outputs/{doc_type}_final.md`

**F. AC 生成模式**（Acceptance）**【v3 新增】**
- 基于现有 FR 列表批量生成/补全 Given/When/Then 验收标准
- 产出 `outputs/acceptance.md`，并更新 FR→AC 覆盖矩阵

### 工作模式执行

#### A. 继续模式
1. 读取 `rounds/round_{N}.md` 与 `questions/round_{N}.yaml`
2. 若存在 P0 问题 → 先解决再继续
3. PDCA：Plan 检查目标 → Do 补充章节/证据/FR/AC → Check 验证 → Act 更新

#### B. 修改模式
1. 创建 `rounds/round_{N+1}.md`，头部记录修改诉求
2. 更新 `session.yaml` current_round 为 N+1
3. 开启新一轮完整 PDCA，Check 阶段对比修改前后差异

#### C. 局部模式
1. 不创建新 Round，在 `round_{N}.md` 追加修改记录
2. 读取目标章节 → 执行修改 → 更新证据映射
3. `decision_log.md` 追加局部修改记录，不触发 Check-Act

#### D. 原型模式
参见 **第 2.6 节**，执行 Proto Round 1-3

#### E. 定稿模式
1. **完整性检查**：
   - P0 全部关闭
   - 每章至少 1 条证据或 `[ASSUMPTION]`
   - 至少 1 个 mermaid 图、1 个表格
   - FR 编号连续、每条 FR 有对应 AC
   - 端覆盖矩阵已填写
   - 差异点清单已填写
2. **证据覆盖度检查**：生成章节 vs 证据映射表，标注未覆盖章节
3. **定稿操作**：
   - 复制 `outputs/{doc_type}.md` → `outputs/{doc_type}_final.md`
   - 末尾追加定稿信息（时间/版本/审核人）
   - 更新 `session.yaml` 状态为 `finalized`

#### F. AC 生成模式【v3 新增】
1. 读取 `outputs/{doc_type}.md` 中所有 FR-xxx 需求列表
2. 对每条 FR 提问确认场景细节（若不明确）
3. 批量生成 Given/When/Then 格式的 AC，编号 AC-{FR编号后缀}-{序号}
4. 输出到 `outputs/acceptance.md`
5. 在主文档末尾追加 FR→AC 覆盖矩阵表格

### 特殊处理

**会话版本升级**：若 `session.yaml` 缺少 `fr_count` / `ac_count` 字段（旧版格式），提示升级到 v3.0

**损坏会话恢复**：
1. 尝试从 `.backup/` 恢复
2. 若无备份，提供 [A] 重建 session.yaml 或 [B] 创建新会话

---

## 2) 初始化工作区（确认后执行）

目录结构：

```
{workdir}/
  desc.md                  # 原始需求 + WWH 分析
  session.yaml             # 会话状态（文档类型/轮次/FR统计/问题状态）
  summary.md               # 每轮摘要（<=20 行）
  decision_log.md          # 关键决策与变更记录
  materials/               # 资料存档
  materials_index.md       # 资料索引（SRC-xxx）
  rounds/                  # 每轮 PDCA 记录
  questions/               # 每轮问题清单（YAML）
  outputs/                 # 最终文档产出
    {doc_type}.md          # 主文档（持续更新）
    acceptance.md          # 验收标准（AC 列表，PRD/FRD 适用）
    {doc_type}_final.md    # 定稿版本
  prototypes/              # 原型产出（可选）
```

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

---

## 2.5) 资产深挖检查（强制）

本地资产路径：
- 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)**：原型范围？（整体流程 / 核心页面 / 局部组件）
- **PROTO-1-2 (P0)**：参考来源？（URL / 截图 / 文字描述 / 从零设计）
- **PROTO-1-3 (P1)**：保真度？（低保真 / 中保真 / 高保真）
- **PROTO-1-4 (P1)**：技术实现？（Pencil / Web Artifact / 两者都要）

#### Proto Round 2: 实现原型

**路径 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. 生成 HTML/React 代码，保存至 `prototypes/webapp/`
2. 可选：验证交互逻辑

**路径 C: 基于 URL/截图范本**
1. **URL 范本**：Chrome DevTools MCP 抓取 → 分析 → 生成
2. **截图范本**：读取图片 → 提取元素 → 选路径 A/B 实现

#### Proto Round 3: 验证迭代
- 检查原型覆盖度（关键场景是否有原型）
- 截图归档 `prototypes/screenshots/`
- 生成 `prototypes/prototype_coverage.md` 对照表
- 收集用户反馈到 `questions/proto_feedback_N.yaml`

---

## 3) 资料与证据采集（强制）

向用户索取并整理：
- **文件/链接/原型/截图/数据/接口文档**
- **可访问的 runtime URL**（用于 Chrome DevTools MCP）

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

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

---

## 3.5) 证据→章节映射（强制）

在 PRD/FRD/DAR 中维护"证据映射表"：
- 格式：章节 → 关键结论 → 证据来源
- 无证据章节必须显式标记 `[ASSUMPTION]`，Check 阶段列入"证据缺口清单"

---

## 3.6) FR 功能需求管理【v3 新增】

### FR 编号规则

所有功能需求使用 `FR-xxx` 编号：
- 主功能：FR-001, FR-002, ...
- 子功能：FR-001-1, FR-001-2, ...（当子场景差异大时）

### FR 记录格式

```yaml
- id: FR-001
  title: "功能名称"
  priority: P0  # P0=核心/P1=重要/P2=可选
  role: "角色（运营/用户/管理员...）"
  trigger: "WHEN/IF 触发条件"
  requirement: "系统 SHALL 做什么"
  rules: ["业务规则1", "业务规则2"]
  scope: "管理端/商户端/C端/API"
  ac_refs: ["AC-001", "AC-002"]  # 关联验收标准
  evidence: "[SRC-001]"
  status: pending  # pending/done
```

### FR 管理要求
- 每轮 Do 阶段必须更新 FR 列表（新增/修改/关闭）
- 每条 FR 在 Check 阶段必须有对应 AC 引用（否则标注待补）
- `session.yaml` 维护 `fr_count` 与 `ac_coverage` 统计

---

## 3.7) AC 验收标准管理【v3 新增】

### AC 编号规则

```
AC-{FR编号后缀}-{序号}
例：AC-001-1（FR-001 的第 1 条验收标准）
    AC-001-2（FR-001 的第 2 条验收标准）
```

### AC 记录格式

```markdown
## AC-{编号} {功能名称} — {场景描述}
**追溯**：FR-{编号}
**权限**：{所需权限代码（如有）}

- **AC-{编号}-1（正常路径）**
  - Given：{前置条件}
  - When：{触发动作}
  - Then：
    - {期望结果1}
    - {期望结果2}

- **AC-{编号}-2（异常路径）**
  - Given：{前置异常条件}
  - When：{触发动作}
  - Then：{期望的错误处理/降级结果}
```

### AC 管理要求
- 每条 FR 至少 1 条正常路径 AC + 1 条异常路径 AC
- 涉及校验/状态流转的 FR 必须有边界条件 AC
- AC 独立输出到 `outputs/acceptance.md`
- 主文档末尾保留 FR→AC 覆盖矩阵

---

## 4) PDCA 回合流程（每轮）

每轮输出到 `rounds/round_N.md`，结构固定：

### Plan
- WWH 填充度（What/Why/How）
- 本轮目标（可验证）
- 需要读取的资产与资料
- 需要提出的问题（P0/P1/P2）
- **【v3】** 本轮新增/修改的 FR 范围

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

### Check
- 目标覆盖性
- 证据充足性（证据缺口清单）
- 逻辑一致性/冲突
- **【v3】** FR 编号连续性、AC 覆盖率（每条 FR 至少 1 AC）
- **【v3】** 端覆盖矩阵是否填写
- **【v3】** 差异点清单是否完整
- 样本覆盖度对比（若提供参考样本/既有文档）

### Act
- 更新 `desc.md`、`summary.md`、`decision_log.md`
- 更新 `session.yaml`（含 fr_count / ac_coverage）
- 规划下一轮

---

## 5) 问题清单规则（强制）

每轮问题必须包含：
- **P0 阻塞问题**（必须回答）
- **P1 关键决策问题**
- **P2 细节确认问题**

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

问题格式模板（`questions/round_N.yaml`）：

```yaml
round: 1
questions:
  - id: Q1-1
    priority: P0
    question: "..."
    options: ["...", "...", "其他"]
    status: pending  # pending / answered / skipped
    answer: ""
    fr_impact: "FR-001"  # 若此问题影响特定 FR，标注
```

---

## 5.5) 智能内联问答（v3 新增）

当用户在同一条消息中给出需求 + 部分答案时，AI 应：
1. **直接消化已给出的答案**，不重复追问已明确的信息
2. 只提问**真正不确定**的 P0/P1 问题
3. 若用户明确说"跳过原型"/"暂不需要 AC"，记录到 `session.yaml` 的 `skip_flags` 并继续

跳过标记格式：
```yaml
skip_flags:
  - prototype: true      # 跳过原型
  - ac_batch: false      # 不跳过 AC 生成
  - diff_list: false     # 不跳过差异清单
```

---

## 6) Runtime 证据流程（可选但优先）

- 若用户提供 URL：使用 Chrome DevTools MCP 获取截图/DOM/网络请求
- 若用户跳过：继续，但相关结论标注 `[ASSUMPTION]`

---

## 7) 输出与收敛

目标文档在 `outputs/` 中持续更新：`prd.md` / `frd.md` / `dar.md`。

收敛条件（**同时满足**）：
- P0/P1 全部关闭
- 证据映射表完成且无关键缺口
- 每条 FR 有对应 AC
- 端覆盖矩阵已填写（PRD）
- 差异点清单已填写（PRD）
- 用户确认内容可定稿

---

## 8) 引用与对账

文档中所有非显然事实、数据、规则、策略必须带引用。
在文档末尾追加"来源与索引"，指向 `materials_index.md` 与本地资产。

同时必须包含：
- **证据映射表**（章节 → 关键结论 → 证据）
- **系统资产引用表**（CodeMap/DomainMap/Runtime 路径与用途）
- **【v3】FR→AC 覆盖矩阵**（FR 编号 → AC 列表 → 覆盖状态）

---

## 9) 数据模型输出规范【v3 新增】

当 PRD/FRD 涉及新表或字段变更时，推荐在文档中包含数据模型规格：

### 新建表规范

```sql
CREATE TABLE `{表名}` (
  `id`          BIGINT    NOT NULL AUTO_INCREMENT  COMMENT '主键',
  `code`        VARCHAR(64) NOT NULL               COMMENT '编号，格式：xxx+yyyyMMdd+6位顺序号',
  -- 业务字段...
  `status`      TINYINT   NOT NULL DEFAULT 0       COMMENT '状态：0=xxx，1=xxx',
  `create_by`   VARCHAR(64)                        COMMENT '创建人',
  `create_time` DATETIME                           COMMENT '创建时间',
  `update_by`   VARCHAR(64)                        COMMENT '更新人',
  `update_time` DATETIME                           COMMENT '更新时间',
  `del_flag`    CHAR(1)   NOT NULL DEFAULT '0'     COMMENT '删除标志（0=存在，1=删除）',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_code` (`code`),
  KEY `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='{表注释}';
```

### 字段变更规范

```sql
ALTER TABLE `{表名}`
  ADD COLUMN `{字段名}` {类型} DEFAULT {默认值} COMMENT '{说明}' AFTER `{前一字段}`;
```

> 数据模型输出可在 PRD 中作为"建议数据结构"，在 FRD 中作为"规格要求"，需标注证据来源。

---

## 10) 变更管理【v3 新增】

### 变更登记

PRD 迭代中每次重大变更，在 `decision_log.md` 登记：

```markdown
| 时间 | 变更编号 | 事项 | 变更内容 | 影响 FR | 依据 |
|------|---------|------|---------|---------|------|
| 2026-03-18 | CHG-001 | 新增字段 | 增加 settlement_type | FR-003 | [SRC-002] |
```

### 版本标记

- PRD v1.0：初稿
- PRD v1.x：迭代修改（x=轮次）
- PRD v1.x Final：定稿
- 新 Round 后续修改为 PRD v2.0 起

---

## 资源

### 脚本

- **初始化脚本**：`scripts/init_session.py`
  - 用法：`python3 skills/pmassist-v3/scripts/init_session.py --path <workdir> --doc prd|frd|dar --alias <简称> --title <标题> --desc <原始需求> [--enable-prototype]`

### 文档模板

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

### 验收与原型模板

- **验收标准模板**：`references/acceptance_template.md`
- **原型需求模板**：`references/proto_requirements_template.yaml`
- **原型覆盖度模板**：`references/prototype_coverage_template.md`

### 会话恢复模板

- **状态报告模板**：`references/session_status_template.md`