---
name: managing-scripts
description: Manages shared scripts repository for reusable data analysis tools. Check scripts/README.md before writing, design generalized scripts with parameters, and keep documentation in sync.
---

# Managing Scripts

管理可复用的数据分析脚本资源库，通过通用化设计最大化脚本复用价值。

## Quick Start

编写数据分析脚本时的通用化流程：
1. 读取 `./scripts/README.md` 检查是否有可复用的现成脚本
2. 如有合适脚本，优先复用
3. 如需编写新脚本，**设计通用化方案**而非解决单一问题
4. 保存到 `./scripts/` 并更新 README

## Instructions

### 使用前检查

当用户请求任何数据处理/分析任务时：

1. 检查 `./scripts/README.md` 是否存在
2. 查找可处理**此类问题**的脚本（非完全匹配即可）
3. 现有脚本可通过参数调整满足需求时，优先复用
4. 告知用户使用的是现成脚本

### 编写通用化脚本

核心原则：**解决一类问题，而非单一问题**

#### 1. 识别问题模式

在编写脚本前，分析当前请求属于哪类通用模式：

| 问题类型 | 通用模式 | 可参数化项 |
|---------|---------|-----------|
| 数据转换 | 格式A → 格式B | 输入文件、输出格式、字段映射 |
| 数据分析 | 统计/聚合/可视化 | 数据源、分析维度、输出类型 |
| 数据清洗 | 去重/填充/过滤 | 规则配置、阈值参数 |
| 文件操作 | 批量处理文件 | 文件路径、匹配模式、操作类型 |

#### 2. 参数化设计

将硬编码值改为可配置参数：

```python
# ❌ 不通用：硬编码特定字段
def analyze_sales():
    df = pd.read_excel("sales_data.xlsx")
    result = df.groupby("region")["amount"].sum()

# ✅ 通用化：参数化输入
def analyze_data(input_file, group_by_column, aggregate_column, method="sum"):
    """
    通用数据聚合分析
    :param input_file: 输入文件路径
    :param group_by_column: 分组列名
    :param aggregate_column: 聚合列名
    :param method: 聚合方法 (sum/mean/count/etc)
    """
    df = pd.read_excel(input_file)
    return df.groupby(group_by_column)[aggregate_column].agg(method)
```

#### 3. 使用命令行参数

```python
import argparse

def main():
    parser = argparse.ArgumentParser(description="通用数据聚合工具")
    parser.add_argument("--input", required=True, help="输入文件路径")
    parser.add_argument("--output", help="输出文件路径")
    parser.add_argument("--group-by", required=True, help="分组列名")
    parser.add_argument("--agg-column", required=True, help="聚合列名")
    parser.add_argument("--method", default="sum", help="聚合方法")
    args = parser.parse_args()
    # ... 处理逻辑
```

#### 4. 配置文件支持

复杂逻辑使用配置文件：

```yaml
# config.yaml
transformations:
  - column: "date"
    action: "parse_format"
    params: {"format": "%Y-%m-%d"}
  - column: "amount"
    action: "fill_na"
    params: {"value": 0}
```

### 保存新脚本

脚本验证成功后：

1. 使用**通用性强的命名**：
   - ✅ `aggregate_data.py`、`convert_format.py`、`clean_dataset.py`
   - ❌ `analyze_sales_2024.py`、`fix_import_error.py`

2. 保存到 `./scripts/` 文件夹

3. 在 `./scripts/README.md` 添加说明，包含：
   - **通用功能描述**（描述解决的问题类型，非具体业务）
   - 使用方法（含所有参数说明）
   - 输入/输出格式
   - 使用示例
   - 依赖要求

### 修改现有脚本

修改 `./scripts/` 下的脚本时：

1. 保持/增强通用性，避免收缩为特定用途
2. 同步更新 README.md 文档
3. 在变更日志中记录修改内容

## Examples

**场景：用户请求分析销售数据**

```
用户：帮我分析这个 Excel 文件，按地区统计销售额

思考过程：
1. 这是一个"数据聚合"问题，属于通用模式
2. 检查 scripts/README.md 是否有聚合工具
3. 如没有，创建通用聚合脚本 aggregate_data.py
4. 支持参数：--input、--group-by、--agg-column、--method
5. 用户调用：python scripts/aggregate_data.py \
              --input data.xlsx --group-by region --agg-column amount
```

**通用脚本模板示例：**

```python
#!/usr/bin/env python3
"""
通用数据聚合工具
支持按任意列分组，对任意列进行聚合统计
"""

import argparse
import pandas as pd

def aggregate_data(input_file, group_by, agg_column, method="sum", output=None):
    """通用聚合函数"""
    # 根据文件扩展名选择读取方法
    ext = input_file.split(".")[-1]
    read_func = getattr(pd, f"read_{ext}", pd.read_csv)
    df = read_func(input_file)

    # 执行聚合
    result = df.groupby(group_by)[agg_column].agg(method)

    # 输出
    if output:
        result.to_csv(output)
    return result

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="通用数据聚合工具")
    parser.add_argument("--input", "-i", required=True, help="输入文件路径")
    parser.add_argument("--group-by", "-g", required=True, help="分组列名")
    parser.add_argument("--agg-column", "-a", required=True, help="聚合列名")
    parser.add_argument("--method", "-m", default="sum",
                       choices=["sum", "mean", "count", "min", "max"],
                       help="聚合方法")
    parser.add_argument("--output", "-o", help="输出文件路径")
    args = parser.parse_args()

    aggregate_data(args.input, args.group_by, args.agg_column,
                   args.method, args.output)
```

## Guidelines

### 通用化设计原则

- **抽象思维**：识别问题的本质模式，而非表面细节
- **参数化一切**：任何可能变化的值都应可配置
- **避免业务术语**：使用通用技术术语（如 "group_by" 而非 "region"）
- **支持扩展**：预留扩展点，便于未来增加新功能
- **提供默认值**：合理默认值降低使用门槛

### 命名规范

| 类型 | 推荐 | 避免 |
|-----|------|------|
| 脚本名 | `aggregate_data.py` | `sales_analysis.py` |
| 参数名 | `--group-by` | `--region` |
| 函数名 | `transform_data()` | `fix_sales_format()` |

### 文档规范

README 条目应说明：
- **解决哪类问题**（非具体业务场景）
- **所有参数及默认值**
- **支持的输入格式**
- **使用示例**（至少2个不同场景）

### 何时创建新脚本

创建新脚本当：
- 现有脚本无法通过参数调整满足需求
- 问题属于新的通用模式
- 预计该场景会重复出现

### 何时修改现有脚本

修改现有脚本当：
- 增强通用性（添加新参数/配置）
- 修复 bug 但不破坏现有接口
- 扩展功能范围

## Directory Structure

```
./scripts/
├── README.md              # 脚本目录和使用说明（必须存在）
├── aggregate_data.py      # 通用聚合工具
├── convert_format.py      # 格式转换工具
├── clean_dataset.py       # 数据清洗工具
└── config/                # 可选：配置文件目录
    └── templates.yaml
```