需求分析技能

<workflow>

工作流

graph TD
    START([用户请求]) --> SR{{场景识别}}
    SR -->|检测 PRD.md 存在| Mode{工作模式}
    Mode -->|无 PRD| T0["T0: 模式选择"]
    Mode -->|有 PRD| T0
    T0 --> T1["T1: 文档扫描"]

    T1 --> HasNL{含自然语言?}
    HasNL -->|是| T1_5["T1.5: 对话式需求提取"]
    HasNL -->|否| T2["T2: 文档解析与功能提取"]
    T1_5 --> T2

    T2 --> T3["T3: 智能整合(去重/冲突/补充)"]
    T3 -->|🔴 CHECKPOINT| T4["T4: INVEST 质量评估"]
    T4 --> T5["T5: 需求澄清"]
    T5 -->|🔴问题未清零| T5
    T5 -->|🔴全部清零| T6["T6: 最终确认"]
    T6 -->|🔴 CHECKPOINT| T7["T7: 生成 PRD.md"]
    T7 -->|🔴 CHECKPOINT| T8{"需要可视化原型?"}
    T8 -->|是| T8_Execute["T8: pencil-designer 原型设计"]
    T8 -->|否| END([完成])
    T8_Execute --> END([完成])

> 分工标注: [LLM 决策] 语义/交互 | [Script] 确定性脚本 | [LLM→Script] 决策后脚本执行

场景识别

跳过规则

• 无自然语言 → 跳过 T1.5；快速模式 → T5 批量确认；非增量 → 跳过 T6 变更展示；🔴 清零 → T5 提前结束；不生成原型 → 跳过 T8

</workflow>

<constraint name="全局约束">
- 冲突不自动解决: 在 PRD 中列出所有版本并标注 ⚠️ 待确认，必须由用户决定
- 🔴 严重矛盾清零前不得生成 PRD
- 快速模式默认值标注: 自动填充的默认值在 PRD 中标记 默认值待确认
- 问题分批: 同一用户旅程内可一次性展示全部问题（允许超过 5 个）；跨旅程时每批最多 5 个。每个问题附带 A/B/C 选项，降低用户回答成本
- 每轮只改 1 个功能维度: 修改后需重新确认
- 需求/功能/方案 分层甄别: 对每条输入（含文档内容）先区分"需求 / 功能 / 方案"，用户提供的往往是"方案"而非真实"需求"，需上钻到需求后再提取，防止方案绑架需求
- 所有脚本通过 stdin JSON 接收、stdout JSON 输出
- 脚本禁止使用关键词/正则匹配解析用户自然语言输入
- pencil-designer 原型设计为可选流程: 用户明确选择后才执行，不阻塞主 PRD 生成流程
</constraint>

执行流程

<task name="模式选择与环境检测">

Task 0: 模式选择与环境检测

分工: [LLM 决策]

• [ ] Step 1: 检查工作区根目录是否存在 PRD.md
• 存在 → 读取已有 PRD.md，提取功能项列表，记 mode = incremental
• 不存在 → 进入 Step 2
• [ ] Step 2: 询问用户是否需要快速模式（简化澄清、自动填默认值）
• 未明确选择时默认 mode = standard
• [ ] 🔴 CHECKPOINT: 展示选定的工作模式，用户确认后再继续

输出: mode 标识（standard / quick / incremental）+ 增量模式下的已有功能项列表

</task>

<task name="文档扫描">

Task 1: 文档扫描

分工: [LLM 决策]

• [ ] Step 1: 检查用户是否直接提供了自然语言描述
• [ ] Step 2: 扫描工作区根目录及子目录，匹配支持的扩展名
• Markdown .md/.markdown｜Word .docx（.doc 需提示转换）｜Excel .xlsx/.xls｜思维导图 .xmind/.mm/.mmap
• [ ] Step 3: 排除系统目录（node_modules, .git, dist, build, .venv 等）
• [ ] Step 4: 按优先级分组并排序：自然语言 > Markdown > Word > Excel > 思维导图
• [ ] Step 5: 显示扫描结果摘要给用户

