---
name: prd-writer
description: 产品需求文档（PRD）标准化生成。按最终可落地的需求格式输出结构化 PRD：用户故事带优先级、流程图按信号触发（fireworks 泳道图）、功能需求按价值切片拆解、技术与数据需求分层（PM 业务层 + 开发补充）。流程：Markdown 预览 → 用户确认 → Word 终稿。
metadata:
  type: skill
---

# PRD Writer

## 触发
用户说"写 PRD"/"需求文档"/"给研发开发"/"需求说明"时激活。

## 核心流程

**两步走：先 Markdown 预览 → 用户确认 → 再 Word。**

禁止跳过预览直接生成 Word。

**确认后追加一步：创建/更新需求决策索引**（见文末「决策索引联动」）。

## PRD 最终可用格式

PRD 必须让研发和测试看完就能直接动手实现，因此需求描述采用「升级点 → 多级编号大纲（搜索栏/按钮/列表/表单）」结构，字段四要素齐全、按钮必含交互，避免大段散文。

---

## 一、背景与问题（Problem）

### 背景
一句话描述功能/模块定位，当前存在的问题或机会点。

### 用户痛点

按编号列出。每条格式极简：

> **痛点 N：标题** —— 一句话描述，点到为止，不展开用户场景。
>
> 痛点数量不限，以精准描述为准。每个痛点应尽可能对应后续方案中的一个升级点。

---

## 二、用户故事（User Stories）

每个用户故事带优先级 P1/P2/P3，用一句话概括，覆盖角色、场景、目标、价值四个要素：

> ### 用户故事 N（P1）：标题
> 作为 <角色>，在 <场景> 下，我希望 <目标>，以便 <价值>。
>
> **独立验收：** 只实现本故事，用户能得到什么可用价值（一句话）。写不出来说明故事拆错了。
>
> **验收标准：**
> - Given ... When ... Then ...
> - 或用更严格的 EARS 句式：`WHEN <触发>，THE SYSTEM SHALL <响应>`；异常场景用 `IF <条件>，THEN THE SYSTEM SHALL <响应>`

**规则：**
- P1 = 最小可用切片（只交付 P1 也成立）；P2 = 重要增强；P3 = 锦上添花。
- 用户故事求精简但不强求数量上限，以精准覆盖场景为准，不刻意限制每条不超过 3 条验收标准。

---

## 三、方案概述（Solution）

> **核心功能一句话描述** —— 用一句话概括本次升级的核心价值（引用块高亮展示）。

### 流程图（按信号触发）

**触发信号（命中任一即必须出图）：** 跨页面跳转、多角色协作、审批/状态流转、核心业务链路重构。
单页面操作、少量字段变更的需求不出图。

**出图方式：**
1. 调用 `fireworks-tech-graph` skill 生成泳道流程图（SVG，几何校验零交叉），存到 PRD 所在月份目录下 `assets/`。
2. Markdown 预览内嵌 SVG 引用；Word 终稿插入 PNG 版本。
3. 图下附「流程节点表」，把图翻译成研发可逐行核对的文字：

| 流程节点 | 页面/角色 | 用户行为 | 分支条件 | 异常去向 |
|---------|----------|---------|---------|---------|

**原则：** 节点以动作或状态命名，线条标注触发条件，不画字段级细节。

### 升级点清单

先列出本次所有升级点（一句话/行），让用户快速了解全貌。例如：

- 4.1 重构水印模板浏览与管理
- 4.2 新增我的模板管理菜单
- 4.3 升级全屏模板设计器
- 4.4 新增定制水印入口

**拆解硬规则（防乱防充）：**
1. 粒度：以「整个功能模块」为单位拆分，禁止把搜索框、按钮、列表字段拆成独立升级点。
2. 每个升级点 = 一个可独立验收的价值切片，详情中必须写「独立验收」一句话；写不出来说明拆错了，应合并或重拆。
3. 升级点与第二章用户故事对应（如 4.1 承接故事 1、2）。拆解完成后回检：每个 P1/P2 故事至少有一个升级点承接；找不到承接故事的升级点，必须在 Non-Goals 或开放问题中说明为什么做。

---

## 四、功能需求（Feature Requirements）

每个升级点一个二级标题。开头必须有「功能说明 + 独立验收」，正文用**多级编号大纲**按功能区块组织（搜索栏 / 按钮 / 列表 / 表单内容 / 表单按钮），无此区块则跳过：

