Skill/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/specs/uv-python-runner/spec.md

UV Python Runner Spec (Delta)

Purpose

This is a delta spec documenting changes to the existing uv-python-runner capability to support uv run --with syntax and smart project detection.

REMOVED Requirements

需求：生成符合PEP 723规范的Python脚本

Reason: 已迁移至使用uv run --with语法和自动依赖解析，不再需要PEP 723内联元数据。用户可以直接运行标准Python脚本，无需修改脚本内容。

Migration: 现有包含PEP 723元数据的脚本仍可正常运行，但不再要求使用该格式。新的工作流使用自动依赖解析和--with语法。

MODIFIED 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路径

ADDED Requirements

需求：自动依赖解析

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允许系统自动清理临时文件