优化python runner的skill名称

2026-02-05 09:31:24 +08:00
parent 081278af74
commit a3169930fd
2 changed files with 1 additions and 1 deletions
--- a/skills/python-runner/SKILL.md
+++ b/skills/python-runner/SKILL.md
@@ -0,0 +1,372 @@
+---
+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. 系统自动清理临时文件
+```
+
+**关键特点：**
+
+- 跨平台自动适配
+- 环境隔离
+- 自动依赖管理
+- 临时文件直接返回路径，无需手动拼接
+- 系统自动清理临时文件，无需手动管理
--- a/skills/python-runner/script/get_temp_path.py
+++ b/skills/python-runner/script/get_temp_path.py
@@ -0,0 +1,12 @@
+# /// script
+# dependencies = []
+# ///
+
+import tempfile
+
+temp_dir = tempfile.gettempdir()
+temp_file_path = tempfile.NamedTemporaryFile(
+    mode="w", suffix=".py", prefix="uv_script_", dir=temp_dir, delete=False
+).name
+
+print(temp_file_path)