16 KiB
16 KiB
name, description
| name | description |
|---|---|
| pmassist | 产品文档协作与缺陷分析助手。用于创建或修订 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的路径
验证会话有效性
- 检查目录是否存在
- 验证必备文件：
session.yaml、desc.md、summary.md - 若任一缺失 → 提示损坏，建议创建新会话
状态回顾（自动生成报告）
读取以下文件：
session.yaml→ 获取文档类型、当前 Round、状态summary.md→ 回顾已完成内容questions/round_*.yaml→ 统计遗留问题（P0/P1/P2）outputs/{doc_type}.md→ 检查章节完成度session.yaml的prototype块 → 原型状态（如果启用）
生成会话状态报告并展示给用户：
📊 会话状态报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 工作目录：{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. 继续模式流程
- 读取
rounds/round_{N}.md获取上次工作内容 - 读取
questions/round_{N}.yaml获取未答问题 - 若存在 P0 问题 → 先解决 P0 再继续
- 继续执行 PDCA：
- Plan：检查本轮目标是否完成
- Do：补充缺失章节/证据
- Check：验证完整性
- Act：更新 summary 并判断是否进入下轮
B. 修改模式流程
- 创建
rounds/round_{N+1}.md - 在
round_{N+1}.md头部记录修改诉求 - 更新
session.yaml中的current_round为 N+1 - 开启新一轮 PDCA 循环：
- Plan：分析修改影响范围，提出问题清单
- Do：执行修改并更新证据链
- Check：对比修改前后差异，验证一致性
- Act：更新 decision_log.md 记录变更原因
C. 局部模式流程
- 不创建新 Round，在当前 Round 的
round_{N}.md追加修改记录 - 读取目标章节当前内容
- 执行修改（覆盖/插入/删除）
- 更新
outputs/{doc_type}.md中的对应章节 - 检查证据映射是否需要更新
- 在
decision_log.md追加局部修改记录 - 不触发 Check-Act，完成后直接返回
D. 原型模式流程
参见 2.6 节 原型设计环节，执行 Proto Round 1-3
E. 定稿模式流程
- 完整性检查：
- 所有 P0 问题已解决
- 每章至少 1 条证据或
[ASSUMPTION] - 至少 1 个 Mermaid 图、1 个表格
- 章节编号/标题/目录一致
- 证据覆盖度检查：
- 生成章节 vs 证据映射表
- 标注未覆盖章节（需补充或标注假设）
- 定稿操作：
- 复制
outputs/{doc_type}.md→outputs/{doc_type}_final.md - 在末尾追加"定稿信息"：时间、版本、审核人
- 更新
session.yaml状态为finalized - 更新
summary.md标注定稿时间
- 复制
- 交付物清单：
- 最终文档：
outputs/{doc_type}_final.md - 原型文件（如有）：
prototypes/* - 决策日志：
decision_log.md - 证据索引：
materials_index.md
- 最终文档：
特殊处理
会话版本升级
若检测到 session.yaml 格式过旧（缺少 prototype 块），提示：
⚠️ 检测到旧版会话格式（v1.x），是否升级到 v2.0？
- [Y] 自动增加 prototype 配置块并创建 prototypes/ 目录
- [N] 保持原样继续（不支持原型功能）
损坏会话恢复
若必备文件损坏或缺失：
- 尝试从备份恢复（检查
.backup/目录） - 若无备份，询问用户：
- [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 设计稿（适合静态视觉展示）
- 使用
mcp__pencil__get_style_guide_tags()获取设计风格标签 - 使用
mcp__pencil__get_style_guide(tags=[...])获取设计指南 - 使用
mcp__pencil__open_document("new")创建画布 - 使用
mcp__pencil__batch_design(operations=...)批量设计 - 使用
mcp__pencil__get_screenshot(nodeId=...)生成截图 - 保存至
prototypes/design.pen与prototypes/screenshots/
路径 B: Web Artifact 交互原型（适合可点击演示）
- 使用
Skill(skill="document-skills:frontend-design", args="...")生成 React/HTML - 保存至
prototypes/webapp/ - 可选：使用
document-skills:webapp-testing验证交互
路径 C: 基于 URL/截图范本
- 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/
- 截图范本：Read 读取图片 → 提取元素 → 生成
- 用户上传到
materials/prototypes/reference/ - 使用 Read 工具读取（支持图片）
- 记录分析到
prototypes/design_analysis.md
- 用户上传到
- 根据分析结果选择路径 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）
处理规则：
- 读取并摘要：对每个资料做 5-10 行摘要。
- 存档：保存到
materials/，更新materials_index.md。 - 引用 ID：为每份资料分配
SRC-001形式的 ID。 - 使用时引用：在文档内容中标注
[SRC-001]。 - 公开模板/行业规范若被引用，也需登记为来源。
本地资产引用规则：
- 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）：
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（用于生成会话状态报告）