lanyuanxiaoyao/Skill
1
0
Fork 0
Code Activity
Files
9e42c2ccd901ee35556045bd81b4ee17bd037c2e
Skill/skills/python-runner/SKILL.md

7.6 KiB
Raw Blame History

name, description
name description
python-runner 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脚本

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

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

import package1
import package2

# 你的代码...

规则：

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

示例：

有外部依赖：

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

import pandas as pd
import numpy as np

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

仅使用标准库：

# /// script
# dependencies = []
# ///

import os
import json

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

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

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

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执行

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文件的统计信息

# /// 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获取仓库信息

# /// 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：文件操作

场景： 批量重命名文件

# /// 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. 总使用内联元数据

    # 即使没有依赖也要声明
# 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

完整的典型工作流：

# 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. 系统自动清理临时文件

关键特点：

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