<example>

发现 5 个需求来源: 自然语言 1 | Markdown 2 | Word 1 | Excel 1

</example>

输出: 文档扫描清单 {files: [{path, format, priority}]}

</task>

<task name="对话式需求提取">

Task 1.5: 对话式需求提取

分工: [LLM 决策]
触发条件: 仅当 T1 检测到自然语言输入时执行

> 对用户通过自然语言描述的需求进行策略性提取和澄清。

1.5.0 需求/功能/方案 分层甄别（先分层，再提取）

用户常把"不成熟的方案"当成需求提出（例：要一台更快的马车，但汽车才是真正需要的）。提取前先做三层甄别，防止方案绑架需求：

单向推导: 需求 → 功能 → 方案；不能从方案倒推需求。

上钻追问规则（按输入形态选择）

甄别流程: 先判断输入属于哪一层 → 方案则下钻到需求并记录候选（不锁死）；功能则上钻到需求确认"为什么做"；需求则确认后往下推功能/方案 → 保留「需求→功能→方案」映射写入 PRD 附录。

输入: "我要一台更快的马车"
→ 分层: 马车=方案；"更快"=隐含需求
→ 上钻: "马车是方案，你真正要的是『更快省力到达』这个结果吗？"
→ 沉淀: 需求=更快省力出行；功能=载人运输/快速移动；候选=马车改进/汽车/公交
→ 若只接受"马车"→ 锁死方案，错失汽车等更优解；需求必须先于方案落定

> 效果：把"用户要 X 系统"上钻为"解决 Y 问题"，避免做出一堆功能却偏离真实目标。

1.5.1 输入类型识别

1.5.2 反推需求技巧（功能清单 → 需求）

用户只给功能列表时，按「角色 → 流程 → 隐含 → 边界」反推：

输入: "用户注册、用户登录、查看订单、申请退款"
→ 角色: 普通用户（前台），可能有管理员 → 追问"是否有管理员角色？能做什么？"
→ 流程: 注册→登录→购物→查看→售后 → 追问"如何下单？是否需要购物车？"
→ 隐含: 有登录无退出 → 补退出；有退款无审批 → 追问"谁审批？自动/人工？"
       有查看订单无状态 → 追问"订单有哪些状态？如何流转？"
→ 边界: "导出数据"→格式/范围/上限；"搜索"→条件/模糊；"消息通知"→渠道/触发

1.5.3 引导式提问

按「宏观 → 核心 → 管理端」渐进追问：宏观（目标用户/商品类型/是否支付）→ 核心（浏览→下单→支付→发货）→ 管理端（商品/订单/用户/统计）。

1.5.4 追问维度（交互原则）

每批问题附带 A/B/C 选项并标注优先级（🔴 必须 / 🟡 建议 / 🟢 可选），确认后复述理解、保留用户原始表述。

1.5.5 🔴 提取完成检查点

展示提取结果供用户确认：

📋 需求提取结果
  用户角色: [角色1], [角色2]
  核心业务流程: [流程描述]
  识别到的功能: 模块 [模块名]: 1.[功能1] 2.[功能2]
  待补充信息: [缺失项1]

A. ✅ 确认，继续解析文档  B. 📝 需要修改（请指出）  C. ⏸ 暂停

输出: 用户确认后的结构化需求描述（统一中间格式）

执行规则: A→进入阶段 2；B→修改后重新确认；C→暂停，保存进度

</task>

<task name="文档解析与功能提取">

Task 2: 文档解析与功能提取

分工: [Script 执行]

• [ ] Step 1: 对每个文档，调用 scripts/parse_document.py：

echo '{"path": "<file_path>", "format": "<markdown|docx|xlsx|xmind|mm>"}' | python scripts/parse_document.py

