Skill/skills/python-runner/SKILL.md

---
name: python-runner
description: Any task that requires Python processing should use this skill.
---

# UV Python Runner Skill

通用型工具skill，指导大模型使用uv运行Python脚本来处理各种任务，无需预安装依赖，保持系统环境整洁。

## Purpose

指导大模型在需要执行Python脚本时，利用uv的隔离环境特性来：

- 自动管理虚拟环境和依赖
- 避免在系统Python环境安装依赖包
- 使用临时文件，执行完成后立即清理
- 保持跨平台兼容性（Windows/macOS/Linux）

## When to Use

大模型**任何需要用Python处理的任务**都应该使用此skill。

### 典型场景

**数据处理**

- pandas, numpy, scipy等数据分析
- CSV, JSON, YAML文件转换和处理
- 数据清洗、统计分析、可视化

**API交互**

- HTTP请求和测试（requests, httpx, aiohttp）
- API数据检索和验证
- 身份验证和会话管理

**文件操作**

- 文件重命名、批量处理
- 路径操作（pathlib, shutil, os）
- 文件格式转换、内容替换

**科学计算**

- 数学计算（numpy, scipy）
- 符号计算（sympy）
- 数据可视化（matplotlib, plotly）

**系统工具**

- 日志处理（logging）
- 配置管理（configparser）
- 进度跟踪（tqdm, rich）

### 不适用场景

- ✗ 需要用户交互的脚本（input(), input()等）
- ✗ 需要持久化环境（每次都是新的隔离环境）
- ✗ 需要传递命令行参数（所有参数嵌入脚本）
- ✗ 需要从stdin读取输入

## Workflow

### 步骤1：生成符合PEP 723的Python脚本

在脚本顶部添加内联元数据块：

```python
# /// script
# dependencies = [
#   "package-name-1",
#   "package-name-2",
# ]
# ///

import package1
import package2

# 你的代码...
```

**规则：**

- ✓ 总是包含`# /// script`块
- ✓ 列出所有**外部**依赖
- ✓ 如果没有依赖：`# dependencies = []`
- ✓ 不指定版本（让uv使用最新）
- ✓ 不指定Python版本（使用uv默认）

**示例：**

有外部依赖：

```python
# /// script
# dependencies = [
#   "pandas",
#   "numpy",
# ]
# ///

import pandas as pd
import numpy as np

data = pd.read_csv('data.csv')
print(data.describe())
```

仅使用标准库：

```python
# /// script
# dependencies = []
# ///

import os
import json

with open('data.json') as f:
    data = json.load(f)
print(f"Keys: {list(data.keys())}")
```

### 步骤2：获取临时脚本文件路径

调用辅助脚本创建临时Python脚本文件并获取文件路径（使用相对路径）：

```bash
temp_file_path=$(uv run ./script/get_temp_path.py)
```

**输出：**

- 临时Python脚本文件的完整路径
  - Linux/macOS: `/tmp/uv_script_xxx.py`
  - Windows: `C:\Users\<username>\AppData\Local\Temp\uv_script_xxx.py`

**说明：**

- 辅助脚本已在临时目录创建了空的Python脚本文件
- 大模型直接得到脚本文件路径
- 无需拼接路径，直接使用返回的文件路径

### 步骤3：写入PEP 723脚本内容

使用大模型的文件创建工具（Write等）在步骤2返回的脚本文件路径中写入PEP 723脚本内容。

### 步骤4：使用uv执行

```bash
uv run <temp_file_path>
```

## Error Handling

### 场景1：uv未安装

**错误消息：**

```
uv not found

无法找到uv命令。请先安装uv：
https://docs.astral.sh/uv/getting-started/installation/
```

**操作：** 停止任务

### 场景2：Python语法错误

**检测：** 在创建临时文件之前检测语法错误

**错误消息：**

```
Python语法错误：[错误描述]
文件：<script_path>
行号：<line_number>
错误：<python_error_message>

请检查Python代码的语法正确性。
```

### 场景3：依赖解析失败

**错误消息：**

```
依赖解析失败

uv错误输出：
[完整的uv错误信息]

临时文件保留用于调试：<temp_file_path>
```

