@prd-improve/cli 1.0.0 → 1.1.1

package/dist/skill/prd-improve-forge/templates/prd.yaml

@@ -0,0 +1,287 @@
+# =============================================================================
+# PRD 工作稿模板 (prd.yaml)
+# -----------------------------------------------------------------------------
+# 一个功能 = 一份 prd.yaml。这份文件是结构化的真相源 (source of truth)。
+# spec.md 和 context.md 由 CLI 从此文件自动 render，不要手写那两份。
+#
+# 约定：
+#   - 顶层 key 使用英文（方便 CLI / schema / 后端统一）
+#   - value 用中文（方便 PM、开发、测试阅读）
+#   - 每个 key 都有中文注释说明它的配置目的
+#   - 注释删留规则：
+#       保留：模块头部 `# === section | 用途 ===` 分隔块、字段右侧 `-- 中文名` 标签、
+#             以及给读者做向导的 # 自然语言说明
+#       可删：完成填写后的 `[必填] / [选填] / [PM 填] / [CLI 管] / [机器读]` 任务标记注释
+#             （这些是给写作者看的脚手架，定稿后已无信息量）
+#
+# 字段标记约定：
+#   [必填] / [选填]       字段在冻结前是否必须有值；CLI 校验按此判定能否 freeze
+#   [PM 填] / [CLI 管]    谁负责写入该字段
+#                           - [PM 填]：PM 或 Skill 引导 AI 手动填写
+#                           - [CLI 管]：由 CLI / 后端自动维护，PM 不要手改
+#   [机器读]              该字段会被 CLI / 后端按严格结构消费，格式务必规范
+#                           - 无此标记的字段主要给人读，允许自然语言
+#
+# ID 前缀约定（互不冲突，用于稳定引用）：
+#   EN-*   （实体）
+#   S-*    （范围项）
+#   R-*    （业务规则）
+#   SC-*   （场景）
+#   E-*    （异常/边界）
+#   UI-*   （页面）
+#   AC-*   （验收标准）
+#   Q-*    （待确认问题）
+#   DC-*   （数据约束）
+#   API-*  （接口约束）
+#   PC-*   （性能约束）
+#   SEC-*  （安全约束）
+#
+# 路径约定：
+#   .prd/features/<feature-slug>/working/prd.yaml           <- 工作稿（本文件）
+#   .prd/features/<feature-slug>/frozen/<version>/prd.yaml  <- 冻结版
+# =============================================================================
+
+
+# 本模板自身的 schema 版本号（不是 PRD 内容版本）
+schema_version: "v0.2"        # [必填][CLI 管][机器读] 骨架升级时 CLI 据此决定迁移策略；PM 不要手改
+
+
+# =============================================================================
+# meta | 元信息
+# -----------------------------------------------------------------------------
+# 用途：记录 PRD 的身份、负责人、来源材料，以及 CLI 管理的生命周期字段。
+# 结构：业务标识（PM 填）+ lifecycle 子块（CLI 管）两部分明确分开。
+# =============================================================================
+meta:
+  # --- 业务标识（由 PM 填写）---
+  team: ""                    # [必填][PM 填][机器读] 所属团队 slug（kebab-case，如 prd-improve）；team → project → feature 三层归类的顶层
+  project: ""                 # [必填][PM 填][机器读] 所属项目 slug，对应后端 project 模型；同一 workspace 下的多个 feature 会共用 project
+  feature: ""                 # [必填][PM 填][机器读] 功能 slug，小写连字符格式，必须与 .prd/features/<slug>/ 目录同名，如 import-history-prds
+  title: ""                   # [必填][PM 填] 功能的完整中文名称，展示给人看，如"批量导入历史 PRD 文件"
+  summary: ""                 # [必填][PM 填][机器读] 一句话功能概要（建议 ≤ 50 字）。给机器读：会被 CLI 写入 context.md 首行、作为搜索索引。与 background 区分：background 给人读的详细版，summary 给机器读的极短版
+  owner: ""                   # [必填][PM 填] 该功能的 PM 负责人（姓名或邮箱）
+  tags: []                    # [选填][PM 填][机器读] 标签列表，用于 CLI 搜索过滤，如 ["import", "migration"]
+  created_at: ""              # [必填][PM 填] PRD 首次建立日期，格式 YYYY-MM-DD
+  source_materials:           # [选填][PM 填] 原始材料列表，对齐后端 source_material 模型；填写时每个条目都是一个对象
+    - type: ""                #   来源类型：meeting_notes（会议纪要）/ chat（聊天摘录）/ old_prd（旧 PRD）/ ai_dialog（AI 对话）/ wiki / other
+      title: ""               #   材料标题
+      url: ""                 #   URL 或本地路径（可留空）
+      excerpt: ""             #   关键摘录文本（可留空）
+      captured_at: ""         #   采集日期 YYYY-MM-DD（可留空）
+
+  # --- 生命周期（由 CLI 管理，PM 不要手改）---
+  lifecycle:
+    version: "working"        # [必填][CLI 管][机器读] working 代表工作稿；冻结后由 `prd freeze` 写入 v1.0 / v1.1 等
+    status: "draft"           # [必填][CLI 管][机器读] draft（起草）/ in_review（评审中）/ frozen（已冻结），由 CLI 和 Web 工作台流转
+    updated_at: ""            # [必填][CLI 管][机器读] 最后修改日期 YYYY-MM-DD，CLI 每次写操作自动刷新
+
+
+# =============================================================================
+# background_and_goals | 背景与目标
+# -----------------------------------------------------------------------------
+# 用途：回答"为什么要做"和"本期要达到什么可衡量的效果"。
+# 所有后续取舍（范围裁剪、不做项、优先级）都以本节为依据。
+# 注：本期"不做"的事项统一归档到顶层 out_of_scope，本节不重复列出。
+# =============================================================================
+background_and_goals:
+  background: ""              # [必填][PM 填] 给人读：当前痛点、业务场景、触发本次需求的事件；说清"不做会怎样"
+  goals:                      # [必填][PM 填] 本期要达到的具体目标，可衡量优先，按优先级排序
+    - ""                      # 例："让 PM 能把 Notion 上的旧 PRD 一次性迁移到 .prd/ 目录，单次支持 ≥ 50 个文件"
+
+
+# =============================================================================
+# users_and_roles | 用户与角色
+# -----------------------------------------------------------------------------
+# 用途：列出所有会和本功能交互的角色，以及他们的使用目的。
+# state_permissions、ui_interaction 等会引用这里的 role 名，命名要稳定。
+# =============================================================================
+users_and_roles:
+  - role: ""                  # [必填][PM 填][机器读] 角色名，简短稳定，如"产品经理"、"系统管理员"
+    description: ""           # [必填][PM 填] 这个角色是谁、在组织里的位置、和本功能的关系
+    typical_goals:            # [必填][PM 填] 他们使用该功能想达成的目标，至少 1 条
+      - ""
+
+
+# =============================================================================
+# in_scope | 本期范围
+# -----------------------------------------------------------------------------
+# 用途：本期承诺要做的事情清单。每项要能独立被验收。
+# 每项有 ID，在 scenarios / business_rules / acceptance_criteria 中引用。
+# =============================================================================
+in_scope:
+  - id: "S-1"                 # -- 范围项。[必填][PM 填][机器读] 编号 S-1 / S-2 / ... 递增，一旦分配不要复用
+    name: ""                  # [必填][PM 填] 短名称
+    summary: ""               # [必填][PM 填] 一段话说清楚"做到什么程度算这一项完成"
+
+
+# =============================================================================
+# out_of_scope | 明确不做
+# -----------------------------------------------------------------------------
+# 用途：本期明确不做的事项 + 不做的原因。
+# 本节是"本期不做什么"的唯一归档，其他模块不要重复声明。
+# =============================================================================
+out_of_scope:
+  - item: ""                  # [必填][PM 填] 明确不做的事项（可以是功能、效果、兼容场景等）
+    reason: ""                # [必填][PM 填] 为什么本期不做：时间 / 优先级 / 风险 / 后续迭代再做 / 不属于本期目标
+
+
+# =============================================================================
+# entities | 核心实体
+# -----------------------------------------------------------------------------
+# 用途：列出本功能涉及的关键数据对象。不是数据库建表，是业务级描述。
+# 每个实体有 ID，state_permissions 等通过 ID 引用（改名不断链）。
+# =============================================================================
+entities:
+  - id: "EN-1"                # -- 实体。[必填][PM 填][机器读] 编号 EN-1 / EN-2 / ... 递增
+    name: ""                  # [必填][PM 填] 实体名，如"导入任务"、"导入记录"
+    description: ""           # [必填][PM 填] 一段话说明这个实体在业务中代表什么
+    fields:                   # [必填][PM 填] 主要业务字段，至少列关键识别字段和状态字段
+      - name: ""              #   字段名
+        type: ""              #   类型：string | int | enum | datetime | reference<实体名> 等
+        required: true        #   是否必填
+        notes: ""             #   约束、枚举值、默认值、业务含义
+    relations: []             # [选填][PM 填] 与其他实体的关系，如"一个任务包含多个文件记录"
+    lifecycle_states: []      # [选填][PM 填][机器读] 该实体可能经历的状态名列表。具体状态由功能决定：如导入任务 pending/running/succeeded/failed；如审批单 draft/submitted/approved/rejected
+
+
+# =============================================================================
+# main_flow | 主流程
+# -----------------------------------------------------------------------------
+# 用途：描述"正常路径"下，用户和系统如何配合完成一次任务。
+# 异常、降级、失败恢复放到 edge_cases，不要堆在这里。
+# =============================================================================
+main_flow:
+  - step: 1                   # [必填][PM 填][机器读] 步骤编号，从 1 开始递增
+    actor: ""                 # [必填][PM 填] 该步骤的执行者：角色名 / "系统" / "后台任务"
+    trigger: ""               # [必填][PM 填] 触发这一步的事件（用户点击、上一步完成、定时任务等）
+    action: ""                # [必填][PM 填] 发生了什么操作
+    outcome: ""               # [必填][PM 填] 结束时的状态或产出
+
+
+# =============================================================================
+# state_permissions | 状态与操作权限
+# -----------------------------------------------------------------------------
+# 用途：每个实体在每个状态下，允许哪些角色做哪些操作。
+# 是 entities.lifecycle_states × users_and_roles.role 的交叉矩阵。
+# =============================================================================
+state_permissions:
+  - entity_id: "EN-1"         # -- 实体外键。[必填][PM 填][机器读] 引用 EN-*（实体）的 ID，改名不断链
+    state: ""                 # [必填][PM 填][机器读] 状态名，需在对应实体的 lifecycle_states 列表中出现
+    allowed_actions:          # [必填][PM 填] 该状态下允许的操作列表
+      - action: ""            #   操作名，如"取消任务"、"追加文件"、"查看详情"
+        roles: []             #   哪些角色可执行，值来自 users_and_roles[].role
+        notes: ""             #   额外限制条件（如仅自己创建的任务、需要二次确认等）
+
+
+# =============================================================================
+# business_rules | 业务规则
+# -----------------------------------------------------------------------------
+# 用途：必须遵守的业务约束、判定逻辑、计算方法。
+# 每条有 ID，便于在 scenarios 和 acceptance_criteria 中引用。
+# =============================================================================
+business_rules:
+  - id: "R-1"                 # -- 业务规则。[必填][PM 填][机器读] 编号 R-1 / R-2 / ... 递增
+    rule: ""                  # [必填][PM 填] 规则内容，陈述性、可判断真假
+    rationale: ""             # [选填][PM 填] 为什么要这么规定（业务原因、合规要求、历史教训）。鼓励填；填不出来可能说明规则没想清楚
+    applies_to: []            # -- 作用对象。[选填][PM 填][机器读] 作用于 EN-*（实体）或 S-*（范围项）的 ID 列表
+
+
+# =============================================================================
+# scenarios | 场景矩阵
+# -----------------------------------------------------------------------------
+# 用途：穷举"在 X 条件下系统应该怎样"。正常和常见变体都放这里。
+# 极端异常放 edge_cases。目标是让测试能从这里直接提取用例。
+# =============================================================================
+scenarios:
+  - id: "SC-1"                # -- 场景。[必填][PM 填][机器读] 编号 SC-1 / SC-2 / ... 递增
+    condition: ""             # [必填][PM 填] 前置条件 / 输入组合（简洁自然语言）
+    expected_behavior: ""     # [必填][PM 填] 系统应该如何响应
+    input: ""                 # [选填][PM 填] 具体输入样例（JSON / 文本 / 操作步骤）
+    output: ""                # [选填][PM 填] 期望输出样例
+    refers_to: []             # -- 引用对象。[选填][PM 填][机器读] 对应 S-*（范围项）/ R-*（业务规则）/ E-*（异常）的 ID 列表
+
+
+# =============================================================================
+# edge_cases | 异常与边界
+# -----------------------------------------------------------------------------
+# 用途：异常路径、失败恢复、极限值、并发冲突、网络中断等。
+# 每条必须说清"期望的系统行为"——不能留白。
+# =============================================================================
+edge_cases:
+  - id: "E-1"                 # -- 异常/边界。[必填][PM 填][机器读] 编号 E-1 / E-2 / ... 递增
+    situation: ""             # [必填][PM 填] 异常情形描述
+    expected_behavior: ""     # [必填][PM 填] 系统如何响应：报错 / 降级 / 重试 / 回滚 / 提示用户
+    mitigation: ""            # [选填][PM 填] 缓解或恢复手段：重试策略 / 补偿操作 / 人工介入路径
+
+
+# =============================================================================
+# ui_interaction | 页面与交互
+# -----------------------------------------------------------------------------
+# 用途：列出主要页面、关键元素、用户操作、三种必备状态（空 / 加载 / 错误）。
+# 非视觉稿级别，只说清页面结构与关键状态。
+# 若本功能纯后台、无用户界面，此模块可整体为空数组：ui_interaction: []
+# =============================================================================
+ui_interaction:
+  - id: "UI-1"                # -- 页面。[必填][PM 填][机器读] 编号 UI-1 / UI-2 / ... 递增
+    page: ""                  # [必填][PM 填] 页面名或组件名
+    purpose: ""               # [必填][PM 填] 这个页面要解决什么问题
+    key_elements: []          # [必填][PM 填] 关键 UI 元素列表（按钮、表格列、输入框、状态标签等）
+    user_actions: []          # [必填][PM 填] 用户在此页面可执行的操作
+    empty_state: ""           # [必填][PM 填] 无数据时展示什么：空提示文案、引导 CTA
+    loading_state: ""         # [必填][PM 填] 加载中展示什么：骨架屏 / 进度条 / 占位
+    error_state: ""           # [必填][PM 填] 出错时展示什么：错误文案、重试按钮、降级展示
+
+
+# =============================================================================
+# data_and_api | 数据与接口约束
+# -----------------------------------------------------------------------------
+# 用途：业务级的数据规则、接口契约、性能期望、安全要求。
+# 不是 DB DDL、不是 API schema，是"开发实现时必须遵守"的业务约束。
+# 每条约束独立 ID，未来做 diff / change request 可按条变更。
+# =============================================================================
+data_and_api:
+  data_constraints:           # [选填][PM 填] 数据层约束列表
+    - id: "DC-1"              # -- 数据约束。编号 DC-1 / DC-2 / ...
+      text: ""                #   约束内容，如"单文件 ≤ 10MB"、"title 长度 1-200"
+      applies_to: []          # -- 作用对象。作用于 EN-*（实体）的 ID 或字段名
+  api_constraints:            # [选填][PM 填] 接口层约束列表
+    - id: "API-1"             # -- 接口约束。编号 API-1 / API-2 / ...
+      text: ""                #   约束内容：幂等性、超时时间、返回格式、错误码规约
+      applies_to: []          # -- 作用对象。作用于 EN-*（实体）的 ID 或接口名
+  performance_constraints:    # [选填][PM 填] 性能期望列表
+    - id: "PC-1"              # -- 性能约束。编号 PC-1 / PC-2 / ...
+      text: ""                #   约束内容，如"列表首屏 ≤ 2s"、"关键操作响应 ≤ 500ms"
+      applies_to: []          # -- 作用对象。作用于 EN-*（实体）的 ID 或场景名
+  security_constraints:       # [选填][PM 填] 权限、审计、脱敏、合规、防滥用等
+    - id: "SEC-1"             # -- 安全约束。编号 SEC-1 / SEC-2 / ...
+      text: ""                #   约束内容
+      applies_to: []          # -- 作用对象。作用于 EN-*（实体）的 ID 或字段名
+
+
+# =============================================================================
+# acceptance_criteria | 验收标准
+# -----------------------------------------------------------------------------
+# 用途：本期完成的判定条件。每条必须能被测试 / 演示 / 验证。
+# 写不出验收标准的范围项，说明需求还没想清楚——应退回 open_questions。
+# =============================================================================
+acceptance_criteria:
+  - id: "AC-1"                # -- 验收标准。[必填][PM 填][机器读] 编号 AC-1 / AC-2 / ... 递增
+    criterion: ""             # [必填][PM 填] 验收条件，陈述性、可判断通过 / 不通过
+    priority: "must"          # [必填][PM 填][机器读] must（必须实现，未通过不能上线）/ should（建议实现）/ could（锦上添花）。context.md 的 Must Build 清单按此过滤
+    verification_method: ""   # [必填][PM 填] 如何验证：手工用例 / 演示 / 自动化测试 / 日志核查
+    refers_to: []             # -- 引用对象。[选填][PM 填][机器读] 支持 S-*（范围项）/ SC-*（场景）/ R-*（业务规则）/ E-*（异常）/ DC-*（数据约束）/ PC-*（性能约束）/ SEC-*（安全约束）的 ID 列表
+
+
+# =============================================================================
+# open_questions | 待确认问题
+# -----------------------------------------------------------------------------
+# 用途：悬而未决的问题清单。
+# 冻结前所有 blocking 级问题必须被回答，否则 CLI 校验会失败。
+# =============================================================================
+open_questions:
+  - id: "Q-1"                 # -- 待确认问题。[必填][PM 填][机器读] 编号 Q-1 / Q-2 / ... 递增
+    question: ""              # [必填][PM 填] 具体问题
+    severity: "non_blocking"  # [必填][PM 填][机器读] blocking（阻塞冻结）/ non_blocking（可带着冻结）
+    deferred_to: ""           # [选填][PM 填] 问题延后到哪里解决：留空 / "v1.1" / "CR-XXX" / "business-review"
+    owner: ""                 # [必填][PM 填] 谁负责回答（PM 姓名 / 业务方 / 技术负责人）
+    due_date: ""              # [选填][PM 填] 期望回答日期，格式 YYYY-MM-DD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prd-improve/cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "PRD Improve CLI - validate / freeze / context for .prd/features/*.yaml",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "build": "tsc -p .",
+    "build": "tsc -p . && node scripts/copy-skill.mjs",
     "dev": "tsx src/cli.ts",
     "test": "vitest run --passWithNoTests",
     "test:watch": "vitest",