235 lines
9.7 KiB
Markdown
235 lines
9.7 KiB
Markdown
## 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/lyxy-runner-python/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/lyxy-runner-python/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/lyxy-runner-python/`
|
||
2. 创建skill文件：`skills/lyxy-runner-python/SKILL.md`
|
||
3. 编写skill内容（YAML元数据 + Markdown文档）
|
||
4. 测试skill是否可以被正确加载和触发
|
||
|
||
**回滚策略：**
|
||
- 如有问题，直接删除`skills/lyxy-runner-python/`目录即可
|
||
- skill文件不影响系统或现有代码
|
||
|
||
## Open Questions
|
||
|
||
无。所有设计决策已在上述章节明确说明。
|