### 场景4：脚本运行时错误

**错误消息：**

```
脚本执行失败

Traceback (most recent call last):
[完整的Python traceback]

临时文件保留用于调试：<temp_file_path>
```

## Examples

### 示例1：数据分析

**场景：** 分析CSV文件的统计信息

```python
# /// script
# dependencies = [
#   "pandas",
# ]
# ///

import pandas as pd

df = pd.read_csv('data.csv')
print(f"数据形状: {df.shape}")
print(f"描述统计:\n{df.describe()}")
```

**执行流程：**

1. 调用辅助脚本获取临时目录
2. 构造临时文件路径
3. 创建文件并写入上述内容
4. 执行：`uv run <temp_file_path>`
5. 捕获输出

### 示例2：API交互

**场景：** 从GitHub API获取仓库信息

```python
# /// script
# dependencies = [
#   "requests",
# ]
# ///

import requests

resp = requests.get('https://api.github.com/repos/python/cpython')
data = resp.json()

print(f"仓库: {data['full_name']}")
print(f"Star数: {data['stargazers_count']}")
print(f"描述: {data['description'][:100]}...")
```

### 示例3：文件操作

**场景：** 批量重命名文件

```python
# /// script
# dependencies = []
# ///

import os
import glob
from pathlib import Path

for i, file in enumerate(glob.glob('*.txt')):
    new_name = f"file_{i:03d}.txt"
    os.rename(file, new_name)
    print(f"✓ {file} → {new_name}")
```

## Notes

### 为什么使用uv？

| 特性         | 优势                                             |
| ------------ | ------------------------------------------------ |
| 环境隔离     | 不污染系统Python环境，每个脚本都有独立的虚拟环境 |
| 自动依赖管理 | 无需手动pip install，uv自动解析和安装依赖        |
| 快速启动     | 比传统venv快10-100倍，快速创建和销毁环境         |
| 标准兼容     | 支持PEP 723格式，官方Python规范                  |
| 零配置       | 开箱即用，无需额外配置或初始化                   |

### 最佳实践

1. **总使用内联元数据**

   ```python
   # 即使没有依赖也要声明
   # dependencies = []
   ```

2. **使用最新版本**
   - 不指定版本约束
   - 让uv自动选择
   - 保持依赖更新和安全

3. **错误处理**
   - 脚本内部处理预期的错误（try-except）
   - 严格模式处理意外的错误（立即停止）

4. **清理资源**
   - 临时文件使用系统临时目录（/tmp 或 Windows Temp）
   - 系统会自动清理临时文件，无需手动管理
   - 失败时可手动删除临时文件调试

### 限制

- ✗ 不支持命令行参数
  - 所有参数必须嵌入在脚本中
  - 不支持`uv run script.py arg1 arg2`

- ✗ 不支持stdin输入
  - 不支持`echo "code" | uv run -`
  - 所有数据必须硬编码或从文件读取

- ✗ 不支持持久化环境
  - 每次执行都是新的临时环境
  - 不缓存或保留虚拟环境

- ✗ 不支持自定义Python版本
  - 使用uv的默认Python版本
  - 不在元数据中指定`requires-python`

- ✗ 不支持复杂的依赖约束
  - 只支持简单的包名
  - 不支持版本范围（`>=1.0,<2.0`）
  - 不支持Git URL或本地包

## Dependencies

### 必需依赖

- **uv** (https://docs.astral.sh/uv/)
  - Python包管理器和运行器
  - 支持PEP 723内联元数据格式
  - 提供环境隔离和自动依赖管理

### 可选依赖

无

## Workflow Summary

完整的典型工作流：

```bash
# 1. 获取临时脚本文件路径
temp_file_path=$(uv run skills/uv-python-runner/script/get_temp_path.py)

# 2. 写入PEP 723脚本内容
# 使用大模型的Write工具在 temp_file_path 中写入...

# 3. 执行脚本
uv run $temp_file_path

# 4. 系统自动清理临时文件
```

**关键特点：**

- 跨平台自动适配
- 环境隔离
- 自动依赖管理
- 临时文件直接返回路径，无需手动拼接
- 系统自动清理临时文件，无需手动管理