## Context

当前项目中还没有skill实现，需要创建第一个skill来指导大模型使用uv运行Python脚本。该项目专门用于开发大模型工具技能，所有skill都放在`skills`目录下，每个子目录代表一个skill。

Python环境管理是一个常见问题：大模型在处理各种任务时经常需要执行Python脚本（数据分析、API测试、文件操作等），传统做法需要在系统Python环境预安装依赖，导致环境污染、版本冲突等问题。

uv是Astral开发的快速Python包管理器，支持PEP 723内联元数据格式，可以在脚本中声明依赖，并在隔离环境中执行，自动管理虚拟环境和依赖安装。这为解决环境隔离问题提供了标准化的解决方案。

**约束条件：**
- skill文件遵循特定格式：YAML前置元数据 + Markdown内容
- skill必须是指导型的，不直接执行代码
- 不支持命令行参数或stdin输入
- 不支持持久化环境
- 严格错误处理模式
- 必须支持Windows、macOS、Linux三个平台的临时目录处理

**利益相关者：**
- 大模型：需要清晰的模式指导来生成符合规范的Python脚本
- 最终用户：通过大模型获得环境隔离的Python执行能力

## Goals / Non-Goals

**Goals:**
- 创建指导大模型使用uv执行Python脚本的通用skill
- 提供符合PEP 723规范的脚本编写模式
- 确保环境隔离，不污染系统Python环境
- 严格错误处理，任何错误都停止并给出清晰提示
- 临时文件使用系统目录，系统自动清理
- 适用于任何Python可处理的任务（数据处理、API交互、文件操作等）
- 支持Windows、macOS、Linux跨平台自动适配临时目录

**Non-Goals:**
- 不直接执行用户提供的Python代码（只指导大模型）
- 不支持命令行参数传递给脚本
- 不支持从stdin读取输入
- 不支持持久化虚拟环境（每次都是临时隔离环境）
- 不支持自定义Python版本约束（使用uv默认版本）
- 不支持复杂的依赖版本约束解析
- 不处理动态import语句

## Decisions

### Decision 1: 技能定位为指导型而非执行型

**决策：** skill提供指导模式和最佳实践，不直接执行Python代码。

**理由：**
- skill的主要用户是大模型，而不是最终用户
- 大模型需要理解"如何用uv执行"的模式和规范
- 保持skill的通用性，可以适应各种任务场景

**替代方案考虑：**
- 执行型skill：直接接收Python代码并执行
  - ❌ 需要处理更多边界情况（代码注入、安全性等）
  - ❌ 限制了灵活性（无法指导大模型编写更复杂的脚本）
  - ❌ 增加了复杂度

### Decision 2: 使用辅助脚本实现跨平台临时目录

**决策：** 创建`skills/python-runner/script/get_temp_path.py`辅助脚本，使用Python标准库的`tempfile`模块在系统临时目录中创建空的Python脚本文件，并返回脚本文件路径。**辅助脚本本身也使用uv run执行，保持一致性。**

**理由：**
- `tempfile.gettempdir()`自动适配所有平台（Windows/macOS/Linux）
- 避免了大模型需要检测平台和记住不同路径的复杂度
- 辅助脚本直接创建临时Python脚本文件，大模型直接得到脚本文件路径
- 简化大模型工作流：无需拼接路径，直接使用返回的文件路径写入内容
- 使用Python标准库，保证跨平台兼容性
- 辅助脚本可以复用，逻辑集中管理
- **使用uv run执行辅助脚本，保持skill内所有Python脚本使用统一方式**

**辅助脚本设计：**
- **功能**：在系统临时目录创建空的Python脚本文件，返回文件路径
- **无注释**：脚本只包含必要代码，没有文档字符串或注释
- **PEP 723格式**：包含空的依赖声明`# dependencies = []`
- **执行方式**：`uv run skills/python-runner/script/get_temp_path.py`
- **输出**：直接在stdout输出临时Python脚本文件的完整路径
  - Linux/macOS: `/tmp/uv_script_xxx.py`
  - Windows: `C:\Users\<username>\AppData\Local\Temp\uv_script_xxx.py`

**大模型使用流程：**
1. 调用辅助脚本获取临时脚本文件路径（使用相对路径`./script/get_temp_path.py`，相对于SKILL.md所在目录）
   ```bash
   temp_file_path=$(uv run ./script/get_temp_path.py)
   ```
2. 在返回的脚本文件路径中直接写入PEP 723脚本内容：
   ```python
   # 使用大模型的Write工具
   with open(temp_file_path, 'w') as f:
       f.write(script_content)
   ```
3. 使用`uv run`执行脚本：
   ```bash
   uv run $temp_file_path
   ```
4. 系统自动清理临时文件，无需手动管理

**替代方案考虑：**
- 在辅助脚本中导出函数供导入：
  - ❌ 需要大模型导入模块并调用函数，增加了复杂度
  - ❌ 辅助脚本需要更多代码（函数定义、文档等）
  - ❌ 不符合"简单直接"的设计原则
