优化python-runner

2026-02-06 17:39:36 +08:00
parent 4621a4abcf
commit efd7f21a28
9 changed files with 957 additions and 316 deletions
--- a/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/.openspec.yaml
+++ b/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-06
--- a/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/design.md
+++ b/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/design.md
@@ -0,0 +1,254 @@
+## Context
+
+当前python-runner skill要求用户在Python脚本顶部添加PEP 723元数据块来声明依赖，这需要修改用户现有的脚本文件，降低了使用便利性。此外，现有实现总是使用临时文件，即使在用户明确指定路径时也是如此。
+
+该skill目前的工作流程：
+1. 要求LLM生成包含PEP 723元数据的Python脚本
+2. 使用辅助脚本创建临时文件
+3. 写入脚本内容（包含元数据块）
+4. 使用`uv run <temp_file_path>`执行
+
+现有实现的限制：
+- 用户必须修改现有脚本以添加PEP 723元数据
+- 总是使用临时文件，即使用户指定了存储路径
+- 无法智能识别uv项目，每次都创建新的虚拟环境
+
+## Goals / Non-Goals
+
+**Goals:**
+- 无需修改用户现有Python脚本即可使用uv执行
+- 自动解析脚本依赖并使用`--with`语法传递
+- 智能检测uv项目，复用项目虚拟环境
+- 尊重用户指定的脚本路径，仅在未指定时使用临时文件
+- 保持跨平台兼容性（Windows/macOS/Linux）
+- 保持严格错误处理和调试支持
+
+**Non-Goals:**
+- 不修改用户现有的脚本文件
+- 不实现复杂版本约束或依赖冲突解决（交给uv）
+- 不支持命令行参数或stdin输入（保持现有限制）
+- 不持久化虚拟环境（每次执行都是新的）
+
+## Decisions
+
+### 决策1：项目检测方法
+
+**选择：** 使用`uv sync --dry-run`命令检测当前目录是否为uv项目
+
+**原因：**
+- `uv sync --dry-run`是uv提供的官方方法，能准确判断目录是否为有效的uv项目
+- 不仅检查pyproject.toml存在性，还验证项目配置的有效性
+- 如果命令成功退出（exit code 0），则目录是有效的uv项目
+- 如果命令失败（非零退出码），则目录不是uv项目或配置无效
+
+**替代方案考虑：**
+1. 仅检查pyproject.toml文件存在
+   - 优点：简单快速
+   - 缺点：无法验证文件有效性，可能误判
+   - **拒绝理由**：不够可靠，可能导致误判
+
+2. 检查.venv目录存在
+   - 优点：可以检测已初始化的虚拟环境
+   - 缺点：uv项目可能尚未运行过sync，没有.venv目录
+   - **拒绝理由**：对未初始化的uv项目不友好
+
+**实现细节：**
+```bash
+# 检测当前目录是否为uv项目
+if uv sync --dry-run > /dev/null 2>&1; then
+  # 是uv项目，使用项目环境
+  uv run <script_path>
+else
+  # 不是uv项目，使用--with语法
+  uv run --with package1 --with package2 <script_path>
+fi
+```
+
+### 决策2：依赖解析策略
+
+**选择：** 使用大模型的分析能力直接从脚本内容提取import语句，而非使用外部工具
+
+**原因：**
+- 大模型已经理解脚本内容，可以直接提取import语句
+- 避免引入新的依赖（如ast模块解析工具）
+- 大模型可以理解各种import语法变体（import x, from x import y, import x as z等）
+- 可以排除Python标准库模块，只需检查是否为常见标准库名称
+
+**实现细节：**
+1. 大模型分析脚本中的所有import语句
+2. 提取包名（import pandas → pandas, from numpy import array → numpy）
+3. 排除已知的标准库名称（os, sys, json, pathlib, re等）
+4. 去重后生成依赖列表
+
+**限制：**
+- 大模型需要维护标准库列表（可基于Python 3.10+标准库）
+- 对于动态导入（__import__）和条件导入，可能无法识别
+- 不支持解析requirements.txt或其他依赖文件（只解析脚本内容）
+
+### 决策3：路径处理策略
+
+**选择：** 三层路径处理逻辑（用户指定 → 现有脚本 → 临时文件）
+
+**原因：**
+- 优先尊重用户明确指定的路径
+- 对现有脚本直接执行，无需修改
+- 仅在大模型自主生成且未指定路径时使用临时文件
+
+**决策树：**
+
+```
+用户是否指定脚本存储路径？
+├─ 是：写入用户指定路径 → 执行
+└─ 否：
+    ├─ 用户是否指定现有脚本路径？
+    │   ├─ 是：直接执行该脚本
+    │   └─ 否：创建临时文件 → 执行
+```
+
+**实现细节：**
+- 用户指定路径示例："在scripts/data.py中写入" → 写入`scripts/data.py`
+- 用户指定现有脚本："运行analyze.py" → 执行`analyze.py`（读取内容解析依赖）
+- 大模型自主生成：使用`get_temp_path.py`辅助脚本创建临时文件
+
+### 决策4：执行命令构造
+
+**选择：** 根据项目检测和依赖解析结果动态构造`uv run`命令
+
+**命令模式：**
+
+| 场景 | 命令格式 |
+|------|----------|
+| uv项目内脚本 | `uv run <script_path>` |
+| 非uv项目，有依赖 | `uv run --with pkg1 --with pkg2 <script_path>` |
+| 非uv项目，无依赖 | `uv run <script_path>` |
+
+**原因：**
+- uv项目：依赖已在pyproject.toml中管理，不需要`--with`
+- 非uv项目：使用`--with`逐个指定依赖，uv自动处理隔离环境
+- 无依赖：不需要`--with`，使用标准库环境
+
+### 决策5：不使用辅助脚本进行项目检测
+
+**选择：** 直接使用大模型的命令行工具执行`uv sync --dry-run`进行项目检测
+
+**原因：**
+- 大模型可以直接执行bash命令，无需额外的辅助脚本
+- 简化实现，减少维护成本
+- 避免辅助脚本的版本管理问题
+
+**实现细节：**
+```bash
+# 使用大模型的命令行工具执行项目检测
+uv sync --dry-run
+```
+
+- 如果命令返回exit code 0，则当前目录是有效的uv项目
+- 如果命令返回非零退出码，则当前目录不是uv项目
+- 检测结果直接由大模型判断，无需解析辅助脚本输出
+
+## Risks / Trade-offs
+
+### 风险1：uv项目检测失败
+
+**描述：** `uv sync --dry-run`在某些情况下可能误判（如网络问题、依赖解析错误）
+
+**缓解措施：**
+- 检测失败时回退到非uv项目模式（使用`--with`语法）
+- 记录检测失败日志，但不阻塞脚本执行
+- 用户可以手动指定使用项目环境（通过注释或显式指令）
+
+### 风险2：依赖解析不完整
+
+**描述：** 大模型可能遗漏某些import语句或误判标准库模块
+
+**缓解措施：**
+- 在SKILL.md中提供常见标准库列表供参考
+- 当脚本执行失败时，检查是否为缺失依赖，提示用户
+- 允许用户手动指定依赖（通过参数或注释）
+
+### 风险3：路径冲突和权限问题
+
+**描述：** 用户指定的路径可能不存在、无写入权限或与现有文件冲突
+
+**缓解措施：**
+- 写入前检查目录是否存在，不存在则创建（如果允许）
+- 写入前检查文件权限，失败时提示用户
+- 支持覆盖提示（如果文件已存在）
+
+### 风险4：跨平台路径处理复杂
+
+**描述：** Windows和Unix系统的路径分隔符、路径长度限制不同
+
+**缓解措施：**
+- 使用Python的`pathlib`或`os.path`处理路径，而非字符串拼接
+- 保持辅助脚本使用标准库路径处理函数
+- 测试覆盖Windows、macOS、Linux三个平台
+
+### 权衡1：自动依赖解析 vs 用户显式声明
+
+**当前选择：** 自动解析import语句
+
+**权衡：**
+- 优点：用户无需手动声明依赖，开箱即用
+- 缺点：可能遗漏某些隐式依赖（如动态导入）
+
+**缓解：** 支持用户通过参数或注释显式指定依赖
+
+### 权衡2：项目检测成本 vs 准确性
+
+**当前选择：** 使用`uv sync --dry-run`（准确但较慢）
+
+**权衡：**
+- 优点：准确判断uv项目，避免误判
+- 缺点：每次执行都需要运行检测命令（约几百毫秒）
+
+**缓解：** 可以考虑缓存检测结果（在同一工作目录内）
+
+## Migration Plan
+
+### 步骤1：更新SKILL.md文档
+
+1. 移除PEP 723相关内容
+2. 添加依赖解析指导
+3. 添加项目检测流程
+4. 更新路径处理说明
+5. 更新执行命令示例
+6. 保持错误处理和调试支持部分
+
+### 步骤2：更新工作流示例
+
+在SKILL.md中提供新的工作流示例：
+- uv项目内执行脚本
+- 非uv项目执行脚本（有依赖）
+- 非uv项目执行脚本（无依赖）
+- 用户指定路径的执行流程
+
+### 步骤4：测试验证
+
+在三个平台（Windows/macOS/Linux）上测试：
+1. uv项目检测
+2. 依赖解析准确性
+3. 路径处理（临时/指定/现有）
+4. 跨平台兼容性
+5. 错误处理
+
+### 回滚策略
+
+如果新实现存在问题，可以直接回退到旧版SKILL.md内容（从git历史恢复）。
+
+## Open Questions
+
+1. **依赖解析准确性：** 是否需要维护一个更完整的Python标准库模块列表，以减少误判？
+   - 建议：基于Python 3.10+标准库文档维护列表
+
+2. **项目检测缓存：** 是否需要在同一工作目录内缓存项目检测结果，避免重复运行`uv sync --dry-run`？
+   - 建议：初期不实现，观察性能影响后再决定
+
+3. **隐式依赖处理：** 如何处理通过`__import__()`或动态加载的隐式依赖？
+   - 建议：暂不支持，在SKILL.md中说明限制
+
+4. **用户干预机制：** 是否提供机制让用户在脚本中显式声明额外依赖（如通过特殊注释）？
+   - 建议：初期不实现，通过错误提示引导用户
+
+5. **Windows路径长度限制：** Windows路径最大260字符限制如何处理？
+   - 建议：使用长路径前缀（\\?\）或尽量使用相对路径
--- a/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/proposal.md
+++ b/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/proposal.md
@@ -0,0 +1,41 @@
+## Why
+
+当前python-runner skill要求使用PEP 723规范在脚本顶部添加内联元数据块来声明依赖，这需要修改用户现有的Python脚本，降低了使用便利性。通过改用`uv run --with`语法并自动解析脚本内容中的依赖，可以在不改动用户脚本的情况下利用uv的隔离环境直接运行脚本，提升用户体验和灵活性。
+
+## What Changes
+
+- **BREAKING**: 移除对PEP 723规范的依赖，不再要求脚本顶部包含`# /// script`元数据块
+- **BREAKING**: 不再保持对包含PEP 723元数据的旧脚本的兼容性
+- 新增依赖解析功能：通过分析脚本内容自动识别所需的Python包
+- 新增智能执行逻辑：
+  - 使用`uv sync --dry-run`检测当前目录是否为uv项目
+  - 如果是uv项目，直接使用`uv run script.py`执行
+  - 如果不是uv项目，使用`uv run --with package1 --with package2 script.py`执行
+- 新增路径处理逻辑：
+  - 当用户指定脚本存储路径时，将脚本写入指定目录
+  - 仅在用户未指定路径或由大模型自主生成脚本时，才使用临时脚本
+- 更新执行命令模式，统一使用`--with`语法传递依赖
+- 简化实现：直接使用大模型命令行工具执行项目检测，无需新增辅助脚本
+
+## Capabilities
+
+### New Capabilities
+- `uv-run-with-syntax`: 使用`uv run --with`语法执行Python脚本的能力，包括自动依赖解析和智能项目检测
+
+### Modified Capabilities
+- `uv-python-runner`: 现有spec需要更新以反映新的执行流程，包括：移除PEP 723要求、新增依赖解析逻辑、新增智能路径和项目检测
+
+## Impact
+
+- **代码影响**：
+  - 修改`skills/python-runner/SKILL.md`，更新执行工作流和示例
+  - 保留现有的`get_temp_path.py`辅助脚本
+  - 不新增辅助脚本，项目检测直接使用命令行工具
+- **行为影响**：
+  - 不再支持PEP 723元数据格式
+  - 新版工作流可以不经修改直接运行用户现有的Python脚本
+  - 改进了与现有uv项目的集成体验
+- **依赖影响**：无新增依赖，继续使用uv作为核心依赖
+- **兼容性**：
+  - 保持跨平台兼容性（Windows/macOS/Linux）
+  - 不保持对旧版PEP 723格式的兼容性（BREAKING CHANGE）
--- a/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/specs/uv-python-runner/spec.md
+++ b/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/specs/uv-python-runner/spec.md
@@ -0,0 +1,113 @@
+# 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允许系统自动清理临时文件
--- a/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/specs/uv-run-with-syntax/spec.md
+++ b/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/specs/uv-run-with-syntax/spec.md
@@ -0,0 +1,111 @@
+# 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在不修改的情况下成功执行
--- a/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/tasks.md
+++ b/openspec/changes/archive/2026-02-06-optimize-python-runner-uv-syntax/tasks.md
@@ -0,0 +1,93 @@
+## 1. 文档准备
+
+- [x] 1.1 备份现有 SKILL.md 文件为 SKILL.md.backup
+- [x] 1.2 阅读 python-runner skill 文档结构，了解现有内容组织方式
+
+## 2. 移除PEP 723相关内容
+
+- [x] 2.1 移除"生成符合PEP 723规范的Python脚本"相关章节
+- [x] 2.2 移除所有PEP 723元数据块的示例代码
+- [x] 2.3 移除`# /// script`、`# dependencies = []`等PEP 723语法说明
+- [x] 2.4 更新Purpose部分，移除对PEP 723的提及
+
+## 3. 添加依赖解析指导
+
+- [x] 3.1 添加"自动解析脚本依赖"章节，说明如何从import语句提取依赖
+- [x] 3.2 添加常见Python标准库模块列表（os、sys、json、pathlib等）
+- [x] 3.3 添加依赖解析示例（pandas、numpy、requests等外部包）
+- [x] 3.4 说明去重逻辑和过滤标准库的规则
+
+## 4. 添加项目检测流程
+
+- [x] 4.1 添加"智能项目检测"章节，说明使用`uv sync --dry-run`检测uv项目
+- [x] 4.2 说明检测逻辑：exit code 0为uv项目，非零为非uv项目
+- [x] 4.3 添加项目检测失败的处理说明（回退到非uv项目模式）
+
+## 5. 更新路径处理说明
+
+- [x] 5.1 添加路径处理三层逻辑说明（用户指定 → 现有脚本 → 临时文件）
+- [x] 5.2 更新临时文件获取流程，保留`get_temp_path.py`辅助脚本的使用
+- [x] 5.3 添加用户指定路径的处理说明和示例
+- [x] 5.4 添加现有脚本直接执行的说明
+
+## 6. 更新执行命令示例
+
+- [x] 6.1 添加uv项目内执行命令示例：`uv run script.py`
+- [x] 6.2 添加非uv项目有依赖执行命令示例：`uv run --with pandas --with numpy script.py`
+- [x] 6.3 添加非uv项目无依赖执行命令示例：`uv run script.py`
+- [x] 6.4 移除所有使用PEP 723元数据的执行示例
+
+## 7. 更新工作流章节
+
+- [x] 7.1 重写工作流步骤，移除"步骤1：生成符合PEP 723的Python脚本"
+- [x] 7.2 新增"步骤1：解析脚本依赖"（读取或生成脚本后分析import语句）
+- [x] 7.3 新增"步骤2：检测是否为uv项目"（执行`uv sync --dry-run`）
+- [x] 7.4 更新"步骤3：根据用户需求确定脚本路径"
+- [x] 7.5 更新"步骤4：根据检测结果构造执行命令"
+- [x] 7.6 更新完整工作流示例，包含三种场景（uv项目、非uv项目有依赖、非uv项目无依赖）
+
+## 8. 更新错误处理章节
+
+- [x] 8.1 添加项目检测失败的场景和错误处理
+- [x] 8.2 添加依赖解析不准确导致执行失败的处理说明
+- [x] 8.3 更新现有错误处理场景，移除对PEP 723的引用
+- [x] 8.4 添加路径权限问题的错误处理
+
+## 9. 更新示例章节
+
+- [x] 9.1 重写"示例1：数据分析"，使用标准Python脚本（无PEP 723）
+- [x] 9.2 重写"示例2：API交互"，使用标准Python脚本（无PEP 723）
+- [x] 9.3 重写"示例3：文件操作"，使用标准Python脚本（无PEP 723）
+- [x] 9.4 新增"示例4：uv项目内执行"，展示在uv项目中的执行流程
+- [x] 9.5 新增"示例5：用户指定路径"，展示指定存储路径的执行流程
+
+## 10. 更新说明和最佳实践
+
+- [x] 10.1 更新"为什么使用uv？"表格，移除PEP 723相关说明
+- [x] 10.2 更新"最佳实践"部分，移除PEP 723相关内容
+- [x] 10.3 添加新的最佳实践：依赖解析的准确性注意事项
+- [x] 10.4 更新"限制"部分，移除PEP 723相关限制
+- [x] 10.5 添加新的限制说明：项目检测失败、动态导入等
+
+## 11. 更新Workflow Summary
+
+- [x] 11.1 重写完整工作流示例，反映新的执行流程
+- [x] 11.2 更新关键特点说明，移除PEP 723相关内容
+- [x] 11.3 添加项目检测和依赖解析的特点说明
+
+## 12. 验证和测试
+
+- [x] 12.1 在Windows平台测试uv项目检测
+- [x] 12.2 在macOS平台测试uv项目检测
+- [x] 12.3 在Linux平台测试uv项目检测
+- [x] 12.4 测试依赖解析准确性（包含标准库和外部包）
+- [x] 12.5 测试三种路径模式（用户指定、现有脚本、临时文件）
+- [x] 12.6 测试错误处理场景（uv未安装、语法错误、依赖失败等）
+- [x] 12.7 验证SKILL.md文档的完整性和一致性
+
+## 13. 清理和提交
+
+- [x] 13.1 删除备份文件 SKILL.md.backup（如果一切正常）
+- [x] 13.2 验证修改后的SKILL.md符合所有spec要求
+- [x] 13.3 确认辅助脚本 `get_temp_path.py` 仍然可用
+- [x] 13.4 确认无需新增辅助脚本（项目检测直接使用命令行工具）