# Yy Create Python Script

> 创建基于当前技能 `scripts/` 参考工程的 Python 脚本项目骨架，或按同一结构补齐空白/轻量脚本项目。 当用户需要快速落地命令行脚本、CSV/文件处理流水线、可选并发处理或 PyInstaller 打包脚本时触发，不用于 Web 服务、数据科学实验、单文件代码片段或成熟项目重构。

- Skill: `bulls-cows/yy-create-python-script` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-create-python-script`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-create-python-script/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-create-python-script

---


# yy-create-python-script

## 描述

基于当前技能目录下 `scripts/` 的权威参考工程，创建或补齐 Python 脚本项目。模板由真实 Python 脚本项目脱敏提炼而来，只保留通用脚本工程能力：命令行参数解析、运行路径解析、CSV 读写、可选并发处理、子进程清理、基础测试和 PyInstaller 打包配置。

## 使用场景

- 用户需要新建 Python 脚本项目
- 用户需要生成命令行脚本、批处理脚本或 CSV/文件处理流水线的标准目录结构
- 用户需要在空白或轻量项目中补齐 Python 脚本工程基础设施
- 用户需要脚本支持可选并发处理、外部命令调用或 PyInstaller 打包
- 用户希望复用当前技能 `scripts/` 参考工程中的配置、源码骨架和测试结构

不应触发：

- 用户只需要单个 Python 代码片段
- 用户要创建 FastAPI、Django、Flask 等 Web 服务项目
- 用户要创建 Jupyter、机器学习实验或数据科学分析项目
- 用户要对成熟现有项目做大规模迁移、重构或架构改造
- 用户只是询问 Python、CSV、multiprocessing 或 PyInstaller 的概念和用法

## 指令

### 步骤 1. 确认任务边界与最小输入

收集完成任务所需的最小信息：

- 项目名称，使用英文短横线命名，如 `my-python-script`
- 目标目录
- 脚本用途，用一句话描述输入、处理和输出
- 输入类型，默认使用 CSV 文件
- 是否需要并发处理，默认保留模板能力但不强制启用
- 是否需要调用外部命令，默认保留模板能力但不预置业务命令
- 是否需要 PyInstaller 打包，默认保留打包配置
- 是否执行依赖安装、测试或打包验证
- 目标目录是新目录、空目录还是已有项目目录

**决策分支**：

- **用户已提供关键信息**：直接进入步骤 2
- **仅缺少少量必要信息**：只追问缺失项，不重复确认已明确内容
- **目标目录已有内容但处理边界不明**：先确认只做补齐或对齐，不默认覆盖、删除或清空现有文件

### 步骤 2. 判定生成模式

以当前技能目录下的 `scripts/` 为唯一权威参考，以 `templates/` 中的轻量说明为快速校准材料。

**决策分支**：

- **目标目录不存在或为空目录**：按“新建项目”模式处理，复制参考工程的基础骨架，再做最小定制
- **目标目录已有少量工程文件，且用户明确要求对齐结构**：按“补齐项目”模式处理，只新增缺失文件或修改与本次目标直接相关的文件
- **目标目录已有成熟工程内容**：说明该技能只适合脚手架创建和轻量对齐，要求用户缩小范围后再继续

### 步骤 3. 复制参考工程并过滤无效产物

从 `scripts/` 复制项目骨架时，只保留可作为脚手架的一次性源文件，不复制缓存、安装产物和敏感运行数据。

**决策分支**：

- **新建项目模式**：复制 `scripts/` 中的基础目录、配置文件、源码骨架、测试文件和打包脚本
- **补齐项目模式**：逐项对照 `scripts/`，只补齐缺失的目录、配置和基础源码文件

**禁止复制的内容**：

- `.venv/`
- `venv/`
- `__pycache__/`
- `.pytest_cache/`
- `build/`
- `dist/`
- `htmlcov/`
- `.coverage`
- `.env`
- `*.pyc`
- `*.pyo`
- `*.pyd`
- 其他缓存、临时目录、本地安装产物和业务运行资源

**建议处理方式**：

- `package.json`、`pyproject.toml`、`requirements.txt`、`build.ps1`、`.gitignore`、`.editorconfig`、`README.md` 直接以 `scripts/` 同名文件为基准
- `package.json` 必须包含 `npm run lint` 和 `npm run ready` 对应脚本，其中 `npm run lint` 用于格式化代码和执行测试用例，`npm run ready` 用于安装依赖包
- `*.spec` 保留为 PyInstaller 打包入口，并根据项目名称做最小重命名
- `main.py` 保留为可冻结入口，确保 Windows 打包时执行 `multiprocessing.freeze_support()`
- `resources/` 只保留 `.gitkeep` 或用户明确需要的模板资源，不写入真实业务数据

### 步骤 4. 生成目录结构与基础配置

确保目标项目至少具备与参考工程一致的基础目录结构：

```text
project-name/
├── main.py
├── package.json
├── pyproject.toml
├── requirements.txt
├── build.ps1
├── resources/
├── src/
│   └── python_script_template/
└── tests/
```

配置文件处理规则：

- 复制 `scripts/pyproject.toml` 后，仅调整项目名称、描述、脚本入口和用户明确要求的元数据
- 复制 `scripts/package.json` 后，仅调整包名，并保留 `lint` 与 `ready` 两个命令；`lint` 必须执行代码格式化和测试用例，`ready` 必须安装依赖包
- 项目名称使用 kebab-case，包目录和导入路径使用 snake_case
- 复制 `scripts/requirements.txt`，默认保留 PyInstaller 构建依赖
- 复制 `scripts/build.ps1` 和 `scripts/*.spec` 后，同步替换可执行文件名称、入口路径和包目录名称
- 复制 `.gitignore` 与 `.editorconfig`，保持基础缓存和构建产物过滤规则
- 若用户需要环境变量文件，只创建 `.env.example`，不写入真实密钥、真实路径或真实业务参数

### 步骤 5. 生成脚本流水线源码

优先复制 `scripts/src/` 和 `scripts/tests/` 的基础文件，再围绕用户输入做最小定制。

必须保留的通用能力：

- `main.py` 作为冻结入口，负责插入 `src/` 到 `sys.path` 并调用包入口
- `src/<package_name>/__main__.py` 作为统一业务入口，串联参数解析、输入读取、记录处理、输出写入和退出码控制
- `read_csv()` 支持常见 CSV 编码回退，不默认假设单一编码
- `run_rows_serial()` 与 `run_rows_parallel()` 同时保留，便于按任务规模启用并发
- `build_parallel_batches()` 按工作目录键分批，避免同一工作目录的记录被并发处理
- `run_process_with_cleanup()` 支持超时清理子进程，避免外部命令残留
- `tests/` 保留运行路径、CSV 处理和批次分配的基础测试

源码定制规则：

- 将 `python_script_template` 包名替换为项目名称对应的 snake_case 包名
- 将 README、CLI 描述、默认输出文件名和示例命令替换为用户提供的项目用途
- 若用户未提供具体处理逻辑，保留模板中的示例转换逻辑，不编造业务规则
- 若用户提供外部命令调用需求，只更新命令参数、环境变量和结果解析的最小必要部分

### 步骤 6. 安装依赖并执行验证

在目标项目根目录执行安装和验证，默认使用当前环境可用的 Python。

**决策分支**：

- **用户未禁止安装与验证**：优先执行 `npm run lint`，用统一命令完成格式化和测试
- **用户要求安装依赖或准备环境**：执行 `npm run ready` 安装依赖包
- **用户要求验证打包能力**：先执行依赖安装，再执行 `./build.ps1` 或等价 PyInstaller 命令
- **用户明确要求跳过安装或当前环境不适合创建虚拟环境**：跳过命令执行，并在结果中说明未验证项

验证时保持以下约束：

- 不默认执行真实业务输入文件
- 不默认运行外部命令、部署、发布或推送操作
- 不为验证而写入真实业务数据、真实密钥或机器专属路径
- `npm run lint` 是统一验证入口，必须包含格式化代码和执行测试用例；无法执行 npm 命令时，回退执行 `python -m unittest discover -s tests` 并说明原因

### 步骤 7. 补齐 lint 支持

在项目创建或补齐完成后，检测当前环境是否可用 `yy-enable-lint` 技能，并在可用时触发该技能为项目添加 `npm run lint` 支持。

**决策分支**：

- **当前环境可用 `yy-enable-lint`**：在目标项目目录触发 `yy-enable-lint`，使其按项目技术栈补齐 lint 支持
- **当前环境不可用 `yy-enable-lint`**：不阻塞项目生成，跳过 lint 补齐
- **用户明确要求不补齐 lint 支持**：跳过，仅在交付结果中说明
- **`yy-enable-lint` 执行失败**：记录失败原因，不扩大处理范围

### 步骤 8. 输出结果

输出以下内容：

1. 项目结构，使用 `tree` 或 `text` 代码块展示
2. 本次创建或补齐的核心文件与目录
3. 验证结果，区分已执行、跳过和失败项
4. 关键注意事项，包括包名映射、入口文件、打包方式和后续替换示例处理逻辑的位置

## 安全边界

- 不修改当前技能目录下的 `scripts/` 参考工程本身
- 不删除目标目录中的无关现有文件
- 未获用户明确授权时，不覆盖与本次目标无关的已有实现
- 不复制真实业务 CSV、日志、密钥、打包产物或机器专属路径
- 不执行部署、发布、推送或其他与脚手架创建无关的高影响操作

## 相关资源

- `templates/project-structure.md`：Python 脚本项目结构轻量说明，权威来源为 `scripts/`
- `scripts/`：完整参考工程，也是目录结构、配置、基础源码、测试和打包脚本的唯一权威来源