优化python-runner

skills/python-runner/SKILL.md

@@ -5,368 +5,243 @@ description: Any task that requires Python processing should use this skill.
 
 # UV Python Runner Skill
 
-通用型工具skill，指导大模型使用uv运行Python脚本来处理各种任务，无需预安装依赖，保持系统环境整洁。
+指导大模型使用uv运行Python脚本，无需预安装依赖，保持环境整洁。
 
 ## Purpose
 
-指导大模型在需要执行Python脚本时，利用uv的隔离环境特性来：
+**必需依赖**: 此skill必需uv工具，不兼容其他Python运行方式。
 
+利用uv隔离环境特性：
 - 自动管理虚拟环境和依赖
-- 避免在系统Python环境安装依赖包
-- 使用临时文件，执行完成后立即清理
-- 保持跨平台兼容性（Windows/macOS/Linux）
+- 避免系统Python污染
+- 支持用户现有脚本（无需修改）
+- 自动解析依赖并使用`--with`传递
+- 智能检测uv项目，复用项目环境
+- 跨平台兼容（Windows/macOS/Linux）
+
+**重要**: 如果uv未安装，立即停止任务并引导用户安装。不要使用python、pip、poetry、venv等替代工具。
 
 ## When to Use
 
-大模型**任何需要用Python处理的任务**都应该使用此skill。
+任何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）
+- **数据处理**: pandas, numpy, scipy / CSV/JSON/YAML转换 / 统计分析
+- **API交互**: HTTP请求（requests, httpx） / API数据检索
+- **文件操作**: 重命名、批量处理 / pathlib, shutil操作
+- **科学计算**: numpy, scipy / matplotlib, plotly可视化
+- **系统工具**: logging / configparser / tqdm, rich进度跟踪
 
 ### 不适用场景
+- ✗ 需要用户交互（input()）
+- ✗ 需要持久化环境（每次都是新环境）
+- ✗ 需要命令行参数
+- ✗ 需要从stdin读取
 
-- ✗ 需要用户交互的脚本（input(), input()等）
-- ✗ 需要持久化环境（每次都是新的隔离环境）
-- ✗ 需要传递命令行参数（所有参数嵌入脚本）
-- ✗ 需要从stdin读取输入
+## Automatic Dependency Parsing
 
-## Workflow
+分析import语句，提取外部包名，排除标准库。
 
-### 步骤1：生成符合PEP 723的Python脚本
+### 标准库（排除）
+**核心**: 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. 去重
 
+### 示例
 ```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
+import json  # 标准库，排除
+from pathlib import Path  # 标准库，排除
 
-data = pd.read_csv('data.csv')
-print(data.describe())
+# 结果: [pandas, numpy]
 ```
 
-仅使用标准库：
+## Smart Project Detection
 
-```python
-# /// script
-# dependencies = []
-# ///
-
-import os
-import json
-
-with open('data.json') as f:
-    data = json.load(f)
-print(f"Keys: {list(data.keys())}")
+### 检测命令
+```bash
+uv sync --dry-run
 ```
 
-### 步骤2：获取临时脚本文件路径
+### 判断逻辑
+- Exit code 0 → uv项目
+- 非零退出码 → 非uv项目
+- 失败 → 回退到非uv项目模式（使用`--with`），不阻塞执行
 
-调用辅助脚本创建临时Python脚本文件并获取文件路径（使用相对路径）：
+## Path Handling
+
+### 三层逻辑
+1. **用户指定存储路径** → 写入指定路径
+2. **用户指定现有脚本** → 直接执行
+3. **未指定** → 临时文件
 
 ```bash
+# 临时文件获取
 temp_file_path=$(uv run ./script/get_temp_path.py)
 ```
 
-**输出：**
+## Execution Commands
 
-- 临时Python脚本文件的完整路径
-  - Linux/macOS: `/tmp/uv_script_xxx.py`
-  - Windows: `C:\Users\<username>\AppData\Local\Temp\uv_script_xxx.py`
+| 场景 | 命令 |
+|------|------|
+| 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环境
 
-- 辅助脚本已在临时目录创建了空的Python脚本文件
-- 大模型直接得到脚本文件路径
-- 无需拼接路径，直接使用返回的文件路径
+## Workflow
 
-### 步骤3：写入PEP 723脚本内容
+**步骤1**: 解析依赖（见"Automatic Dependency Parsing"）
 
-使用大模型的文件创建工具（Write等）在步骤2返回的脚本文件路径中写入PEP 723脚本内容。
+**步骤2**: 检测项目（见"Smart Project Detection"）
 
-### 步骤4：使用uv执行
+**步骤3**: 确定路径（见"Path Handling"）
 
-```bash
-uv run <temp_file_path>
-```
+**步骤4**: 构造并执行命令（见"Execution Commands"）
+
+执行命令并捕获输出。
 
 ## Error Handling
 
-### 场景1：uv未安装
+### uv未安装
 
-**错误消息：**
+**检测**: `uv`命令失败
 
+**错误消息**:
 ```
 uv not found
 
-无法找到uv命令。请先安装uv：
-https://docs.astral.sh/uv/getting-started/installation/
+此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完成后，可以重新执行任务
 
-### 场景2：Python语法错误
+**操作**: 立即停止所有执行，等待用户安装uv
 
-**检测：** 在创建临时文件之前检测语法错误
+### 其他错误
 
