2026-01-16 23:05:30 +08:00

7.0 KiB

Raw Blame History

name	description
managing-scripts	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

编写数据分析脚本时的通用化流程：

读取 ./scripts/README.md 检查是否有可复用的现成脚本
如有合适脚本，优先复用
如需编写新脚本，设计通用化方案而非解决单一问题
保存到 ./scripts/ 并更新 README

Instructions

使用前检查

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

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

编写通用化脚本

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

1. 识别问题模式

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

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

2. 参数化设计

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

# ❌ 不通用：硬编码特定字段
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. 使用命令行参数

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. 配置文件支持

复杂逻辑使用配置文件：

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

保存新脚本

脚本验证成功后：

使用通用性强的命名：
- ✅ aggregate_data.py、convert_format.py、clean_dataset.py
- ❌ analyze_sales_2024.py、fix_import_error.py
保存到 ./scripts/ 文件夹
在 ./scripts/README.md 添加说明，包含：
- 通用功能描述（描述解决的问题类型，非具体业务）
- 使用方法（含所有参数说明）
- 输入/输出格式
- 使用示例
- 依赖要求

修改现有脚本

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

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

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

通用脚本模板示例：

#!/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

7.0 KiB Raw Blame History Unescape Escape