需求解析 Skill
目标
把各种格式的原始需求文档转换成统一的 Markdown 格式，确保可读性和可测试性。
输入输出
- 输入：
original-requirements/（PDF/DOCX/图片等各种格式） - 输出：
cleaned-requirements/index.md、cleaned-requirements/assets/（图片）
核心原则
- 忠实还原：不改变原文意思，严格依据原文
- 格式修复：修复乱码、格式错乱等问题
- 图片转文字：用详细描述替代图片占位符
- 上下文连贯：确保文档逻辑清晰
执行流程
1. 解析流程
- 扫描
original-requirements/目录 - 识别文件类型（PDF/DOCX/图片/纯文本）
- 调用解析脚本处理文件：
- PDF/DOCX：调用 .claude/skills/req-parser/scripts/parse_doc.py，脚本会自动解析并生成 Markdown 片段到 chunks/ - 图片：提取到 assets/，在片段中插入占位符 - 纯文本：直接复制到 chunks/
- AI 读取
chunks/中的所有 Markdown 片段 - AI 合并所有片段到
index.md（同时替换图片占位符为描述）
解析脚本调用：
uv run .claude/skills/req-parser/scripts/parse_doc.py \
--input-dir "original-requirements" \
--output-dir "cleaned-requirements/chunks"2. 图片处理
图片处理分两步：
步骤1：解析时
- 提取图片到
cleaned-requirements/assets/ - 在文档中插入占位符：
<!-- image: figure-1.png -->
步骤2：生成 index.md 时
- 读取所有图片占位符
- 用多模态能力生成详细描述
- 替换占位符为描述文字
- 最终 index.md 中不包含占位符，只有图片描述
描述要求：
- 说明图片类型（原型图/流程图/表格截图/示意图）
- 列出图片中的关键元素
- 解释图片的含义和作用
多模态分析引导：
在分析原型图或界面截图时，必须进行深度思考和详细描述：
- 整体布局识别：描述页面的整体结构（头部、主体、底部等）
- 交互元素识别：列出所有按钮、输入框、下拉框、链接等交互元素
- 文本内容提取：准确提取图片中的所有文字内容
- 业务逻辑推理：根据界面元素推理业务流程和功能意图
- 状态识别：识别不同状态（正常、禁用、错误、加载等）
描述格式要求：
- 使用结构化的 Markdown 格式（标题、列表、表格）
- 明确标注每个交互元素的位置和功能
- 提取所有可见的文字内容（包括按钮文字、提示文本等）
- 说明页面的业务场景和用户操作流程
3. 格式修复
常见问题及处理：
问题1：乱码
- 根据上下文推理正确内容
- 推理限度：必须有明确依据，不能臆测
问题2：格式错乱
- 修复标题层级
- 修复列表格式
- 修复表格结构
问题3：重复内容
- 保留第一次出现的内容
- 删除重复部分
4. 合并规则
将 chunks/ 下的所有文件合并到 index.md：
- 按需求文档的逻辑顺序排列
- 每个文件内容之间用
---分隔 - 添加来源标注：
<!-- 来源：文件名.md -->
示例
示例1：图片处理
解析时生成：
用户登录流程如下：
<!-- image: login-flow.png -->AI 读取后替换为：
用户登录流程如下：
[流程图描述]
这是一个登录流程图，包含以下步骤：
1. 用户输入手机号和验证码
2. 系统验证验证码有效性
3. 验证成功后跳转到首页
4. 验证失败显示错误提示
图中还标注了两个分支：
- 验证码过期：提示"验证码已过期，请重新获取"
- 验证码错误：提示"验证码错误，还可尝试X次"示例2：格式修复
原文（乱码）：
用户可以上传图片，支持jpg、png、gif格式，大小不超过5MB。
用户可以上传图片，支持jpg、png、gif格式，大小不超过5MB。（重复）修复后：
用户可以上传图片，支持jpg、png、gif格式，大小不超过5MB。示例3：合并文件
chunks/ 目录：
PRD.md
原型图.md
接口文档.md合并后的 index.md：
<!-- 来源：PRD.md -->
# 产品需求文档
...
---
<!-- 来源：原型图.md -->
# 原型设计
...
---
<!-- 来源：接口文档.md -->
# 接口说明
...检查清单
- 所有文件都已解析
- 图片已提取到 assets/
- 图片占位符已替换为描述
- 图片描述准确（特别是原型图和界面截图）
- 表格结构完整（无错行、错列）
- 格式问题已修复
- 没有乱码
- 没有重复内容
- 已生成 index.md
- 文档逻辑连贯
产物结构
cleaned-requirements/
├── index.md # 合并后的完整需求文档
├── chunks/ # 解析片段（按原文件名）
│ ├── 01-功能需求.md
│ ├── 02-接口文档.md
│ └── 03-原型说明.md
└── assets/ # 图片资源
├── figure-1.png
└── figure-2.png异常处理
| 错误 | 处理方式 |
|---|---|
| PDF 加密 | 提示用户提供解密密码 |
| 文件损坏 | 跳过并记录错误 |
| 编码问题 | 尝试自动检测编码（UTF-8, GBK, GB2312） |
| Docling 失败 | 降级使用 PyPDF2 |
| 图片识别失败 | 保留原图，添加"待补充"标记 |
脚本接口
parse_doc.py
uv run .claude/skills/req-parser/scripts/parse_doc.py \
--input-dir <输入目录> \
--output-dir <输出目录> \
[--force] # 强制覆盖已有文件返回值：
- 0: 成功
- 1: 部分失败（有文件无法解析）
- 2: 完全失败
输出：解析统计 JSON
{
"total": 5,
"success": 4,
"failed": 1,
"failed_files": ["encrypted.pdf"]
}