需求解析 Skill
目标
把各种格式的原始需求文档转换成统一的 Markdown 格式，确保可读性和可测试性。
输入输出
-
输入：original-requirements/ （PDF/DOCX/图片等各种格式）
-
输出：cleaned-requirements/index.md 、cleaned-requirements/assets/ （图片）
核心原则
-
忠实还原：不改变原文意思，严格依据原文
-
格式修复：修复乱码、格式错乱等问题
-
图片转文字：用详细描述替代图片占位符
-
上下文连贯：确保文档逻辑清晰
执行流程
- 解析流程
-
扫描 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"
- 图片处理
图片处理分两步：
步骤1：解析时
-
提取图片到 cleaned-requirements/assets/
-
在文档中插入占位符：<!-- image: figure-1.png -->
步骤2：生成 index.md 时
-
读取所有图片占位符
-
用多模态能力生成详细描述
-
替换占位符为描述文字
-
最终 index.md 中不包含占位符，只有图片描述
描述要求：
-
说明图片类型（原型图/流程图/表格截图/示意图）
-
列出图片中的关键元素
-
解释图片的含义和作用
多模态分析引导：
在分析原型图或界面截图时，必须进行深度思考和详细描述：
-
整体布局识别：描述页面的整体结构（头部、主体、底部等）
-
交互元素识别：列出所有按钮、输入框、下拉框、链接等交互元素
-
文本内容提取：准确提取图片中的所有文字内容
-
业务逻辑推理：根据界面元素推理业务流程和功能意图
-
状态识别：识别不同状态（正常、禁用、错误、加载等）
描述格式要求：
-
使用结构化的 Markdown 格式（标题、列表、表格）
-
明确标注每个交互元素的位置和功能
-
提取所有可见的文字内容（包括按钮文字、提示文本等）
-
说明页面的业务场景和用户操作流程
- 格式修复
常见问题及处理：
问题1：乱码
-
根据上下文推理正确内容
-
推理限度：必须有明确依据，不能臆测
问题2：格式错乱
-
修复标题层级
-
修复列表格式
-
修复表格结构
问题3：重复内容
-
保留第一次出现的内容
-
删除重复部分
- 合并规则
将 chunks/ 下的所有文件合并到 index.md ：
-
按需求文档的逻辑顺序排列
-
每个文件内容之间用 --- 分隔
-
添加来源标注：<!-- 来源：文件名.md -->
示例
示例1：图片处理
解析时生成：
用户登录流程如下：
<!-- image: login-flow.png -->
AI 读取后替换为：
用户登录流程如下：
[流程图描述] 这是一个登录流程图，包含以下步骤：
- 用户输入手机号和验证码
- 系统验证验证码有效性
- 验证成功后跳转到首页
- 验证失败显示错误提示
图中还标注了两个分支：
- 验证码过期：提示"验证码已过期，请重新获取"
- 验证码错误：提示"验证码错误，还可尝试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"] }