404 lines
16 KiB
Markdown
404 lines
16 KiB
Markdown
---
|
||
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 阶段补齐。
|
||
- **若存在 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) 资产深挖检查（强制）
|
||
- 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. **公开模板/行业规范**若被引用，也需登记为来源。
|
||
|
||
本地资产引用规则：
|
||
- 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`（用于生成会话状态报告）
|