-**错误消息：**
-
-```
-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>
-```
+| 场景 | 错误消息 | 操作 |
+|------|---------|------|
+| 项目检测失败 | 回退到非uv模式，使用`--with` | 警告后继续 |
+| 依赖解析不准确 | 依赖可能不完整<br>Traceback: [traceback] | 停止，保留脚本调试 |
+| 语法错误 | Python语法错误: [描述]<br>文件: <path><br>行号: <line> | 停止 |
+| 路径权限问题 | 无法写入: <path><br>建议: 使用临时文件模式 | 回退到临时文件 |
 
 ## Examples
 
-### 示例1：数据分析
-
-**场景：** 分析CSV文件的统计信息
-
+### 示例1: 数据分析
 ```python
-# /// script
-# dependencies = [
-#   "pandas",
-# ]
-# ///
-
 import pandas as pd
+import numpy as np
 
 df = pd.read_csv('data.csv')
-print(f"数据形状: {df.shape}")
-print(f"描述统计:\n{df.describe()}")
+print(f"形状: {df.shape}")
+print(df.describe())
 ```
+**执行**: `uv run --with pandas --with numpy /tmp/script_xxx.py`
 
-**执行流程：**
-
-1. 调用辅助脚本获取临时目录
-2. 构造临时文件路径
-3. 创建文件并写入上述内容
-4. 执行：`uv run <temp_file_path>`
-5. 捕获输出
-
-### 示例2：API交互
-
-**场景：** 从GitHub API获取仓库信息
-
+### 示例2: 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]}...")
+print(f"仓库: {data['full_name']}, Stars: {data['stargazers_count']}")
 ```
+**执行**: `uv run --with requests /tmp/script_xxx.py`
 
-### 示例3：文件操作
-
-**场景：** 批量重命名文件
-
+### 示例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}")
+    os.rename(file, f"file_{i:03d}.txt")
 ```
+**执行**: `uv run /tmp/script_xxx.py`（无依赖）
+
+### 示例4: uv项目内执行
+```python
+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: 用户指定路径
+```python
+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环境，每个脚本都有独立的虚拟环境 |
-| 自动依赖管理 | 无需手动pip install，uv自动解析和安装依赖        |
-| 快速启动     | 比传统venv快10-100倍，快速创建和销毁环境         |
-| 标准兼容     | 支持PEP 723格式，官方Python规范                  |
-| 零配置       | 开箱即用，无需额外配置或初始化                   |
+| 特性 | 优势 |
+|------|------|
+| 环境隔离 | 不污染系统Python |
+| 自动依赖 | `--with`语法，无需pip install |
+| 快速启动 | 比venv快10-100倍 |
+| 项目集成 | 自动检测uv项目 |
+| 零配置 | 开箱即用，无需PEP 723 |
 
 ### 最佳实践
-
-1. **总使用内联元数据**
-
-   ```python
-   # 即使没有依赖也要声明
-   # dependencies = []
-   ```
-
-2. **使用最新版本**
-   - 不指定版本约束
-   - 让uv自动选择
-   - 保持依赖更新和安全
-
-3. **错误处理**
-   - 脚本内部处理预期的错误（try-except）
-   - 严格模式处理意外的错误（立即停止）
-
-4. **清理资源**
-   - 临时文件使用系统临时目录（/tmp 或 Windows Temp）
-   - 系统会自动清理临时文件，无需手动管理
-   - 失败时可手动删除临时文件调试
+1. **依赖解析**: 排除标准库；失败时检查遗漏依赖；复杂项目用uv项目模式
+2. **路径**: 用户指定优先；临时文件用于自主生成；跨平台由辅助脚本保证
+3. **错误**: 预期错误脚本内处理；意外错误立即停止；检测失败自动回退
+4. **清理**: 临时文件使用系统目录，自动清理，失败时手动删除
 
 ### 限制
+- ✗ 不支持命令行参数、stdin输入、持久化环境
+- ✗ 使用uv默认Python版本（项目可在pyproject.toml指定）
+- ✗ 依赖解析可能不完整（动态导入、条件导入可能遗漏）
+- ✗ 项目检测可能误判（网络问题导致回退）
 
-- ✗ 不支持命令行参数
-  - 所有参数必须嵌入在脚本中
-  - 不支持`uv run script.py arg1 arg2`
+### uv工具要求
 
-- ✗ 不支持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内联元数据格式
-  - 提供环境隔离和自动依赖管理
-
-### 可选依赖
-
-无
+- **uv是此skill的必需依赖，不可替代**
+- **不支持**: python, pip, poetry, venv, virtualenv
+- 如果检测到uv未安装，必须停止任务并引导用户安装
+- 不要尝试使用替代方案或自动安装uv
 
 ## Workflow Summary
 
-完整的典型工作流：
+**完整流程**:
+1. 解析import语句，提取外部包名（排除标准库）
+2. 执行`uv sync --dry-run`检测项目
+3. 确定脚本路径（用户指定/现有脚本/临时文件）
+4. 构造执行命令（根据项目类型和依赖）
+5. 执行并捕获输出
 
-```bash
-# 1. 获取临时脚本文件路径
-temp_file_path=$(uv run ./script/get_temp_path.py)
-
-# 2. 写入PEP 723脚本内容
-# 使用大模型的Write工具在 temp_file_path 中写入...
-
-# 3. 执行脚本
-uv run $temp_file_path
-
-# 4. 系统自动清理临时文件
-```
-
-**关键特点：**
-
-- 跨平台自动适配
-- 环境隔离
-- 自动依赖管理
-- 临时文件直接返回路径，无需手动拼接
-- 系统自动清理临时文件，无需手动管理
+**关键特点**:
+- 自动依赖解析：分析import自动提取
+- 智能项目检测：自动识别uv项目
+- 灵活路径：支持指定/现有/临时三种模式
+- 跨平台：自动适配Windows/macOS/Linux
+- 环境隔离：独立虚拟环境