req-parser

name	req-parser
description	解析原始需求文档为 Markdown
allowed-tools	Read, Write, Bash, Glob

需求解析 Skill

目标

把各种格式的原始需求文档转换成统一的 Markdown 格式，确保可读性和可测试性。

输入输出

• 输入：original-requirements/（PDF/DOCX/图片等各种格式）
• 输出：cleaned-requirements/index.md、cleaned-requirements/assets/（图片）

核心原则

1. 忠实还原：不改变原文意思，严格依据原文
2. 格式修复：修复乱码、格式错乱等问题
3. 图片转文字：用详细描述替代图片占位符
4. 上下文连贯：确保文档逻辑清晰

执行流程

1. 解析流程

1. 扫描 original-requirements/ 目录
2. 识别文件类型（PDF/DOCX/图片/纯文本）
3. 调用解析脚本处理文件：
   • PDF/DOCX：调用 .claude/skills/req-parser/scripts/parse_doc.py，脚本会自动解析并生成 Markdown 片段到 chunks/
   • 图片：提取到 assets/，在片段中插入占位符
   • 纯文本：直接复制到 chunks/
4. AI 读取 chunks/ 中的所有 Markdown 片段
5. 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 中不包含占位符，只有图片描述

描述要求：

• 说明图片类型（原型图/流程图/表格截图/示意图）
• 列出图片中的关键元素
• 解释图片的含义和作用

多模态分析引导：

在分析原型图或界面截图时，必须进行深度思考和详细描述：

1. 整体布局识别：描述页面的整体结构（头部、主体、底部等）
2. 交互元素识别：列出所有按钮、输入框、下拉框、链接等交互元素
3. 文本内容提取：准确提取图片中的所有文字内容
4. 业务逻辑推理：根据界面元素推理业务流程和功能意图
5. 状态识别：识别不同状态（正常、禁用、错误、加载等）

描述格式要求：

• 使用结构化的 Markdown 格式（标题、列表、表格）
• 明确标注每个交互元素的位置和功能
• 提取所有可见的文字内容（包括按钮文字、提示文本等）
• 说明页面的业务场景和用户操作流程

3. 格式修复

常见问题及处理：

问题1：乱码

• 根据上下文推理正确内容
• 推理限度：必须有明确依据，不能臆测

问题2：格式错乱

• 修复标题层级
• 修复列表格式
• 修复表格结构

问题3：重复内容

• 保留第一次出现的内容
• 删除重复部分

4. 合并规则

将 chunks/ 下的所有文件合并到 index.md：

1. 按需求文档的逻辑顺序排列
2. 每个文件内容之间用 --- 分隔
3. 添加来源标注：<!-- 来源：文件名.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"]
}