232 lines
7.0 KiB
Markdown
232 lines
7.0 KiB
Markdown
---
|
||
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
|
||
```
|