8.1 KiB
UV Python Runner Spec
Purpose
Define requirements for the lyxy-runner-python skill, which enables execution of Python scripts using uv with automatic dependency parsing, smart project detection, and flexible path handling.
Requirements
需求：在隔离的uv环境中执行脚本
Skill SHALL指导LLM使用uv run命令执行Python脚本，并根据脚本位置和项目类型选择执行策略。Skill SHALL支持临时文件和用户指定路径两种模式。Skill SHALL使用--with语法传递依赖或利用项目现有依赖配置。
场景：成功执行独立脚本（无uv项目）
- WHEN LLM生成有效的Python脚本且当前目录不是uv项目
- THEN skill SHALL解析脚本内容获取依赖列表
- THEN skill SHALL在用户指定路径或临时目录创建/使用脚本文件
- THEN skill SHALL使用
uv run --with package1 --with package2 <script_path>执行脚本 - THEN uv SHALL自动创建隔离的虚拟环境，安装依赖，并执行脚本
- THEN skill SHALL捕获并返回stdout/stderr输出
场景：成功执行uv项目内的脚本
- WHEN LLM执行位于uv项目内的脚本（存在pyproject.toml）
- THEN skill SHALL识别为uv项目
- THEN skill SHALL使用
uv run <script_path>执行脚本（相对路径） - THEN uv SHALL使用项目的虚拟环境和依赖配置
- THEN skill SHALL捕获并返回stdout/stderr输出
场景：脚本执行失败
- WHEN 脚本执行失败（运行时错误、依赖解析失败等）
- THEN skill SHALL保留脚本文件用于调试（临时或指定路径）
- THEN skill SHALL显示包含traceback的完整错误消息
- THEN skill SHALL显示脚本文件路径
- THEN skill SHALL停止任务（严格错误处理模式）
需求：跨平台路径支持
Skill SHALL支持Windows、macOS、Linux三个平台的路径处理，包括临时文件和用户指定路径。Skill SHALL在需要时使用辅助脚本获取平台特定的临时目录。
场景：创建临时脚本文件
- WHEN LLM需要创建临时Python脚本且用户未指定路径
- THEN skill SHALL指导LLM调用辅助脚本获取临时目录
- THEN skill SHALL在临时目录创建唯一的Python文件
- THEN 辅助脚本SHALL使用
tempfile.gettempdir()自动返回平台特定的路径
场景：使用用户指定路径
- WHEN 用户明确指定脚本存储或执行路径
- THEN skill SHALL使用用户指定的完整路径或相对路径
- THEN skill SHALL不创建临时文件
- THEN skill SHALL确保路径在不同平台（Windows/macOS/Linux）上的有效性
场景：Windows平台路径处理
- WHEN 在Windows平台创建或执行脚本
- THEN skill SHALL正确处理Windows路径分隔符（
\） - THEN 辅助脚本SHALL返回Windows临时目录（例如：
C:\Users\<username>\AppData\Local\Temp） - THEN skill SHALL确保大模型不需要硬编码Windows路径
场景：macOS/Linux平台路径处理
- WHEN 在macOS或Linux平台创建或执行脚本
- THEN skill SHALL正确处理Unix路径分隔符（
/） - THEN 辅助脚本SHALL返回
/tmp路径 - THEN skill SHALL确保大模型不需要硬编码Unix路径
需求：自动依赖解析
Skill SHALL自动分析Python脚本内容以识别所需的Python包，排除Python标准库模块。
场景：解析import语句提取依赖
- WHEN Skill分析Python脚本的import语句
- THEN Skill SHALL提取外部包名
- THEN Skill SHALL排除Python标准库模块
- THEN Skill SHALL生成用于
--with参数的依赖列表
需求：智能项目检测
Skill SHALL检测当前工作目录是否为uv项目（存在pyproject.toml），并据此选择执行策略。
场景：检测到uv项目
- WHEN 当前工作目录包含
pyproject.toml文件 - THEN Skill SHALL使用项目依赖配置执行脚本
- THEN Skill SHALL不添加
--with参数
场景：非uv项目环境
- WHEN 当前工作目录不包含
pyproject.toml文件 - THEN Skill SHALL使用
--with语法传递解析的依赖
需求：灵活脚本路径处理
Skill SHALL支持用户指定脚本路径、现有脚本文件和临时脚本三种模式。
场景：用户指定脚本存储路径
- WHEN 用户明确指定脚本存储路径
- THEN Skill SHALL将脚本写入用户指定的路径
- THEN Skill SHALL不使用临时文件
场景：用户指定现有脚本路径
- WHEN 用户指定要运行的现有Python脚本
- THEN Skill SHALL直接在指定路径执行
- THEN Skill SHALL不修改用户脚本内容
场景：自主生成脚本且未指定路径
- WHEN 大模型自主生成脚本且用户未指定存储路径
- THEN Skill SHALL使用临时文件路径
- THEN Skill SHALL允许系统自动清理临时文件
需求：严格错误处理
Skill SHALL强制执行严格错误处理模式。任何错误条件SHALL导致任务停止并显示清晰错误消息。错误条件SHALL包括：uv未安装、生成的脚本中的Python语法错误、uv的依赖解析失败、以及脚本运行时错误。
场景：uv未安装
- WHEN LLM尝试执行脚本但系统中未找到uv命令
- THEN skill SHALL显示清晰错误消息："uv not found"
- THEN skill SHALL提供uv安装链接：https://docs.astral.sh/uv/getting-started/installation/
- THEN skill SHALL停止任务
场景：Python语法错误
- WHEN LLM生成包含语法错误的Python代码
- THEN skill SHALL在创建临时文件之前检测语法错误
- THEN skill SHALL显示包含行号和Python错误描述的错误消息
- THEN skill SHALL停止任务而不创建临时文件
场景：依赖解析失败
- WHEN uv无法解析或安装声明的依赖
- THEN skill SHALL显示完整的uv错误输出
- THEN skill SHALL显示临时文件路径，用户可手动删除调试
- THEN skill SHALL停止任务
场景：脚本运行时错误
- WHEN Python脚本执行但在运行时抛出异常
- THEN skill SHALL显示完整的Python traceback
- THEN skill SHALL显示临时文件路径，用户可手动删除调试
- THEN skill SHALL停止任务
需求：无外部输入或参数
Skill SHALL要求所有输入、参数和数据源都直接嵌入在Python脚本中。Skill SHALL不支持传递给脚本的命令行参数。Skill SHALL不支持从stdin读取输入。所有必要的数据SHALL硬编码或从脚本引用的文件中读取。
场景：数据处理任务
- WHEN LLM需要处理数据（例如：CSV文件分析）
- THEN skill SHALL指导LLM将文件路径作为字符串字面量包含在脚本中
- THEN skill SHALL不接受文件路径或参数的外部命令行参数
- THEN 所有数据处理逻辑SHALL嵌入在脚本中
场景：API交互任务
- WHEN LLM需要与API交互（例如：对特定URL的GET请求）
- THEN skill SHALL指导LLM将URL和参数作为字符串字面量包含在脚本中
- THEN skill SHALL不接受作为命令行参数的API端点或身份验证令牌
- THEN 所有API交互逻辑SHALL嵌入在脚本中
需求：通用任务适用性
Skill SHALL适用于任何可以用Python脚本完成的任务。Skill SHALL不限于特定领域，但SHALL为常见用例提供指导，包括数据处理（pandas、numpy）、API交互（requests、httpx）、文件操作（pathlib、shutil）、科学计算（scipy、sympy）和数据转换（json、yaml、csv）。
场景：数据分析任务
- WHEN 用户请求数据分析或统计计算
- THEN skill SHALL提供生成具有适当依赖（例如：pandas）的脚本的指导
- THEN skill SHALL不基于任务领域进行限制或过滤
场景：文件操作任务
- WHEN 用户请求文件操作（重命名、转换、格式化）
- THEN skill SHALL提供生成具有适当标准库或外部模块的脚本的指导
- THEN skill SHALL不基于任务领域进行限制或过滤
场景：API测试任务
- WHEN 用户请求API测试或数据检索
- THEN skill SHALL提供生成具有适当HTTP客户端库的脚本的指导
- THEN skill SHALL不基于任务领域进行限制或过滤