Markdown 解析功能说明

概述

generate_excel.py 现在支持从 SOP Markdown 文件自动解析任务数据，无需手动维护硬编码的任务列表。这使得文档和 Excel 报告保持同步变得更加简单。

快速开始

基本用法

# 从 markdown 文件生成 Excel
python3 generate_excel.py --markdown sop-003-product-creation-e2e.md

这将： 1. 解析 markdown 文件中的所有任务 2. 提取任务标题、前置条件和表格数据 3. 生成 Excel 文件（文件名自动从 SOP 编号提取，如：SOP-003.xlsx）

自定义输出文件名

python3 generate_excel.py \
  --markdown sop-001-customer-creation-e2e.md \
  --output "客户创建测试报告"

支持的 Markdown 格式

脚本能够解析符合以下格式的 markdown 文件：

1. 文档标题

# SOP-XXX：标题名称
  • 第一行的 # 标题会被提取作为文档标题
  • SOP 编号（如 SOP-003）会被自动识别并用作默认文件名

2. 任务标题

### 任务 T1：环境与账号验证
  • 任务必须以 ### 任务 T{编号}： 开头
  • 支持任意数量的任务（T1, T2, T3, T4, T5, ...）
  • 任务名称会被自动提取

3. 前置条件/入口信息

入口：`http://localhost:3000/crm`

或

前置条件：T1 成功且当前在产品列表
  • 在任务标题下方的入口或前置条件会被自动识别
  • 这些信息会被添加到 Excel 中的任务标题下方

4. 任务表格

| Action Steps | Input / Payload | 预期结果 | 验证方式 | 证据 | 状态 | 下游任务 |
|--------------|----------------|----------|----------|------|------|----------|
| 步骤1：打开浏览器 | — | 浏览器启动成功 | 浏览器窗口打开 | 屏幕截图 | `[ ]` | 步骤 2 |
| 步骤2：输入 URL | `http://localhost:3000/crm` | 页面开始加载 | 地址栏显示正确 URL | 屏幕截图 | `[ ]` | 步骤 3 |

表格要求： - 必须包含 7 列（如上所示） - 列的顺序必须保持一致 - 状态列（[ ] 或 [x]）会被自动转换为可交互的复选框

解析规则

1. Markdown 格式清理

脚本会自动清理以下 markdown 格式标记： - 反引号（`）：http://localhost:3000 → http://localhost:3000 - 代码块标记 - 其他 markdown 格式符号

2. 特殊符号处理

  • —（破折号）会被转换为空字符串
  • 多个空格会被规范化

3. 截图路径生成

脚本会自动为每个步骤生成截图路径：

screenshots/{任务ID}-step{步骤序号}.png

例如： - T1 步骤1：screenshots/T1-step1.png - T2 步骤3：screenshots/T2-step3.png

完整示例

输入：Markdown 文件

# SOP-003：CRM 产品创建 E2E 测试

## 任务矩阵（Excel Checklist 行模板）

### 任务 T1：环境与账号验证

入口：`http://localhost:3000/crm`

| Action Steps | Input / Payload | 预期结果 | 验证方式 | 证据 | 状态 | 下游任务 |
|--------------|----------------|----------|----------|------|------|----------|
| 步骤1：打开浏览器 | — | 浏览器启动成功 | 浏览器窗口打开 | 屏幕截图 | `[ ]` | 步骤 2 |
| 步骤2：输入 URL | `http://localhost:3000/crm` | 页面开始加载 | 地址栏显示正确 URL | 屏幕截图 | `[ ]` | T2 |

### 任务 T2：新建产品 UI 操作

前置条件：T1 成功且当前在产品列表

| Action Steps | Input / Payload | 预期结果 | 验证方式 | 证据 | 状态 | 下游任务 |
|--------------|----------------|----------|----------|------|------|----------|
| 步骤1：点击创建按钮 | — | 弹出产品创建对话框 | 对话框显示 | 屏幕截图 | `[ ]` | 步骤 2 |

输出：Excel 文件结构

  1. 测试汇总表
  2. 标题：SOP-003：CRM 产品创建 E2E 测试 - 进度汇总
  3. 包含所有任务的概览

  4. 每个任务 ID 可点击跳转到详细表

  5. 任务详细表（每个任务一个工作表）

  6. 工作表名称：T1-环境与账号验证、T2-新建产品UI操作 等
  7. 包含该任务的所有步骤
  8. 步骤间和任务间可通过超链接跳转

批量生成

可以使用循环批量生成多个 SOP 的 Excel：

# 生成所有基础功能 SOP
for sop in sop-001-*.md sop-002-*.md sop-003-*.md; do
    if [ -f "$sop" ]; then
        echo "生成: $sop"
        python3 generate_excel.py --markdown "$sop"
    fi
done

或者生成所有 SOP：

# 生成目录下所有 SOP
for sop in sop-*.md; do
    if [ -f "$sop" ]; then
        python3 generate_excel.py --markdown "$sop"
    fi
done

向后兼容

如果不指定 --markdown 参数，脚本仍然会使用硬编码的默认数据：

# 使用默认硬编码数据
python3 generate_excel.py

这确保了与旧版本的完全兼容。

故障排查

问题：无法找到任务

可能原因： - 任务标题格式不正确 - 必须是 ### 任务 T{编号}：{标题} 格式

解决方法： - 确保任务标题以 ### 任务 开头 - 确保有空格和正确的标点符号

问题：表格解析失败

可能原因： - 表格列数不足 7 列 - 表格分隔线不正确

解决方法： - 确保表格有完整的 7 列 - 确保表头和分隔线格式正确

问题：生成的 Excel 中某些步骤缺失

可能原因： - 表格格式不标准 - 某些行的列数不一致

解决方法： - 检查 markdown 表格的每一行是否都有 7 列 - 确保使用 | 正确分隔每一列

相关文档