> ## 4.X 功能名称（动词+名词）
>
> ### 功能说明
> 一句话说明谁能做什么、做完得到什么。若包含隐藏/移除/新增入口，需在此处一句话点名。
>
> **独立验收：** 只做本升级点，用户能得到什么可用价值（一句话）。
>
> 1. 搜索栏（如适用）
>    1. 字段名：模糊搜索 / 下拉选 / 精确匹配
> 2. 按钮（每个按钮必须写交互逻辑）
>    1. 按钮名（新增）：功能说明 + 交互
>    2. 按钮名（隐藏）：按钮隐藏
>    3. 按钮名（优化）：优化点 --> 功能说明
> 3. 列表（如适用）
>    1. 列名（新增/优化）：说明
>    2. 操作：按钮名：交互逻辑
> 4. 表单内容（弹窗/新建页，按分组展开）
>    1. 分组名
>       1. 字段名
>          1. 格式：输入框 / 下拉选择框 / 文本框（自动生成）
>          2. 提示内容：请输入/请选择 xxx
>          3. 必填项 / 非必填项
>          4. 选择项 / 限制：具体规则；未变更写「保留原有功能」
> 5. 表单按钮
>    1. 取消：按钮逻辑（如关闭弹窗/返回列表页）
>    2. 确认：
>       1. 前端：格式校验 → toast 提示文案（精确到字）→ 成功后行为（跳转/关闭/刷新）
>       2. 后端：校验 → 保存逻辑

**格式说明：**
- 升级点标题必须使用「动词 + 名词」结构（如「重构员工账号列表」「新增批量导入账号」「优化编辑账号弹窗」），禁止只用名词短语。
- 变更标记必须显式：（新增）（优化）（隐藏）；未变更的写「保留原有功能/逻辑」。禁止不写标记让研发猜。
- 字段四要素缺一不可：格式、提示内容、必填与否、选择项/限制。字段中文名必须与页面展示文案保持一致。
- 按钮必须写交互：点击后校验什么、提示什么文案（精确到字）、成功/失败后页面行为；提交类按钮区分前端/后端两层。
- 全部用多级编号大纲，不用表格（流程节点表除外），同类信息用编号层级分隔。

**示例参考（以用户管理列表页优化为例）：**

> ## 4.1 优化用户管理列表页
>
> ### 功能说明
> 优化用户列表的搜索、按钮与列展示：新增导入/导出，低频操作隐藏并入批量操作，列表按操作时间排序。
>
> **独立验收：** 只做本升级点，管理员可完成账号的搜、增、导、批量启停。
>
> 1. 搜索栏
>    1. 登录账号：模糊搜索
>    2. 用户姓名：模糊搜索
>    3. 用户平台：下拉选
> 2. 按钮
>    1. 新增账号：逻辑优化 --> 功能说明
>    2. 导入（新增）：功能说明
>    3. 导出（新增）：导出数据和导入模板保持一致
>    4. 角色配置（隐藏）
>    5. 批量操作：停用账号 / 启用账号 / 密码重置 / 角色配置
> 3. 列表（移除 sort 排序规则，按操作时间倒序）
>    1. 启用状态（优化）：修改为账号状态
>    2. 操作人（新增）：字段新增
>    3. 操作时间（新增）：字段新增
>    4. 操作：查看（隐藏）；编辑：功能说明；重置密码：保留原有逻辑，重置后弹窗提示「确定重置密码？重置后密码为手机尾号后六位」
> 4. 表单内容（新增账号弹窗）
>    1. 基础信息
>       1. 登录账号
>          1. 格式：输入框
>          2. 提示内容：请输入登录账号
>          3. 必填项
>          4. 限制：4-20 位字母数字，重号拦截
> 5. 表单按钮
>    1. 取消：关闭弹窗，不保存
>    2. 确认：
>       1. 前端：必填与格式校验，失败 toast 精确文案（如「登录账号已存在」）；成功提示「新增成功」，1s 后关闭弹窗并刷新列表
>       2. 后端：重号校验，保存数据

### 边界与异常

用编号列出系统级边界与核心异常分支（空数据、超长文本、弱网、未登录、无权限、并发操作、数据兼容性）。数量不限，以精准覆盖场景为准；各升级点特有的异常已在交互流程中描述的，此处不重复。

### Non-Goals（本次明确不做）

列出与本次需求相邻但明确不做的内容，每条一句话，防止范围蔓延。例如：「不做模板分享功能」「不改动常用分类的现有排序逻辑」。

---

## 五、技术与数据需求

PM 写到业务层为止，技术选型留给研发。

### 5.1 数据与业务逻辑
- 数据来源与去向（哪张表/哪个接口/哪个第三方）
- 排序、筛选、去重、状态流转等业务规则
- 跨升级点共用的通用字段（如用户ID、时间戳）的口径
- 数据获取失败的托底策略

### 5.2 接口诉求（PM 业务层）
- 需要哪些新接口或改动，用自然语言描述（要什么数据、什么时机、什么量级）
- 性能预期的业务化表达（如「列表秒开」「导入 1 万行不超时」）
- 技术实现细节（路径、入参、出参、缓存）由开发补充，标注：
  > ⚠️ 以下内容由开发补充

