lanyuanxiaoyao/Skill
1
0
Fork 0
Code Activity
Files
efd7f21a28406aa37cc90922694f025c2fd4190d
Skill/skills/python-runner/SKILL.md
lanyuanxiaoyao efd7f21a28 优化python-runner
2026-02-06 17:39:36 +08:00

7.0 KiB
Raw Blame History

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

UV Python Runner Skill

指导大模型使用uv运行Python脚本，无需预安装依赖，保持环境整洁。

Purpose

必需依赖: 此skill必需uv工具，不兼容其他Python运行方式。

利用uv隔离环境特性：

  • 自动管理虚拟环境和依赖
  • 避免系统Python污染
  • 支持用户现有脚本（无需修改）
  • 自动解析依赖并使用--with传递
  • 智能检测uv项目，复用项目环境
  • 跨平台兼容（Windows/macOS/Linux）

重要: 如果uv未安装，立即停止任务并引导用户安装。不要使用python、pip、poetry、venv等替代工具。

When to Use

任何Python处理任务都应使用此skill。

典型场景

  • 数据处理: pandas, numpy, scipy / CSV/JSON/YAML转换 / 统计分析
  • API交互: HTTP请求（requests, httpx） / API数据检索
  • 文件操作: 重命名、批量处理 / pathlib, shutil操作
  • 科学计算: numpy, scipy / matplotlib, plotly可视化
  • 系统工具: logging / configparser / tqdm, rich进度跟踪

不适用场景

  • ✗ 需要用户交互（input()）
  • ✗ 需要持久化环境（每次都是新环境）
  • ✗ 需要命令行参数
  • ✗ 需要从stdin读取

Automatic Dependency Parsing

分析import语句，提取外部包名，排除标准库。

标准库（排除）

核心: os, sys, pathlib, shutil, json, csv, re, datetime, math 网络: http.client, urllib, socket, io, logging 高级: itertools, functools, typing, dataclasses, enum

解析规则

  1. 提取：import pandas → pandas, from numpy import array → numpy
  2. 排除标准库
  3. 去重

示例

import pandas as pd
import numpy as np
import json  # 标准库，排除
from pathlib import Path  # 标准库，排除

# 结果: [pandas, numpy]

Smart Project Detection

检测命令

uv sync --dry-run

判断逻辑

  • Exit code 0 → uv项目
  • 非零退出码 → 非uv项目
  • 失败 → 回退到非uv项目模式（使用--with），不阻塞执行

Path Handling

三层逻辑

  1. 用户指定存储路径 → 写入指定路径
  2. 用户指定现有脚本 → 直接执行
  3. 未指定 → 临时文件
# 临时文件获取
temp_file_path=$(uv run ./script/get_temp_path.py)

Execution Commands

场景 命令
uv项目 uv run <script_path>
非uv+有依赖 uv run --with pkg1 --with pkg2 <script_path>
非uv+无依赖 uv run <script_path>

特点:

  • uv项目：使用项目环境，无--with
  • 非uv有依赖：每个--with创建隔离环境
  • 非uv无依赖：使用标准Python环境

Workflow

步骤1: 解析依赖（见"Automatic Dependency Parsing"）

步骤2: 检测项目（见"Smart Project Detection"）

步骤3: 确定路径（见"Path Handling"）

步骤4: 构造并执行命令（见"Execution Commands"）

执行命令并捕获输出。

Error Handling

uv未安装

检测: uv命令失败

错误消息:

uv not found

此skill依赖uv工具运行Python脚本。

请安装uv: https://docs.astral.sh/uv/getting-started/installation/

安装命令示例：
  curl -LsSf https://astral.sh/uv/install.sh | sh    # Linux/macOS
  powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

重要提示:

  • 立即停止任务，等待用户安装uv后再继续
  • 不要尝试使用：python, pip, poetry, venv, virtualenv等
  • 不要自动安装uv
  • 用户安装uv完成后，可以重新执行任务

操作: 立即停止所有执行，等待用户安装uv

其他错误

场景 错误消息 操作
项目检测失败 回退到非uv模式，使用--with 警告后继续
依赖解析不准确 依赖可能不完整
Traceback: [traceback]		 停止，保留脚本调试
语法错误 Python语法错误: [描述]
文件:
行号: 		停止
路径权限问题 无法写入:
建议: 使用临时文件模式		 回退到临时文件

Examples

示例1: 数据分析

import pandas as pd
import numpy as np

df = pd.read_csv('data.csv')
print(f"形状: {df.shape}")
print(df.describe())

执行: uv run --with pandas --with numpy /tmp/script_xxx.py

示例2: API交互

import requests

resp = requests.get('https://api.github.com/repos/python/cpython')
data = resp.json()
print(f"仓库: {data['full_name']}, Stars: {data['stargazers_count']}")

执行: uv run --with requests /tmp/script_xxx.py

示例3: 文件操作

import os
import glob

for i, file in enumerate(glob.glob('*.txt')):
    os.rename(file, f"file_{i:03d}.txt")

执行: uv run /tmp/script_xxx.py（无依赖）

示例4: uv项目内执行

import pandas as pd
from my_project import helper

df = pd.read_csv('data.csv')
result = helper.process(df)
print(result)

执行: uv run scripts/data_process.py（使用项目环境）

示例5: 用户指定路径

import requests

resp = requests.get('https://api.example.com/data')
print(f"处理完成: {len(resp.json())} 条")

执行: uv run --with requests scripts/api_analyzer.py（写入指定路径）

Notes

为什么使用uv？

特性 优势
环境隔离 不污染系统Python
自动依赖 --with语法，无需pip install
快速启动 比venv快10-100倍
项目集成 自动检测uv项目
零配置 开箱即用，无需PEP 723

最佳实践

  1. 依赖解析: 排除标准库；失败时检查遗漏依赖；复杂项目用uv项目模式
  2. 路径: 用户指定优先；临时文件用于自主生成；跨平台由辅助脚本保证
  3. 错误: 预期错误脚本内处理；意外错误立即停止；检测失败自动回退
  4. 清理: 临时文件使用系统目录，自动清理，失败时手动删除

限制

  • ✗ 不支持命令行参数、stdin输入、持久化环境
  • ✗ 使用uv默认Python版本（项目可在pyproject.toml指定）
  • ✗ 依赖解析可能不完整（动态导入、条件导入可能遗漏）
  • ✗ 项目检测可能误判（网络问题导致回退）

uv工具要求

  • uv是此skill的必需依赖，不可替代
  • 不支持: python, pip, poetry, venv, virtualenv
  • 如果检测到uv未安装，必须停止任务并引导用户安装
  • 不要尝试使用替代方案或自动安装uv

Workflow Summary

完整流程:

  1. 解析import语句，提取外部包名（排除标准库）
  2. 执行uv sync --dry-run检测项目
  3. 确定脚本路径（用户指定/现有脚本/临时文件）
  4. 构造执行命令（根据项目类型和依赖）
  5. 执行并捕获输出

关键特点:

  • 自动依赖解析：分析import自动提取
  • 智能项目检测：自动识别uv项目
  • 灵活路径：支持指定/现有/临时三种模式
  • 跨平台：自动适配Windows/macOS/Linux
  • 环境隔离：独立虚拟环境
View Git Blame Copy Permalink