## Context

当前lyxy-runner-python 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字符限制如何处理？
   - 建议：使用长路径前缀（\\?\）或尽量使用相对路径