• [ ] Step 2: 分层提取判断 — 调用 scripts/chunked_extractor.py 的 analyze 模式，输出骨架层：

echo '{"mode":"analyze","parsed_data": <parse_document 输出>}' | python scripts/chunked_extractor.py

返回 {too_large, total_features, chunk_count, chunk_size, modules:[...]}。
- too_large=false → 走单次提取（feature_extractor）
- too_large=true → 分层提取，避免一次读入全部超出上下文窗口：骨架确认（展示模块/功能名/数量）→ 按 chunk_index 逐批 chunk 提取（每批 ≤ chunk_size 项）→ 全部完成后 merge 合并去重

# 小文件：单次提取
echo '{"parsed_data": <parse_document 输出>}' | python scripts/feature_extractor.py
# 大文件：分层提取（骨架 → 逐批 → 合并）
echo '{"mode":"chunk","parsed_data": ...,"chunk_index":0}' | python scripts/chunked_extractor.py
echo '{"mode":"merge","chunks":[<各批 features>]}' | python scripts/chunked_extractor.py

> 📎 参考: references/输入格式示例.md — 各格式的典型结构和统一中间格式说明

错误处理:

输出: 统一中间格式 JSON 数组 [{id, name, description, module, priority, fields, actions, screenshots, related_pages, source}]

> 截图字段（可选）: 若用户提供了界面截图/原型图，或在澄清过程中补充了现状截图，为对应功能项附加 screenshots: [{path, caption, description}]。path 使用相对 PRD 的路径（建议存放在 screenshots/ 目录），生成 PRD 时在每个功能下渲染为「截图」小节。
> 相关页面字段（可选）: 若已有原型页面截图（如 pencil-designer 产出），为对应功能项附加 related_pages: [{name, path, caption, description}]（建议存放在 prototype/ 目录），生成 PRD 时在每个功能下渲染为「相关页面」小节。

• [ ] Step 3: [LLM 决策] 信息补充 — 必需字段缺失时从高优先级文档补充，仍缺失标记"待补充"

> 📎 参考: references/冲突标注示例.md — 冲突标注的标准格式

• [ ] 🔴 CHECKPOINT: 展示整合摘要供用户确认

📊 整合摘要

- 识别模块: X 个 | 功能项: Y 个
- 去重合并: Z 项 | 冲突检测: M 处

A. ✅ 继续
B. 📝 查看详细功能列表
C. ⏸ 暂停

输出: 整合后的功能列表 + 冲突报告

执行规则:

• 用户选择 A → 进入阶段 5
• 用户选择 B → 展示所有功能项详情，再询问
• 用户选择 C → 暂停，保存进度

</task>

<task name="INVEST需求质量评估">

Task 4: INVEST 需求质量评估

分工: [Script 执行]

• [ ] Step 1: 调用 scripts/invest_assessor.py 对每个功能项执行六维评估：

echo '{"features": [<整合后的功能列表>]}' | python scripts/invest_assessor.py

INVEST 评估维度: Independent（能否独立实现/测试）、Negotiable（实现细节可协商）、Valuable（体现业务/用户价值）、Estimable（描述具体可估算）、Small（功能粒度单一职责）、Testable（验收标准明确），每项评 ★ 1-3。

输出: INVEST 评分报告（每项 1-3★ + 建议），作为 PRD 附录

</task>

<task name="需求澄清">

Task 5: 需求澄清

分工: [LLM 决策]

5.0 NFR 基线规则（默认值，无需逐条提问）

进入澄清前，先按下列基线为 PRD 附录填入默认值，仅当触发特殊条件时才升级为 🔴 问题：

> 效果：自动填平约 80% 的非功能坑，仅将极端特殊情况（如"金融级加密"）作为 🔴 问题抛出。

• [ ] Step 0: 生成 NFR 基线清单，写入 PRD 附录；无特殊情况不单独提问

