Skill/openspec/specs/uv-run-with-syntax/spec.md

UV Run With Syntax Spec

Purpose

Define requirements for using uv run --with syntax to execute Python scripts with automatic dependency parsing, smart project detection, and flexible path handling.

Requirements

需求：自动解析脚本依赖

Skill SHALL自动分析Python脚本内容以识别所需的Python包。Skill SHALL解析import语句并提取外部包名，排除Python标准库模块。

场景：解析包含外部依赖的脚本

• WHEN Skill分析包含import语句的Python脚本（例如：import pandas as pd）
• THEN Skill SHALL提取包名（pandas）
• THEN Skill SHALL排除Python标准库模块（os、sys、json等）
• THEN Skill SHALL生成依赖列表，用于--with参数

场景：解析多个import来源

• WHEN 脚本包含多种import语句（import pandas, from numpy import array, import requests as req）
• THEN Skill SHALL正确提取所有外部包名（pandas, numpy, requests）
• THEN Skill SHALL处理import ... as和from ... import语法
• THEN Skill SHALL去重依赖列表

场景：仅使用标准库的脚本

• WHEN 脚本只使用Python标准库（os、sys、json、pathlib等）
• THEN Skill SHALL生成空的依赖列表
• THEN Skill SHALL不添加任何--with参数到执行命令中

需求：智能项目检测

Skill SHALL检测当前工作目录是否为uv项目，并据此选择执行策略。

场景：检测到uv项目

• WHEN 当前工作目录包含pyproject.toml文件
• THEN Skill SHALL识别为uv项目
• THEN Skill SHALL对当前目录下的脚本使用uv run script.py直接执行
• THEN Skill SHALL不添加--with参数（依赖由项目pyproject.toml管理）

场景：非uv项目环境

• WHEN 当前工作目录不包含pyproject.toml文件
• THEN Skill SHALL识别为非uv项目
• THEN Skill SHALL对脚本使用uv run --with package1 --with package2 script.py执行
• THEN Skill SHALL根据解析的依赖列表动态构建--with参数

场景：脚本位于工作目录外

• WHEN 用户指定的脚本路径不在当前工作目录下
• THEN Skill SHALL按独立脚本处理
• THEN Skill SHALL使用uv run --with package1 --with package2 <script_path>执行
• THEN Skill SHALL解析脚本内容以获取依赖列表

需求：灵活路径处理

Skill SHALL根据用户指定和上下文灵活处理脚本路径，支持用户指定路径、现有脚本文件和临时脚本。

场景：用户指定脚本存储路径

• WHEN 用户明确指定脚本存储路径（例如："在scripts/data_processing.py中写入脚本"）
• THEN Skill SHALL将脚本内容写入用户指定的路径
• THEN Skill SHALL不使用临时文件
• THEN Skill SHALL在指定路径执行脚本

场景：用户指定现有脚本路径

• WHEN 用户指定要运行的现有Python脚本（例如："运行scripts/my_script.py"）
• THEN Skill SHALL读取该脚本内容（如需解析依赖）
• THEN Skill SHALL直接在指定路径执行脚本
• THEN Skill SHALL不修改用户脚本内容

场景：大模型自主生成脚本且未指定路径

• WHEN 大模型自主生成Python脚本且用户未指定存储路径
• THEN Skill SHALL使用辅助脚本获取临时文件路径
• THEN Skill SHALL将脚本内容写入临时文件
• THEN Skill SHALL在临时路径执行脚本
• THEN Skill SHALL允许系统自动清理临时文件

需求：使用--with语法执行

Skill SHALL使用uv run --with语法将依赖传递给uv，替代PEP 723内联元数据方式。

场景：有外部依赖的脚本执行

• WHEN 脚本解析结果包含依赖列表[package1, package2]
• THEN Skill SHALL构造命令：uv run --with package1 --with package2 <script_path>
• THEN uv SHALL为每个--with指定的包创建隔离环境
• THEN Skill SHALL捕获并返回脚本输出

场景：无外部依赖的脚本执行

• WHEN 脚本解析结果为空依赖列表
• THEN Skill SHALL构造命令：uv run <script_path>
• THEN Skill SHALL不包含任何--with参数
• THEN uv SHALL使用隔离的Python标准库环境执行

场景：uv项目内的脚本执行

• WHEN 脚本位于检测到的uv项目内
• THEN Skill SHALL构造命令：uv run <script_path>（相对路径）
• THEN Skill SHALL不包含--with参数
• THEN uv SHALL使用项目的虚拟环境和依赖配置

需求：向后兼容性

Skill SHALL保持对包含PEP 723元数据的旧脚本的兼容性，但不再要求使用该格式。

场景：执行包含PEP 723元数据的脚本

• WHEN 用户提供的脚本顶部包含PEP 723元数据块
• THEN Skill SHALL正常执行脚本（PEP 723元数据将被uv忽略）
• THEN Skill SHALL仍使用--with语法传递解析出的依赖
• THEN 脚本SHALL成功执行

场景：新工作流执行标准Python脚本

• WHEN 用户提供的标准Python脚本无任何元数据
• THEN Skill SHALL自动解析import语句
• THEN Skill SHALL使用--with语法传递依赖
• THEN 脚本SHALL在不修改的情况下成功执行