lanyuanxiaoyao/Skill
1
0
Fork 0
Code Activity
Files
120edb82e62a2b654dd6c6886d4f4b32a4cd1d3c
Skill/openspec/specs/python-runner/spec.md
lanyuanxiaoyao 120edb82e6 规范命名
2026-02-06 14:55:59 +08:00

6.9 KiB
Raw Blame History

UV Python Runner Spec

Purpose

Define requirements for the python-runner skill, which enables execution of Python scripts with PEP 723 metadata using uv for isolated dependency management and cross-platform temporary file handling.

Requirements

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

Skill SHALL指导LLM生成符合PEP 723内联元数据规范的Python脚本。脚本SHALL在顶部包含# /// script块，使用dependencies字段声明所有外部依赖。依赖SHALL使用不带版本约束的包名，允许uv选择兼容的最新版本。没有依赖的脚本SHALL声明空的依赖列表。

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

  • WHEN LLM需要执行需要外部包的Python代码（例如：pandas、requests、numpy）
  • THEN skill SHALL指导LLM包含列出所有必需包的PEP 723元数据块
  • THEN 依赖列表SHALL只包含包名，不带版本约束
  • THEN 脚本SHALL是有效的Python代码，顶部包含元数据块

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

  • WHEN LLM需要执行只使用标准库模块的Python代码
  • THEN skill SHALL指导LLM包含空依赖的PEP 723元数据块：# dependencies = []
  • THEN 脚本SHALL是有效的Python代码，顶部包含元数据块

需求：在隔离的uv环境中执行脚本

Skill SHALL指导LLM在系统临时目录中创建临时Python文件，并使用uv run命令执行它们。临时文件SHALL使用包含时间戳和随机标识符的唯一名称创建。Skill SHALL确保所有脚本参数和逻辑都嵌入在脚本本身中，没有命令行参数或stdin输入。

场景：成功执行脚本

  • WHEN LLM生成符合PEP 723的有效Python脚本
  • THEN skill SHALL指导LLM在/tmp/uv_script_<timestamp>_<random>.py创建临时文件
  • THEN skill SHALL指导LLM使用uv run /tmp/uv_script_XXX.py执行脚本
  • THEN uv SHALL自动创建隔离的虚拟环境，安装依赖，并执行脚本
  • THEN skill SHALL捕获并返回stdout/stderr输出
  • THEN 临时文件使用系统目录，系统自动清理

场景：脚本执行失败

  • WHEN 脚本执行失败（运行时错误、依赖解析失败等）
  • THEN skill SHALL保留临时文件用于调试
  • THEN skill SHALL显示包含traceback的完整错误消息
  • THEN skill SHALL显示保留的临时文件路径
  • THEN skill SHALL停止任务（严格错误处理模式）

需求：跨平台临时目录支持

Skill SHALL使用skills/python-runner/script/get_temp_path.py辅助脚本来获取平台特定的临时目录。Skill SHALL在创建临时Python文件之前，先调用此辅助脚本获取临时目录路径。Skill SHALL支持Windows、macOS、Linux三个平台。

场景：获取临时目录路径

  • WHEN LLM需要为Python脚本创建临时文件
  • THEN skill SHALL指导LLM先调用辅助脚本获取临时目录
  • THEN skill SHALL指导LLM导入并使用get_temp_dir()函数
  • THEN skill SHALL指导LLM使用get_temp_file_path()函数生成唯一文件路径（可选）
  • THEN 辅助脚本SHALL使用tempfile.gettempdir()自动返回平台特定的路径

场景：Windows平台

  • WHEN 辅助脚本在Windows平台运行
  • THEN skill SHALL指导LLM调用辅助脚本会返回Windows临时目录（例如：C:\Users\<username>\AppData\Local\Temp）
  • THEN skill SHALL确保大模型不需要检测或硬编码Windows路径

场景：macOS/Linux平台

  • WHEN 辅助脚本在macOS或Linux平台运行
  • THEN skill SHALL指导LLM调用辅助脚本会返回/tmp路径
  • THEN skill SHALL确保大模型不需要检测或硬编码Unix路径

需求：严格错误处理

Skill SHALL强制执行严格错误处理模式。任何错误条件SHALL导致任务停止并显示清晰错误消息。错误条件SHALL包括：uv未安装、生成的脚本中的Python语法错误、uv的依赖解析失败、以及脚本运行时错误。

场景：uv未安装

场景：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不基于任务领域进行限制或过滤
View Git Blame Copy Permalink