- 在skill文档中说明平台差异：
  - ❌ 大模型需要检测平台，容易出错
  - ❌ 文档冗长，增加了复杂度
  - ❌ 不符合"简化使用模式"的设计目标

### Decision 3: 依赖声明使用无版本约束的包名

**决策：** 在PEP 723元数据块中只声明包名，不指定版本约束，让uv自动选择兼容的最新版本。

**理由：**
- 简化依赖声明，降低大模型的认知负担
- uv的依赖解析器会自动选择兼容版本
- 使用最新版本通常更安全（包含安全修复）
- 避免版本固定带来的兼容性问题

**替代方案考虑：**
- 固定版本号（如`pandas==2.1.0`）：
  - ❌ 需要大模型了解每个包的最新版本
  - ❌ 版本过时可能引入安全漏洞
  - ❌ 可能与其他包产生版本冲突
  - ❌ 增加维护成本

### Decision 4: 严格错误处理模式

**决策：** 任何错误条件都停止任务并显示清晰错误消息。错误类型包括：uv未安装、Python语法错误、依赖解析失败、脚本运行时错误。

**理由：**
- 严格模式符合skill作为工具的定位（可靠、可预测）
- 避免错误传播导致难以调试的问题
- 清晰的错误消息帮助大模型和用户快速定位问题
- 保留失败的临时文件便于调试

**替代方案考虑：**
- 宽松模式（跳过错误包继续执行）：
  - ❌ 可能导致部分依赖缺失的脚本执行
  - ❌ 错误难以定位和调试
  - ❌ 不符合"可靠工具"的设计目标

### Decision 5: 无外部输入支持

**决策：** 所有输入、参数和数据源都嵌入在Python脚本内部。不支持命令行参数和stdin输入。

**理由：**
- 简化skill的使用模型
- 符合大模型生成脚本的使用模式（大模型知道所有参数）
- 避免参数传递的复杂度和安全风险
- 保持脚本的完整性和可移植性

**替代方案考虑：**
- 支持命令行参数：
  - ❌ 增加skill复杂度（需要参数传递机制）
  - ❌ 脚本可能依赖外部输入而不可移植
  - ❌ 不符合"所有逻辑嵌入脚本"的设计目标

### Decision 6: 通用任务适用性

**决策：** skill不限制在特定领域，适用于任何Python可处理的任务。在文档中提供常见用例示例（数据分析、API交互、文件操作等），但不硬编码限制。

**理由：**
- 最大化skill的复用性
- Python的适用范围很广，不应预先限制
- 通过示例而非硬编码来引导使用

**替代方案考虑：**
- 针对特定领域（如只支持数据分析）：
  - ❌ 限制了skill的通用性
  - ❌ 可能需要多个类似skill覆盖不同场景
  - ❌ 违反"通用工具"的设计目标

## Risks / Trade-offs

### Risk 1: uv依赖外部可用性

**风险：** 技能依赖uv包管理器，如果系统未安装uv，skill无法工作。

**缓解措施：**
- 错误消息中提供清晰的uv安装链接
- 在skill文档中明确说明uv是必需依赖
- 提供uv安装指南（https://docs.astral.sh/uv/getting-started/installation/）

### Risk 2: 临时文件

**风险：** 临时文件存储在系统临时目录（/tmp 或 Windows Temp），磁盘空间占用。

**缓解措施：**
- 临时文件使用系统标准临时目录，系统会自动定期清理
- 文件名包含时间戳，便于识别
- 在失败时显示文件路径，方便用户手动删除

### Risk 3: 依赖解析时间

**风险：** 首次执行某个脚本时，uv需要下载和安装依赖，可能需要较长时间，影响用户体验。

**缓解措施：**
- 在文档中说明首次执行可能较慢
- uv的依赖解析和安装速度很快（比传统pip快10-100倍）
- 使用最新版本通常减少兼容性问题，加快解析速度

### Risk 4: PyPI包可用性

**风险：** 如果声明的依赖包在PyPI上不存在或名称错误，依赖解析会失败。

**缓解措施：**
- 严格错误处理模式会显示uv的完整错误输出
- 大模型在编写脚本时已经知道依赖的包名
- 保留失败的临时文件便于检查依赖声明

### Risk 5: 大模型理解复杂度

**风险：** PEP 723元数据格式对大模型来说可能不熟悉，可能生成不符合规范的脚本。

**缓解措施：**
- skill文档提供清晰的示例和模板
- 严格错误处理会在语法或格式错误时立即停止并提示
- 文档中说明常见的格式错误和修正方法

## Migration Plan

这是新skill的首次实现，不存在迁移问题。

**部署步骤：**
1. 创建skill目录：`skills/python-runner/`
2. 创建skill文件：`skills/python-runner/SKILL.md`
3. 编写skill内容（YAML元数据 + Markdown文档）
4. 测试skill是否可以被正确加载和触发

**回滚策略：**
- 如有问题，直接删除`skills/python-runner/`目录即可
- skill文件不影响系统或现有代码

## Open Questions

无。所有设计决策已在上述章节明确说明。