# Req Parser

> 解析原始需求文档为 Markdown

- Skill: `chyax98/req-parser` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add chyax98/req-parser`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chyax98/req-parser/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: chyax98 (https://skillmd.com/u/chyax98)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/chyax98/req-parser

---


# 需求解析 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`（同时替换图片占位符为描述）

**解析脚本调用**：

```bash
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：图片处理

**解析时生成**：
```markdown
用户登录流程如下：

<!-- image: login-flow.png -->
```

**AI 读取后替换为**：
```markdown
用户登录流程如下：

[流程图描述]
这是一个登录流程图，包含以下步骤：
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**：
```markdown
<!-- 来源：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

```bash
uv run .claude/skills/req-parser/scripts/parse_doc.py \
  --input-dir <输入目录> \
  --output-dir <输出目录> \
  [--force]  # 强制覆盖已有文件
```

**返回值**：
- 0: 成功
- 1: 部分失败（有文件无法解析）
- 2: 完全失败

**输出**：解析统计 JSON
```json
{
  "total": 5,
  "success": 4,
  "failed": 1,
  "failed_files": ["encrypted.pdf"]
}
```