jsharness 1.8.1 → 1.8.3

package/.harness/skills/prd-generator/SKILL.md

@@ -0,0 +1,584 @@
+---
+name: prd-generator
+description: 生成标准化 Markdown 产品需求文档（PRD）— 包含背景、用户角色、业务主流程、用户故事、功能清单、功能详细描述、产品运行分析、非功能性需求和附录十大章节，支持 Mermaid 图表
+alwaysApply: false
+enabled: true
+outputPath: .harness/doc/prd/
+---
+
+# PRD Generator（产品需求文档生成器）
+
+> **Skill 类型**: 需求分析辅助 Skill
+> **触发场景**: 用户提出产品需求、功能规划，或明确要求撰写 PRD
+> **所属 Agent**: requirements-analyst（需求分析师在需求分析阶段引用本 skill）
+> **输出路径**: 生成的 PRD 文档写入项目根目录下 `.harness/doc/prd/` 目录
+
+本 Skill 用于生成标准化的 Markdown 格式产品需求文档（PRD）。当用户提出产品需求、功能规划或需要撰写 PRD 时，自动按照以下模板结构输出完整的 PRD 文档。
+
+---
+
+## 文档结构总览
+
+生成的 PRD 必须严格包含以下十大章节，顺序如下：
+
+1. 背景
+2. 用户角色
+3. 业务主流程
+4. 用户故事
+5. 系统用户与功能结构
+6. 功能清单
+7. 功能详细描述
+8. 产品运行分析
+9. 非功能性需求
+10. 附录
+
+---
+
+## 各章节详细规范
+
+### 1. 背景
+
+**目的**：阐述本次需求的来龙去脉，让读者快速理解"为什么要做这件事"。
+
+**必须包含的子项**：
+
+- **需求背景**：描述当前业务现状、痛点或机会，说明触发本次需求的缘由
+- **目的**：明确本次需求要达成的核心目标（建议用 1-3 条精炼描述）
+- **版本范围**：标注本次 PRD 对应的版本号、迭代周期、涉及的产品线/模块范围
+
+**输出格式**：
+
+```markdown
+## 1. 背景
+
+### 1.1 需求背景
+
+<描述当前业务现状、痛点或机会>
+
+### 1.2 目的
+
+- <目标1>
+- <目标2>
+- <目标3>
+
+### 1.3 版本范围
+
+|| 项目 | 内容 |
+||------|------|
+|| 版本号 | v<版本号> |
+|| 迭代周期 | <起止日期或Sprint编号> |
+|| 涉及产品线/模块 | <产品线或模块名称> |
+|| 关联文档 | <相关BRD/MRD/技术方案链接> |
+```
+
+---
+
+### 2. 用户角色
+
+**目的**：定义本次需求涉及的所有用户角色，确保后续章节中角色引用一致且可追溯。
+
+**必须包含的子项**：
+
+- **角色名称**：角色的标准命名
+- **角色定义**：该角色是什么人、代表什么群体
+- **角色权限概述**：该角色在本期需求中的核心权限范围
+
+**输出格式**：
+
+```markdown
+## 2. 用户角色
+
+|| 角色名称 | 角色定义 | 角色权限概述 |
+||----------|----------|-------------|
+|| <角色A> | <该角色是什么人/代表什么群体> | <该角色在本期需求中的核心权限> |
+|| <角色B> | <该角色是什么人/代表什么群体> | <该角色在本期需求中的核心权限> |
+```
+
+---
+
+### 3. 业务主流程
+
+**目的**：从整体层面描述用户角色对应的大业务场景，明确业务目标、参与角色及核心流程，为后续用户故事的拆解提供宏观指导。
+
+**必须包含的子项**：
+
+- **业务场景概述**：描述业务的整体目标、价值和适用范围
+- **参与角色**：列出参与该业务流程的主要角色（需与第2章角色名称一致）
+- **核心流程**：以流程图或步骤形式描述业务的主要执行路径
+- **关键节点说明**：对流程中的重要环节进行补充说明
+
+**输出格式**：
+
+```markdown
+## 3. 业务主流程
+
+### 3.1 业务场景概述
+
+<描述业务的整体目标、价值和适用范围>
+
+### 3.2 参与角色
+
+- <角色A>
+- <角色B>
+- <角色C>
+
+### 3.3 核心流程
+
+**流程图**：
+
+```mermaid
+flowchart TD
+    A[<起点>] --> B[<步骤1>] 
+    B --> C[<步骤2>] 
+    C --> D[<步骤3>] 
+    D --> E[<终点>]
+    B --> F[<异常路径>]
+    F --> G[<异常处理>]
+    G --> E
+```
+
+**流程说明**：
+
+1. <详细描述步骤1的业务动作和目的>
+2. <详细描述步骤2的业务动作和目的>
+3. <详细描述步骤3的业务动作和目的>
+4. <详细描述步骤4的业务动作和目的>
+
+### 3.4 关键节点说明
+
+|| 节点名称 | 说明 | 参与角色 |
+||----------|------|----------|
+|| <节点1> | <节点详细说明> | <角色A> |
+|| <节点2> | <节点详细说明> | <角色B> |
+```
+
+---
+
+### 4. 用户故事
+
+**目的**：从用户视角描述需求场景，明确"谁在什么条件下、什么场景中、执行什么操作、达到什么效果"。
+
+**必须包含的要素**：
+
+- **角色**：哪个用户角色（需与第2章角色名称一致）
+- **前置条件**：触发该故事的前提条件
+- **场景描述**：用户所处的业务场景
+- **操作步骤**：用户执行的具体操作流程（按步骤编号）
+- **预期效果**：操作完成后系统应呈现的结果或状态
+
+**输出格式**：
+
+```markdown
+## 4. 用户故事
+
+### US-01：<用户故事标题>
+
+|| 要素 | 描述 |
+||------|------|
+|| 编号 | US-01 |
+|| 角色 | <角色名称> |
+|| 前置条件 | <触发前提> |
+|| 场景描述 | <业务场景> |
+
+**操作步骤**：
+
+1. <步骤1：用户执行的操作>
+2. <步骤2：用户执行的操作>
+3. <步骤3：用户执行的操作>
+
+**预期效果**：
+
+- <效果1：系统呈现的结果/状态>
+- <效果2：系统呈现的结果/状态>
+
+---
+
+### US-02：<用户故事标题>
+
+|| 要素 | 描述 |
+||------|------|
+|| 编号 | US-02 |
+|| 角色 | <角色名称> |
+|| 前置条件 | <触发前提> |
+|| 场景描述 | <业务场景> |
+
+**操作步骤**：
+
+1. <步骤1>
+2. <步骤2>
+
+**预期效果**：
+
+- <效果1>
+- <效果2>
+
+---
+```
+
+> **注意**：用户故事编号从 US-01 开始递增，每个用户故事之间用 `---` 分隔线隔开。
+
+---
+
+### 5. 系统用户与功能结构
+
+**目的**：明确功能涉及的系统用户角色及权限分配，通过功能结构将功能清单整理为清晰的菜单层级，便于用户理解和系统实现。
+
+**必须包含的子项**：
+
+- **系统用户**：列出当前功能涉及的菜单及对应的权限角色（需与第2章角色名称一致）
+- **功能结构**：将功能清单按照场景整合为一级菜单、二级菜单，形成清晰的功能层级
+
+**输出格式**：
+
+```markdown
+## 5. 系统用户与功能结构
+
+### 5.1 系统用户
+
+|| 菜单名称 | 功能模块 | 权限角色 |
+||----------|----------|----------|
+|| <一级菜单> | <二级菜单> | <角色A>, <角色B> |
+|| <一级菜单> | <二级菜单> | <角色C> |
+
+### 5.2 功能结构
+
+```mermaid
+graph TB
+    subgraph 用户层
+        A[用户]
+    end
+    subgraph 接入层
+        B[Web端]
+        C[移动端]
+    end
+    subgraph 业务服务层
+        D[业务逻辑]
+        E[API服务]
+    end
+    subgraph 数据层
+        F[数据库]
+        G[缓存]
+    end
+    subgraph 外部系统
+        H[第三方服务]
+    end
+    A --> B
+    A --> C
+    B --> D
+    C --> D
+    D --> E
+    E --> F
+    E --> G
+    D --> H
+```
+
+**功能结构说明**：
+
+|| 一级菜单 | 二级菜单 | 包含功能点 | 说明 |
+||----------|----------|------------|------|
+|| <一级菜单1> | <二级菜单1-1> | F-01, F-02 | <简要说明> |
+|| <一级菜单1> | <二级菜单1-2> | F-03 | <简要说明> |
+|| <一级菜单2> | <二级菜单2-1> | F-04 | <简要说明> |
+|| <一级菜单2> | <二级菜单2-2> | F-05 | <简要说明> |
+```
+
+---
+
+### 6. 功能清单
+
+**目的**：将用户故事拆解为可实施的功能点，建立用户故事与功能的映射关系。
+
+**必须包含的子项**：
+
+- **功能编号**：唯一标识（F-01, F-02, ...）
+- **功能名称**：功能的简明命名
+- **功能描述**：功能的简要说明
+- **关联用户故事**：该功能对应的用户故事编号
+- **优先级**：P0（必须有）/ P1（应该有）/ P2（可以有）
+- **状态**：待开发 / 开发中 / 已完成
+
+**输出格式**：
+
+```markdown
+## 6. 功能清单
+
+|| 功能编号 | 功能名称 | 功能描述 | 关联用户故事 | 优先级 | 状态 |
+||----------|----------|----------|-------------|--------|------|
+|| F-01 | <功能名称> | <简要说明> | US-01 | P0 | 待开发 |
+|| F-02 | <功能名称> | <简要说明> | US-01, US-02 | P1 | 待开发 |
+|| F-03 | <功能名称> | <简要说明> | US-02 | P2 | 待开发 |
+```
+
+---
+
+### 7. 功能详细描述
+
+**目的**：对功能清单中的每个功能进行详细说明，明确功能的输入、条件、输出及验收标准，为开发和测试提供明确依据。
+
+**每个功能必须包含的子项**：
+
+- **功能编号与名称**：与功能清单一致
+- **适用角色**：该功能面向哪些角色（需与第2章一致）
+- **权限限制**：角色使用该功能的前提权限或限制条件
+- **前置条件**：触发该功能的前置业务条件
+- **输入**：用户需要提供或系统接收的输入项
+- **处理逻辑**：系统在给定输入和条件下执行的核心处理流程
+- **输出**：系统处理后的输出结果
+- **业务逻辑（业务规则）**：功能涉及的后台业务规则和逻辑
+- **限制条件**：功能使用的限制条件和边界情况
+- **验收标准**：可验证的、明确的验收条件（建议用 Given-When-Then 格式）
+
+**输出格式**：
+
+```markdown
+## 7. 功能详细描述
+
+### F-01：<功能名称>
+
+|| 项目 | 描述 |
+||------|------|
+|| 功能编号 | F-01 |
+|| 适用角色 | <角色A>、<角色B> |
+|| 权限限制 | <使用该功能需要的权限或限制> |
+|| 前置条件 | <触发该功能的前置业务条件> |
+
+**输入**：
+
+|| 输入项 | 类型 | 必填 | 说明 |
+||--------|------|------|------|
+|| <字段名1> | <数据类型> | 是/否 | <字段说明> |
+|| <字段名2> | <数据类型> | 是/否 | <字段说明> |
+
+**处理逻辑**：
+
+1. <步骤1：系统执行的逻辑>
+2. <步骤2：系统执行的逻辑>
+3. <步骤3：异常/边界处理>
+
+**输出**：
+
+|| 输出项 | 类型 | 说明 |
+||--------|------|------|
+|| <输出字段1> | <数据类型> | <字段说明> |
+|| <输出字段2> | <数据类型> | <字段说明> |
+
+**业务逻辑（业务规则）**：
+
+1. <业务规则1>：<规则详细说明>
+2. <业务规则2>：<规则详细说明>
+3. <业务规则3>：<规则详细说明>
+
+**限制条件**：
+
+1. <限制条件1>：<条件详细说明>
+2. <限制条件2>：<条件详细说明>
+
+**验收标准**：
+
+- **AC-01**：Given <前置条件>，When <操作>，Then <预期结果>
+- **AC-02**：Given <前置条件>，When <操作>，Then <预期结果>
+- **AC-03**：Given <异常条件>，When <操作>，Then <异常处理结果>
+
+**状态机图**：
+
+```mermaid
+stateDiagram-v2
+    [*] --> <状态1>
+    <状态1> --> <状态2> : <触发条件>
+    <状态2> --> <状态3> : <触发条件>
+    <状态3> --> [*] : <触发条件>
+    <状态1> --> <异常状态> : <异常条件>
+    <异常状态> --> <状态1> : <恢复条件>
+```
+
+---
+
+### F-02：<功能名称>
+
+（同上结构）
+
+---
+```
+
+> **注意**：功能编号与第6章功能清单保持一致，每个功能之间用 `---` 分隔线隔开。验收标准必须可验证、可量化。
+
+---
+
+### 8. 产品运行分析
+
+**目的**：从本期功能点中提炼产品运行分析指标，明确上线后需达到的指标效果，为产品运营决策和迭代优化提供数据依据。
+
+**必须包含的子项**：
+
+- **指标编号**：唯一标识（MET-01, MET-02, ...）
+- **关联功能**：该指标对应的功能编号（需与第6章功能编号一致）
+- **指标名称**：指标的标准命名
+- **指标定义**：指标的计算方式或统计口径
+- **指标类型**：使用频次类 / 运行效率类 / 转化类 / 质量类
+- **目标值**：上线后需达到的指标效果（需可量化）
+- **统计周期**：指标的统计频率（日/周/月）
+- **采集方式**：埋点 / 系统日志 / 业务报表 / 第三方工具
+
+**指标类型说明**：
+
+|| 指标类型 | 说明 | 示例 |
+||----------|------|------|
+|| 使用频次类 | 衡量功能被使用的频率和活跃度 | 日均使用次数、周活跃用户数、功能渗透率 |
+|| 运行效率类 | 衡量功能运行的性能和效率 | 平均响应时间、处理成功率、批量任务完成率 |
+|| 转化类 | 衡量用户行为转化效果 | 操作完成率、漏斗转化率、留存率 |
+|| 质量类 | 衡量功能运行质量 | 错误率、异常中断率、数据准确率 |
+
+**输出格式**：
+
+```markdown
+## 8. 产品运行分析
+
+### 8.1 运行分析指标总览
+
+|| 指标编号 | 关联功能 | 指标名称 | 指标定义 | 指标类型 | 目标值 | 统计周期 | 采集方式 |
+||----------|----------|----------|----------|----------|--------|----------|----------|
+|| MET-01 | F-01 | <指标名称> | <计算方式/统计口径> | 使用频次类 | <可量化目标> | 日/周/月 | 埋点/日志/报表/第三方 |
+|| MET-02 | F-01, F-02 | <指标名称> | <计算方式/统计口径> | 运行效率类 | <可量化目标> | 日/周/月 | 埋点/日志/报表/第三方 |
+|| MET-03 | F-03 | <指标名称> | <计算方式/统计口径> | 转化类 | <可量化目标> | 日/周/月 | 埋点/日志/报表/第三方 |
+|| MET-04 | F-01 | <指标名称> | <计算方式/统计口径> | 质量类 | <可量化目标> | 日/周/月 | 埋点/日志/报表/第三方 |
+
+### 8.2 指标详情
+
+#### MET-01：<指标名称>
+
+|| 项目 | 描述 |
+||------|------|
+|| 指标编号 | MET-01 |
+|| 关联功能 | F-01 |
+|| 指标类型 | 使用频次类 |
+|| 指标定义 | <详细计算公式或统计口径> |
+|| 目标值 | <上线后需达到的量化目标> |
+|| 基线值 | <上线前当前值（若有）> |
+|| 统计周期 | <日/周/月> |
+|| 采集方式 | <埋点/系统日志/业务报表/第三方工具> |
+|| 预警阈值 | <低于此值需触发预警> |
+|| 负责人 | <指标负责人> |
+
+#### MET-02：<指标名称>
+
+（同上结构）
+```
+
+> **注意**：每个功能点至少提炼 1 个运行分析指标；P0 优先级功能必须提炼至少 2 个指标（至少包含 1 个使用频次类或转化类指标）。目标值必须可量化，避免使用"提升""优化"等模糊表述。
+
+---
+
+### 9. 非功能性需求
+
+**目的**：明确除业务功能外，系统需要满足的安全性、性能、可用性、可交付性等质量属性要求。
+
+**必须覆盖的维度**（根据实际需求选择填写，无则标注"无特殊要求"）：
+
+- **安全性需求**：数据加密、权限控制、审计日志、防攻击等
+- **性能需求**：响应时间、并发量、吞吐量等
+- **可用性需求**：SLA、容灾、降级策略等
+- **兼容性需求**：浏览器、设备、系统版本等
+- **可交付性需求**：部署方式、灰度策略、回滚方案等
+- **数据合规需求**：隐私保护、数据保留策略等
+
+**输出格式**：
+
+```markdown
+## 9. 非功能性需求
+
+### 9.1 安全性需求
+
+|| 编号 | 需求描述 | 优先级 |
+||------|----------|--------|
+|| NFR-SEC-01 | <需求描述> | P0/P1/P2 |
+|| NFR-SEC-02 | <需求描述> | P0/P1/P2 |
+
+### 9.2 性能需求
+
+|| 编号 | 需求描述 | 优先级 |
+||------|----------|--------|
+|| NFR-PERF-01 | <需求描述> | P0/P1/P2 |
+
+### 9.3 可用性需求
+
+|| 编号 | 需求描述 | 优先级 |
+||------|----------|--------|
+|| NFR-AVAIL-01 | <需求描述> | P0/P1/P2 |
+
+### 9.4 兼容性需求
+
+|| 编号 | 需求描述 | 优先级 |
+||------|----------|--------|
+|| NFR-COMP-01 | <需求描述> | P0/P1/P2 |
+
+### 9.5 可交付性需求
+
+|| 编号 | 需求描述 | 优先级 |
+||------|----------|--------|
+|| NFR-DEL-01 | <需求描述> | P0/P1/P2 |
+
+### 9.6 数据合规需求
+
+|| 编号 | 需求描述 | 优先级 |
+||------|----------|--------|
+|| NFR-COMPL-01 | <需求描述> | P0/P1/P2 |
+```
+
+---
+
+### 10. 附录
+
+**目的**：以数据字典的形式，汇总本期涉及的所有字段参数，供各章节引用和查阅。
+
+**必须包含的子项**：
+
+- **字段名称**：字段的英文/技术命名
+- **字段中文名**：字段对应的中文含义
+- **数据类型**：String / Integer / Boolean / Date / Enum / Decimal 等
+- **字段长度/取值范围**：最大长度、取值范围或枚举值列表
+- **必填**：是 / 否
+- **默认值**：无则填"-"
+- **说明**：补充说明
+
+**输出格式**：
+
+```markdown
+## 10. 附录
+
+### 10.1 数据字典
+
+|| 字段名称 | 字段中文名 | 数据类型 | 长度/取值范围 | 必填 | 默认值 | 说明 |
+||----------|-----------|----------|-------------|------|--------|------|
+|| <field_name> | <中文名> | <类型> | <范围> | 是/否 | <默认值> | <补充说明> |
+|| <field_name> | <中文名> | <类型> | <范围> | 是/否 | <默认值> | <补充说明> |
+
+### 10.2 枚举值字典
+
+|| 枚举名称 | 枚举值 | 枚举描述 | 所属字段 |
+||----------|--------|----------|----------|
+|| <ENUM_NAME> | <value1> | <描述1> | <字段名称> |
+|| <ENUM_NAME> | <value2> | <描述2> | <字段名称> |
+
+### 10.3 术语表
+
+|| 术语 | 全称 | 说明 |
+||------|------|------|
+|| <缩写> | <全称> | <解释> |
+```
+
+---
+
+## 使用指引
+
+1. 当用户提出产品需求、功能规划，或明确要求撰写 PRD 时，触发本 Skill
+2. 根据用户提供的需求信息，填充上述模板中的各章节内容
+3. 若用户信息不足以填充某个章节，应主动追问，而非留空
+4. 所有角色名称、功能编号、用户故事编号必须在各章节之间保持一致和可追溯
+5. 验收标准必须使用 Given-When-Then 格式，确保可验证
+6. 优先级统一使用 P0/P1/P2 三级体系
+7. 产品运行分析指标必须与功能清单中的功能点关联，每个功能至少提炼 1 个指标，P0 功能至少 2 个指标
+8. 运行分析指标的目标值必须可量化，避免使用"提升""优化"等模糊表述
+9. 输出的 Markdown 文档应结构清晰、格式规范，可直接用于团队协作
+10. 图表必须使用 Mermaid 语法，包括系统框架图、数据模型图、业务流程图、状态机图
+11. 每完成一章立即输出，不要等所有章节完成后再一起输出
+12. 信息不足则标注 `[TODO]`，而不是编造内容