### 5.3 非功能需求（按需激活，写不出量化值就省略）
- 性能：页面加载/接口响应的量化目标
- 兼容性：机型、浏览器、老版本数据兼容
- 安全：输入校验、权限控制、敏感数据处理

---

## 六、成功指标（可选）

只在能量化时写，1~3 条；每条必须注明验证哪个升级点，挂不上功能的指标是充数指标，删掉。表格：

| 指标名称 | 目标值 | 验证功能 | 追踪周期 |
|----------|--------|----------|----------|

写不出可量化目标时整节省略，并在开放问题中注明「指标待补」。

---

## 七、开放问题与假设

**开放问题** —— 用编号列出待确认事项。数量不限，指向技术可行性、数据兼容性、业务规则等。

**假设清单** —— 正文中所有未经确认的推断（默认沿用的口径、复用的老逻辑、未经确认的字段来源），逐条列出请相关方确认；正文对应位置用 `[假设]` 标注。

---

## 硬规则

1. 必须先 Markdown 预览，后 Word。
2. PRD 固定六段：背景与问题、用户故事、方案概述、功能需求、技术与数据需求、开放问题与假设；成功指标为可选段（能量化才写）。
3. 流程图按信号触发：命中跨页面/多角色/状态流转/核心链路重构任一信号，必须调用 `fireworks-tech-graph` 出泳道图 + 流程节点表。
4. 功能需求内部不用表格（流程节点表除外），用段落切割；升级点以整个功能模块为粒度，禁止把搜索框、按钮、列表字段拆成独立升级点；每个升级点必须写「独立验收」。
5. 每个升级点内部采用「功能说明 → 独立验收 → 多级编号大纲（搜索栏/按钮/列表/表单内容/表单按钮）」结构；字段四要素齐全（格式/提示内容/必填与否/选择项或限制），按钮必含交互（提示文案精确到字，提交类区分前端/后端），变更标记显式（新增/优化/隐藏/保留原有功能）。
6. 数量不限，以精准为准（痛点、边界情况、开放问题、用户故事及验收标准均不刻意设下限）。
7. 先给结构（升级点清单），再展开细节。
8. 涉及复杂表单（如新建/编辑弹窗、批量导入向导）时，必须逐字段说明：字段 ID、类型、必填、默认值、校验规则、研发注意事项。
9. `<feature-slug>` 必须用英文短横线小写，且与该需求的原型目录、决策索引三者保持一致（见「输出命名」）。

## 示例参考

- 复杂表单字段描述示例：`examples/scheduled-task-form.md`（定时任务新建/编辑弹窗）
- 引用方式：生成 PRD 时，如涉及同类复杂表单，参考该示例的字段粒度进行描述

## Word 生成（确认后执行）

使用 `document-skills:docx` 调用 docx-js，必须满足以下格式规范：

### 基础版式
- 字体：Arial（正文 12pt / 24 half-points）
- 页面：A4（11906 × 16838 DXA），四边边距 1 英寸（1440 DXA）
- 页眉：文档标题居中，灰色 #666666，10pt
- 页脚：「第 N 页」居中，10pt
- 行距：正文 1.5 倍行距（line = 360），避免文字揉在一起

### 标题层级
- Heading1：Arial，18pt，粗体，蓝色 #2E75B6
- Heading2：Arial，15pt，粗体
- Heading3：Arial，13pt，粗体
- Heading4：Arial，12pt，粗体，深灰 #333333（用于「功能说明 / 入口 / 交互流程 / 字段与限制 / 状态与展示」）
- Heading5：Arial，11pt，粗体，深灰 #444444（用于「正常流程/异常流程」）
- **禁止把 `#`、`##`、`###`、`####`、`#####` 渲染成正文文本，必须映射为对应 Heading 样式。**
- 目录（TOC）使用 headingStyleRange: '1-3'，只收录一、二、三级标题，避免导航层级过碎。

### 列表与编号
- 无序列表：使用 `LevelFormat.BULLET`，圆点符号，统一一个全局 bullets 引用。
- **有序列表：每个独立列表必须使用独立的 numbering 引用，确保每个模块的编号从 1 开始，禁止全局连续编号。** 例如「前置条件」的 1、2 与「正常流程」的 1、2、3 必须分别计数，不能接续成 1、2、3、4、5。

### 段落间距
- Heading 上下间距随层级递减，但最小保持 120pt/after。
- 正文段落：before 100pt，after 100pt，line 360。
- 表格上下：各 80-160pt 留白。
- 模块之间（如一个升级点结束到下一个升级点开始）通过 Heading 间距自然分隔，禁止文字紧贴。

### 表格
- 宽度：内容区全宽（A4 内容区约 9026 DXA），使用 `WidthType.DXA`，禁止百分比。
- 表头：蓝色 #2E75B6 背景，白色文字，Arial 11pt，粗体。
- 单元格：Arial 11pt，内边距 top/bottom 80、left/right 100。
- 边框：浅灰 #CCCCCC 单线。

