OA/zentao-flow

Fork 0

Files

T

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

2026-10-08 16:15:33 +08:00

20 KiB

Raw Blame History

name, description

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

name

description

pmassist-v3

产品文档协作与缺陷分析助手 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 的路径

验证会话有效性

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

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

读取以下文件并生成会话状态报告：

session.yaml → 文档类型、当前 Round、状态、FR 统计
summary.md → 已完成内容
questions/round_*.yaml → 遗留问题（P0/P1/P2）
outputs/{doc_type}.md → 章节完成度
outputs/acceptance.md → AC 完成数（如存在）

📊 会话状态报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 工作目录：{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. 继续模式

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

B. 修改模式

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

C. 局部模式

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

D. 原型模式

参见 第 2.6 节，执行 Proto Round 1-3

E. 定稿模式

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

F. AC 生成模式【v3 新增】

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

特殊处理

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

损坏会话恢复：

尝试从 .backup/ 恢复
若无备份，提供 [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 设计稿（静态视觉展示）

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 交互原型（可点击演示）

生成 HTML/React 代码，保存至 prototypes/webapp/
可选：验证交互逻辑

路径 C: 基于 URL/截图范本

URL 范本：Chrome DevTools MCP 抓取 → 分析 → 生成
截图范本：读取图片 → 提取元素 → 选路径 A/B 实现

Proto Round 3: 验证迭代

检查原型覆盖度（关键场景是否有原型）
截图归档 prototypes/screenshots/
生成 prototypes/prototype_coverage.md 对照表
收集用户反馈到 questions/proto_feedback_N.yaml

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

向用户索取并整理：

文件/链接/原型/截图/数据/接口文档
可访问的 runtime URL（用于 Chrome DevTools MCP）

处理规则：

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

本地资产引用规则：

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 记录格式

- 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 记录格式

## 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）：

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 应：

直接消化已给出的答案，不重复追问已明确的信息
只提问真正不确定的 P0/P1 问题
若用户明确说"跳过原型"/"暂不需要 AC"，记录到 session.yaml 的 skip_flags 并继续

跳过标记格式：

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 涉及新表或字段变更时，推荐在文档中包含数据模型规格：

新建表规范

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='{表注释}';

字段变更规范

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

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

10) 变更管理【v3 新增】

变更登记

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

| 时间 | 变更编号 | 事项 | 变更内容 | 影响 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

20 KiB Raw Blame History Unescape Escape

pmassist-v3

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

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

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

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

0.1) 触发示例

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

1.5) 会话恢复（Resume Session）

触发条件

验证会话有效性

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

询问工作模式

工作模式执行

A. 继续模式

B. 修改模式

C. 局部模式

D. 原型模式

E. 定稿模式

F. AC 生成模式【v3 新增】

特殊处理

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

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

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

触发条件

执行流程（Proto Round 1-3）

Proto Round 1: 收集需求

Proto Round 2: 实现原型

Proto Round 3: 验证迭代

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

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

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

FR 编号规则

FR 记录格式

FR 管理要求

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

AC 编号规则

AC 记录格式

AC 管理要求

4) PDCA 回合流程（每轮）

Plan

Do

Check

Act

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

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

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

7) 输出与收敛

8) 引用与对账

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

新建表规范

字段变更规范

10) 变更管理【v3 新增】

变更登记

版本标记

资源

脚本

文档模板

验收与原型模板

会话恢复模板

20 KiB

Raw Blame History