5.1 问题检测与分级

5.2 标准模式（MoSCoW 锚定 + 旅程分批 + 冲突可视化）

• [ ] Step 1: MoSCoW 优先级锚定 — 先为每个功能项推断 Must-Have / Should-Have / Could-Have / Won't-Have
• 遇到棘手模糊问题时先问："该功能在 MVP 阶段是否为 Must-Have？若非，可暂用人工手动配置简化逻辑，不再深究细节。"
• 将非 Must-Have 的模糊功能标记为"可简化"，不再逐条澄清细节，聚焦核心主干
• [ ] Step 2: 收集所有功能项中的问题，按用户核心旅程分组（注册登录流程 / 浏览下单流程 / 售后维权流程 / 管理后台流程 等），而非按严重程度排序
• [ ] Step 3: 一次性问完当前旅程的所有问题（同一场景可超过 5 个），让用户整体思考一条完整故事线；附原文引用 + 类型标签 + 建议方向

• [ ] Step 4: 冲突可视化 — 检测到矛盾时生成"冲突影响分析表"（来源 A / 来源 B / 业务影响 / 建议方案），而非纯文字标注，如：订单删除 → 物理删除 vs 软删除，影响客服误删恢复，建议软删除。

• [ ] Step 5: 用户回复后更新功能项，检查是否产生新问题

• [ ] Step 6: 重复直到所有 🔴 问题清零
• [ ] Step 7: 输出澄清报告

5.3 快速模式

• [ ] Step 1: 检测问题并收集列表，但不逐条交互
• [ ] Step 2: 对模糊/缺失项自动填入合理默认值
• [ ] Step 3: 一条消息展示所有默认值，让用户批量确认（全部接受/修改部分/切换标准模式）
• [ ] Step 4: 用户拒绝的项标记"待确认"在 PRD 中

输出: 澄清后的功能列表（🔴 问题清零）+ NFR 基线清单

</task>

<task name="最终确认">

Task 6: 最终确认

分工: [LLM 决策]

• [ ] Step 1: 前置检查 — 确认所有 🔴 矛盾已解决。未解决时提示用户返回 T5
• [ ] Step 2 (增量模式): 展示变更差异让用户确认：

📊 变更检测
  - 新增: 3 个 | 变更: 1 个 | 移除: 0 个 | 未变更: 8 个
1. ✅ 确认合并  2. 🔄 查看详细变更  3. ⏸ 暂停

• [ ] Step 3 (标准/快速模式): 展示缺失项标注

⚠️ 功能"用户注册"缺少字段类型信息，将在 PRD 中标注"待补充"
1. ✅ 确认生成  2. ⏸ 暂停补充信息

• [ ] 🔴 CHECKPOINT: 等待用户明确确认

输出: 用户确认标记 + 最终功能列表

</task>

> 📎 参考样例文件: references/PRD模板.md（PRD 标准模板）、references/数据字典示例.md（数据字典格式）、references/冲突标注示例.md（冲突/待确认标注格式）

<task name="生成PRD">

Task 7: 生成 PRD.md

分工: [Script 执行]

• [ ] Step 1: 选择输出路径 — 调用 scripts/suggest_output.py，结合当前目录结构推荐输出位置：

echo '{"cwd": "<工作区根目录>", "default": "PRD.md"}' | python scripts/suggest_output.py

返回 {recommended, reason, choices, doc_dirs, existing_prd}。向用户展示推荐理由与选项：
- 默认推荐：检测到文档类子目录 → 输出到该子目录；否则输出到工作区根目录
- 用户可指定任意子目录（如 docs/PRD.md、output/需求/PRD.md），支持增量模式沿用已有 PRD 所在路径

• [ ] Step 2: 选择输出模板 — 询问用户需要哪种版本：
• full（完整版）— 含字段说明/按钮逻辑/交互说明 + 附录 INVEST 质量评估（默认）

