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

2026-10-08 16:15:33 +08:00
commit e98660ce4e
284 changed files with 26838 additions and 0 deletions
@@ -0,0 +1,403 @@
+---
+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`（用于生成会话状态报告）