结构化整理层级型 Excel 表格(.xlsx),处理父子层级关系、向下填充、分组首行显示、筛选优化。当用户上传 Excel 文件并要求「结构化整理」「填充数据」「整理表格」「整理测试用例」「清理表格格式」时使用。
---
name: excel-table-structurer
description: 结构化整理层级型 Excel 表格(.xlsx),处理父子层级关系、向下填充、分组首行显示、筛选优化。当用户上传 Excel 文件并要求「结构化整理」「填充数据」「整理表格」「整理测试用例」「清理表格格式」时使用。
---
# Excel 表格结构化整理
## 核心概念
很多业务表格(如测试用例、项目清单、台账)是**层级结构**的:
```
A列(业务场景) → B列(测试分类) → C列(用例编号) + D/E列(信息)
↓
F列(操作步骤1) + G列(期望结果1)
F列(操作步骤2) + G列(期望结果2)
...
```
处理这类表格的核心操作:
| 操作 | 说明 | 示例 |
|------|------|------|
| **fill-down** | 父层级值向下填充到所有子行 | 业务场景、测试分类每行都可见 |
| **group-header** | 组级信息仅首行显示 | 用例编号/名称仅在用例首行 |
| **fill-down-group** | 组级信息填充到所有行(便于筛选) | 测试结论向下填充,筛选 fail 可看完整步骤 |
## 使用方法
### 快速上手
```python
python3 scripts/restructure.py 输入文件.xlsx 输出文件.xlsx --spec '<JSON_SPEC>'
```
`JSON_SPEC` 定义列的层级角色。
### 分析表格结构
收到用户文件后,先读取数据确认层级关系:
1. 哪些列是父层级(A/B列),需要**fill-down**
2. 哪一列是分组键(C列,定义行组),需要**group-header**
3. 哪些列携带组级信息(H列测试结论),需要**fill-down-group**
4. 哪些列需要额外处理
### JSON_SPEC 参数说明
```jsonc
{
"sheet": "Sheet1", // 工作表名称(可选,默认 Sheet1)
"fill_down_columns": [0, 1], // 父层级列(0-based index)→ 向下填充
"group_key_column": 2, // 分组键列 → 定义行组
"group_header_columns": [2, 3, 4], // 组首行列 → 仅首行显示
"fill_down_group_columns": [7], // 组级填充列 → 所有行显示(便于筛选)
"col_widths": {"0": 20, "1": 18}, // 列宽(可选,key=col_index, value=width)
"freeze_panes": "A2", // 冻结窗格(可选,默认 A2)
"skip_empty_rows": true // 跳过空行(可选,默认 true)
}
```
### 常见场景
**场景一:测试用例整理(本次案例)**
```
A=业务场景, B=测试分类 → fill-down
C=用例编号, D=用例名称, E=前提条件 → group-header(仅有首行)
H=测试结论 → fill-down-group(复制到所有行便于筛选)
```
```json
{
"fill_down_columns": [0, 1],
"group_key_column": 2,
"group_header_columns": [2, 3, 4],
"fill_down_group_columns": [7],
"col_widths": {"0": 20, "1": 18, "2": 14, "3": 35, "4": 40, "5": 55, "6": 45, "7": 12, "8": 35}
}
```
**场景二:项目任务清单**
```
A=项目名称 → fill-down
B=负责人, C=截止日期 → group-header(仅有首行)
D=任务状态 → fill-down-group(所有行可见,便于筛选)
E=任务事项, F=备注 → 每行独有
```
```json
{
"fill_down_columns": [0],
"group_key_column": 1,
"group_header_columns": [1, 2],
"fill_down_group_columns": [3]
}
```
**场景三:台账明细表**
```
A=客户名称 → fill-down
B=合同编号, C=合同金额 → group-header
D=开票状态 → fill-down-group
E=发票号, F=开票日期 → 每行独有
```
```json
{
"fill_down_columns": [0],
"group_key_column": 1,
"group_header_columns": [1, 2],
"fill_down_group_columns": [3]
}
```
## 输出格式
- 首行冻结 + 自动筛选
- 组交替底色(白/浅灰)
- 结论列自动着色(pass=绿, fail=红, 无法测试=黄)
- fail 行左侧红色边框高亮
## 输出说明
运行后脚本返回统计信息:
```json
{"total_rows": 562, "group_count": 119}
```
- `total_rows` = 数据行数(不含表头)
- `group_count` = 分组数量(如测试用例数)
## 使用流程
1. 用户发送 Excel 文件并说明需求
2. 读取文件,分析列层级关系
3. 构造 JSON_SPEC
4. 运行 `restructure.py`
5. 验证输出,将结果文件发送给用户
don't have the plugin yet? install it then click "run inline in claude" again.