• summary（业务摘要版）— 删减数据字典等技术细节，仅保留业务视角的功能清单与验收标准

• [ ] Step 3: 调用 scripts/prd_generator.py：

echo '{
  "features": [...],
  "assessments": [...],
  "conflicts": [...],
  "mode": "standard|quick|incremental",
  "template": "full|summary",
  "version": "1.0.0",
  "project_name": "<从需求推断或询问用户>",
  "pending_items": [...],
  "nfr_baseline": [{"name": "并发量", "default": "日均 1000 UV", "trigger": "大促/高并发场景"}],
  "need_feature_map": [{"need": "更快到达", "feature": "交通调度", "solution": "汽车/公共交通"}]
}' | python scripts/prd_generator.py --output "<Step 1 选定路径>"

> 📎 参考: references/PRD模板.md — PRD 标准模板结构（含完整版/摘要版差异）
> 📎 参考: references/数据字典示例.md — 数据字典格式

• [ ] Step 4: 增量模式特殊处理:
• 保留已有 PRD 中未变更内容
• 新增功能追加到对应模块
• 变更功能在原位更新并标注 > 🔄 本次变更
• 版本号递增（v1.0.0 → v1.1.0）

PRD 必需章节: 需求概述 → 功能清单 → 附录（变更历史 + 待确认事项；完整版含 INVEST 质量评估）

输出: 用户选定路径下的 PRD.md（完整版或业务摘要版）

</task>

<task name="可视化原型设计">

Task 8: 可视化原型设计（可选）

分工: [LLM→Script] — LLM 决策是否启动，调用 pencil-designer skill 执行

> 触发条件: 用户在 PRD 确认后提出可视化原型需求，或 PRD.md 中标记了需要原型设计的模块。
> 依赖: 本 Task 依赖 Task 7 输出的 PRD.md。
> 环境检查说明: pen.dev 环境探测、后端选择、CLI/MCP 命令等细节由 pencil-designer skill 自行处理，本 skill 只做简单引导，不重复执行。

8.1 是否需要原型设计？

• [ ] Step 1: 展示 PRD.md 摘要，询问用户是否需要生成可视化原型

📊 PRD 已生成，检测到以下模块：[模块1]（N 项）、[模块2]（M 项）...
是否需要基于此 PRD 生成可视化原型？
1. ✅ 是，使用 pencil-designer 生成原型
2. 📝 我需要先修改 PRD 再生成
3. ⏸ 暂不生成，仅输出 PRD.md

• [ ] 🔴 CHECKPOINT: 用户选择"否"则跳过本 Task，流程结束

8.2 简单引导调用 pencil-designer

用户选择"✅ 是"时，只做以下引导，其余交给 pencil-designer：

• [ ] Step 1: 将 PRD.md 路径 与 用户原始需求 透传给 pencil-designer skill，明确说明"基于此 PRD 生成可视化原型"
• [ ] Step 2: 不重复执行环境探测 / 后端选择 / CLI-MCP 命令，交由 pencil-designer 按自身流程处理

输出: 由 pencil-designer 生成的 design.pen 原型文件 + 可交互原型

8.3 完成检查点

✅ 原型生成完成！原型文件: design.pen | 可交互原型: design-prototype.html
A. ✅ 确认完成，流程结束  B. 📝 需要修改设计（反馈传入 pencil-designer 迭代）  C. ⏸ 暂停，保存进度

执行规则:
- 用户选择 A → 流程结束
- 用户选择 B → 将修改意见传入 pencil-designer，迭代修改 design.pen
- 用户选择 C → 暂停，保存进度

</task>

错误处理

注意事项

1. 文档用 UTF-8；2. 冲突需用户最终确认，技能不自动解决；3. 🔴 严重矛盾解决前不得生成 PRD；4. 增量模式依赖 PRD.md 格式一致性