### 引用块
- 左侧蓝色 #2E75B6 竖线，浅灰背景 #F7FAFC，左缩进 240，使用 1.5 倍行距。

### 图片
- Markdown 中的 SVG 流程图引用，在 Word 中替换为 PNG 插入（fireworks-tech-graph 出图时同步导出 PNG）。
- 图片居中，宽度不超过内容区，图下「流程节点表」按表格规范渲染。

### 校验
生成后必须执行：
1. 文件大小 > 0 且 ZIP 结构完整。
2. 打开 document.xml 确认不存在字面量 `####` 或 `#####`。
3. 确认 numbering.xml 中每个有序列表都有独立的 `w:num` 定义。
4. 确认流程图 PNG 已嵌入且清晰可读。
5. 最终通过 Word / WPS 打开目测，确认目录层级清晰、编号不连续、段落不拥挤。

## 输出命名

PRD 按创建月份归档到 `specs/YYYY-MM/` 文件夹，文件名使用与原型、决策索引一致的英文短横线 slug：

- Markdown：`specs/YYYY-MM/YYYYMMDD-<feature-slug>-prd-preview.md`
- Word：`specs/YYYY-MM/<feature-slug>-PRD.docx`

命名规则（与原型目录 `prototypes/YYYY-MM/<feature-slug>-vN`、决策索引 `docs/decisions/YYYY-MM/<feature-slug>.md` 对齐）：

- `<feature-slug>` 为**英文短横线小写**（如 `image-management-space`、`quick-quote`），与原型目录、决策索引共用同一个 slug。
- 同一个需求，原型目录、PRD、决策索引三者 slug 必须一致，确保脚本能按 slug 互相匹配。
- `YYYY-MM` 为当前月份，例如 `2026-07`。生成 Markdown 时若文件夹不存在则自动创建。
- Word 通过 `scripts/build-prd-docx.js` 生成，默认输出到输入 Markdown 所在月份文件夹。

## 决策索引联动（确认用户故事后执行）

PRD 预览经用户确认后，立即创建或更新该需求的决策索引，把「来源 / 问题定义 / 用户故事」沉淀进去。

**执行步骤：**

1. 用本 PRD 的 `<feature-slug>` 运行：
   ```bash
   node scripts/create-requirement-decision.js <feature-slug>
   ```
   脚本幂等：索引已存在则跳过创建，只提示更新。

2. 打开生成的 `docs/decisions/YYYY-MM/<feature-slug>.md`，确认/补全：
   - 「来源」：本需求的 Obsidian 领域判断 / 灵感 / 反馈链接
   - 「问题定义」：用本 PRD 第一节「背景与问题」浓缩填入（**必填**，不可留占位）
   - 「方案演进」表 PRD 列：填入本 PRD 的 `specs/...` 路径
   - 「当前结论」：采用版本与未决问题

3. **必须同步建 Obsidian 领域判断**（固定流程，不可跳过）：
   在 `E:/Obsidian/02 - Areas/工作/汽配云/<模块>/` 下建 `YYYY-MM-DD-<需求名>-核心判断.md`，内容含：一句话判断、推理链、已验证/已推翻、未决问题、反向链接到决策索引。把该文件路径回填到决策索引「来源 → 领域判断」字段，形成双向链接。

4. 刷新总表：
   ```bash
   node scripts/generate-requirements-index.js
   ```

5. **回写 Obsidian 长期记忆库**（固定流程，不可跳过）：
   把本次 PRD 沉淀的「偏好 / 工作流 / 规划」更新回 Obsidian：
   - 偏好：如果本次 PRD 涉及新的命名规范、决策风格、技术选型 → 更新 `E:/Obsidian/06 - 长期记忆库/偏好/<主题>.md`
   - 工作流：如果发现了新的有效操作步骤或避坑指南 → 更新 `E:/Obsidian/06 - 长期记忆库/工作流/<主题>.md`
   - 规划：如果涉及长期路线变动 → 更新 `E:/Obsidian/06 - 长期记忆库/规划/<主题>.md`
   - 决策：把本次决策结论追加到 `E:/Obsidian/06 - 长期记忆库/决策/需求决策索引.md`（或链接到原型项目索引）

**判断归属**：脚本只自动填链接与骨架；「关键改动 / 推翻的假设」与 Obsidian 领域判断的「推理链」永远由人工补，不自动生成。

**三个必填项（固定流程）**：① 决策索引的「问题定义」；② 对应的 Obsidian 领域判断；③ 回写 Obsidian 长期记忆库。缺一项即流程未完成。

> 触发逻辑详见 `docs/superpowers/specs/2026-07-15-requirement-decision-index-design.md` 第四节。